Connect to an existing Keycloak instance
In this guide, we'll demonstrate how to connect the Identity component to your existing Keycloak instance.
Prerequisites​
- Access to your Keycloak Admin Console
- A basic understanding of administering realms and clients in Keycloak
Steps​
To connect Identity to an existing Keycloak instance, take the following steps:
- Log in to your Keycloak Admin Console.
- Select the realm you would like to connect Identity to. In our example, this is Test Realm.
- Select Clients in the navigation menu, and click the Create button to create a new client.
- Enter the client ID and the URL of where your Identity instance will be hosted and click Save.What client ID should I use?
By default, Identity uses the Client ID
camunda-identity
, so we recommend using this too. If you choose a different client ID, this will need to be set in the Identity application environment variables. - On the page for the created client, set the Access Type to
confidential
, Service Accounts Enabled toON
, and save your changes by clicking the Save button. - Navigate to the Service Account Roles tab in the top navigation.
- Select the
realm-management
client from the Client Roles dropdown. - Assign the
manage-clients
,manage-realm
, andmanage-users
role from the Available Roles list.Why does Identity need these roles?Identity is designed to allow users to manage the various entities related to Camunda. To achieve this, it requires specific access to the realm.
- Navigate to the Credentials tab and copy the client secret.
- Set the
IDENTITY_CLIENT_SECRET
environment variable with the value from Step 9. - Set the
KEYCLOAK_REALM
environment variable to the realm you selected in Step 2.tipIf you are using a specific realm, you need to set additional variables to use the intended realm. See the environment variables page for details of Keycloak-specific variables to consider.
- Start the Identity application.
The Identity application creates a base set of configurations required to function successfully. To understand more about what is created and why, see the starting configuration.
Considerations​
When connecting Identity to a shared realm, we are unable to accurately determine what clients should and should not be displayed in the Identity UI. This means the clients in the realm you connect Identity to will be shown in the Identity UI and can have their secrets viewed and updated. We recommend that users with access to Identity should be considered as having administrators level access to the system.