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. To connect to a Keycloak authentication provider, see our guide on using an existing Keycloak.
In this guide, we step through the configuration required to connect Camunda to your authentication provider.
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
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.
Internally the Camunda components use Identity to handle authentication with your OIDC provider. However, the Identity UI is not available for this version.
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.
- Make a note of the following values for each application you create:
- Client ID
- Client secret
- Audience
- Set the following environment variables for the component you are configuring an app for:
- 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 2>
CAMUNDA_IDENTITY_CLIENT_SECRET=<Client secret from Step 2>
CAMUNDA_IDENTITY_AUDIENCE=<Audience from Step 2>
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"
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
.
Steps
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.
- Navigate to the new application's Overview page, and make note of the Client ID.
- Within your new application, configure a platform for the appropriate component:
- Web: Operate, Tasklist, Optimize, Identity
- Single-page application: Modeler
- Add your component's Microsoft Entra ID redirect URI, found under Component-specific configuration.
- Create a new client secret, and note the new secret's value for later use.
- Set the following environment variables for the component you are configuring an app for:
- 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>
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
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 from Step 2>
clientApiAudience: <Client ID from Step 2>
publicApiAudience: <Audience for using Web Modeler's API. For security reasons, use a different value than for clientApiAudience>
redirectUrl: <See the Helm value in the table below>
connectors:
clientId: <Client ID from Step 2>
existingSecret: <Client secret from Step 5>
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 |
---|---|---|
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 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 | 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 internal API, and one for the external/public API. Using a different OIDC provider than Keycloak currently disables all checks of the permissions claim both for using Web Modeler via the UI and via the public API. 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 " . 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] |