keycloak-admin 0.7.3 → 0.7.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8dc193e7b260cc860b03a8eaaa53180fc6944e71
-  data.tar.gz: 229097dbd02866fa93fa51b834b39dcfba7a97a9
+SHA256:
+  metadata.gz: b7d17b8a5f55e87b615da11c9554bfeec127629207e81bd4e4950fb85971010c
+  data.tar.gz: '097affd8e18b7e778557fe4ecc787e93127bcef133a4dd9e6db590fc7ad65982'
 SHA512:
-  metadata.gz: 084c52d8b2cdd9a38d68f01c1bba6db6ab6d0735efdef1a6d61af31fb248a1ce6d72d2b50e5bf8487edb60d6846d3b15fbdcb3e850202b5413632a26b83d1c50
-  data.tar.gz: 588b84ec13efd6538998bba3d0d7422bf3abdd03525f40e0860e84bc675afd7acd0856f0876f44d11cdb0c5bd2e1528df3c76e6b861ffbfa8c01e7f973d0571d
+  metadata.gz: ffc55b0f6c7719ce1fa38b93838fe2d137fe3cd6395fe1717ac4ef352484bdfedab0363811f88bf9e82815d1ae6f94ec008ab1fb4db5038f638cc816d66362fd
+  data.tar.gz: b8053bb57699928d793523b9d0274a284ebafbedd8e05d8294fbcdebcca967d69531dddf2048fd890b8e51dc3bb9bea2c83a9aee19e34bac13fccbed95a547b7

data/CHANGELOG.md

@@ -5,9 +5,33 @@ 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).
 
+## [0.7.8] - 2020-10-15
+
+* Bug: `rest_client_options` default value does not match the documentation (was `nil` by default, should be `{}`)
+* Update documentation about client setup (based on Keycloak 11)
+
+## [0.7.7] - 2020-07-10
+
+* Fix: `Replace request method shorthand with .execute for proper RestClient option support` (thanks to @RomanHargrave)
+* When sending action emails, add lifespan as an optional parameter (thanks to @hobbypunk90)
+
+## [0.7.6] - 2020-06-22
+
+Thanks to @hobbypunk90 
+* Support for action emails and send forgot passsword mail 
+
+## [0.7.5] - 2020-03-28
+
+Thanks to @RomanHargrave
+* Support for working with federated identity provider (broker) links
+
+## [0.7.4] - 2019-10-17
+
+* Support for Rails 6
+
 ## [0.7.3] - 2019-07-11
 
-Thanks to @cederigo=
+Thanks to @cederigo:
 * For a given user, get her list of groups
 
 ## [0.7.2] - 2019-06-17

data/Dockerfile

@@ -1,4 +1,4 @@
-FROM ruby:2.3
+FROM ruby:2.6.5
 RUN mkdir -p /usr/src/app/lib/keycloak-admin
 WORKDIR /usr/src/app
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    keycloak-admin (0.7.3)
+    keycloak-admin (0.7.8)
       http-cookie (~> 1.0, >= 1.0.3)
       rest-client (~> 2.0)
 
@@ -12,13 +12,15 @@ GEM
     diff-lcs (1.3)
     domain_name (0.5.20190701)
       unf (>= 0.0.5, < 1.0.0)
+    http-accept (1.7.0)
     http-cookie (1.0.3)
       domain_name (~> 0.5)
-    mime-types (3.2.2)
+    mime-types (3.3.1)
       mime-types-data (~> 3.2015)
-    mime-types-data (3.2019.0331)
+    mime-types-data (3.2020.0512)
     netrc (0.11.0)
-    rest-client (2.0.2)
+    rest-client (2.1.0)
+      http-accept (>= 1.7.0, < 2.0)
       http-cookie (>= 1.0.2, < 2.0)
       mime-types (>= 1.16, < 4.0)
       netrc (~> 0.8)
@@ -37,7 +39,7 @@ GEM
     rspec-support (3.7.0)
     unf (0.1.4)
       unf_ext
-    unf_ext (0.0.7.6)
+    unf_ext (0.0.7.7)
 
 PLATFORMS
   ruby

data/README.md

@@ -12,37 +12,59 @@ This gem *does not* require Rails.
 For example, using `bundle`, add this line to your Gemfile.
 
 ```ruby
-gem "keycloak-admin", "0.7.3"
+gem "keycloak-admin", "0.7.8"
 ```
 
 ## Login
 
-You can choose your login process between two different login methods: `username/password` and `Account Service`.
-
-### Login with username/password
-
-Using this login method requires to create a user (and her credentials).
-* In Keycloak 
-  * Make your client `confidential` or `public`
-  * Do not check `Service Accounts Enabled`
-* In this gem's configuration
-  * Set `use_service_account` to `false`
-  * Setup `username` and `password`
-  * Setup `client_secret` if your client is `confidential`
-
-### Login with an Account Service
-
-Using a service account to use the REST Admin API does not require to create a dedicated user (http://www.keycloak.org/docs/2.5/server_admin/topics/clients/oidc/service-accounts.html).
-
-* In Keycloak 
-  * Make your client `confidential`
-  * Check its toggle `Service Accounts Enabled`
-  * Disable both `Standard Flow Enabled` and `Implicit Flow Enabled `
-  * Enable `Direct Access Grants Enabled`
-  * 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.
-* In this gem's configuration
+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 Protocol`: select `openid-connect`
+* `Root URL`: let it blank
+
+The next screen must be configured depending on how you want to authenticate:
+* `username/password` with a user of the realm
+* `Direct Access Grants` with a service account
+
+### Login with username/password (realm user)
+
+* In Keycloak, during the client setup:
+  * `Access Type`: `public` or `confidential`
+  * `Service Accounts Enabled` (when `confidential`): `false`
+  * After saving your client, if you have chosen a `confidential` client, go to `Credentials` tab and copy the `Client Secret`
+
+* In Keycloak, create a dedicated user (and her credentials):
+  * Go to `Users`
+  * Click on the `Add user` button
+  * Setup her mandatory information, depending on your realm's configuration
+  * On the `Credentials` tab, create her a password (toggle off `Temporary`)
+
+* 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` 
+
+### Login with `Direct Access Grants` (Service account)
+
+Using a service account to use the REST Admin API does not require to create a dedicated user (https://www.keycloak.org/docs/latest/server_admin/#_service_accounts).
+
+* In Keycloak, during the client setup:
+  * `Access Type`:  `confidential`
+  * `Service Accounts Enabled` (when `confidential`): `true`
+  * `Standard Flow Enabled`: `false`
+  * `Implicit Flow Enabled`: `false`
+  * `Direct Access Grants Enabled`: `true`
+  * 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_secret`
+  * Setup `client_id` with your `Client ID` (_e.g. my-app-admin-client_)
+  * Copy its Client Secret to `client_secret` 
 
 ## Configuration
 
@@ -97,6 +119,9 @@ All options have a default value. However, all of them can be changed in your in
 * Get list of client role mappings for a user/group
 * Save client role mappings for a user/group
 * Save realm-level role mappings for a user/group
+* Link/Unlink users to federated identity provider brokers
+* Execute actions emails
+* Send forgot passsword mail
 
 ### Get an access token
 
@@ -340,8 +365,4 @@ From the `keycloak-admin-api` directory:
 ```
   $ docker build . -t keycloak-admin:test
   $ docker run -v `pwd`:/usr/src/app/ keycloak-admin:test bundle exec rspec spec
-```
-
-## Future work
-
-* Allow authentication using JWT assertions
+```

data/lib/keycloak-admin.rb

@@ -21,6 +21,7 @@ require_relative "keycloak-admin/representation/impersonation_representation"
 require_relative "keycloak-admin/representation/credential_representation"
 require_relative "keycloak-admin/representation/realm_representation"
 require_relative "keycloak-admin/representation/role_representation"
+require_relative "keycloak-admin/representation/federated_identity_representation"
 require_relative "keycloak-admin/representation/user_representation"
 require_relative "keycloak-admin/resource/base_role_containing_resource"
 require_relative "keycloak-admin/resource/group_resource"
@@ -54,7 +55,7 @@ module KeycloakAdmin
       config.use_service_account = true
       config.username            = nil
       config.password            = nil
-      config.rest_client_options = nil
+      config.rest_client_options = {}
     end
   end
 

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

@@ -16,13 +16,18 @@ module KeycloakAdmin
 
     def exchange_with(user_access_token, token_lifespan_in_seconds)
       response = execute_http do
-        RestClient.post(token_url, {
-          tokenLifespanInSeconds: token_lifespan_in_seconds
-        }.to_json, {
-          Authorization: "Bearer #{user_access_token}",
-          content_type:  :json,
-          accept:        :json
-        })
+        RestClient::Request.execute(
+          @configuration.rest_client_options.merge(
+            method: :post,
+            url: token_url,
+            payload: { tokenLifespanInSeconds: token_lifespan_in_seconds }.to_json,
+            headers: {
+              Authorization: "Bearer #{user_access_token}",
+              content_type: :json,
+              accept: :json
+            }
+          )
+        )
       end
       TokenRepresentation.from_json(response.body)
     end

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

@@ -21,7 +21,14 @@ module KeycloakAdmin
     end
 
     def update(user_id, user_representation_body)
-      RestClient.put(users_url(user_id), user_representation_body.to_json, headers)
+      RestClient::Request.execute(
+        @configuration.rest_client_options.merge(
+          method: :put,
+          url: users_url(user_id),
+          payload: user_representation_body.to_json,
+          headers: headers
+        )
+      )
     end
 
     def get(user_id)
@@ -59,11 +66,26 @@ module KeycloakAdmin
 
     def update_password(user_id, new_password)
       execute_http do
-        RestClient.put(reset_password_url(user_id), {
-          type: "password",
-          value: new_password,
-          temporary: false
-        }.to_json, headers)
+        RestClient::Request.execute(
+          @configuration.rest_client_options.merge(
+            method: :put,
+            url: reset_password_url(user_id),
+            payload: { type: 'password', value: new_password, temporary: false }.to_json,
+            headers: headers
+          )
+        )
+      end
+      user_id
+    end
+
+    def forgot_password(user_id, lifespan=nil)
+      execute_actions_email(user_id, ["UPDATE_PASSWORD"], lifespan)
+    end
+
+    def execute_actions_email(user_id, actions=[], lifespan=nil)
+      execute_http do
+        lifespan_param = lifespan.nil? ? "" : "lifespan=#{lifespan.seconds}"
+        RestClient.put("#{execute_actions_email_url(user_id)}?#{lifespan_param}", actions.to_json, headers)
       end
       user_id
     end
@@ -71,7 +93,14 @@ module KeycloakAdmin
     def impersonate(user_id)
       impersonation = get_redirect_impersonation(user_id)
       response = execute_http do
-        RestClient.post(impersonation.impersonation_url, impersonation.body.to_json, impersonation.headers)
+        RestClient::Request.execute(
+          @configuration.rest_client_options.merge(
+            method: :post,
+            url: impersonation.impersonation_url,
+            payload: impersonation.body.to_json,
+            headers: impersonation.headers
+          )
+        )
       end
       ImpersonationRepresentation.from_response(response, @configuration.server_domain)
     end
@@ -80,6 +109,30 @@ module KeycloakAdmin
       ImpersonationRedirectionRepresentation.from_url(impersonation_url(user_id), headers)
     end
 
+    def link_idp(user_id, idp_id, idp_user_id, idp_username)
+      fed_id_rep                   = FederatedIdentityRepresentation.new
+      fed_id_rep.user_id           = idp_user_id
+      fed_id_rep.user_name         = idp_username
+      fed_id_rep.identity_provider = idp_id
+
+      execute_http do
+        RestClient::Request.execute(
+          @configuration.rest_client_options.merge(
+            method: :post,
+            url: federated_identity_url(user_id, idp_id),
+            payload: fed_id_rep.to_json,
+            headers: headers
+          )
+        )
+      end
+    end
+
+    def unlink_idp(user_id, idp_id)
+      execute_http do
+        RestClient::Resource.new(federated_identity_url(user_id, idp_id), @configuration.rest_client_options).delete(headers)
+      end
+    end
+
     def users_url(id=nil)
       if id
         "#{@realm_client.realm_admin_url}/users/#{id}"
@@ -93,6 +146,11 @@ module KeycloakAdmin
       "#{users_url(user_id)}/reset-password"
     end
 
+    def execute_actions_email_url(user_id)
+      raise ArgumentError.new("user_id must be defined") if user_id.nil?
+      "#{users_url(user_id)}/execute-actions-email"
+    end
+
     def groups_url(user_id)
       raise ArgumentError.new("user_id must be defined") if user_id.nil?
       "#{users_url(user_id)}/groups"
@@ -103,6 +161,12 @@ module KeycloakAdmin
       "#{users_url(user_id)}/impersonation"
     end
 
+    def federated_identity_url(user_id, identity_provider)
+      raise ArgumentError.new("user_id must be defined") if user_id.nil?
+      raise ArgumentError.new("identity_provider must be defined") if identity_provider.nil?
+      "#{users_url(user_id)}/federated-identity/#{identity_provider}"
+    end
+
     private
 
     def build(username, email, password, email_verified, locale)

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

@@ -0,0 +1,15 @@
+module KeycloakAdmin
+  class FederatedIdentityRepresentation < Representation
+    attr_accessor :identity_provider,
+      :user_id,
+      :user_name
+
+    def self.from_hash(hash)
+      rep                   = new
+      rep.identity_provider = hash['identityProvider']
+      rep.user_id           = hash['userId']
+      rep.user_name         = hash['userName']
+      rep
+    end
+  end
+end

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

@@ -4,12 +4,12 @@ require_relative "camel_json"
 class Representation
   include ::KeycloakAdmin::CamelJson
 
-  def as_json
+  def as_json(options=nil)
     Hash[instance_variables.map { |ivar| [ivar.to_s[1..-1], instance_variable_get(ivar)] }]
   end
 
   def to_json(options=nil)
-    snaked_hash = as_json
+    snaked_hash = as_json(options)
     snaked_hash.keys.reduce({}) do |camelized_hash, key|
       camelized_hash[camelize(key, false)] = snaked_hash[key]
       camelized_hash

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

@@ -10,21 +10,23 @@ module KeycloakAdmin
       :email_verified,
       :first_name,
       :last_name,
-      :credentials
+      :credentials,
+      :federated_identities
 
     def self.from_hash(hash)
-      user                   = new
-      user.id                = hash["id"]
-      user.created_timestamp = hash["createdTimestamp"]
-      user.origin            = hash["origin"]
-      user.username          = hash["username"]
-      user.email             = hash["email"]
-      user.enabled           = hash["enabled"]
-      user.email_verified    = hash["emailVerified"]
-      user.first_name        = hash["firstName"]
-      user.last_name         = hash["lastName"]
-      user.attributes        = hash["attributes"]
-      user.credentials       = hash["credentials"]&.map{ |hash| CredentialRepresentation.from_hash(hash) } || []
+      user                      = new
+      user.id                   = hash["id"]
+      user.created_timestamp    = hash["createdTimestamp"]
+      user.origin               = hash["origin"]
+      user.username             = hash["username"]
+      user.email                = hash["email"]
+      user.enabled              = hash["enabled"]
+      user.email_verified       = hash["emailVerified"]
+      user.first_name           = hash["firstName"]
+      user.last_name            = hash["lastName"]
+      user.attributes           = hash["attributes"]
+      user.credentials          = hash["credentials"]&.map{ |hash| CredentialRepresentation.from_hash(hash) } || []
+      user.federated_identities = hash["federatedIdentities"]&.map { |hash| FederatedIdentityRepresentation.from_hash(hash) } || []
       user
     end
 
@@ -32,5 +34,10 @@ module KeycloakAdmin
       @credentials ||= []
       @credentials.push(credential_representation)
     end
+
+    def add_federated_identity(federated_identity_representation)
+      @federated_identities ||= []
+      @federated_identities.push(federated_identity_representation)
+    end
   end
 end

data/lib/keycloak-admin/version.rb

@@ -1,3 +1,3 @@
 module KeycloakAdmin
-  VERSION = "0.7.3"
+  VERSION = "0.7.8"
 end

data/spec/client/user_client_spec.rb

@@ -72,6 +72,31 @@ RSpec.describe KeycloakAdmin::TokenClient do
     end
   end
 
+  describe "#execute_actions_email_url" do
+    let(:realm_name) { "valid-realm" }
+    let(:user_id)    { nil }
+
+    before(:each) do
+      @client = KeycloakAdmin.realm(realm_name).users
+    end
+
+    context "when user_id is not defined" do
+      let(:user_id) { nil }
+      it "raises an error" do
+        expect {
+          @client.execute_actions_email_url(user_id)
+        }.to raise_error(ArgumentError)
+      end
+    end
+
+    context "when user_id is defined" do
+      let(:user_id) { 42 }
+      it "return a proper url" do
+        expect(@client.execute_actions_email_url(user_id)).to eq "http://auth.service.io/auth/admin/realms/valid-realm/users/42/execute-actions-email"
+      end
+    end
+  end
+
   describe "#impersonation_url" do
     let(:realm_name) { "valid-realm" }
     let(:user_id)    { nil }

data/spec/representation/user_representation_spec.rb

@@ -9,7 +9,7 @@ RSpec.describe KeycloakAdmin::UserRepresentation do
     end
 
     it "can convert to json" do
-      expect(@user.to_json).to eq '{"id":null,"createdTimestamp":1559836000,"origin":null,"username":"test_username","email":null,"enabled":true,"emailVerified":null,"firstName":null,"lastName":null,"attributes":null,"credentials":[]}'
+      expect(@user.to_json).to eq '{"id":null,"createdTimestamp":1559836000,"origin":null,"username":"test_username","email":null,"enabled":true,"emailVerified":null,"firstName":null,"lastName":null,"attributes":null,"credentials":[],"federatedIdentities":[]}'
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: keycloak-admin
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.7.8
 platform: ruby
 authors:
 - Lorent Lempereur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-11 00:00:00.000000000 Z
+date: 2020-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http-cookie
@@ -103,6 +103,7 @@ files:
 - lib/keycloak-admin/representation/camel_json.rb
 - lib/keycloak-admin/representation/client_representation.rb
 - lib/keycloak-admin/representation/credential_representation.rb
+- lib/keycloak-admin/representation/federated_identity_representation.rb
 - lib/keycloak-admin/representation/group_representation.rb
 - lib/keycloak-admin/representation/impersonation_redirection_representation.rb
 - lib/keycloak-admin/representation/impersonation_representation.rb
@@ -150,8 +151,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.4
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Keycloak Admin REST API client written in Ruby