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.

Token enrichment

The Enrich keycloak token can by disable permanently by setting the environment variable DISABLE_ENRICH_TOKEN to true.

Variable

Default

Description

DISABLE_ENRICH_TOKEN

false

Disable token enrichment process

Database connection

  • As an environment variable (See environments variables)

  • 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 own 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. We recommended replacing them with Variable substitution.

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.

    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.

Variable substitution

The realm.keycloak, users.keycloak, groups.keycloak, identityProviders.keycloak and federations.keycloak files support the substitution of contents from secrets, environment variables and more.

This allows to easily hide secret (like password, api key) and define them securely.

The following major substitutions are available:

More information are available on the substitution documentation.

For example, to hide a user’s password, you can specify the following for the user’s credential:

"credentials": [
  {
    "type": "password",
    "value": "$(file:UTF-8:/run/secrets/user-initial-password)"
  }
]

And create the corresponding secret.

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

Environment Variables

All modules env variables

Variable Name

Default Value

Usage

PROMETHEUS_PORT

9100

The internal port used for Openmetrics exposition.

DISPATCHER_HOST

modules_configuration-dispatcher_main

The hostname on which the modules can fetch the configuration.

DISPATCHER_PORT

10000

The port used by the module to listen for configuration request.

USE_LEGACY_RESTART

Not set

When this flag is enabled, the container will terminate itself whenever a restart is needed (for example, after a configuration change). This is the legacy restart (before version 2.1.0). Otherwise, the system will simply restart the process running inside the container.

CUSTOM_JVM_OPTIONS

Not set

Allow to inject JVM options. See Configuration changes for more information.

ALLOW_VERSION_MISMATCH

Not set

Allow to disable the version check when a new configuration is published to a module. By default, a module will not be restarted if its configuration does not match its version.

Dedicated variables

Database connection :

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.

Healthcheck

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