Management of multiple Keycloak instances for identity management scaling.

Characteristics

Function

As of yuuvis® Momentum version 2021 Winter, the service provides a solution to scale the identity management (IDM) for yuuvis® Momentum, including the TENANT-MANAGEMENT service, USERSERVICE and BPM-ENGINE service (these services require Keycloak as IDM provider). To support a large number of tenants in scenarios which require this, it is necessary to run multiple Keycloak instances. They can be connected via the KEYCLOAK-PROXY service such that it will be called by the yuuvis® Momentum services instead of one single Keycloak instance. The KEYCLOAK-PROXY service provides the same REST API with respect to realm and user management as a single Keycloak instance which means that existing Keycloak clients do not need code adjustments for its usage. Thus, yuuvis® Momentum can be operated both with a single Keycloak instance, or with a proxy and multiple instances, depending on the total number of tenants to be hosted.

Note: If you use only the core services of yuuvis® Momentum, there is no need for the KEYCLOAK-PROXY service. You can directly configure individual identity provider instances for each tenant.
>> application-oauth2.yml

The KEYCLOAK-PROXY service operates as a load balancer distributing the creation of new tenants to several configured Keycloak instances. For services inside the yuuvis® Momentum Kubernetes cluster, it provides the following endpoints that are the same as for a single Keycloak instance:

• Keycloak Admin REST API endpoints.
  Notes:
  
  • An exception is the GET /auth/admin/serverinfo endpoint that provides information on a single instance. This endpoint is not supported in multi-instance setups.
  • If the KEYCLOAK-PROXY configuration has been changed (e.g., a new Keycloak instance was added), it must be refreshed by calling the appropriate endpoint to apply the new configuration. This can also be achieved by a service restart. However, refreshing the service is the preferred method. A restart of the KEYCLOAK-PROXY service will invalidate its tokens. Thus, a client of the service that reuses its access token will get an exception due to unauthorized calling. Depending on the framework used for client development, the corresponding client may or may not automatically refresh the token. If the refresh does not happen automatically, the client code should be updated to refresh the access token with the same credentials as before.
• OpenID Connect endpoints.

After the KEYCLOAK-PROXY service is started, it retrieves all realms configured in the individual Keycloak instances and creates a mapping between each realm and the corresponding Keycloak instance. Each Keycloak realm corresponds to a tenant in yuuvis® Momentum. An exception is the master realm available in all Keycloak instances. The master realms do not correspond to tenants in yuuvis® Momentum and are therefore ignored by the KEYCLOAK-PROXY service.

Any tenant-specific request sent to the KEYCLOAK-PROXY service is forwarded to the Keycloak instance where the corresponding realm is configured. If the call requires the consideration of all tenants (e.g., retrieving all tenants or creating a new tenant), all Keycloak instances are taken into account. Thus, the KEYCLAOK-PROXY service will prevent the creation of a realm that already exists in any Keycloak instance. In case a duplicate realms exists in a Keycloak instance (e.g., they were created by an administrator who directly accessed instances and thus skipped the safety mechanism of the KEYCLOAK-PROXY service) the first realm found by KEYCLOAK-PROXY will be used as active one and the duplicates will be ignored by the KEYCLOAK-PROXY service.

The KEYCLOAK-PROXY service forwards tenant creation requests to any Keycloak instance in the configuration list keycloak-proxy.instances that has less realms than the configured limit keycloak-proxy.maxRealmsPerInstance. There is no fixed sequence for the selection of instances to be used.

If all Keycloak instances are full, i.e., have reached the configured realm limit per instance, a tenant creation request results in an error. The service does not automatically configure further Keycloak instances in addition to the instances listed in keycloak-proxy.instances.

The KEYCLOAK-PROXY service establishes connections to all Keycloak instances that were configured. If a configured Keycloak instance is not available, it is ignored during service initialization and marked in red on the graphical user interface. The KEYCLOAK-PROXY service automatically tries to establish missing connections during the following requests:

• Retrieval of all tenants
• Retrieval of KEYCLOAK-PROXY server information
• Creation of a tenant
• Retrieval of a tenant that (currently) is not available

The first three of them will be successful even if some connections are still missing, delivering partial data. A warning message will be written to the service log indicating that some Keycloak instances were not available during the request processing.

User Interface

The KEYCLOAK-PROXY service offers a simple graphical user interface to be displayed in a web browser. It can be accessed with a user name and password configured in the keycloak-proxy.yml configuration file as described below.

Administrators get an overview of all Keycloak Instances that are managed via the KEYCLOAK-PROXY service. Their number is displayed as a figure on the right of the Instances heading.

Each individual instance is represented with a tile including its URL and its number of currently configured realms in relation to the limit defined in the KEYCLOAK-PROXY service configuration. If an instance includes a duplicate realm as described before, it will be displayed as ignored realm. Furthermore, via Open Administration Console, the Admin Console of the corresponding Keycloak instance can be called. The credentials for the master realm of the specific instance are required. Configurations for the specific Keycloak instances can be adjusted according to your needs. Use our Tenant Management Endpoints to create new realms to ensure that the KEYCLOAK-PROXY service is able to automatically select a suitable Keycloak instance for the creation of the new realm, avoid duplicates, etc.

After applying changes to individual Keycloak instance configurations, the KEYCLOAK-PROXY service needs to be refreshed:

• Click Open Swagger-UI on the right of the top bar of the KEYCLOAK-PROXY user interface to display the service's endpoints in a Swagger UI.
• In the Select a definition field in the top bar, select Keycloak-Proxy Rest API (Management).
• Open the POST /manage/refresh endpoint.
• Click Try it out and Execute.

Management Endpoints

The endpoints of the KEYCLOAK-PROXY service are not suitable for the usage as a public API. However, it is necessary to refresh the service after applying configuration changes. For this purpose, the refresh endpoint can be used via the Swagger UI.

Authentication and Authorization

Requests by users of KEYCLOAK-PROXY that are not yet authorized will be responded with the HTTP status code 302 and redirected to keycloak-proxy/login where users have to authenticate. In subsequent calls, the secret returned by the service will be used. 

Requirements

The service requires Keycloak as identity provider and role management system, and can be run only with dedicated Keycloak versions.
>> yuuvis® Momentum Requirements

Installation and Configuration

The service is not provided in the default Helm Charts since it is not needed for all customers. It can be installed via Docker image as described below.

An example deployment is provided and described on GitHub.
>> Example Deployment

Service Configuration

In the KEYCLOAK-PROXY service configuration, the following parameters have to be specified:

keycloak-proxy:
  instances: 
    - serverUrl: http://localhost:8001/auth
      username: admin1
      password: changeme1
    - serverUrl: http://localhost:8002/auth
      username: admin2
      password: changeme2

keycloak-proxy:
  maxRealmsPerInstance: 42 # default=50

Adjust the security settings for the KEYCLOAK-PROXY service as follows. Replace the example values for name and password accordingly and use it to access the KEYCLOAK-PROXY service via clients or UI.

spring:
  security:
    user:
      name: "admin"
      password: "changeme"

Encoded passwords are supported as well. For more details, refer to the official documentation about the Password Storage Format of the Spring Security project. The following encoders are supported: 

• bcrypt
• ldap
• MD4
• MD5
• pbkdf2
• scrypt
• SHA-1
• SHA-256
• argon2

Configuration via Profiles

In the configuration file application-oauth2.yml, the following parameters have to be configured such that the AUTHENTICATION service and TENANT-MANAGEMENT service connect to the KEYCLOAK-PROXY service (instead of direct connection to a single Keycloak instance):

Running Multiple Instances

In order to achieve a very high performance and/or high availability of the KEYCLOAK-PROXY service, it might be necessary to realize horizontal scaling by running multiple service instances in parallel. For the scaling of the KEYCLOAK-PROXY service, it is necessary to run multiple instances of the service and to interconnect them with a Hazelcast cluster within the yuuvis® Momentum Kubernetes cluster.
>> Configuring a Hazelcast Cluster