Connect to an existing Keycloak instance

This guide describes how to connect Management Identity to your existing Keycloak instance.

Prerequisites

• Access to your Keycloak Admin Console
• A basic understanding of administering realms and clients in Keycloak

note

Clients in Camunda 8 SaaS and applications in Camunda 8 Self-Managed serve a similar purpose. One key difference is that for Camunda 8 SaaS, you can set up specific client connection credentials, whereas in Management Identity, an application is created with credentials automatically assigned.

Steps

Keycloak URLs

As of version 8.5.3, Management Identity uses the Keycloak frontend URL instead of the backend URL. This change may affect you if the frontend URL is blocked from other services (including Camunda applications) and could impact Management Identity functionality.

To avoid connectivity issues, ensure your Keycloak frontend URL is accessible by adjusting your network, firewall, or security settings as needed. This adjustment is crucial to maintain the integration with Keycloak and ensure compatibility.

To connect Management Identity to an existing Keycloak instance, take the following steps for your Camunda installation.

Prepare an existing Keycloak realm

Management Identity can either create a Keycloak realm called camunda-platform with all settings from scratch, or it can use an already existing Keycloak realm. If you would like to use an existing Keycloak realm, prepare following the steps below. Otherwise you can skip this section.

1. Log in to your Keycloak Admin Console.
2. Select the realm you want to connect Management Identity to (for example, camunda-platform).
   
   warning

   Management Identity only supports Keycloak realms where the realm name and realm ID are the same value.
   This is not the case for realms created through the Keycloak UI (where the ID becomes a generated value).
   You can specify both name and ID when using Keycloak's JSON import feature.

3. In the navigation menu, select Clients, then click Create.
4. Enter a client ID and click Next.
   What client ID should I use?

   By default, Management Identity uses the client ID camunda-identity.
   If you use a different ID, set it in the Management Identity application environment variables.

   
5. Turn Client authentication on, select Service accounts roles, and click Next.
6. In the Root URL field, enter the URL where your Management Identity instance will be hosted, then click Save.
7. Open the created client, then select the Service account roles tab.
8. Click Assign role, then change the filter to Filter by clients.
9. Select the manage-clients, manage-realm, and manage-users roles, then click Assign.
   Why does Management Identity need these roles?

   Management Identity allows users to manage entities related to Camunda.
   These roles provide the necessary access to the Keycloak realm.

10. Open the Credentials tab and copy the client secret.

Configure and start the application

Configure Management Identity with the following environment variables:

1. IDENTITY_CLIENT_ID: The ID of the client you created (or camunda-identity if you let Management Identity create it automatically).
2. KEYCLOAK_REALM: The realm name you want to use (or camunda-platform if using the default).
3. KEYCLOAK_SETUP_USER: The username of an administrative Keycloak user.
4. KEYCLOAK_SETUP_PASSWORD: The password for the administrative user.

tip

If you use a non-default realm, you need to set additional Keycloak-specific variables.
See environment variables for details.

Start the Management Identity application.

What does Management Identity create when starting?

When starting, Management Identity creates a base configuration required for operation.
See starting configuration for details.

Helm chart setup

To run a full Camunda cluster with an existing Keycloak instance, see
Helm chart setup for existing Keycloak.

Considerations

When connecting Management Identity to a shared realm, accurately determining what clients should and should not be displayed in the UI is not possible. Therefore, the clients in the realm you connect Management Identity to will be shown in the UI and can have their secrets viewed and updated. Users with access to Management Identity should be considered as having administrator-level access to the system.