Keycloak Admin Ruby

Ruby client that acts as a client for the Keycloak REST API. This gem basically acts as an url builder using http-client to get responses and serialize them into representation objects.

Warning: This beta gem is currently used for personal used. Most Keycloak Admin features are not implemented yet.

Install

This gem does not require Rails. For example, using bundle, add this line to your Gemfile.

gem "keycloak-admin", "0.2"

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
    • A Redirect URL is required, set it to *
    • 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
    • Set use_service_account to true
    • Setup client_secret

Configuration

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:

KeycloakAdmin.configure do |config|
  config. = false
  config.server_url          = ENV["KEYCLOAK_SERVER_URL"]
  config.client_id           = ENV["KEYCLOAK_ADMIN_CLIENT_ID"]
  config.client_realm_name   = ENV["KEYCLOAK_REALM_ID"]
  config.username            = ENV["KEYCLOAK_ADMIN_USER"]
  config.password            = ENV["KEYCLOAK_ADMIN_PASSWORD"]
  config.logger              = Rails.logger
end

This example is autoloaded in a Rails environment.

Overall configuration options

All options have a default value. However, all of them can be changed in your initializer file.

Option Default Value Type Required? Description Example
server_url nil String Required The base url where your Keycloak server is located. This value can be retrieved in your Keycloak client configuration.  auth:8080/auth
client_realm_name "" String Required Name of the realm that contain 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 connetio nto the client uses a username/password credential false
username nil String Optional Username that access to the Admin REST API. Recommended if user_service_account is set to false. mummy
password nil String Optional Clear password that access to 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 

Use Case

exit

Supported features

  • Get an access token
  • Create a user
  • Reset credentials
  • Delete a user

Get an access token

Returns an instance of KeycloakAdmin::TokenRepresentation.

KeycloakAdmin.realm("a_realm").token.get

Search for users

Returns an array of KeycloakAdmin::UserRepresentation.

KeycloakAdmin.realm("a_realm").users.search("a_username_or_an_email")

Save a user

Returns the provided user, which must be of type KeycloakAdmin::UserRepresentation.

KeycloakAdmin.realm("a_realm").users.save(user)

Create and save a user with password

Returns the created user of type KeycloakAdmin::UserRepresentation.

username       = "pioupioux"
email          = "[email protected]"
password       = "acme0"
email_verified = true
KeycloakAdmin.realm("a_realm").users.create!(username, email, password, email_verified)

Reset a password

user_id      = "95985b21-d884-4bbd-b852-cb8cd365afc2"
new_password = "coco"
KeycloakAdmin.realm("commuty").users.update_password(user_id, new_password)

How to execute library tests

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