Guideline for manual installation and configuration of keycloak as an identity provider for yuuvis® Momentum.

Introduction

Identity providers such as Keycloak can be connected to yuuvis® API for authentication using Connect/OAuth2 via the authentication-service.

Keycloak is the recommended identity provider for yuuvis® Momentum and is consistently used for testing. In principle, any identity provider supporting OAuth2 can be used in the same way.

As standard, the installation is done by means of a Helm chart. Two demonstration tenants are created and configured automatically. Further tenants for productive use have to be added and configured manually.
>> Installation Guide

The manual installation and configuration of Keycloak for yuuvis® Momentum API are broadly described here.

After installation, Keycloak provides two administrative services, one for system administrators and one for users.

• Admin Console
  In order to create and administrate realms and user accounts, Keycloak provides the Admin Console. Roles can be defined and assigned in the Admin Console as well. An administrator login is required.
  >> https://www.keycloak.org/docs/latest/server_admin/#admin-console
• User Account Service
  Any user has access to the User Account Service provided by Keycloak. Users can change their credentials and other personal data.
  >> https://www.keycloak.org/docs/latest/server_admin/#_account-service

Keycloak Installation

To install Keycloak manually, follow these steps:

• Download version 11.0.2 at https://www.keycloak.org/archive/downloads-11.0.2.html and extract it to a local directory.
• Modify the standalone.xml configuration file in the \standalone\configuration\ directory:
  Add the following entry to the <interfaces> section:
  • <interface name="any">
  <any-address/>
</interface>
  • In the <socket-binding-group> section, for the <default-interface> attribute, enter the following value: any
  • If port 8080 is not available, change the port via the following line in the <socket-binding-group> section:
    <socket-binding name="http" port="${jboss.http.port:8080}"/>
• Start Keycloak via the \keycloak\bin\standalone.bat file.
  Note: The file must be run as an administrator.
• Call the Keycloak Admin Console: http://localhost:8080/
• Start by creating an administrator account.

Note: For productive use, it is recommended to connect Keycloak to a different relational database management system (RDBMS) instead of the embedded standard H2. Suggestions for compatible RDBMS are provided by Keycloak: https://www.keycloak.org/docs/latest/server_installation/index.html#database.

Keycloak: Tenant and User

You require a tenant and a user.

Note: Users in Keycloak must also be entered in the yuuvis® user administration.

To create tenants and users, follow these steps:

• Call the Keycloak Admin Console: http://localhost:8080/auth/admin

• Create a new tenant in the navigation area via Master > Add realm.

• Create and save a user for the tenant via Users > Add user.

• Enter a password in the Credentials tab on the user page, set the Temporary option to Off, and save with Set Password.

Keycloak: Connecting to yuuvis® API

To establish a connection, create a client following these steps:

• Call the Keycloak Admin Console: http://localhost:8080/auth/admin

• Select the tenant and create the new client via Clients > Create.

• Enter a name in the Client ID field, and enter and save the yuuvis® authentication-service URL in the Root URL field.

• Configure the following in the Settings tab of the client page:

  • Access Type > confidential

  • Authorization Enabled > ON

  • Valid Redirect URIs > Schema: http://<authentication-service>/*
All yuuvis® API hosts must be specified according to this schema.

• Save the configuration by clicking Save.

• Set the required user roles for the yuuvis® API components as simple strings via Roles > Add Roles.
  Afterwards, the roles can be activated for the users via Role Mappings > Assigned Roles.

In case of a yuuvis® Momentum system with multiple tenants, the authentication-service has to be registered as a Keycloak client in each corresponding realm.

Connecting yuuvis® authentication-service to SSL-secured Keycloak

• Export certificate with Firefox:
  
  • Call the encrypted welcome page of Keycloak in Firefox: https://localhost:8443/auth/
  • Open the Protection Settings via the shield icon to the left of the address bar.
  • Display the certificate via Security > View Certificates.
  • Export the certificate as localhost.pem via the tab Authorities in the certificate manager.
• Alternatively, export certificate with Chrome:
  
  • Call the encrypted welcome page of Keycloak in Chrome: https://localhost:8443/auth/
  • Open the Settings via the three dots icon to the right of the address bar.
  • Display the certificate via Privacy and security > Security > Manage certificates.
  • Export the certificate in Base-64 format as localhost.pem.

• Import the certificate in the Java Trust Store with the following batch call:

  ...\service-manager\jdk\bin\keytool ^
      -import ^
      -trustcacerts ^
      -keystore ...\service-manager\jdk\jre\lib\security\cacerts ^
      -storepass changeit ^
      -noprompt ^
      -alias localhost ^
      -file ...\path\to\localhost.pem

• Restart the yuuvis® authentication-service.

Embedding the Login Page into an iframe

The Keycloak login page can be embedded as an iframe into a second web page if this web page is published on the same host as Keycloak. If the secondary web page is published on a different host, it has to be legitimized in every Keycloak tenant that will use this web page for the login process:

• Call the Keycloak Admin Console: http://localhost:8080/auth/admin/
• Select the tenant and and add the host name of the web page via Realm Settings > Security Defenses > Content-Security-Policy > frame-ancestors.
  Multiple host names are seperated by blank spaces.

Impersonation

In order to allow users with a specific role to log in as any other user, impersonation can be activated in Keycloak. Thus, users with this specific role can use their own password to log in to the account of any other user within their tenant. In Keycloak, the feature is realized via impersonation by means of token exchange.

Activating Token Exchange

• Open the StatefulSet of Keycloak in your Kubernetes cluster for editing by running the command:

  kubectl -n infrastructure edit statefulset keycloak

• Extend the containers section as follows:

  containers:
    - args:
      - -Dkeycloak.profile.feature.token_exchange=enabled
      - -Dkeycloak.profile.feature.admin_fine_grained_authz=enabled

• Restart Keycloak.

Configuring the User Account and Keycloak Clients

• Call the Keycloak Admin Console: http://localhost:8080/auth/admin
• Select the user you want to grant access to other user accounts and switch to the Role Mappings tab.
• Display the Client Roles for the realm-management client and assign its impersonation role to the user.
• In the same realm, select the client admin-cli and switch to the Permissions tab.
• Flip the Permissions Enabled switch to ON.
• In the appearing table, click token-exchange in the scope-name column.
• From the Create Policy selection list in the Apply Policy section, select Role.
• Name it impersonation-policy.
• From the Realm Roles selection list, select the administrative role that will enable users to impersonate other users within their tenant. Tick the Required checkbox.
• From the Clients selection list, select realm-management.
• From the Client Roles selection list, select impersonation. Tick the Required checkbox.
• Save the configuration for the policy.
• Save the configuration for the permission settings.

Testing Impersonation with cURL

The following commands use an administrative user root with the password changeme belonging to the tenant tenant1 with the impersonation authorization as configured before. This user requests access to the account of the user specified by the ID cc14e5d4-e8da-4108-92ad-c87066aed4c3.

• Request a token for the administrative user with the impersonation authorization:

  curl -k ^
    -d "client_id=admin-cli" ^
    -d "username=root" ^
    -d "password=changeme" ^
    -d "grant_type=password" ^
    "http://localhost:8080/auth/realms/tenant1/protocol/openid-connect/token"

• Request a token for the account of the target user where the login is needed. The previously retrieved token of the administrative user is referenced as subject_token whereas the ID of the target user is specified as requested_subject.

  curl -k ^
    -H "Content-Type: application/x-www-form-urlencoded" ^
    -d "client_id=admin-cli" ^
    -d "requested_subject=cc14e5d4-e8da-4108-92ad-c87066aed4c3" ^
    -d "subject_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJueEZ..." ^
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" ^
    "http://localhost:8080/auth/realms/tenant1/protocol/openid-connect/token"

  The retrieved token can be used by the administrative user root for authentication in yuuvis® Momentum with the account of the target user.

• The following command retrieves user-specific information on the user who will be logged in with the token specified in the authorization header. Check whether the token retrieved before identifies the desired target user. Thus, in this example, the command should retrieve a data set for the user with ID cc14e5d4-e8da-4108-92ad-c87066aed4c3.
  

  curl -k ^
    --request GET ^
    --url "http://localhost:8080/auth/realms/tenant1/protocol/openid-connect/userinfo" ^
    --header "accept: application/json" ^
    --header "authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAi1dXVSZ3daQldhTTJZaXNlZElFXzg..."

Suppressing Duplicate Information on Roles

Per default, the access token generated by Keycloak contains the roles of the currently logged-in user. The AUTHENTICATION service creates an internal JSON Web Token (JWT) that includes the unchanged Keycloak access token. However, in order to allow a separate role management, the AUTHENTICATION service requests the roles of the corresponding in a separate request and adds them to the internal JWT in addition to the Keycloak access token. The roles stored in the original Keycloak access token are a duplicate of the information and are always ignored. In order to reduce the size of the JWT, their inclusion in the Keycloak access token can be suppressed by applying the configuration adjustment described below. Thus, for any request to the yuuvis® Momentum API, the request header size is reduced.

• Call the Keycloak Admin Console: http://localhost:8080/auth/admin/ with administrator login.
• Select the realm for which the configuration is to be changed.
• Open the Client Scopes.
• Open the roles scope.
• In the Mappers tab, delete the entries realm roles and client.

These configuration steps have to be applied to each realm in each Keycloak instance in which to suppress the inclusion of role information in the Keycloak access token.

Session Management

For each user session, HTTP client and browser set session cookies as described here:
>> Authentication against the Core API

Additionally, the following cookies are set by Keycloak. For more information, please refer to the official Keycloak documentation.

• AUTH_SESSION_ID_LEGACY
• AUTH_SESSION_ID
• KEYCLOAK_IDENTITY_LEGACY
• KEYCLOAK_IDENTITY
• KEYCLOAK_PROXY_SESSION_ID
• KEYCLOAK_SESSION_LEGACY
• KEYCLOAK_SESSION

Summary

This article explained how to install and configure Keycloak as an identity provider and access management system for yuuvis® Momentum in a manual procedure.