keycloak-admin 1.1.6 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db97e606c0a299c2daff7be37a2df4a1c2a7261d2430b62dd196b8d29dc9117d
-  data.tar.gz: a1581e41e26b30d576273036ccf87abf463db0e4a80cd1f3a0961b87f874c373
+  metadata.gz: cdb86e769e4a945994d979061cd6b44cb49fd40dd72c2c2b4ff40470e4386dc7
+  data.tar.gz: caaf2546d1802ec1b837d4f7bc43878c32a107978e61ea6e51e33e99a3fc0a3f
 SHA512:
-  metadata.gz: 33416a0ad66f8f054a2192f560fbd72d6d68d1a29101521d8bfa2be5bd705888f46740d325ee265ef0e983bbd611901e7902db2a14f5693bd066c250692bb417
-  data.tar.gz: 6e17f0a84457d4bf8ce7332b756b0892fbe51a606a8895e5434fca458d9b936594006057820fb3e753d1713b5fdd895fe546f82f90a60fea948f3065e4905bed
+  metadata.gz: 96e7940acc1d832bf9ff990642cec3a470450ea6bf19259cc301d080b48b8cea95cd668c2ca9b63e818769e1b67904d3d1b6e0c1ef2fe932ecd0919a0e10ec47
+  data.tar.gz: 01eecef72d13cb4f47d7387f21ee4dd70d7eb54275ae4738828bd57b2d21d193a1ef1ca03b330d06840a5d6192771b7204ed1131ba5e26b5087d8dc01f988a1f

data/.github/workflows/ci.yml

@@ -19,25 +19,37 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
-    services:
-      keycloak:
-        image: tillawy/keycloak-github-actions:25.0.1
-        ports:
-          - 8080:8080
-        options: '--health-cmd "exec 3<>/dev/tcp/localhost/8080" --health-interval 5s --health-timeout 5s --health-retries 10 --health-start-period 100s'
-        env:
-          KEYCLOAK_ADMIN: "admin"
-          KEYCLOAK_ADMIN_PASSWORD: "admin"
-          KC_HOSTNAME: "http://localhost:8080"
-          KC_HOSTNAME_ADMIN: "http://localhost:8080"
-          KC_HTTP_ENABLED: "true"
-          KC_DB: "dev-file"
 
     strategy:
       matrix:
         ruby-version: ['3.2']
 
     steps:
+    - name: Start Keycloak
+      run: |
+        docker run -d --name keycloak -p 8080:8080 \
+          -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
+          -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
+          -e KC_HOSTNAME=http://localhost:8080 \
+          -e KC_HOSTNAME_ADMIN=http://localhost:8080 \
+          -e KC_HTTP_ENABLED=true \
+          -e KC_DB=dev-file \
+          quay.io/keycloak/keycloak:26.7.0 \
+          start-dev
+
+    - name: Wait for Keycloak to be ready
+      run: |
+        for i in $(seq 1 30); do
+          if curl --silent --fail http://localhost:8080/realms/master > /dev/null; then
+            echo "Keycloak is ready"
+            exit 0
+          fi
+          sleep 5
+        done
+        echo "Keycloak did not become ready in time"
+        docker logs keycloak
+        exit 1
+
     - name: create realm
       run: |
          TOKEN=$(curl --silent --location --request POST "http://localhost:8080/realms/master/protocol/openid-connect/token" \
@@ -68,7 +80,7 @@ jobs:
              "redirectUris":["http://localhost:8180/demo"]
            }'
 
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-07-30
+
+* [Chore] Bump `http-cookie` dependency from 1.1.0 to 1.1.6.
+* [Chore] Upgrade Docker base image from `ruby:3.2.2-slim-bullseye` to `ruby:3.3.12-slim-trixie`.
+* [Chore] CI now boots Keycloak 26.7.0 (`quay.io/keycloak/keycloak`) instead of the abandoned `tillawy/keycloak-github-actions:25.0.1`
+
+## [1.1.7] - 2026-03-27
+
+* [Feature] Client scopes - supported operations:  `create!`, `get`, `delete`, `list`, and `search`.
+* [Feature] Client scopes protocol mappers - supported operations:  `create!`,  `get`, `delete`, `list`, and `search`.
+
 ## [1.1.6] - 2026-01-05
 
 * [Feature] Support for Organizations (Multi-tenancy):

data/Dockerfile

@@ -1,4 +1,4 @@
-FROM ruby:3.2.2-slim-bullseye
+FROM ruby:3.3.12-slim-trixie
 
 RUN apt-get update -qq && apt-get install -y build-essential git ruby-dev && apt-get clean && \
   mkdir -p /usr/src/app/lib/keycloak-admin

data/Gemfile.lock

@@ -1,25 +1,29 @@
 PATH
   remote: .
   specs:
-    keycloak-admin (1.1.6)
+    keycloak-admin (1.2.0)
       http-cookie (~> 1.0, >= 1.0.3)
       rest-client (~> 2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    byebug (12.0.0)
+    byebug (13.0.0)
+      reline (>= 0.6.0)
     diff-lcs (1.6.2)
     domain_name (0.6.20240107)
     http-accept (1.7.0)
-    http-cookie (1.1.0)
+    http-cookie (1.1.6)
       domain_name (~> 0.5)
+    io-console (0.8.2)
     logger (1.7.0)
     mime-types (3.7.0)
       logger
       mime-types-data (~> 3.2025, >= 3.2025.0507)
-    mime-types-data (3.2025.0924)
+    mime-types-data (3.2026.0701)
     netrc (0.11.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
     rest-client (2.1.0)
       http-accept (>= 1.7.0, < 2.0)
       http-cookie (>= 1.0.2, < 2.0)
@@ -34,18 +38,18 @@ GEM
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.7)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.6)
+    rspec-support (3.13.7)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  byebug (= 12.0.0)
+  byebug (= 13.0.0)
   keycloak-admin!
   rspec (= 3.13.2)
 
 BUNDLED WITH
-   2.1.4
+   2.7.2

data/README.md

@@ -12,7 +12,7 @@ This gem *does not* require Rails.
 For example, using `bundle`, add this line to your Gemfile.
 
 ```ruby
-gem "keycloak-admin", "1.1.6"
+gem "keycloak-admin", "1.2.0"
 ```
 
 ## Login
@@ -135,6 +135,8 @@ All options have a default value. However, all of them can be changed in your in
 * Execute actions emails
 * Send forgot passsword mail
 * Client Authorization, create, update, get, delete Resource, Scope, Policy, Permission, Policy Enforcer
+* Get list of client scopes, create/save/get/delete/search a client scope
+* Get list of protocol mappers for a client scope, create/save/get/delete a protocol mapper
 * Get list of organizations, create/update/get/delete an organization
 * Get list of members of an organization, add/remove members
 * Invite new or existing users to an organization
@@ -757,6 +759,120 @@ KeycloakAdmin.realm("realm_a").authz_permissions(client.id, 'scope').delete(scop
  KeycloakAdmin.realm("realm_a").authz_permissions(client.id, 'resource').delete(resource_permission.id)
 ```
 
+### Manage Client Scopes
+
+### List all client scopes in a realm
+
+Returns an array of `KeycloakAdmin::ClientScopeRepresentation`.
+
+```ruby
+KeycloakAdmin.realm("a_realm").client_scopes.list
+```
+
+### Get a client scope by its id
+
+Returns an instance of `KeycloakAdmin::ClientScopeRepresentation`.
+
+```ruby
+client_scope_id = "7686af34-204c-4515-8122-78d19febbf6e"
+KeycloakAdmin.realm("a_realm").client_scopes.get(client_scope_id)
+```
+
+### Search for client scopes by name
+
+Returns an array of `KeycloakAdmin::ClientScopeRepresentation` whose names contain the given substring.
+
+```ruby
+KeycloakAdmin.realm("a_realm").client_scopes.search("my-scope")
+```
+
+### Create a client scope
+
+Takes `scope_representation` of type `KeycloakAdmin::ClientScopeRepresentation`. Returns `true` on success.
+
+```ruby
+scope             = KeycloakAdmin::ClientScopeRepresentation.new
+scope.name        = "my-scope"
+scope.description = "My custom scope"
+scope.protocol    = "openid-connect"
+scope.attributes  = { "display.on.consent.screen" => "true", "include.in.token.scope" => "true" }
+KeycloakAdmin.realm("a_realm").client_scopes.create!(scope)
+```
+
+### Save (update) a client scope
+
+Takes `scope_representation` of type `KeycloakAdmin::ClientScopeRepresentation` (must include its `id`). Returns `true` on success.
+
+```ruby
+client_scope_id = "7686af34-204c-4515-8122-78d19febbf6e"
+scope           = KeycloakAdmin.realm("a_realm").client_scopes.get(client_scope_id)
+scope.description = "Updated description"
+KeycloakAdmin.realm("a_realm").client_scopes.save(scope)
+```
+
+### Delete a client scope
+
+```ruby
+client_scope_id = "7686af34-204c-4515-8122-78d19febbf6e"
+KeycloakAdmin.realm("a_realm").client_scopes.delete(client_scope_id)
+```
+
+### Manage Protocol Mappers for a Client Scope
+
+Protocol mappers allow you to transform tokens and assertions. The following operations are available on the protocol mappers of a given client scope.
+
+### List protocol mappers for a client scope
+
+Returns an array of `KeycloakAdmin::ProtocolMapperRepresentation`.
+
+```ruby
+client_scope_id = "7686af34-204c-4515-8122-78d19febbf6e"
+KeycloakAdmin.realm("a_realm").client_scope_protocol_mappers(client_scope_id).list
+```
+
+### Get a protocol mapper by its id
+
+Returns an instance of `KeycloakAdmin::ProtocolMapperRepresentation`.
+
+```ruby
+client_scope_id = "7686af34-204c-4515-8122-78d19febbf6e"
+mapper_id       = "95985b21-d884-4bbd-b852-cb8cd365afc2"
+KeycloakAdmin.realm("a_realm").client_scope_protocol_mappers(client_scope_id).get(mapper_id)
+```
+
+### Create a protocol mapper for a client scope
+
+Takes `mapper_representation` of type `KeycloakAdmin::ProtocolMapperRepresentation`. Returns `true` on success.
+
+```ruby
+client_scope_id     = "7686af34-204c-4515-8122-78d19febbf6e"
+mapper              = KeycloakAdmin::ProtocolMapperRepresentation.new
+mapper.name         = "my-mapper"
+mapper.protocol     = "openid-connect"
+mapper.protocolMapper = "oidc-usermodel-attribute-mapper"
+mapper.config       = { "user.attribute" => "locale", "claim.name" => "locale", "jsonType.label" => "String", "id.token.claim" => "true", "access.token.claim" => "true", "userinfo.token.claim" => "true" }
+KeycloakAdmin.realm("a_realm").client_scope_protocol_mappers(client_scope_id).create!(mapper)
+```
+
+### Save (update) a protocol mapper for a client scope
+
+Takes `mapper_representation` of type `KeycloakAdmin::ProtocolMapperRepresentation` (must include its `id`). Returns `true` on success.
+
+```ruby
+client_scope_id    = "7686af34-204c-4515-8122-78d19febbf6e"
+mapper             = KeycloakAdmin.realm("a_realm").client_scope_protocol_mappers(client_scope_id).get(mapper_id)
+mapper.config["claim.name"] = "updated_claim"
+KeycloakAdmin.realm("a_realm").client_scope_protocol_mappers(client_scope_id).save(mapper)
+```
+
+### Delete a protocol mapper from a client scope
+
+```ruby
+client_scope_id = "7686af34-204c-4515-8122-78d19febbf6e"
+mapper_id       = "95985b21-d884-4bbd-b852-cb8cd365afc2"
+KeycloakAdmin.realm("a_realm").client_scope_protocol_mappers(client_scope_id).delete(mapper_id)
+```
+
 ## How to execute library tests
 
 From the `keycloak-admin-api` directory:

data/keycloak-admin.gemspec

@@ -20,5 +20,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency "http-cookie", "~> 1.0", ">= 1.0.3"
   spec.add_dependency "rest-client", "~> 2.0"
   spec.add_development_dependency "rspec",  "3.13.2"
-  spec.add_development_dependency "byebug", "12.0.0"
+  spec.add_development_dependency "byebug", "13.0.0"
 end

data/lib/keycloak-admin/client/client_scope_client.rb

@@ -0,0 +1,65 @@
+module KeycloakAdmin
+  class ClientScopeClient < Client
+    def initialize(configuration, realm_client)
+      super(configuration)
+
+      raise ArgumentError.new("realm must be defined") unless realm_client.name_defined?
+
+      @realm_client = realm_client
+    end
+
+    def list
+      response = execute_http do
+        RestClient::Resource.new(client_scopes_url, @configuration.rest_client_options).get(headers)
+      end
+
+      JSON.parse(response).map { |h| ClientScopeRepresentation.from_hash(h) }
+    end
+
+    def get(client_scope_id)
+      response = execute_http do
+        RestClient::Resource.new(client_scopes_url(client_scope_id), @configuration.rest_client_options).get(headers)
+      end
+
+      ClientScopeRepresentation.from_hash(JSON.parse(response))
+    end
+
+    def create!(client_scope_representation)
+      execute_http do
+        RestClient::Resource.new(client_scopes_url, @configuration.rest_client_options).post(
+          create_payload(client_scope_representation), headers
+        )
+      end
+
+      true
+    end
+
+    def save(client_scope_representation)
+      execute_http do
+        RestClient::Resource.new(client_scopes_url(client_scope_representation.id), @configuration.rest_client_options).put(
+          create_payload(client_scope_representation), headers
+        )
+      end
+
+      true
+    end
+
+    def search(name)
+      list.select { |scope| scope&.name&.include?(name) }
+    end
+
+    def delete(client_scope_id)
+      execute_http do
+        RestClient::Resource.new(client_scopes_url(client_scope_id), @configuration.rest_client_options).delete(headers)
+      end
+
+      true
+    end
+
+    def client_scopes_url(client_scope_id = nil)
+      base = "#{@realm_client.realm_admin_url}/client-scopes"
+
+      client_scope_id ? "#{base}/#{client_scope_id}" : base
+    end
+  end
+end

data/lib/keycloak-admin/client/client_scope_protocol_mapper_client.rb

@@ -0,0 +1,62 @@
+module KeycloakAdmin
+  class ClientScopeProtocolMapperClient < Client
+    def initialize(configuration, realm_client, client_scope_id)
+      super(configuration)
+
+      raise ArgumentError.new("realm must be defined") unless realm_client.name_defined?
+
+      @realm_client    = realm_client
+      @client_scope_id = client_scope_id
+    end
+
+    def list
+      response = execute_http do
+        RestClient::Resource.new(protocol_mappers_url, @configuration.rest_client_options).get(headers)
+      end
+
+      JSON.parse(response).map { |h| ProtocolMapperRepresentation.from_hash(h) }
+    end
+
+    def get(mapper_id)
+      response = execute_http do
+        RestClient::Resource.new(protocol_mappers_url(mapper_id), @configuration.rest_client_options).get(headers)
+      end
+
+      ProtocolMapperRepresentation.from_hash(JSON.parse(response))
+    end
+
+    def create!(mapper_representation)
+      execute_http do
+        RestClient::Resource.new(protocol_mappers_url, @configuration.rest_client_options).post(
+          create_payload(mapper_representation), headers
+        )
+      end
+
+      true
+    end
+
+    def save(mapper_representation)
+      execute_http do
+        RestClient::Resource.new(protocol_mappers_url(mapper_representation.id), @configuration.rest_client_options).put(
+          create_payload(mapper_representation), headers
+        )
+      end
+
+      true
+    end
+
+    def delete(mapper_id)
+      execute_http do
+        RestClient::Resource.new(protocol_mappers_url(mapper_id), @configuration.rest_client_options).delete(headers)
+      end
+
+      true
+    end
+
+    def protocol_mappers_url(mapper_id = nil)
+      base = "#{@realm_client.realm_admin_url}/client-scopes/#{@client_scope_id}/protocol-mappers/models"
+
+      mapper_id ? "#{base}/#{mapper_id}" : base
+    end
+  end
+end

data/lib/keycloak-admin/client/realm_client.rb

@@ -103,6 +103,14 @@ module KeycloakAdmin
       UserResource.new(@configuration, self, user_id)
     end
 
+    def client_scopes
+      ClientScopeClient.new(@configuration, self)
+    end
+
+    def client_scope_protocol_mappers(client_scope_id)
+      ClientScopeProtocolMapperClient.new(@configuration, self, client_scope_id)
+    end
+
     def authz_scopes(client_id, resource_id = nil)
       ClientAuthzScopeClient.new(@configuration, self, client_id, resource_id)
     end

data/lib/keycloak-admin/representation/client_scope_representation.rb

@@ -0,0 +1,21 @@
+module KeycloakAdmin
+  class ClientScopeRepresentation < Representation
+    attr_accessor :id,
+                  :name,
+                  :description,
+                  :protocol,
+                  :attributes,
+                  :protocol_mappers
+
+    def self.from_hash(hash)
+      rep                  = new
+      rep.id               = hash["id"]
+      rep.name             = hash["name"]
+      rep.description      = hash["description"]
+      rep.protocol         = hash["protocol"]
+      rep.attributes       = hash["attributes"]
+      rep.protocol_mappers = (hash["protocolMappers"] || []).map { |m| ProtocolMapperRepresentation.from_hash(m) }
+      rep
+    end
+  end
+end

data/lib/keycloak-admin/version.rb

@@ -1,3 +1,3 @@
 module KeycloakAdmin
-  VERSION = "1.1.6"
+  VERSION = "1.2.0"
 end

data/lib/keycloak-admin.rb

@@ -16,6 +16,8 @@ require_relative "keycloak-admin/client/identity_provider_client"
 require_relative "keycloak-admin/client/configurable_token_client"
 require_relative "keycloak-admin/client/attack_detection_client"
 require_relative "keycloak-admin/client/client_authz_scope_client"
+require_relative "keycloak-admin/client/client_scope_client"
+require_relative "keycloak-admin/client/client_scope_protocol_mapper_client"
 require_relative "keycloak-admin/client/client_authz_resource_client"
 require_relative "keycloak-admin/client/client_authz_policy_client"
 require_relative "keycloak-admin/client/client_authz_permission_client"
@@ -39,6 +41,7 @@ require_relative "keycloak-admin/representation/identity_provider_mapper_represe
 require_relative "keycloak-admin/representation/identity_provider_representation"
 require_relative "keycloak-admin/representation/attack_detection_representation"
 require_relative "keycloak-admin/representation/session_representation"
+require_relative "keycloak-admin/representation/client_scope_representation"
 require_relative "keycloak-admin/representation/client_authz_scope_representation"
 require_relative "keycloak-admin/representation/client_authz_resource_representation"
 require_relative "keycloak-admin/representation/client_authz_policy_representation"

data/spec/client/client_scope_client_spec.rb

@@ -0,0 +1,220 @@
+RSpec.describe KeycloakAdmin::ClientScopeClient do
+  let(:realm_name)      { "valid-realm" }
+  let(:client_scope_id) { "valid-scope-id" }
+
+  let(:scope_json) do
+    <<~JSON
+      {"id":"valid-scope-id","name":"my-scope","description":"A test scope","protocol":"openid-connect","attributes":{"display.on.consent.screen":"true","include.in.token.scope":"true"}}
+    JSON
+  end
+
+  let(:scope_with_mappers_json) do
+    <<~JSON
+      {"id":"valid-scope-id","name":"my-scope","description":"A test scope","protocol":"openid-connect","attributes":{},"protocolMappers":[{"id":"mapper-id","name":"my-claim","protocol":"openid-connect","protocolMapper":"oidc-hardcoded-claim-mapper","config":{"claim.name":"my_claim","claim.value":"bar","access.token.claim":"true"}}]}
+    JSON
+  end
+
+  describe "#initialize" do
+    context "when realm_name is defined" do
+      it "does not raise any error" do
+        expect { KeycloakAdmin.realm(realm_name).client_scopes }.to_not raise_error
+      end
+    end
+
+    context "when realm_name is not defined" do
+      it "raises an argument error" do
+        expect { KeycloakAdmin.realm(nil).client_scopes }.to raise_error(ArgumentError)
+      end
+    end
+  end
+
+  describe "#list" do
+    before(:each) do
+      @client = KeycloakAdmin.realm(realm_name).client_scopes
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:get).and_return stub_response
+    end
+
+    context "with one scope" do
+      let(:stub_response) { "[#{scope_json}]" }
+
+      it "returns one scope" do
+        expect(@client.list.size).to eq 1
+      end
+
+      it "returns the correct scope attributes" do
+        expect(@client.list.first).to have_attributes(
+          id:          "valid-scope-id",
+          name:        "my-scope",
+          description: "A test scope",
+          protocol:    "openid-connect"
+        )
+      end
+
+      it "returns attributes map" do
+        expect(@client.list.first.attributes).to include(
+          "display.on.consent.screen" => "true",
+          "include.in.token.scope"    => "true"
+        )
+      end
+    end
+
+    context "with multiple scopes" do
+      let(:second_scope_json) { '{"id":"other-scope-id","name":"other-scope","protocol":"openid-connect"}' }
+      let(:stub_response) { "[#{scope_json},#{second_scope_json}]" }
+
+      it "returns two scopes" do
+        expect(@client.list.size).to eq 2
+      end
+
+      it "includes both scope names" do
+        expect(@client.list.map(&:name)).to include("my-scope", "other-scope")
+      end
+    end
+  end
+
+  describe "#get" do
+    before(:each) do
+      @client = KeycloakAdmin.realm(realm_name).client_scopes
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:get).and_return stub_response
+    end
+
+    context "without protocol mappers" do
+      let(:stub_response) { scope_json }
+
+      it "returns the correct id" do
+        expect(@client.get(client_scope_id).id).to eq "valid-scope-id"
+      end
+
+      it "returns the correct name" do
+        expect(@client.get(client_scope_id).name).to eq "my-scope"
+      end
+
+      it "returns the correct description" do
+        expect(@client.get(client_scope_id).description).to eq "A test scope"
+      end
+
+      it "returns the correct protocol" do
+        expect(@client.get(client_scope_id).protocol).to eq "openid-connect"
+      end
+
+      it "returns an empty protocolMappers list" do
+        expect(@client.get(client_scope_id).protocol_mappers).to eq []
+      end
+    end
+
+    context "with protocol mappers" do
+      let(:stub_response) { scope_with_mappers_json }
+
+      it "returns protocol mappers" do
+        expect(@client.get(client_scope_id).protocol_mappers.size).to eq 1
+      end
+
+      it "returns the correct mapper name" do
+        expect(@client.get(client_scope_id).protocol_mappers.first.name).to eq "my-claim"
+      end
+    end
+  end
+
+  describe "#create!" do
+    before(:each) do
+      @client = KeycloakAdmin.realm(realm_name).client_scopes
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:post).and_return ""
+    end
+
+    let(:scope_representation) do
+      scope             = KeycloakAdmin::ClientScopeRepresentation.new
+      scope.name        = "my-scope"
+      scope.description = "A test scope"
+      scope.protocol    = "openid-connect"
+      scope.attributes  = { "display.on.consent.screen" => "true", "include.in.token.scope" => "true" }
+      scope
+    end
+
+    it "creates successfully" do
+      expect(@client.create!(scope_representation)).to be true
+    end
+  end
+
+  describe "#save" do
+    before(:each) do
+      @client = KeycloakAdmin.realm(realm_name).client_scopes
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:put).and_return ""
+    end
+
+    let(:scope_representation) { KeycloakAdmin::ClientScopeRepresentation.from_hash(JSON.parse(scope_json)) }
+
+    it "calls put on the scope url" do
+      expect_any_instance_of(RestClient::Resource).to receive(:put).with(anything, anything)
+      @client.save(scope_representation)
+    end
+
+    it "returns true" do
+      expect(@client.save(scope_representation)).to be true
+    end
+  end
+
+  describe "#search" do
+    let(:second_scope_json) { '{"id":"other-scope-id","name":"other-scope","protocol":"openid-connect"}' }
+
+    before(:each) do
+      @client = KeycloakAdmin.realm(realm_name).client_scopes
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:get).and_return "[#{scope_json},#{second_scope_json}]"
+    end
+
+    context "when the name matches one scope" do
+      it "returns only the matching scope" do
+        expect(@client.search("my-scope").size).to eq 1
+      end
+
+      it "returns the correct scope" do
+        expect(@client.search("my-scope").first).to have_attributes(id: "valid-scope-id", name: "my-scope")
+      end
+    end
+
+    context "when the name is a partial match" do
+      it "returns all scopes containing the substring" do
+        expect(@client.search("scope").size).to eq 2
+      end
+    end
+
+    context "when no scope matches" do
+      it "returns an empty array" do
+        expect(@client.search("unknown")).to eq []
+      end
+    end
+  end
+
+  describe "#delete" do
+    before(:each) do
+      @client = KeycloakAdmin.realm(realm_name).client_scopes
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:delete).and_return ""
+    end
+
+    it "returns true" do
+      expect(@client.delete(client_scope_id)).to eq true
+    end
+  end
+
+  describe "#client_scopes_url" do
+    let(:client)   { KeycloakAdmin.realm(realm_name).client_scopes }
+    let(:base_url) { "http://auth.service.io/auth/admin/realms/valid-realm/client-scopes" }
+
+    context "without a client_scope_id" do
+      it "returns the base url" do
+        expect(client.client_scopes_url).to eq base_url
+      end
+    end
+
+    context "with a client_scope_id" do
+      it "returns the url with client_scope_id appended" do
+        expect(client.client_scopes_url(client_scope_id)).to eq "#{base_url}/valid-scope-id"
+      end
+    end
+  end
+end

data/spec/client/client_scope_protocol_mapper_client_spec.rb

@@ -0,0 +1,230 @@
+RSpec.describe KeycloakAdmin::ClientScopeProtocolMapperClient do
+  let(:realm_name)      { "valid-realm" }
+  let(:client_scope_id) { "valid-scope-id" }
+  let(:mapper_id)       { "valid-mapper-id" }
+
+  let(:mapper_json) do
+    <<~JSON
+      {"id":"valid-mapper-id","name":"my-claim","protocol":"openid-connect","protocolMapper":"oidc-hardcoded-claim-mapper","config":{"claim.name":"my_claim","claim.value":"bar","access.token.claim":"true"}}
+    JSON
+  end
+
+  let(:audience_mapper_json) do
+    <<~JSON
+      {"protocol":"openid-connect","protocolMapper":"oidc-audience-mapper","name":"audience-config-rvw-123","config":{"included.client.audience":"","included.custom.audience":"https://api.example.com","id.token.claim":"false","access.token.claim":"true","lightweight.claim":"false","introspection.token.claim":"true"}}
+    JSON
+  end
+
+  describe "#initialize" do
+    context "when realm_name is defined" do
+      it "does not raise any error" do
+        expect { KeycloakAdmin.realm(realm_name).client_scope_protocol_mappers(client_scope_id) }.to_not raise_error
+      end
+    end
+
+    context "when realm_name is not defined" do
+      it "raises an argument error" do
+        expect { KeycloakAdmin.realm(nil).client_scope_protocol_mappers(client_scope_id) }.to raise_error(ArgumentError)
+      end
+    end
+  end
+
+  describe "#list" do
+    before(:each) do
+      @client = KeycloakAdmin.realm(realm_name).client_scope_protocol_mappers(client_scope_id)
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:get).and_return stub_response
+    end
+
+    context "with a hardcoded claim mapper" do
+      let(:stub_response) { "[#{mapper_json}]" }
+
+      it "returns one mapper" do
+        expect(@client.list.size).to eq 1
+      end
+
+      it "returns the correct mapper attributes" do
+        expect(@client.list.first).to have_attributes(id: "valid-mapper-id", name: "my-claim", protocol: "openid-connect", protocolMapper: "oidc-hardcoded-claim-mapper")
+      end
+    end
+
+    context "with an audience mapper" do
+      let(:stub_response) { "[#{audience_mapper_json}]" }
+
+      it "returns one mapper" do
+        expect(@client.list.size).to eq 1
+      end
+
+      it "returns the correct mapper attributes" do
+        expect(@client.list.first).to have_attributes(name: "audience-config-rvw-123", protocol: "openid-connect", protocolMapper: "oidc-audience-mapper")
+      end
+    end
+
+    context "with multiple mappers" do
+      let(:stub_response) { "[#{mapper_json},#{audience_mapper_json}]" }
+
+      it "returns two mappers" do
+        expect(@client.list.size).to eq 2
+      end
+
+      it "includes both mapper names" do
+        expect(@client.list.map(&:name)).to include("my-claim", "audience-config-rvw-123")
+      end
+    end
+  end
+
+  describe "#get" do
+    before(:each) do
+      @client = KeycloakAdmin.realm(realm_name).client_scope_protocol_mappers(client_scope_id)
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:get).and_return stub_response
+    end
+
+    context "with a hardcoded claim mapper" do
+      let(:stub_response) { mapper_json }
+
+      it "returns the correct id" do
+        expect(@client.get(mapper_id).id).to eq "valid-mapper-id"
+      end
+
+      it "returns the correct name" do
+        expect(@client.get(mapper_id).name).to eq "my-claim"
+      end
+
+      it "returns the correct protocol" do
+        expect(@client.get(mapper_id).protocol).to eq "openid-connect"
+      end
+
+      it "returns the correct protocolMapper" do
+        expect(@client.get(mapper_id).protocolMapper).to eq "oidc-hardcoded-claim-mapper"
+      end
+    end
+
+    context "with an audience mapper" do
+      let(:stub_response) { audience_mapper_json }
+
+      it "returns the correct name" do
+        expect(@client.get(mapper_id).name).to eq "audience-config-rvw-123"
+      end
+
+      it "returns the correct protocol" do
+        expect(@client.get(mapper_id).protocol).to eq "openid-connect"
+      end
+
+      it "returns the correct protocolMapper" do
+        expect(@client.get(mapper_id).protocolMapper).to eq "oidc-audience-mapper"
+      end
+
+      it "returns the correct config" do
+        expect(@client.get(mapper_id).config).to include(
+          "included.custom.audience"  => "https://api.example.com",
+          "access.token.claim"        => "true",
+          "introspection.token.claim" => "true",
+          "id.token.claim"            => "false"
+        )
+      end
+    end
+  end
+
+  describe "#create!" do
+    before(:each) do
+      @client = KeycloakAdmin.realm(realm_name).client_scope_protocol_mappers(client_scope_id)
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:post).and_return stub_response
+    end
+
+    context "with a hardcoded claim mapper" do
+      let(:stub_response) { mapper_json }
+      let(:mapper_representation) do
+        mapper = KeycloakAdmin::ProtocolMapperRepresentation.new
+        mapper.name           = "my-claim"
+        mapper.protocol       = "openid-connect"
+        mapper.protocolMapper = "oidc-hardcoded-claim-mapper"
+        mapper.config         = { "claim.name" => "my_claim", "claim.value" => "bar", "access.token.claim" => "true" }
+        mapper
+      end
+
+      it "creates successfully" do
+        expect(@client.create!(mapper_representation)).to be true
+      end
+    end
+
+    context "with an audience mapper" do
+      let(:stub_response)         { audience_mapper_json }
+      let(:mapper_representation) do
+        mapper = KeycloakAdmin::ProtocolMapperRepresentation.new
+        mapper.name           = "audience-config-rvw-123"
+        mapper.protocol       = "openid-connect"
+        mapper.protocolMapper = "oidc-audience-mapper"
+        mapper.config         = {
+          "included.client.audience"  => "",
+          "included.custom.audience"  => "https://api.example.com",
+          "id.token.claim"            => "false",
+          "access.token.claim"        => "true",
+          "lightweight.claim"         => "false",
+          "introspection.token.claim" => "true"
+        }
+        mapper
+      end
+
+      it "creates successfully" do
+        expect(@client.create!(mapper_representation)).to be true
+      end
+    end
+  end
+
+  describe "#save" do
+    before(:each) do
+      @client = KeycloakAdmin.realm(realm_name).client_scope_protocol_mappers(client_scope_id)
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:put).and_return ""
+    end
+
+    context "with a hardcoded claim mapper" do
+      let(:mapper_representation) { KeycloakAdmin::ProtocolMapperRepresentation.from_hash(JSON.parse(mapper_json)) }
+
+      it "calls put on the mapper url" do
+        expect_any_instance_of(RestClient::Resource).to receive(:put).with(anything, anything)
+        @client.save(mapper_representation)
+      end
+    end
+
+    context "with an audience mapper" do
+      let(:mapper_representation) { KeycloakAdmin::ProtocolMapperRepresentation.from_hash(JSON.parse(audience_mapper_json)) }
+
+      it "calls put on the mapper url" do
+        expect_any_instance_of(RestClient::Resource).to receive(:put).with(anything, anything)
+        @client.save(mapper_representation)
+      end
+    end
+  end
+
+  describe "#delete" do
+    before(:each) do
+      @client = KeycloakAdmin.realm(realm_name).client_scope_protocol_mappers(client_scope_id)
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:delete).and_return ""
+    end
+
+    it "returns true" do
+      expect(@client.delete(mapper_id)).to eq true
+    end
+  end
+
+  describe "#protocol_mappers_url" do
+    let(:client)   { KeycloakAdmin.realm(realm_name).client_scope_protocol_mappers(client_scope_id) }
+    let(:base_url) { "http://auth.service.io/auth/admin/realms/valid-realm/client-scopes/valid-scope-id/protocol-mappers/models" }
+
+    context "without a mapper_id" do
+      it "returns the base url" do
+        expect(client.protocol_mappers_url).to eq base_url
+      end
+    end
+
+    context "with a mapper_id" do
+      it "returns the url with mapper_id appended" do
+        expect(client.protocol_mappers_url(mapper_id)).to eq "#{base_url}/valid-mapper-id"
+      end
+    end
+  end
+end

data/spec/representation/client_scope_representation_spec.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+RSpec.describe KeycloakAdmin::ClientScopeRepresentation do
+  describe ".from_hash" do
+    context "with all fields" do
+      let(:hash) do
+        {
+          "id"          => "valid-scope-id",
+          "name"        => "my-scope",
+          "description" => "A test scope",
+          "protocol"    => "openid-connect",
+          "attributes"  => {
+            "display.on.consent.screen" => "true",
+            "include.in.token.scope"    => "true"
+          },
+          "protocolMappers" => [
+            {
+              "id"             => "mapper-id",
+              "name"           => "my-claim",
+              "protocol"       => "openid-connect",
+              "protocolMapper" => "oidc-hardcoded-claim-mapper",
+              "config"         => { "claim.name" => "my_claim", "claim.value" => "bar" }
+            }
+          ]
+        }
+      end
+
+      subject { described_class.from_hash(hash) }
+
+      it "returns an instance of the class" do
+        expect(subject).to be_a described_class
+      end
+
+      it "sets id" do
+        expect(subject.id).to eq "valid-scope-id"
+      end
+
+      it "sets name" do
+        expect(subject.name).to eq "my-scope"
+      end
+
+      it "sets description" do
+        expect(subject.description).to eq "A test scope"
+      end
+
+      it "sets protocol" do
+        expect(subject.protocol).to eq "openid-connect"
+      end
+
+      it "sets attributes" do
+        expect(subject.attributes).to eq(
+          "display.on.consent.screen" => "true",
+          "include.in.token.scope"    => "true"
+        )
+      end
+
+      it "deserializes protocolMappers as ProtocolMapperRepresentation objects" do
+        expect(subject.protocol_mappers.size).to eq 1
+        expect(subject.protocol_mappers.first).to be_a KeycloakAdmin::ProtocolMapperRepresentation
+      end
+
+      it "sets the correct mapper attributes" do
+        expect(subject.protocol_mappers.first).to have_attributes(
+          id:             "mapper-id",
+          name:           "my-claim",
+          protocol:       "openid-connect",
+          protocolMapper: "oidc-hardcoded-claim-mapper"
+        )
+      end
+    end
+
+    context "without protocolMappers" do
+      subject { described_class.from_hash({ "id" => "valid-scope-id", "name" => "my-scope" }) }
+
+      it "defaults protocolMappers to an empty array" do
+        expect(subject.protocol_mappers).to eq []
+      end
+    end
+
+    context "with minimal fields" do
+      subject { described_class.from_hash({ "name" => "my-scope", "protocol" => "saml" }) }
+
+      it "sets name" do
+        expect(subject.name).to eq "my-scope"
+      end
+
+      it "sets protocol" do
+        expect(subject.protocol).to eq "saml"
+      end
+
+      it "leaves id nil" do
+        expect(subject.id).to be_nil
+      end
+
+      it "leaves description nil" do
+        expect(subject.description).to be_nil
+      end
+
+      it "leaves attributes nil" do
+        expect(subject.attributes).to be_nil
+      end
+    end
+  end
+
+  describe "#to_json" do
+    subject do
+      described_class.from_hash(
+        "id"          => "valid-scope-id",
+        "name"        => "my-scope",
+        "description" => "A test scope",
+        "protocol"    => "openid-connect",
+        "attributes"  => { "include.in.token.scope" => "true" }
+      )
+    end
+
+    it "serializes to JSON" do
+      parsed = JSON.parse(subject.to_json)
+      expect(parsed["id"]).to          eq "valid-scope-id"
+      expect(parsed["name"]).to        eq "my-scope"
+      expect(parsed["description"]).to eq "A test scope"
+      expect(parsed["protocol"]).to    eq "openid-connect"
+      expect(parsed["attributes"]).to  eq("include.in.token.scope" => "true")
+    end
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: keycloak-admin
 version: !ruby/object:Gem::Version
-  version: 1.1.6
+  version: 1.2.0
 platform: ruby
 authors:
 - Lorent Lempereur
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-05 00:00:00.000000000 Z
+date: 2026-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http-cookie
@@ -64,14 +63,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 12.0.0
+        version: 13.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 12.0.0
+        version: 13.0.0
 description: Keycloak Admin REST API client written in Ruby
 email:
 - lorent.lempereur.dev@gmail.com
@@ -101,6 +100,8 @@ files:
 - lib/keycloak-admin/client/client_client.rb
 - lib/keycloak-admin/client/client_role_client.rb
 - lib/keycloak-admin/client/client_role_mappings_client.rb
+- lib/keycloak-admin/client/client_scope_client.rb
+- lib/keycloak-admin/client/client_scope_protocol_mapper_client.rb
 - lib/keycloak-admin/client/configurable_token_client.rb
 - lib/keycloak-admin/client/group_client.rb
 - lib/keycloak-admin/client/identity_provider_client.rb
@@ -119,6 +120,7 @@ files:
 - lib/keycloak-admin/representation/client_authz_resource_representation.rb
 - lib/keycloak-admin/representation/client_authz_scope_representation.rb
 - lib/keycloak-admin/representation/client_representation.rb
+- lib/keycloak-admin/representation/client_scope_representation.rb
 - lib/keycloak-admin/representation/credential_representation.rb
 - lib/keycloak-admin/representation/federated_identity_representation.rb
 - lib/keycloak-admin/representation/group_representation.rb
@@ -147,6 +149,8 @@ files:
 - spec/client/client_authz_scope_client_spec.rb
 - spec/client/client_client_spec.rb
 - spec/client/client_role_mappings_client_spec.rb
+- spec/client/client_scope_client_spec.rb
+- spec/client/client_scope_protocol_mapper_client_spec.rb
 - spec/client/client_spec.rb
 - spec/client/configurable_token_client_spec.rb
 - spec/client/group_client_spec.rb
@@ -165,6 +169,7 @@ files:
 - spec/representation/client_authz_resource_representation_spec.rb
 - spec/representation/client_authz_scope_representation_spec.rb
 - spec/representation/client_representation_spec.rb
+- spec/representation/client_scope_representation_spec.rb
 - spec/representation/credential_representation_spec.rb
 - spec/representation/group_representation_spec.rb
 - spec/representation/identity_provider_mapper_representation_spec.rb
@@ -182,7 +187,6 @@ homepage: https://github.com/looorent/keycloak-admin-ruby
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -197,8 +201,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Keycloak Admin REST API client written in Ruby
 test_files: []