Keycloak in the CN QS

Note

This page is a work in progress. It may contain incomplete or incorrect information.

Contents

Keycloak in the CN QS

Realm structure

Keycloak configuration

Customizing Keycloak for business needs

Accessing the admin console

Customization scenarios

Add a new user

Modify client settings

Add a new client

Update environment variables

Troubleshooting

Keycloak is an open-source Identity and Access Management (IAM) solution that provides authentication, authorization, and user management for modern applications and services. It acts as a centralized authentication server that handles user logins, session management, and security token issuance.

The CN QS uses Keycloak to provide secure authentication across its distributed architecture. Keycloak maintains separation between authentication concerns and business logic.

Realm structure

The CN QS defines two Keycloak realms. The AppProvider realm manages authentication for services and users on the provider side of the application. The AppUser realm handles authentication for the consumer side. When components like validators or participant nodes receive requests, they validate the authentication tokens against the appropriate realm.

Keycloak configuration

The default .env configuration includes predefined users in each realm:

• User “Pat” (AUTH_APP_PROVIDER_WALLET_ADMIN_USER_NAME=pat)

• UUID: 553c6754-8879-41c9-ae80-b302f5af92c9

  (AUTH_APP_PROVIDER_WALLET_ADMIN_USER_ID)

AppUser realm:

• User “Alice” (AUTH_APP_USER_WALLET_ADMIN_USER_NAME=alice)

• UUID: 92a520cb-2f09-4e55-b465-d178c6cfe5e4

  (AUTH_APP_USER_WALLET_ADMIN_USER_ID)

• Password: abc123 (AUTH_APP_USER_WALLET_ADMIN_USER_PASSWORD)

Customizing Keycloak for business needs

You can customize the Keycloak configuration to meet your specific business requirements.

Accessing the admin console

The Keycloak admin console is available at:

http://keycloak.localhost:8082/admin/master/console/#/master

To log in use the default credentials:

• Username: ``admin``

• Password: ``admin``

Customization scenarios

Add a new user

1. Log in to the Keycloak Admin console

2. Select the appropriate realm (AppProvider or AppUser)

3. Navigate to the “Users” -> “Add user”

Click Add user

4. Fill in the user details and click Create

5. Go to the Credentials tab to set a password

Set the password

6. Save the password

7. You can now sign in using the new user and their password.

   1. Return to the login page and click AppUser

Log in as Bob

8. Bob is now a user

Modify client settings

1. Return to the realm selection view

2. Navigate to Clients -> select the client to modify

3. Update settings per your needs

4. Save changes

Add a new client

1. Select the appropriate realm

2. Navigate to “Clients” -> “Create”

3. Configure the client’s general settings. Click Next for additional

   configuration options

4. Configure additional settings

Click Next for additional configuration options

5. Save the client

Update environment variables

After making changes to Keycloak configuration, you may need to update the corresponding environment variables in the .env file:

1. The Keycloak user must have the same ID as the ledger user’s ID. This is not the party id.

2. For client changes, update the corresponding client ID and secret

3. For user changes, update the corresponding user ID and credentials

4. Restart the services to apply the changes:

make stop && make start

Troubleshooting

Login failures:

1. Verify Keycloak is running: make status

Find keycloak near grafana and loki in the list.

Keycloak should show as “healthy”

2. Check keycloak credentials in .env file

AUTH_APP_USER_ISSUER_URL_BACKEND=http://nginx-keycloak:8082/realms/AppUser
# for backend

AUTH_APP_USER_ISSUER_URL=http://keycloak.localhost:8082/realms/AppUser #
for backend, wallet-ui

AUTH_APP_PROVIDER_ISSUER_URL=http://keycloak.localhost:8082/realms/AppProvider
# for backend oidc client conf, wallet-ui

AUTH_APP_PROVIDER_ISSUER_URL_BACKEND=http://nginx-keycloak:8082/realms/AppProvider
# for backends

3. Check that the Keycloak user ID matches the ledger user ID

App User

Compare the ID value in Keycloak’s User Details with the AUTH_APP_USER_WALLET_ADMIN_USER_ID value in .env.

Note

In this example, AUTH_APP_USER_WALLET_ADMIN_USER_ID=92a520cb-2f09-4e55-b465-d178c6cfe5e4

App Provider

Compare the ID value in Keycloak’s User Details with the AUTH_APP_PROVIDER_WALLET_ADMIN_USER_ID value in .env.

Note

In this example, AUTH_APP_PROVIDER_WALLET_ADMIN_USER_ID=553c6754-8879-41c9-ae80-b302f5af92c9

Learn more about using Keycloak through their documentation portal:

Keycloak official documentation

Keycloak server administration guide

Securing applications with Keycloak