Version: 8.7

Connect to an OpenID Connect provider

To enable a smoother integration with your existing systems, Camunda supports connecting to an OpenID Connect (OIDC) authentication provider. A full list of supported and unsupported features when using an OIDC provider is available in the OIDC features table.

This guide steps through the configuration required to connect Camunda to your authentication provider.

note

To connect to a Keycloak authentication provider, see our guide on using an existing Keycloak.

Prerequisites

Information about your OIDC provider's configuration, including the issuer URL.
Ability to create applications in your OIDC provider.
Ability to access the following information about the applications you have created in your OIDC provider:
- Client ID
- Client secrets
- Audience
A claim name and value to use for initial access.

note

The steps below are a general approach for the Camunda components; it is important you reference the component-specific configuration to ensure the components are configured correctly.

Configuration

Generic
Microsoft Entra ID

Steps

In your OIDC provider, create an application for each of the components you want to connect. The expected redirect URI of the component you are configuring an app for can be found in component-specific configuration.
note
Redirect URIs serve as an approved list of destinations across identity providers. Only the URLs specified in the redirect URIs configuration will be permitted as valid redirection targets for authentication responses. This security measure ensures that tokens and authorization codes are only sent to pre-approved locations, preventing potential unauthorized access or token theft.
For all Components, ensure the appropriate application type is used:
- Operate, Tasklist, Optimize, Identity, Web Modeler API: Web applications requiring confidential access/a confidential client
- Console, Web Modeler UI: Single-page applications requiring public access/a public client
Make a note of the following values for each application you create:
- Client ID
- Client secret
- Audience
Set the following environment variables or Helm values for the component you are configuring an app for:

note

You can connect to your OIDC provider through either environment variables or Helm values. Ensure only one configuration option is used.

Environment variables
Helm values

   CAMUNDA_IDENTITY_TYPE=GENERIC
   CAMUNDA_IDENTITY_BASE_URL=<IDENTITY_URL>
   CAMUNDA_IDENTITY_ISSUER=<URL_OF_ISSUER>
   CAMUNDA_IDENTITY_ISSUER_BACKEND_URL=<URL_OF_ISSUER> // this is used for container to container communication
   CAMUNDA_IDENTITY_CLIENT_ID=<Client ID from Step 3>
   CAMUNDA_IDENTITY_CLIENT_SECRET=<Client secret from Step 3>
   CAMUNDA_IDENTITY_AUDIENCE=<Audience from Step 3>
   IDENTITY_INITIAL_CLAIM_NAME=<Initial claim name  if not using the default "oid">
   IDENTITY_INITIAL_CLAIM_VALUE=<Initial claim value>
   SPRING_PROFILES_ACTIVE=oidc

global:
  identity:
    auth:
      issuer: <URL_OF_ISSUER>
      # this is used for container to container communication
      issuerBackendUrl: <URL_OF_ISSUER>
      tokenUrl: <TOKEN_URL_ENDPOINT>
      jwksUrl: <JWKS_URL>
      type: "GENERIC"
      identity:
        clientId: <Client ID from Step 3>
        existingSecret: <Client secret from Step 3>
        audience: <Audience from Step 3>
        initialClaimName: <Initial claim name if not using the default "oid">
        initialClaimValue: <Initial claim value>
      operate:
        clientId: <Client ID from Step 3>
        audience: <Audience from Step 3>
        existingSecret: <Client secret from Step 3>
      tasklist:
        clientId: <Client ID from Step 3>
        audience: <Audience from Step 3>
        existingSecret: <Client secret from Step 3>
      optimize:
        clientId: <Client ID from Step 3>
        audience: <Audience from Step 3>
        existingSecret: <Client secret from Step 3>
      zeebe:
        clientId: <Client ID from Step 3>
        audience: <Audience from Step 3>
        existingSecret: <Client secret from Step 3>
      webModeler:
        clientId: <Client ID of Web Modeler's UI from Step 3>
        clientApiAudience: <Audience of Web Modeler's UI from Step 3>
        publicApiAudience: <Audience of Web Modeler's API from Step 3>
      console:
        clientId: <Client ID from Step 3>
        audience: <Audience from Step 3>

note

Once set, you cannot update your initial claim name and value using environment or Helm values. You must change these values directly in the database.

Additional considerations

For authentication, the Camunda components use the scopes email, openid, offline_access, and profile.

Steps

note

Ensure you register a new application for each component.

Within the Entra ID admin center, register a new application for each component you would like to connect. Web Modeler requires two applications: one for the UI, and one for the API.
Navigate to the new application's Overview page, and make note of the Client ID. This will also be used as the audience ID.
Within your new application, configure a platform for the appropriate component:
- Web: Operate, Tasklist, Optimize, Identity, Web Modeler API
- Single-page application: Console, Web Modeler UI
Add your component's Microsoft Entra ID redirect URI, found under Component-specific configuration.
note
Redirect URIs serve as an approved list of destinations across identity providers. Only the URLs specified in the redirect URIs configuration will be permitted as valid redirection targets for authentication responses. This security measure ensures that tokens and authorization codes are only sent to pre-approved locations, preventing potential unauthorized access or token theft.
Create a new client secret, and note the new secret's value for later use. The secret ID is not needed, only the secret value is required.
Set the following environment variables or Helm values for the component you are configuring an app for:

note

You can connect to your OIDC provider through either environment variables or Helm values. Ensure only one configuration option is used.

Environment variables
Helm values

    CAMUNDA_IDENTITY_TYPE=MICROSOFT
    CAMUNDA_IDENTITY_BASE_URL=<IDENTITY_URL>
    CAMUNDA_IDENTITY_ISSUER=https://login.microsoftonline.com/<Microsoft Entra tenant ID>/v2.0
    CAMUNDA_IDENTITY_ISSUER_BACKEND_URL=https://login.microsoftonline.com/<Microsoft Entra tenant ID>/v2.0
    CAMUNDA_IDENTITY_CLIENT_ID=<Client ID from Step 2>
    CAMUNDA_IDENTITY_CLIENT_SECRET=<Client secret from Step 5>
    CAMUNDA_IDENTITY_AUDIENCE=<Client ID from Step 2>
    IDENTITY_INITIAL_CLAIM_NAME=<Initial claim name if not using the default "oid">
    IDENTITY_INITIAL_CLAIM_VALUE=<Initial claim value>
    SPRING_PROFILES_ACTIVE=oidc

global:
  identity:
    auth:
      issuer: https://login.microsoftonline.com/<Microsoft Entra tenant ID>/v2.0
      # this is used for container to container communication
      issuerBackendUrl: https://login.microsoftonline.com/<Microsoft Entra tenant ID>/v2.0
      tokenUrl: https://login.microsoftonline.com/<Microsoft Entra tenant ID>/oauth2/v2.0/token
      jwksUrl: https://login.microsoftonline.com/<Microsoft Entra tenant ID>/discovery/v2.0/keys
      type: "MICROSOFT"
      publicIssuerUrl: https://login.microsoftonline.com/<Microsoft Entra tenant ID>/v2.0
      identity:
        clientId: <Client ID from Step 2>
        existingSecret: <Client secret from Step 5>
        audience: <Audience from Step 2>
        # This is the object ID of the first user. A role mapping in Identity will automatically be generated for this user.
        initialClaimValue: <Initial claim value>
        redirectUrl: <See the Helm value in the table below>
      operate:
        clientId: <Client ID from Step 2>
        audience: <Client ID from Step 2>
        existingSecret: <Client secret from Step 5>
        redirectUrl: <See the Helm value in the table below>
      tasklist:
        clientId: <Client ID from Step 2>
        audience: <Client ID from Step 2>
        existingSecret: <Client secret from Step 5>
        redirectUrl: <See the Helm value in the table below>
      optimize:
        clientId: <Client ID from Step 2>
        audience: <Client ID from Step 2>
        existingSecret: <Client secret from Step 5>
        redirectUrl: <See the Helm value in the table below>
      zeebe:
        clientId: <Client ID from Step 2>
        audience: <Client ID from Step 2>
        existingSecret: <Client secret from Step 5>
        tokenScope: "<Client ID from Step 2>/.default"
      webModeler:
        clientId: <Client ID of Web Modeler's UI from Step 2>
        clientApiAudience: <Client ID of Web Modeler's UI from Step 2>
        publicApiAudience: <Client ID of Web Modeler's API from Step 2>
        redirectUrl: <See the Helm value in the table below>
      console:
        clientId: <Client ID from Step 2>
        audience: <Client ID from Step 2>
        redirectUrl: <See the Helm value in the table below>
        wellKnown: <Found in the "Endpoints" section of the app registrations page>
      connectors:
        clientId: <Client ID from Step 2>
        existingSecret: <Client secret from Step 5>

danger

Once set, your initial claim name and value cannot be updated using environment or Helm values, and must be changed directly in the database.

Additional considerations

Due to technical limitations regarding third party content, front channel single sign out is not supported. This means that when a user logs out of one component, they will not be logged out of the other components.

For authentication, the Camunda components use the scopes email, openid, offline_access, profile, and <CLIENT_UUID>/.default. To ensure your users are able to successfully authenticate with Entra ID, you must ensure that either there is an admin consent flow configured or grant consent on behalf of your users using the admin consent process.

The client should be configured to support grant_type:

To create an M2M token, the client_credentials grant type is required. The response contains an access token.
To renew a token using a refresh token, the refresh_token grant type is required.
To create a token via authorization flow, the authorization_code grant type is required. The response contains both access and refresh tokens.

To successfully authenticate with Entra ID, you should use the v2.0 API. This means that the CAMUNDA_IDENTITY_ISSUER_BACKEND_URL value should end with /v2.0.

Follow the Microsoft Entra instructions to configure the app manifest, and set the requestedAccessTokenVersion under Api: to 2:

    "requestedAccessTokenVersion": 2,

Component-specific configuration

Component	Redirect URI	Notes/Limitations
Identity	Microsoft Entra ID: `https://<IDENTITY_URL>/auth/login-callback` Helm: `https://<IDENTITY_URL>`
Operate	Microsoft Entra ID: `https://<OPERATE_URL>/identity-callback` Helm: `https://<OPERATE_URL>`
Optimize	Microsoft Entra ID: `https://<OPTIMIZE_URL>/api/authentication/callback` Helm: `https://<OPTIMIZE_URL>`	There is a fallback if you use the existing environment variables to configure your authentication provider. If you use a custom `yaml`, update your properties to match the new values in this guide. When using an OIDC provider, the following Optimize features are not currently available: - The User permissions tab in collections - The Alerts tab in collections - Digests - Accessible usernames for owners of resources (the `sub` claim value is displayed instead).
Tasklist	Microsoft Entra ID: `https://<TASKLIST_URL>/identity-callback` Helm: `https://<TASKLIST_URL>`
Web Modeler	Microsoft Entra ID: `https://<WEB_MODELER_URL>/login-callback` Helm: `https://<WEB_MODELER_URL>`	Web Modeler requires two clients: one for the UI, and one for the API. Required configuration variables for the `webapp` component: `OAUTH2_CLIENT_ID=[ui-client-id]` `OAUTH2_JWKS_URL=[provider-jwks-url]` `OAUTH2_TOKEN_AUDIENCE=[ui-audience]` `OAUTH2_TOKEN_ISSUER=[provider-issuer]` `OAUTH2_TYPE=[provider-type]` Required configuration variables for the `restapi` component: `CAMUNDA_IDENTITY_BASEURL=[identity-base-url]` `CAMUNDA_IDENTITY_TYPE=[provider-type]` `CAMUNDA_MODELER_SECURITY_JWT_AUDIENCE_INTERNAL_API=[ui-audience]` `CAMUNDA_MODELER_SECURITY_JWT_AUDIENCE_PUBLIC_API=[api-audience]` `SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI=[provider-issuer]` When using Microsoft Entra ID, the `BEARER_TOKEN` authentication for configured clusters is not supported as Entra ID does not allow access tokens with multiple audiences. Use `CLIENT_CREDENTIALS` instead and provide the following configuration variables: `CAMUNDA_MODELER_CLUSTERS__OAUTH_URL=[token-endpoint-url]` `CAMUNDA_MODELER_CLUSTERS__OAUTH_SCOPE=[zeebe-client-id]./default` `CAMUNDA_MODELER_CLUSTERS_*_OAUTH_AUDIENCE_ZEEBE=[zeebe-client-id]`.
Console	Microsoft Entra ID: `https://<CONSOLE_URL>` Helm: `https://<CONSOLE_URL>`
Zeebe	no redirect URI	Instead, include `tokenScope:"<Azure-AppRegistration-ClientID> /.default "`. This refers to the Helm value `global.identity.auth.zeebe.tokenScope`, which should be set to the displayed value.
Connectors		Connectors act as a client in the OIDC flow. For outbound-only mode (when `CAMUNDA_CONNECTOR_POLLING_ENABLED` is `false`), only Zeebe client properties are required: `ZEEBE_CLIENT_ID=[client-id]` `ZEEBE_CLIENT_SECRET=[client-secret]` `ZEEBE_AUTHORIZATION_SERVER_URL=[provider-issuer]` `ZEEBE_TOKEN_AUDIENCE=[Zeebe audience]` `ZEEBE_TOKEN_SCOPE=[Zeebe scope]` (optional) For inbound mode, Operate client properties are required: `CAMUNDA_IDENTITY_TYPE=[provider-type]` `CAMUNDA_IDENTITY_AUDIENCE=[Operate audience]` `CAMUNDA_IDENTITY_CLIENT_ID=[client-id]` `CAMUNDA_IDENTITY_CLIENT_SECRET=[client-secret]` `CAMUNDA_IDENTITY_ISSUER_BACKEND_URL=[provider-issuer]`

Supported and unsupported OIDC features

When using Identity with an OIDC provider, not all features of authentication and authorization are available. The following table lists OIDC supported and unsupported features.

Feature name	Description	Availability
Single sign-on (SSO)	Redirects users to the identity provider for authentication, and enables seamless login across applications. Zeebe, Operate, Tasklist, Optimize, Identity, and Connectors use an identity provider-issued JWT. Web Modeler and Console use PCKE (Proof Key for Code Exchange) to connect to the Camunda Identity service.
Authentication flows (Authorization code flow with PKCE)	Securely handles user login using the recommended authorization code flow with PKCE (Proof Key for Code Exchange) for security. Web Modeler and Console use PCKE, but do not directly connect to the identity provider with OIDC. Web Modeler and Console use PCKE to connect to the Camunda Identity service.
ID token handling	Validates and extracts user identity details from the ID token after authentication.
Access token management	Uses access tokens issued by the identity provider to securely access protected APIs.
Session management	Ensures users remain logged in across sessions and applications or automatically re-authenticate when needed.
Logout handling (RP-initiated logout)	Triggers user logout from the application and notifies the identity provider to sign out users across all connected systems.
Role and group synchronization	Maps user roles and permissions from the identity provider into the client application for access control.
User profile management	Fetches user details from the UserInfo endpoint after authentication to personalize the user experience.

To request a missing feature, please contact us.

Prerequisites​

Configuration​

Steps

Additional considerations

Steps

Additional considerations

Component-specific configuration​

Supported and unsupported OIDC features​

Prerequisites

Configuration

Component-specific configuration

Supported and unsupported OIDC features