keycloak-admin 1.0.24 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6bc5dc390440dedbf6a682c53717e334e4f174b31e43b7990dae87bed2e0bbf
-  data.tar.gz: b37367aaa9726b48a266b55baf7fcebf772f302c18f215ad0e694d6e60421608
+  metadata.gz: 140b6a3bb680503f4bac8336250974b930535ef270f66b56b488ad78e182cd6b
+  data.tar.gz: 45c9d2ed7af63d6eaf027eebb4a6a9309d115d1fea88df9d8b4bb5c0d14ec7cc
 SHA512:
-  metadata.gz: 869a2108bbffcdc242a438a20b6d8c06fa907354e2d0648cac91920d08ba070b2bf9cc35d710f1a1fcb40691176b84b515372af540bdc7383d4835217e9ce989
-  data.tar.gz: ed68ed6de159d1d0bf87c298b49fab7fc94cc1d5f563ef25a2b56e922807ddb98b9fba69f189bc7ccc843380595afce42cc202e14b53f07fcc97f7c141145e43
+  metadata.gz: da197ebef3a7bc8fc82a95258eb684d007fbb69d48b62f6f19afd510fbbce11b30ac0c98f3b0731ebc56556311330707360a72f0505c9021d7f34d799a045534
+  data.tar.gz: e77461558697bbe7c372973673a3e58d9530720da6db2eaa76b79b1616e06ad05148cf843bd3c23a9d15a6fa55e27ac8988fccea776d593fd96e5f1130b6c0e1

data/CHANGELOG.md

@@ -5,6 +5,11 @@ 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.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.0)
       http-cookie (~> 1.0, >= 1.0.3)
       rest-client (~> 2.0)
 
@@ -15,9 +15,9 @@ GEM
     http-accept (1.7.0)
     http-cookie (1.0.5)
       domain_name (~> 0.5)
-    mime-types (3.4.1)
+    mime-types (3.5.1)
       mime-types-data (~> 3.2015)
-    mime-types-data (3.2023.0218.1)
+    mime-types-data (3.2023.0808)
     netrc (0.11.0)
     rest-client (2.1.0)
       http-accept (>= 1.7.0, < 2.0)
@@ -33,10 +33,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)
+    rspec-support (3.12.1)
     unf (0.1.4)
       unf_ext
     unf_ext (0.0.8.2)

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,8 +113,8 @@ 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
@@ -279,10 +279,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 +309,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`.
@@ -415,4 +447,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

data/lib/keycloak-admin/version.rb

@@ -1,3 +1,3 @@
 module KeycloakAdmin
-  VERSION = "1.0.24"
+  VERSION = "1.1.0"
 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" }
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: keycloak-admin
 version: !ruby/object:Gem::Version
-  version: 1.0.24
+  version: 1.1.0
 platform: ruby
 authors:
 - Lorent Lempereur
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-07 00:00:00.000000000 Z
+date: 2023-10-03 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