Clients in Keycloak¶

Clients are entities that can request Keycloak to authenticate a user.

Clients can also be entities that simply want to request an access token to securely invoke other services on the network that are secured by Keycloak.

Adding a new clients¶

There are several ways to create these clients. The options described here are to add the client manually and with a registration token.

Adding the client manually¶

Go to the IEM url and log in using the customer_admin user, or any existing users with access to IAM:

https://<IEM-IP or HOSTNAME>

Once logged-in select the Identity & Access Management tile in the launchpad.

Navigate to Clients in the sidebar and click create Client. There you can enter a client ID and create the client.

Settings¶

Afterwards some Settings must be set:

Access Type needs to be confidential.
Service Accounts Enabled needs to be enabled.
Valid Redirect URIs needs to be set, e.g. https://<iem_ip>/auth/*

To allow the client to access the IEM administration pages, the Service Account Roles must be set.

The service account must have the Admin role of the IEM client.

Once the settings are done the client needs the client ID and the client secret from the credential page. With these the client can get a token from keycloak and then access the IEM admin pages.

Registration of a client with Registration Token¶

The client can also register itself with keycloak. For that the client needs an initial access token. To create this token got to customer realm -> realm settings -> Client registration. There you can create a new token and specify how many clients can register with that token and how long the token is valid.

The client needs to change some of its settings.
Access Type needs to be confidential.
Client Secret needs to be set.
Service Accounts Enabled needs to be enabled.
Its service account needs to get the Admin role of the IEM client.

Getting Access Token¶

Once created, the client can get an access token from Keycloak with its ID and secret.

curl --location --request POST 'https://<iem_ip>/auth/realms/customer/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<cliend_id>' \
--data-urlencode 'client_secret=<client_secret>'

Keycloak returns a JSON object with the access_token in it:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI2bm9NQVg3MjJwRVFSb2FQcFlLSUtlODVhQXpZSkVqY1gzeFd0cUtWOVgwIn0.eyJleHAiOjE2NjQ5OTUxMjEsImlhdCI6MTY2NDk3MzUyMSwianRpIjoiYjUxYTE0N2EtOTFkNy00NzM2LWJkYzktOTA3M2EyNzcwODZkIiwiaXNzIjoiaHR0cHM6Ly8xOTIuMTY4LjQ5LjIvYXV0aC9yZWFsbXMvY3VzdG9tZXIiLCJhdWQiOiI0MWZmNzNjOTcxOWE0MmJkYjAzNDgzNTUxMTRjZWI4MiIsInN1YiI6ImNiMTI4YzI1LTNhZTAtNGQ0ZS1hYWFkLTk4ZDE3ODM1MzgzMCIsInR5cCI6IkJlYXJlciIsImF6cCI6InRlc3QyIiwiYWNyIjoiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIiwiZGVmYXVsdC1yb2xlcy1jdXN0b21lciJdfSwic2NvcGUiOiJlbWFpbCBwcm9maWxlIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJjbGllbnRJZCI6InRlc3QyIiwiY2xpZW50SG9zdCI6IjE5Mi4xNjguNDkuMSIsInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2UtYWNjb3VudC10ZXN0MiIsImNsaWVudEFkZHJlc3MiOiIxOTIuMTY4LjQ5LjEifQ.XfdSd0O0vTQmVEbzSZlXmoHYhlPWgTg8oes8Gs9Dn_M6AVkomwweXhL6psx3V2T3_yzLnZhtf5kCsHgjLwk80AEhrdmbQsAmwuAl7EF8s4MMBocIeO-hp5F2JkylAX3nbF5iqP9_Ecjjht4O4ilLLKjKtFKPcRkXFEgzNxekfGt6adH0v5dGIMd8DLVFpJq5UMM7wtbMusTuXRP_SeX1Y1AnCRkM0j-smGWYpbEIE-rax-UAyiaznU9Q87JoOXG75Q5_xiC0BTI8Gb8wpoI99lAFZO6Gp4iCR0iPEHLVQErW58cj26dxObHoMk9OTNq-UL4LPdOcRgbuNRhU9pq6eQ",
    "expires_in": 21600,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "email profile"
}

The access_token can then be used as a bearer token to access the APIs of the IEM .

Important Clients to Keep - User Should Avoid Deleting¶

The Customer Realm is used as the default tenant for the Industrial Edge Management System. This is where all IEM users are configured.

NOTICE

Deleting this realm would result in a broken IEM system.
There are multiple OAuth clients configured for the system. The ClientID is used to reference them.

NOTICE

Deleting these clients would result in a partially broken IEM system. The key clients for the system are shown in the figure below. Additional clients that are installed by the Industrial Edge components are labeled "ie-*". These clients must remain unchanged.
Client secrets are provided to the applications as k8s secret and mounted on the containers. Changing these secrets would require changing the secrets in the k8s cluster as well.
OAuth clients also bring additional roles that can be assigned to users. Removing the client roles would result in a partially broken system.
Realm roles are used for system-wide access control, which is typically client-independent. Multiple roles are created during bootstrapping. Deleting these roles would result in a broken IAM system.

External Clients¶

API¶

The IAM can be managed through API calls. The base URL for this is https://<iem-ip>/auth. You can find the documentation about the CLI in the 'CLI tool documentation' entry .

For each call to the REST API, you must log in and have access to the realm. You can obtain a valid token by signing in:

curl --location --request POST 'https://<iem_ip>/auth/realms/customer/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=admin-cli' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<username>' \
--data-urlencode 'password=<password>'

CLI tools¶

Keycloak also provides a CLI tool to configure an instance. The CLI tool makes calls to the Admin REST API. In order to make a call, you must be logged in with the CLI and have access to the realm. You can find the CLI in the Downloadable Keycloak archive entry. You can find the documentation about the CLI in the 'CLI tool documentation' entry.