osp-keycloak

Overview

The Keycloak module provides the user management for OnSphere. The module requires a Mysql database to store its data. By default, we provide the osp-mysql but it is recommended to create an external database.

Value

Based on the event generated by Keycloak, we can create values to signal operations done like a user login, logout, error or the modification of the configuration.

Theming

The theme (logo, name and background) is configured via stack.cfg. Images must be added on the module via the module.resources file.

• The name is used below the logo on the login page.

• The logo without text is used on the login page.

• The logo with text is used on the account edition navigation bar.

• The background image is used on the login page.

Configuration

On the module.service file, the following options allow to change the database used to store the current state and the administrator credential.

Database connection

• As an environment variable :

Variable	Default	Description
DB_VENDOR	mysql	The provider of the DB to use
DB_ADDR	osp-mysql	The address of the database.
DB_PORT	3306	The port of the database.
DB_DATABASE	keycloak	The name of the database to use.
DB_USER	keycloak	The user to connect to the database.

• As secrets :

  database_password: The password for the database (<stack_name>_database_password by default).

Change the database password

See Rotate database password to change the database password.

Administrator username and password

• admin-user : The username of the administrator (<stack_name>_admin-user by default).

• admin-pwd : The password for the admin user (<stack_name>_admin-pwd by default).

Change the administrator user

See Rotate admin user to change the database password.

Change the administrator password

See Rotate admin password to change the database password.

List of configuration files

Filename	Short description	Format	Documentation
module.service	Each service is described in its onw file and then assembled	yaml	See the Swarm administration or Official documentation
module.keycloak	Defines the communication parameter, logging, …	json	module.keycloak
federations.keycloak	Defines the configuration to access a LDAP, RADIUS server to import the user	json	federations.keycloak
realm.keycloak	Defines the base configuration of the OnSphere realm	json	realm.keycloak
groups.keycloak	Defines the stack local group (The group can also be used in the mapper of a federation or a identity provider)	json	groups.keycloak
users.keycloak	Defines the stack local user	json	users.keycloak
identityProviders.keycloak	Defines the configuration to delegate the authentication to a LDAP, RADIUS server	json	identityProviders.keycloak
owner.keycloak	Defines the value generated by Keycloak when event occurs	json	owner.keycloak

Complementary information about the definition of some files

For the following file, we encourage you to configure the realm via the Keycloak UI and once the configuration is working, export the it (Keycloak configuration) and extract the part you need.

Warning

The Keycloak export hides passwords with *********. It is necessary to replace them for Keycloak to work after the push.

Note

The id might cause problem if the configuration is added to a different stack.

• realm.keycloak

  This file contains the standard configuration of OnSphere realm. It is automatically generated if not present. If you need to edit this part, be very careful, it can completely break Keycloak. We encourage you to test it on a standalone Keycloak.

• federations.keycloak

  This file contains the configuration for the federations. The federation is automatically imported at startup.

  To use LDAP with SSL, you need to configure the connectionUrl` with `ldaps://.... If your CA certificate is self-signed, you need to add your CA certificate into certs/external. Otherwise, you can set includeSystemCA` to `true` in `module.keycloak. This will load all CA provided into Keycloak.

  In either case, the module will need to be manually restarted.

• identityProviders.keycloak

  This file contains the identity providers configuration. Identity providers are automatically imported at startup.

Offline access

Offline access allows a user to keep a connection going permanently. This is used the front-end to give access to a 24/7 display.

To be able to issue an offline access, users need to have the role offline_access. We recommend creating a group dedicated to the Wall screen as you can limit or completely block any action. To set a role, the following steps are needed:

• For a group defined in the configuration (preferred choice):

  1. Open the groups.keycloak file

  2. Add the offline_access on realmRoles

  3. Push the configuration

• For a user

  1. Connect to <stack-ip>:<front-end-port>/auth/admin with the admin password

  2. Go to User view

  3. In the Role Mappings tab, assign role offline_access

Revoking offline access

Once an offline access has been granted, it will never expire unless no action is made at least once every 30 days (corresponds to Offline Session Idle timeout). In order to revoke an access, you need to revoke it manually.

To revoke an offline access, following steps are needed:

• For a user:

  1. Connect to OnSphere normally

  2. On the side menu, go to Account management

  3. Then go on the Applications menu

  4. Click on revoke for the wanted offline_token

• For a supervisor:

  1. Connect to OnSphere normally

  2. On the side menu, go to User management

  3. Then go on the Users menu

  4. Select the user owning the token to revoke

  5. Go to Consents

  6. Click on revoke

• For an administrator

  1. Connect to <stack-ip>:<front-end-port>/auth/admin with the admin password

  2. Go to User view

  3. Start by logging out all potential active sessions of the user, in the Sessions tab

  4. Revoke the granted Offline Token in the Consents tab

Healthcheck

The keycloak health check tests the HTTP availability of the master domain, the health check timer value is the default.