keycloak-admin 1.0.24 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6bc5dc390440dedbf6a682c53717e334e4f174b31e43b7990dae87bed2e0bbf
-  data.tar.gz: b37367aaa9726b48a266b55baf7fcebf772f302c18f215ad0e694d6e60421608
+  metadata.gz: bf6847f9dc60316780255644c15320d06a998331df2283e30a007c4bea951ba1
+  data.tar.gz: 4af207ec29032148c58ff23194f4ade85aec556718bb4896c00ec29fe95000a9
 SHA512:
-  metadata.gz: 869a2108bbffcdc242a438a20b6d8c06fa907354e2d0648cac91920d08ba070b2bf9cc35d710f1a1fcb40691176b84b515372af540bdc7383d4835217e9ce989
-  data.tar.gz: ed68ed6de159d1d0bf87c298b49fab7fc94cc1d5f563ef25a2b56e922807ddb98b9fba69f189bc7ccc843380595afce42cc202e14b53f07fcc97f7c141145e43
+  metadata.gz: 6e03b3d8ae4f5eac52399fefcbea427d34a5afc5e08475365a8166faa5031eebb7b87cff23393e16e91e2df0f50263023b29262addff9550f79ef7bb5c739637
+  data.tar.gz: 1c91e21ee8d74ba5ca05f773d20acdc11e3a6c8fd8ab3e8098cb75c7d44ed1c7763e3954b094012a5fe9000c1ff4cb048355e7a3a1f134b8911fc349b03919d9

data/CHANGELOG.md

@@ -5,6 +5,16 @@ 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.1.1] - 2024-01-21
+
+* Add/List realm-role/s to a group, Allow role-names with spaces, List groups assigned to role (thanks to @LiquidMagical
+)
+
+## [1.1.0] - 2023-10-03
+
+* Search for groups with parameters (thanks to @@tlloydthwaites)
+* Get client by ID, Find client by Client ID, Update Client (thanks to @gee-forr)
+
 ## [1.0.24] - 2023-06-07
 
 * Revert the modifications on the feature 'Update a User' introduced in `1.0.22`. This implementation had breaking changes such as not being able to update several attributes (`first_name`, `email`, etc).

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    keycloak-admin (1.0.24)
+    keycloak-admin (1.1.1)
       http-cookie (~> 1.0, >= 1.0.3)
       rest-client (~> 2.0)
 
@@ -10,14 +10,13 @@ GEM
   specs:
     byebug (11.1.3)
     diff-lcs (1.5.0)
-    domain_name (0.5.20190701)
-      unf (>= 0.0.5, < 1.0.0)
+    domain_name (0.6.20240107)
     http-accept (1.7.0)
     http-cookie (1.0.5)
       domain_name (~> 0.5)
-    mime-types (3.4.1)
+    mime-types (3.5.2)
       mime-types-data (~> 3.2015)
-    mime-types-data (3.2023.0218.1)
+    mime-types-data (3.2023.1205)
     netrc (0.11.0)
     rest-client (2.1.0)
       http-accept (>= 1.7.0, < 2.0)
@@ -33,13 +32,10 @@ GEM
     rspec-expectations (3.12.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
-    rspec-mocks (3.12.5)
+    rspec-mocks (3.12.6)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
-    rspec-support (3.12.0)
-    unf (0.1.4)
-      unf_ext
-    unf_ext (0.0.8.2)
+    rspec-support (3.12.1)
 
 PLATFORMS
   ruby

data/README.md

@@ -21,7 +21,7 @@ To login on Keycloak's Admin API, you first need to setup a client.
 
 Go to your realm administration page and open `Clients`. Then, click on the `Create` button.
 On the first screen, enter:
-* `Client ID`: _e.g. my-app-admin-client_ 
+* `Client ID`: _e.g. my-app-admin-client_
 * `Client Protocol`: select `openid-connect`
 * `Root URL`: let it blank
 
@@ -45,7 +45,7 @@ The next screen must be configured depending on how you want to authenticate:
 * In this gem's configuration (see Section `Configuration`):
   * Setup `username` and `password` according to your user's configuration
   * Setup `client_id` with your `Client ID` (_e.g. my-app-admin-client_)
-  * If your client is `confidential`, copy its Client Secret to `client_secret` 
+  * If your client is `confidential`, copy its Client Secret to `client_secret`
 
 ### Login with `Direct Access Grants` (Service account)
 
@@ -60,15 +60,15 @@ Using a service account to use the REST Admin API does not require to create a d
   * After saving this client
     * open the `Service Account Roles` and add relevant `realm-management.` client's roles. For instance: `view-users` if you want to search for users using this gem.
     * open the `Credentials` tab and copy the `Client Secret`
-  
+
 * In this gem's configuration  (see Section `Configuration`):
   * Set `use_service_account` to `true`
   * Setup `client_id` with your `Client ID` (_e.g. my-app-admin-client_)
-  * Copy its Client Secret to `client_secret` 
+  * Copy its Client Secret to `client_secret`
 
 ## Configuration
 
-To configure this gem, call `KeycloakAdmin.configure`. 
+To configure this gem, call `KeycloakAdmin.configure`.
 For instance, to configure this gem based on environment variables, write (and load if required) a `keycloak_admin.rb`:
 ```ruby
 KeycloakAdmin.configure do |config|
@@ -96,14 +96,14 @@ All options have a default value. However, all of them can be changed in your in
 | `client_realm_name` | `""`| String | Required | Name of the realm that contains the admin client. | `master` |
 | `client_id` | `admin-cli`| String | Required | Client that should be used to access admin capabilities. | `api-cli` |
 | `client_secret` | `nil`| String | Optional | If your client is `confidential`, this parameter must be specified. | `4e3c481c-f823-4a6a-b8a7-bf8c86e3eac3` |
-| `use_service_account` | `true` | Boolean | Required | `true` if the connection to the client uses a Service Account. `false` if the connection to the client uses a username/password credential. | `false` | 
+| `use_service_account` | `true` | Boolean | Required | `true` if the connection to the client uses a Service Account. `false` if the connection to the client uses a username/password credential. | `false` |
 | `username` | `nil`| String | Optional | Username to access the Admin REST API. Recommended if `user_service_account` is set to `false`. | `mummy` |
 | `password` | `nil`| String | Optional | Clear password to access the Admin REST API. Recommended if `user_service_account` is set to `false`. | `bobby` |
 | `logger` | `Logger.new(STDOUT)`| Logger | Optional | The logger used by `keycloak-admin` | `Rails.logger` | 
 | `rest_client_options` | `{}`| Hash | Optional | Options to pass to `RestClient` | `{ verify_ssl: OpenSSL::SSL::VERIFY_NONE }` | 
 
 
-## Use Case
+## Use Cases
 
 ### Supported features
 
@@ -113,13 +113,15 @@ All options have a default value. However, all of them can be changed in your in
 * Reset credentials
 * Impersonate a user
 * Exchange a configurable token
-* Get list of clients
-* Create clients
+* Get list of clients, or find a client by its id or client_id
+* Create, update, and delete clients
 * Get list of groups, create/save a group
 * Get list of roles, save a role
 * Get list of realms, save/update/delete a realm
 * Get list of client role mappings for a user/group
 * Get list of members of a group
+* Get list of groups that have a specific role assigned
+* Get list of realm-roles assigned to a group, add a realm-role to a group
 * Save client role mappings for a user/group
 * Save realm-level role mappings for a user/group
 * Add a Group on a User
@@ -279,10 +281,26 @@ KeycloakAdmin.realm("a_realm").delete
 
 ### Get list of clients in a realm
 
-Returns an array of `KeycloakAdmin::ClientRepresentation`.
+Returns an array of `KeycloakAdmin::ClientRepresentation` or a single `KeycloakAdmin::ClientRepresentation`
+
+Finding a client by its `client_id` is a somewhat slow operation, as it requires fetching all clients and then filtering. Keycloak's API does not support fetching a client by its `client_id` directly.
 
 ```ruby
 KeycloakAdmin.realm("a_realm").clients.list
+KeycloakAdmin.realm("a_realm").clients.get(id) # id is Keycloak's database id, not the client_id
+KeycloakAdmin.realm("a_realm").clients.find_by_client_id(client_id)
+```
+
+### Updating a client
+
+```ruby
+my_client = KeycloakAdmin.realm("a_realm").clients.get(id)
+
+my_client.name        = "My new client name"
+my_client.description = "This is a new description"
+my_client.redirect_uris << "https://www.example.com/auth/callback"
+
+KeycloakAdmin.realm("a_realm").clients.update(client) # Returns the updated client
 ```
 
 ### Get list of groups in a realm
@@ -293,6 +311,22 @@ Returns an array of `KeycloakAdmin::GroupRepresentation`.
 KeycloakAdmin.realm("a_realm").groups.list
 ```
 
+### Search for a group
+
+Returns an array of `KeycloakAdmin::GroupRepresentation`.
+
+According to [the documentation](https://www.keycloak.org/docs-api/22.0.1/rest-api/index.html#_groups):
+* When providing a `String` parameter, this produces an arbitrary search string
+* When providing a `Hash`, you can specify other fields (_e.g_ q, max, first)
+
+```ruby
+KeycloakAdmin.realm("a_realm").groups.search("MyGroup")
+```
+
+```ruby
+KeycloakAdmin.realm("a_realm").groups.search({query: "MyGroup", exact: true, max: 1})
+```
+
 ### Save a group
 
 Returns the id of saved `group` provided, which must be of type `KeycloakAdmin::GroupRepresentation`.
@@ -335,6 +369,30 @@ You can specify paging with `first` and `max`:
 KeycloakAdmin.realm("a_realm").group("group_id").members(first:0, max:100)
 ```
 
+### Get list of groups that have a specific role assigned
+
+Returns an array of `KeycloakAdmin::GroupRepresentation`
+
+```ruby
+KeycloakAdmin.realm("a_realm").roles.list_groups("role_name")
+```
+
+### Get list of realm-roles assigned to a group
+
+Returns an array of `KeycloakAdmin::RoleRepresentation`
+
+```ruby
+KeycloakAdmin.realm("a_realm").groups.get_realm_level_roles("group_id")
+```
+
+### Add a realm-role to a group
+
+Returns added `KeycloakAdmin::RoleRepresentation`
+
+```ruby
+KeycloakAdmin.realm("a_realm").groups.add_realm_level_role_name!("group_id", "role_name")
+```
+
 ### Get list of roles in a realm
 
 Returns an array of `KeycloakAdmin::RoleRepresentation`.
@@ -415,4 +473,3 @@ From the `keycloak-admin-api` directory:
   $ docker build . -t keycloak-admin:test
   $ docker run -v `pwd`:/usr/src/app/ keycloak-admin:test rspec spec
 ```
-

data/bin/console

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "keycloak-admin"
+require "byebug"
+
+require "irb"
+IRB.start

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

@@ -6,6 +6,13 @@ module KeycloakAdmin
       @realm_client = realm_client
     end
 
+    def get(id)
+      response = execute_http do
+        RestClient::Resource.new(clients_url(id), @configuration.rest_client_options).get(headers)
+      end
+      ClientRepresentation.from_hash(JSON.parse(response))
+    end
+
     def save(client_representation)
       execute_http do
         RestClient::Resource.new(clients_url, @configuration.rest_client_options).post(
@@ -21,6 +28,10 @@ module KeycloakAdmin
       JSON.parse(response).map { |client_as_hash| ClientRepresentation.from_hash(client_as_hash) }
     end
 
+    def find_by_client_id(client_id)
+      list.find { |client| client.client_id == client_id }
+    end
+
     def delete(id)
       execute_http do
         RestClient::Resource.new(clients_url(id), @configuration.rest_client_options).delete(headers)
@@ -28,6 +39,16 @@ module KeycloakAdmin
       true
     end
 
+    def update(client_representation)
+      execute_http do
+        RestClient::Resource.new(clients_url(client_representation.id), @configuration.rest_client_options).put(
+          create_payload(client_representation), headers
+        )
+      end
+
+      get(client_representation.id)
+    end
+
     def get_service_account_user(client_id)
       response = execute_http do
         RestClient::Resource.new(service_account_user_url(client_id), @configuration.rest_client_options).get(headers)

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

@@ -7,8 +7,20 @@ module KeycloakAdmin
     end
 
     def list
+      search(nil)
+    end
+
+    def search(query)
+      derived_headers = case query
+                        when String
+                          headers.merge({params: { search: query }})
+                        when Hash
+                          headers.merge({params: query })
+                        else
+                          headers
+                        end
       response = execute_http do
-        RestClient::Resource.new(groups_url, @configuration.rest_client_options).get(headers)
+        RestClient::Resource.new(groups_url, @configuration.rest_client_options).get(derived_headers)
       end
       JSON.parse(response).map { |group_as_hash| GroupRepresentation.from_hash(group_as_hash) }
     end
@@ -49,6 +61,28 @@ module KeycloakAdmin
       JSON.parse(response).map { |user_as_hash| UserRepresentation.from_hash(user_as_hash) }
     end
 
+    # Gets all realm-level roles for a group
+    def get_realm_level_roles(group_id)
+      url = "#{groups_url(group_id)}/role-mappings/realm"
+      response = execute_http do
+        RestClient::Resource.new(url, @configuration.rest_client_options).get(headers)
+      end
+      JSON.parse(response).map { |role_as_hash| RoleRepresentation.from_hash(role_as_hash) }
+    end
+
+    # Adds a realm-level role to a group via the role name
+    def add_realm_level_role_name!(group_id, role_name)
+      # creates a full role-representation object needed by the keycloak api to work
+      role_representation = RoleClient.new(@configuration, @realm_client).get(role_name)
+      url = "#{groups_url(group_id)}/role-mappings/realm"
+      response = execute_http do
+        RestClient::Resource.new(url, @configuration.rest_client_options).post(
+          create_payload([role_representation]), headers
+        )
+      end
+      role_representation
+    end
+
     def groups_url(id=nil)
       if id
         "#{@realm_client.realm_admin_url}/groups/#{id}"

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

@@ -13,13 +13,26 @@ module KeycloakAdmin
       JSON.parse(response).map { |role_as_hash| RoleRepresentation.from_hash(role_as_hash) }
     end
     
+    # Returns the role representation for the specified role name
     def get(name)
+      # allows special characters in the name like space
+      name = URI.encode_uri_component(name)
       response = execute_http do
         RestClient::Resource.new(role_name_url(name), @configuration.rest_client_options).get(headers)
       end
       RoleRepresentation.from_hash JSON.parse(response)
     end
 
+    # Lists all groups that have the specified role name assigned
+    def list_groups(name)
+      # allows special characters in the name like space
+      name = URI.encode_uri_component(name)
+      response = execute_http do
+        RestClient::Resource.new("#{role_name_url(name)}/groups", @configuration.rest_client_options).get(headers)
+      end
+      JSON.parse(response).map { |role_as_hash| GroupRepresentation.from_hash(role_as_hash) }
+    end
+
     def save(role_representation)
       execute_http do
         RestClient::Resource.new(roles_url, @configuration.rest_client_options).post(

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

@@ -3,7 +3,8 @@ module KeycloakAdmin
     attr_accessor :id,
       :name,
       :composite,
-      :client_role
+      :client_role,
+      :container_id,
 
     def self.from_hash(hash)
       role             = new
@@ -11,6 +12,7 @@ module KeycloakAdmin
       role.name        = hash["name"]
       role.composite   = hash["composite"]
       role.client_role = hash["clientRole"]
+      role.container_id = hash["containerId"]
       role
     end
   end

data/lib/keycloak-admin/version.rb

@@ -1,3 +1,3 @@
 module KeycloakAdmin
-  VERSION = "1.0.24"
+  VERSION = "1.1.1"
 end

data/spec/client/client_client_spec.rb

@@ -22,6 +22,49 @@ RSpec.describe KeycloakAdmin::ClientClient do
     end
   end
 
+  describe "#get" do
+    let(:realm_name) { "valid-realm" }
+    let(:id) { "test_client_id" }
+    let(:client_name) { "test_client_name" }
+
+    before(:each) do
+      @client_client = KeycloakAdmin.realm(realm_name).clients
+
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:get).and_return '{"id":"test_client_id","name":"test_client_name"}'
+    end
+
+    it "finds a client" do
+      client = @client_client.get(id)
+      expect(client.name).to eq client_name
+      expect(client.id).to eq id
+    end
+  end
+
+  describe "#find_by_client_id" do
+    let(:realm_name) { "valid-realm" }
+    let(:client_id) { "my_client_id" }
+    let(:client_name) { "test_client_name" }
+
+    before(:each) do
+      @client_client = KeycloakAdmin.realm(realm_name).clients
+
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:get).and_return '[{"id":"test_client_id","clientId": "my_client_id","name":"test_client_name"},{"id":"test_client_id_2","clientId":"client_id_2","name":"test_client_name_2"}]'
+    end
+
+    it "finds a client it has" do
+      client = @client_client.find_by_client_id(client_id)
+      expect(client.name).to eq client_name
+      expect(client.client_id).to eq client_id
+    end
+
+    it "returns nil if it doesn't have the client" do
+      client = @client_client.find_by_client_id("client_id_3")
+      expect(client).to be_nil
+    end
+  end
+
   describe "#list" do
     let(:realm_name) { "valid-realm" }
 
@@ -51,6 +94,25 @@ RSpec.describe KeycloakAdmin::ClientClient do
     end
   end
 
+  describe "#update" do
+    let(:realm_name) { "valid-realm" }
+    let(:client) { KeycloakAdmin::ClientRepresentation.from_hash({ "id" => "test_client_id", "clientId" => "my-client", "name" => "old_name" }) }
+
+    before(:each) do
+      @client_client = KeycloakAdmin.realm(realm_name).clients
+
+      stub_token_client
+      allow_any_instance_of(RestClient::Resource).to receive(:put).and_return ''
+      allow_any_instance_of(RestClient::Resource).to receive(:get).and_return '{"id":"test_client_id", "clientId": "my-client","name":"new_name"}'
+    end
+
+    it "updates a client" do
+      updated_client = @client_client.update(client)
+
+      expect(updated_client.name).to eq "new_name"
+    end
+  end
+
   describe "#delete" do
     let(:realm_name) { "valid-realm" }
 

data/spec/representation/role_representation_spec.rb

@@ -12,7 +12,7 @@ RSpec.describe KeycloakAdmin::RoleRepresentation do
     end
 
     it "can convert to json" do
-      expect(@mapper.to_json).to eq "{\"id\":\"bb79fb10-a7b4-4728-a662-82a4de7844a3\",\"name\":\"abcd\",\"composite\":true,\"clientRole\":false}"
+      expect(@mapper.to_json).to eq "{\"id\":\"bb79fb10-a7b4-4728-a662-82a4de7844a3\",\"name\":\"abcd\",\"composite\":true,\"clientRole\":false,\"containerId\":null}"
     end
   end
 
@@ -31,7 +31,7 @@ RSpec.describe KeycloakAdmin::RoleRepresentation do
     end
 
     it "can convert to json" do
-      expect(@mappers.to_json).to eq "[{\"id\":\"bb79fb10-a7b4-4728-a662-82a4de7844a3\",\"name\":\"abcd\",\"composite\":true,\"clientRole\":false}]"
+      expect(@mappers.to_json).to eq "[{\"id\":\"bb79fb10-a7b4-4728-a662-82a4de7844a3\",\"name\":\"abcd\",\"composite\":true,\"clientRole\":false,\"containerId\":null}]"
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: keycloak-admin
 version: !ruby/object:Gem::Version
-  version: 1.0.24
+  version: 1.1.1
 platform: ruby
 authors:
 - Lorent Lempereur
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-07 00:00:00.000000000 Z
+date: 2024-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http-cookie
@@ -87,6 +87,7 @@ files:
 - Gemfile.lock
 - MIT-LICENSE
 - README.md
+- bin/console
 - keycloak-admin.gemspec
 - lib/keycloak-admin.rb
 - lib/keycloak-admin/client/attack_detection_client.rb