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.

In this guide, we step through the configuration required to connect Camunda to your authentication provider.

note

To connect to a Keycloak authentication provider, see 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 fo the 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

Steps

1. 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.
2. Make a note of the following values for each application you create:
   • Client ID
   • Client secret
   • Audience
3. Set the following environment variables for the component you are configuring an app for:

Environment variables

   CAMUNDA_IDENTITY_TYPE=GENERIC
   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 2>
   CAMUNDA_IDENTITY_CLIENT_SECRET=<Client secret from Step 2>
   CAMUNDA_IDENTITY_AUDIENCE=<Audience from Step 2>
   IDENTITY_INITIAL_CLAIM_NAME=<Initial claim name  if not using the default "oid">
   IDENTITY_INITIAL_CLAIM_VALUE=<Initial claim value>

Helm values

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 2>
        existingSecret: <Client secret from Step 2>
        audience: <Audience from Step 2>
        initialClaimName: <Initial claim name if not using the default "oid">
        initialClaimValue: <Initial claim value>
      operate:
        clientId: <Client ID from Step 2>
        audience: <Audience from Step 2>
        existingSecret: <Client secret from Step 2>
      tasklist:
        clientId: <Client ID from Step 2>
        audience: <Audience from Step 2>
        existingSecret: <Client secret from Step 2>
      optimize:
        clientId: <Client ID from Step 2>
        audience: <Audience from Step 2>
        existingSecret: <Client secret from Step 2>
      zeebe:
        clientId: <Client ID from Step 2>
        audience: <Audience from Step 2>
        existingSecret: <Client secret from Step 2>
      webModeler:
        clientId: <Client ID from Step 2>
        clientApiAudience: <Audience from Step 2>
        publicApiAudience: <Audience for using Web Modeler's API. For security reasons, use a different value than for clientApiAudience>

Additional considerations

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

Microsoft Entra ID

Steps

1. Access the Entra ID admin area and register an application. After registering the app, the Overview page will contain a Client ID; make a note of this value as it will be required later on.

2. Within the app registered in Step 1, configure a platform of type Web for Operate, TaskList, and Optimize. Configure a platform of type Single-page application for Modeler. The expected redirect URI of the component you are configuring an app for can be found in component-specific configuration. Make sure the redirect URIs entered here match the redirect URI's configured in Step 4.

3. Once you have registered a platform for your app a client secret needs to be created. To do this, see adding a client secret. Make a note of the value of the client secret as it will be required later on.

4. Set the following environment variables for the component you are configuring an app for:

Environment variables

   CAMUNDA_IDENTITY_TYPE=MICROSOFT
   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 1>
   CAMUNDA_IDENTITY_CLIENT_SECRET=<Client secret from Step 3>
   CAMUNDA_IDENTITY_AUDIENCE=<Client ID from Step 1>
   IDENTITY_INITIAL_CLAIM_NAME=<Initial claim name if not using the default "oid">
   IDENTITY_INITIAL_CLAIM_VALUE=<Initial claim value>

Helm values

global:
  identity:
    auth:
      issuer: https://login.microsoftonline.com/<Client ID from Step 1>/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/<Client ID from Step 1>/v2.0
      identity:
        clientId: <Client ID from Step 2>
        existingSecret: <Client secret from Step 2>
        audience: <Audience from Step 2>
        initialClaimName: <Initial claim name if not using the default "oid">
        initialClaimValue: <Initial claim value>
        redirectUrl: <See table below>
      operate:
        clientId: <Client ID from Step 1>
        audience: <Client ID from Step 1>
        existingSecret: <Client secret from Step 3>
        redirectUrl: <See table below>
      tasklist:
        clientId: <Client ID from Step 1>
        audience: <Client ID from Step 1>
        existingSecret: <Client secret from Step 3>
        redirectUrl: <See table below>
      optimize:
        clientId: <Client ID from Step 1>
        audience: <Client ID from Step 1>
        existingSecret: <Client secret from Step 3>
        redirectUrl: <See table below>
      zeebe:
        clientId: <Client ID from Step 1>
        audience: <Client ID from Step 1>
        existingSecret: <Client secret from Step 3>
        tokenScope: "<Client ID from Step 1>/.default"
      webModeler:
        clientId: <Client ID from Step 1>
        clientApiAudience: <Client ID from Step 1>
        publicApiAudience: <Audience for using Web Modeler's API. For security reasons, use a different value than for clientApiAudience>
        redirectUrl: <See table below>
      connectors:
        clientId: <Client ID from Step 2>
        existingSecret: <Client secret from Step 3>

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.

It's also important to follow the steps described here to configure the app manifest and set the accesstokenAcceptedVersion to 2 like so:

    "accessTokenAcceptedVersion": 2,

Component-specific configuration

Component	Redirect URI	Notes
Identity	https://<IDENTITY_URL>/auth/login-callback
Operate	https://<OPERATE_URL>/identity-callback
Optimize	https://<OPTIMIZE_URL>/api/authentication/callback	There is a fallback if you use the existing ENV vars to configure your authentication provider, if you use a custom yaml, you need to update your properties to match the new values in this guide. When using an OIDC provider, the following features are not currently available: User permissions tab in collections, digests, Alerts tab in collections.
Tasklist	https://<TASKLIST_URL>/identity-callback
Web Modeler	https://<WEB_MODELER_URL>/login-callback	Required configuration variables for webapp: OAUTH2_CLIENT_ID=[client-id] OAUTH2_JWKS_URL=[provider-jwks-url] OAUTH2_TOKEN_AUDIENCE=[client-audience] OAUTH2_TOKEN_ISSUER=[provider-issuer] OAUTH2_TYPE=[provider-type] Required configuration variables for restapi: CAMUNDA_IDENTITY_BASEURL=[identity-base-url] CAMUNDA_IDENTITY_TYPE=[provider-type] CAMUNDA_MODELER_SECURITY_JWT_AUDIENCE_INTERNAL_API=[client-audience] CAMUNDA_MODELER_SECURITY_JWT_AUDIENCE_PUBLIC_API=[publicapi-audience] (for security reasons, use a different value here than for CAMUNDA_MODELER_SECURITY_JWT_AUDIENCE_INTERNAL_API) SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI=[provider-issuer]
Zeebe	no redirect URI	Instead, include tokenScope:"<Azure-AppRegistration-ClientID> /.default "
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]