4.2 Keycloak

Keycloak is used for identity and access management in the complete Data Context Hub stack. To access data or use endpoints, a user must to obtain an access token from Keycloak and have the required roles assigned.

Building Blocks

Following sections summarize the most important building blocks of Keycloak used by the Data Context Hub. Configuration of these parts have to be done in Keycloak's Admin Console.

Realms

Each realm is an separate space where objects, including users, roles and groups, are managed. A user belongs to and logs into a specific realm, and an access token is only valid in the same realm it was created in.

Roles

Roles define what a user is allowed to do. While Keycloak already includes some built-in roles, Data Context Hub creates it's own roles in order to manage access to different resources. These roles are automatically generated by GBS based on the Data Context Hub license. Each licensed module has two roles: one for reading data <module>-execute and one for manipulating data <module>-modify. Each role is checked individually. A user with the <module>-modify role assigned is not automatically allowed to read data, both roles must be assigned to get read and write access.

Users

Users belong to a realm and represent individuals interacting with a system. Roles are directly assigned to them and they can be part of groups.

Clients

Clients belong to a realm and represent applications and services that interact with the system. Depending on their configuration they can request authentication of a user or request their own access token. The ability to assign roles to clients also depends on their configuration.

Groups

A group is a set of attributes and role mappings that can be applied to a user. It is possible to define a hierarchy of groups. A user can be a member of multiple groups.

Access Token

Access tokens have to be retrieved directly from Keycloak and can then be used in subsequent calls to different endpoints.

Retrieving Access Token for Users

An access token can only be retrieved for users which also have their credentials stored in Keycloak.

caution

In order to retrieve an access token for a user, a client with "Direct Access Grants" enabled is required. Security wise this is not recommended.

curl --request POST '{{keycloakUrl}}/realms/{{realm}}/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={{clientId}}' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username={{username}}' \
--data-urlencode 'password={{password}}'

Retrieving Access Token for Clients

An access token can only be retrieved for clients which have "Client Credentials Grant" flow enabled ( see Client Configuration).

curl --request POST '{{keycloakUrl}}/realms/{{realm}}/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={{clientId}}' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_secret={{clientSecret}}'

Client Configuration

Whenever an application needs access to the Data Context Hub endpoints, a client specific to that application should be created. This can be done in Keycloak's Admin Console:

1. Log into the Admin Console and select the realm the new client should be added to.
2. In the menu select "Clients" and click the "Create client" button.
3. After entering a unique "Client ID", enable "Client authentication" and only select "Service accounts roles" which enables the "Client Credentials Grant" flow for this client. It's best to disable all other authentication flows.

By selecting "Service accounts roles", Keycloak automatically creates a user account with username service-account-<clientId> that is linked to the client. You can perform the same user operations on this account as a regular account. Since roles cannot be directly assigned to clients, they have to be assigned to the linked service account.

User Integration

It is possible to integrate users from other system by either using user federation or identity providers. Keycloak supports LDAP and Kerberos for user federation. It also has several built-in social identity providers as well as standard providers for SAML v2.0 and OpenID Connect v1.0. It is also possible to implement and use custom extensions to integrate systems not supported by built-in features.