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
orpublic
- Do not check
Service Accounts Enabled
- Make your client
- In this gem's configuration
- Set
use_service_account
tofalse
- Setup
username
andpassword
- Setup
client_secret
if your client isconfidential
- Set
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 relevantrealm-management.
client's roles. For instance:view-users
if you want to search for users using this gem.
- Make your client
- In this gem's configuration
- Set
use_service_account
totrue
- Setup
client_secret
- Set
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.use_service_account = 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