README.md

Keycloak

• pt-BR translation

Keycloak gem was developed to integrate applications and services into Red Hat's Keycloak system for user control, authentication, authorization, and session management.

Its development was based on version 3.2 of Keycloak, whose documentation can be found here.

Publication of gem: https://rubygems.org/gems/keycloak

Exemple: https://github.com/imagov/example-gem-keycloak

Installation

Add this line in your application's gemfile:

gem 'keycloak'

Install the gem by running:

$ bundle install

Or install it yourself:

$ gem install keycloak

To add the configuration file:

$ rails generate keycloak:config

Use

Since you already have a Keycloak environment configured and the gem already installed, the next step is to define how the application will authenticate. Keycloak works with key authentication protocols, such as OpenID Connect, Oauth 2.0 and SAML 2.0, integrating system access through Single-Sign On, and can also provide access to LDAP or Active Directory users.

When you register a realm and also a Client in your Keycloak environment, you can download the Client installation file into the config folder of the application so that gem gets the information it needs to interact with Keycloak. To download this, simply access your Client's registry, click the Installation tab, select Keycloak OIDC JSON in the Format option field and click Download. If your application does not only work with a specific client (application server for APIs, for example), then you can tell what is the realm that gem will interact in the keycloak.rb configuration file.

Gem has a main module called Keycloak. Within this module there are three other modules: Client, Admin and Internal.

Module Keycloak

The Keycloak module has some attributes and its definitions are fundamental for the perfect functioning of the gem in the application.

Keycloak.installation_file = 'path/to/file.json'

Allows you to set the location of installation file if you have one. If not set, it will default to keycloak.json in the config folder of your repository. In any case, it will use installation file only if it's present.

Keycloak.realm

If your application does not only work with a specific client (application server for APIs, for example), then you can tell the realm name that gem will interact in that attribute. When installed, gem creates the keycloak.rb file in config / initializers. This attribute can be found and defined in this file.

Keycloak.auth_server_url

For the same scenario as the above attribute, you can tell the url of the realm that the gem will interact in that attribute. When installed, gem creates the keycloak.rb file in config / initializers. This attribute can be found and defined in this file.

Keycloak.proxy

If the environment where your application will be used requires the use of proxy for the consumption of the Keycloak APIs, then define it in this attribute. When it is installed, gem creates the keycloak.rb file in config/initializers. This attribute can be found and defined in this file.

Keycloak.generate_request_exception

This attribute is to define whether the HTTP exceptions generated in the returns of the requests made to Keycloak will or will not burst in the application. If set to false, then the exception will not be blown and the HTTP response will be returned to the application to do its own processing. The default value of this attribute is true. When it is installed, gem creates the keycloak.rb file in config/initializers. This attribute can be found and defined in this file.

Keycloak.keycloak_controller

It is recommended that your application has a controller that centralizes the session actions that Keycloak will manage, such as login action, logout, session update, password reset, among others. Define in this attribute what is the name of the controller that will play this role. If your controller name is SessionController, then the value of this attribute should be session only. When it is installed, gem creates the keycloak.rb file in config/initializers. This attribute can be found and defined in this file.

Keycloak.proc_cookie_token

This attribute is an anonymous method (lambda). The same must be implemented in the application so that the gem has access to the authentication token which, in turn, must be stored in the cookie. When performing the keycloak authentication through gem, the system must store the token returned in the browser cookie, such as:

cookies.permanent[:keycloak_token] = Keycloak::Client.get_token(params[:user_login], params[:user_password])

The application can retrieve the token in the cookie by implementing the Keycloak.proc_cookie_token method as follows:

Keycloak.proc_cookie_token = -> do
  cookies.permanent[:keycloak_token]
end

This way, every time gem needs to use the token information to consume a Keycloak service, it will invoke this lambda method.

Keycloak.proc_external_attributes

Keycloak gives the possibility that new attributes are mapped to the user registry. However, when these attributes are application specific, it is recommended that you manage them yourself. To do this, the best solution is to create these attributes in the application - example: create a table in the database of the application itself containing the columns representing each of the attributes, also inserting in this table a unique key column, same as the User Id created in Keycloak, indicating that the one belonging to that Id has those attributes. In order for gem to have access to these attributes, set the Keycloak.proc_external_attributes attribute to a lambda method by obtaining the attributes of the logged-in user. Example:

Keycloak.proc_external_attributes = -> do
  attribute = UsuariosAtributo.find_or_create_by(user_keycloak_id: Keycloak::Client.get_attribute('sub'))
  if attribute.status.nil?
    attribute.status = false
    attribute.save
  end
  attribute
end

Note: The Keycloak.proc_cookie_token and Keycloak.proc_external_attributes attributes can be defined in the initialize of the controller ApplicationController.

Keycloak.validate_token_when_call_has_role

The introspect of the token will be executed every time the Keycloak::Client.has_role? method is invoked, if this setting is set to true.

Keycloak::Client

The Keycloak::Client module has the methods that represent the endpoint services. These services are fundamental for creating and updating tokens, logging in and logout, and also for obtaining the synthetic information of a logged in user. What enables gem to make use of all these services is the previously mentioned client installation file.

We will detail each of these methods:

Keycloak::Client.get_token(user, password, client_id = '', secret = '')

If you choose to authenticate users using the screen of your own application, then use this method. Simply invoke it in the method of login in the controller defined with the session controller of your application, passing as parameter the user and the password informed by the user. If the authentication is valid, then a JSON containing the access_token and the refresh_token is returned.

Keycloak::Client.url_login_redirect(redirect_uri, response_type = 'code')

To authenticate the users of your application using a template configured in Keycloak, redirect the request to the url returned in this method. Pass as a parameter the url that the user will have access in case of successful authentication (redirect_uri) and also the type of response (response_type), which if not informed, gem will assume the code value. If the authentication is successful, then a code will be returned that will enable you to request a token from Keycloak.

Keycloak::Client.get_token_by_code(code, redirect_uri, client_id = '', secret = '')

When using the Keycloak::Client.url_login_redirect method to get a code, pass it as a parameter in this method so that Keycloak returns a token, thus logging the user in the application. The second parameter (redirect_uri) must be the same one used in the call for Keycloak::Client.url_login_redirect(redirect_uri, response_type = 'code').

If redirect_uri are not equal on both calls, Keycloak::Client.url_login_redirect and Keycloak::Client.get_token_by_code you will receive the following error: {"error":"invalid_grant","error_description":"Incorrect redirect_uri"}

Keycloak::Client.get_token_by_exchange(issuer, issuer_token, client_id = '', secret = '')

To get a token through a token previously obtained from a trusted provider (OpenID standard), such as Facebook, Gooble, Twitter, or even another realm configured in the keycloak, simply invoke this method, passing in the issuer parameter the provider alias configured in the realm, and in the issuer_token parameter the token obtained by that provider. This will return a token authenticated by your realm.

Keycloak::Client.get_userinfo_issuer(access_token = '', userinfo_endpoint = '')

This method returns the user information of a provider (issuer of the get_token_by_exchange method represented by the access_token passed as parameter. If the access_token parameter is not informed, then the gem will get this information in the cookie.

Keycloak::Client.get_token_by_refresh_token(refresh_token = '', client_id = '', secret = '')

When the user is already logged in and your application internally tracks the token expiration time provided by Keycloak, then this method can be used to renew that token if it is still valid. To do this, simply pass the refresh_token as a parameter. If you do not inform refresh_token, gem will use the refresh_token stored in the cookie.

Keycloak::Client.get_token_introspection(token = '', client_id = '', secret = '', token_introspection_endpoint = '')

This method returns the information from the token session passed as parameter. Among the information returned, the most important is the active field, since it informs whether the token session passed in the parameter is active or not. This will help your application control whether the logged-in user session has expired or not. If no token is passed as a parameter, gem will use the last access_token stored in the application's cookie.

Keycloak::Client.get_token_by_client_credentials(client_id = '', secret = '')

There are some Keycloak services like password reset, user registration in the initial screen of the application or even authentication following the standard OAuth 2.0, that the authentication of a user becomes unnecessary. Therefore, we can obtain a token using the credentials of its own application (Client) registered in Keycloak. To obtain this token, pass the client_id - informed by the person who registered your application in Keycloak - and the secret of your application generated by Keycloak - to generate a secret, the Access Type of your Client must be configured as confidential. If you do not pass any of these parameters, gem will use the credentials contained in the installation file mentioned above.

Keycloak::Client.logout(redirect_uri = '', refresh_token = '', client_id = '', secret = '', end_session_endpoint = '')

When used before the expiration of the logged on user's session, this method terminates the session. If the redirect_uri parameter is fed, then Keycloak will redirect your application to the url informed after logout. The second parameter is refresh_token, obtained at the time of authentication or session update. If the latter is not informed, then the gem will use the refresh_token of the cookie

Keycloak::Client.get_userinfo(access_token = '', userinfo_endpoint = '')

This method returns synthetic information from the user represented by the access_token passed as a parameter, such as sub - which is the authenticated user id -, preferred_username - which is the authenticated user name - and email - which is the user's email address. If the access_token parameter is not informed, then the gem will get this information in the cookie.

Keycloak::Client.url_user_account

Returns the url for access to the realm user registry of the installation file (keycloak.json). To access the screen, Keycloak will require user authentication. After connected, and if has permission, the user will have access to his own personal information and could even change them.

Keycloak::Client.has_role?(user_role, access_token = '', client_id = '', secret = '', token_introspection_endpoint = '')

The has_role? method decodes the JWT access_token and verifies that the user who owns the token has the role informed in the user_role parameter. If access_token is not informed then gem will use the access_token of the cookie.

Keycloak::Client.user_signed_in?(access_token = '', client_id = '', secret = '', token_introspection_endpoint = '')

This method checks whether the access_token passed in the parameter is still active. To check whether the user is active or not, the gem invokes the get_token_introspection method internally. If access_token is not informed then gem will use the access_token of the cookie.

Keycloak::Client.get_attribute(attribute_name, access_token = '')

This method decodes the JWT access_token and returns the value of the name attribute passed in the attribute_name parameter. This attribute can be a mapper - registered in the Mappers section of the Realm Client registry. If access_token is not informed then gem will use the access_token of the cookie.

Keycloak::Client.token

Returns the last authenticated token stored in the cookie. When the Keycloak.proc_cookie_token method is implemented in the application and a user authenticates the application, this method returns the token of that user.

Keycloak::Client.external_attributes

When the Keycloak.proc_external_attributes method is implemented, the external_attributes method returns it. The purpose of this method is to return the application-specific attributes not mapped in Keycloak.

Keycloak::Admin

The Keycloak :: Admin module provides methods that represent the REST APIs do Keycloak. In order to use these APIs, an active access_token is required, that is, authentication must occur before using the methods for a valid token to be used as a credential. If access_token is not informed then gem will use the access_token of the cookie. The authenticated user must have the role of the respective service invoked - roles of the realm-management client, which represents the management of the realm.

The list of methods is shown below. The {realm} route parameter of all APIs will be obtained from the keycloak.json installation file:

# GET /admin/realms/{realm}/users
Keycloak::Admin.get_users(query_parameters = nil, access_token = nil)

get_users returns a list of users, filtered according to the parameters hash passed in query_parameters.

# POST /admin/realms/{realm}/users
Keycloak::Admin.create_user(user_representation, access_token = nil)

create_user creates a new user in Keycloak. The user_representation parameter must be a hash according to Keycloak UserRepresentation. The return of this method will be true for success.

# GET /admin/realms/{realm}/users/count
Keycloak::Admin.count_users(access_token = nil)

count_users returns the number of users in the realm.

# GET /admin/realms/{realm}/users/{id}
Keycloak::Admin.get_user(id, access_token = nil)

get_user returns the user representation identified by the id parameter - which is the ID created by Keycloak when creating a new user.

# PUT /admin/realms/{realm}/users/{id}
Keycloak::Admin.update_user(id, user_representation, access_token = nil)

update_user updates the user registry identified by id - which is the ID created by Keycloak when creating a new user. In the user_representation parameter should be a hash with the fields that will be changed, respecting the UserRepresentation of Keycloak. The return of this method will be true for success.

# DELETE /admin/realms/{realm}/users/{id}
Keycloak::Admin.delete_user(id, access_token = nil)

delete_user excludes the user ID identified by the id - which is the ID created by Keycloak when creating a new user. The return of this method will be true for success.

# DELETE /admin/realms/{realm}/users/{id}/consents/{client}
Keycloak::Admin.revoke_consent_user(id, client_id = nil, access_token = nil)

revoke_consent_user revokes the tokens of a user identified by id - which is the ID created by Keycloak when creating a new user - on the client identified by the client_id parameter.

# PUT /admin/realms/{realm}/users/{id}/execute-actions-email
Keycloak::Admin.update_account_email(id, actions, redirect_uri = '', client_id = nil, access_token = nil)

update_account_email sends an account update email to the user represented by the id parameter. The email contains a link that the user can click to execute a set of actions represented by the actions parameter - which awaits an array of actions defined by Keycloak. An example value that can be passed to the actions parameter is ['UPDATE_PASSWORD'], which indicates that the action that the user must take when clicking the link in the email is to change their password. In the redirect_uri parameter, if necessary, a url must be passed so that, at the end of sending the e-mail, the application is redirected. The client_id parameter should be informed if the Client responsible for the actions to be performed is not the same as the keycloak.json installation file.

# GET /admin/realms/{realm}/users/{id}/role-mappings
Keycloak::Admin.get_role_mappings(id, access_token = nil)

get_role_mappings returns all Role Mappings in the realm assigned to the user identified by the id parameter, regardless of the Client.

# GET /admin/realms/{realm}/groups
Keycloak::Admin.get_groups(query_parameters = nil, access_token = nil)

get_groups returns a list of GroupRepresentation for the realm. The optional query_parameters parameter expects a hash with properties matching any of the query parameters accepted by the API.

# GET /admin/realms/{realm}/clients
Keycloak::Admin.get_clients(query_parameters = nil, access_token = nil)

get_clients returns a list of ClientRepresentation pertaining to the realm. The query_parameters parameter expects a hash with clientId attributes - if you want the list to be filtered by client_id - and viewableOnly - to filter whether the Keycloak Administration Clients will be returned in the list.

# GET /admin/realms/{realm}/clients/{id}/roles
Keycloak::Admin.get_all_roles_client(id, access_token = nil)

get_all_roles_client returns a RoleRepresentation list with all client roles identified by the id parameter - this parameter must be passed in the ID of the Clint and not client_id.

# GET /admin/realms/{realm}/clients/{id}/roles/{role-name}
Keycloak::Admin.get_roles_client_by_name(id, role_name, access_token = nil)

get_roles_client_by_name returns the RoleRepresentation of the role identified by the parameter role_name - which is the name of the role.

# POST /admin/realms/{realm}/users/{id}/role-mappings/clients/{client}
Keycloak::Admin.add_client_level_roles_to_user(id, client, role_representation, access_token = nil)

add_client_level_roles_to_user inserts a role from the Client (represented by the client parameter) to the user represented by the id parameter. The role_representation parameter should receive an array of RoleRepresentation that will be entered into the user. On success, the return will be true.

# DELETE /admin/realms/{realm}/users/{id}/role-mappings/clients/{client}
Keycloak::Admin.delete_client_level_roles_from_user(id, client, role_representation, access_token = nil)

delete_client_level_roles_from_user deletes a Client-Role (representado pelo parâmetro client) of the user represented by the id parameter. The role_representation parameter should receive an array of RoleRepresentation that will be removed on the user. On success, the return will be true.

# GET /admin/realms/{realm}/users/{id}/role-mappings/clients/{client}
Keycloak::Admin.get_client_level_role_for_user_and_app(id, client, access_token = nil)

get_client_level_role_for_user_and_app return a list of RoleRepresentation of client Client-Roles, represented by client parameter linked to the user represented by the id parameter.

Keycloak::Admin.update_effective_user_roles(id, client_id, roles_names, access_token = nil)

update_effective_user_roles is not on the Keycloak Admin APIs list. This method binds to the user represented by the id parameter all the roles passed in an array in the roles_names parameter. The roles passed in the roles_names parameter must belong to the Client represented by the client_id parameter. If the user has the link with a role that is not in the roles_names parameter, this link will be removed because the purpose of this method is for the user to effectively assume the roles passed in this parameter. On success, the return will be true.

PUT /admin/realms/{realm}/users/{id}/reset-password
Keycloak::Admin.reset_password(id, credential_representation, access_token = nil)

reset_password change the user password represented by id parameter. The new password is represented by credential_representation parameter, which is a set of information formatted under the CredentialRepresentation section of the Keycloak API manual.

GET /admin/realms/{realm}/groups/{id}/role-mappings/clients/{client}/composite
Keycloak::Admin.get_effective_client_level_role_composite_user(id, client, access_token = nil)

get_effective_client_level_role_composite_user return a list (array) of RoleRepresentation of a Group represented by id parameter attached to a Client represented by client parameter.

If there is any service in the manual Keycloak Admin REST API that has not been implemented in this gem, there is a possibility of being invoked using the Generics Methods of the Keycloak::Admin model. The Generics Methods allow you to request any of the APIs, either GET, POST, PUT or DELETE, passing the request parameters as hashes in the parameters query_parameters and body_parameter of the Generics Methods.
The following are the Generics Methods:

Keycloak::Admin.generic_get(service, query_parameters = nil, access_token = nil)

generic_get allows you to make Keycloak GET service requests. The part of the URI that identifies the service must be passed in the service parameter, already with the route parameters (such as {client}, for example) properly replaced. In the query_parameters parameter you can pass a hash containing the Queries Parameters of the request.
Example:

    Keycloak::Admin.generic_get("users/", {email: 'admin@test.com'}, "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldU...")

Keycloak::Admin.generic_post(service, query_parameters, body_parameter, access_token = nil)

generic_post allows you to make Keycloak POST service requests. The part of the URI that identifies the service must be passed in the service parameter, already with the route parameters (such as {client}, for example) properly replaced. In the query_parameters parameter you can pass a hash containing the Query Parameters of the request. In the body_parameter parameter you can pass a hash containing the Body Parameters of the request.
Example:

    Keycloak::Admin.generic_post("users/", nil, { username: "admin", email: "admin@test.com", enabled: true }, "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldU...")

Keycloak::Admin.generic_put(service, query_parameters, body_parameter, access_token = nil)

generic_put allows you to make Keycloak PUT service requests. The part of the URI that identifies the service must be passed in the service parameter, already with the route parameters (such as {client}, for example) properly replaced. In the query_parameters parameter you can pass a hash containing the Query Parameters of the request. In the body_parameter parameter you can pass a hash containing the Body Parameters of the request.

Keycloak::Admin.generic_delete(service, query_parameters = nil, body_parameter = nil, access_token = nil)

generic_delete allows you to make Keycloak DELETE service requests. The part of the URI that identifies the service must be passed in the service parameter, already with the route parameters (such as {client}, for example) properly replaced. In the query_parameters parameter you can pass a hash containing the Query Parameters of the request. In the body_parameter parameter you can pass a hash containing the Body Parameters of the request.

Keycloak::Internal

The Keycloak::internal module provides methods designed to facilitate interaction between the application and Keycloak. From the information found in the keycloak.json installation file, all invoked methods will be authenticated automatically, using the application credentials (grant_type = client_credentials), depending on the assigned roles assigned to it. request is authorized.

Keycloak::Internal.get_users(query_parameters = nil, client_id = '', secret = '')

get_users invokes the Keycloak::Admin.get_users method that returns a list of users, filtered according to the parameters hash passed in query_parameters.

Keycloak::Internal.get_groups(query_parameters = nil, client_id = '', secret = '')

get_groups invokes the Keycloak::Admin.get_groups method that returns the group hierarchy for the realm, filtered according to the parameters hash passed in query_parameters.

Keycloak::Internal.change_password(user_id, redirect_uri = '', client_id = '', secret = '')

change_password will invoke the Keycloak PUT /admin/realms/{realm}/users/{id}/execute-actions-email API requesting the UPDATE_PASSWORD action. This will cause Keycloak to trigger an email to the user represented by the user_id parameter. The redirect_uri parameter is optional. If it is not filled, then there will be no link to click after the password reset action has been completed.

Keycloak::Internal.get_user_info(user_login, whole_word = false, client_id = '', secret = ''))

get_user_info, based on the user_login parameter, which will be able to receive the username or the email of the user, will return an array of UserRepresentation in the case where the whole_word parameter is false, or it will return a UserRepresentation when the whole_word parameter is true. The whole_word parameter indicates whether the method should consider users that have username or email part of the expression passed in the user_login parameter - for the cases of whole_word = false - or that has exactly the last expression in this parameter - for the cases of whole_word = true.

Keycloak::Internal.forgot_password(user_login, redirect_uri = '', client_id = '', secret = '')

forgot_password will invoke the Keycloak::Internal.change_password method after invoking the Keycloak::Internal.get_user_info method - passing in the user_login parameter of the described method the user_login parameter of this topic and passing true in the parameter whole_word. The use of this method is indicated for the cases of applications allow the reset of the password of the users without it is logged in.

Keycloak::Internal.exists_name_or_email(value, user_id = '', client_id = '', secret = '')

exists_name_or_email checks whether a user with username or email already exists in the value parameter in the realm. The user_id parameter is used to pass the ID of a user in cases where it is desired to change the username or email of the same, so that they are considered in the username and email verification different users of the user with the ID informed in user_id.

Keycloak::Internal.get_logged_user_info(client_id = '', secret = '')

get_logged_user_info returns the UserRepresentation of the user logged into the application.

# GET /admin/realms/{realm}/users
Keycloak::Internal.logged_federation_user?(client_id = '', secret = '')

logged_federation_user? method invokes the Keycloak::Internal.get_logged_user_info method and checks to see if it is an Federation User (an LDAP user for example).

# GET /admin/realms/{realm}/users
Keycloak::Internal.create_starter_user(username, password, email, client_roles_names, proc = nil, client_id = '', secret = '')

create_starter_user is suitable for applications that allow the creation of new users without a user being logged in or even to create new users from rake db: seed. In the username, password and email parameters, the user name, password, and email, respectively, must be passed. In the client_roles_names parameter, a list (array) with the name of the roles of the Client that will be assigned to the user must be passed. The proc parameter is a lambda method that will make available the UserRepresentation of the created user as a parameter, so that actions should be defined by the application. This method returns the same return of the proc parameter method if it is set, otherwise it will return to UserRepresentation of the created user.

Keycloak::Internal.get_client_roles(client_id = '', secret = '')

get_client_roles will return an array of RoleRepresentation from the Client indicated in the client_id parameter or, in the absence of this, by the client of the keycloak.json installation file.

Keycloak::Internal.get_client_user_roles(user_id, client_id = '', secret = '')

get_client_user_roles will invoke the Keycloak::Admin.get_effective_client_level_role_composite_user method by considering the Client indicated in the client_id parameter or, if not, by the client of the keycloak.json installation file and the user represented by the user_id parameter.

Keycloak::Internal.has_role?(user_id, user_role, client_id = '', secret = '')

has_role? informing the user represented by the user_id parameter has role with the name represented by the user_role parameter.