Debugging the authentication flow

This guide explains how to debug issues in the authentication and authorization flow of the Orchestration Cluster.
These techniques help identify where and why access may be denied or restricted.

Common questions you can answer with these steps:

• Why can’t I log into the web applications?
• Why does my search request return empty results?

The flow consists of three key steps:

1. Request authentication

   • Input: HTTP request
   • Output: Spring Authentication object with user identity
   • Layer: Spring Security

2. Establish Orchestration Cluster user context

   • Input: Spring Authentication
   • Output: CamundaAuthentication object with roles, groups, and tenant memberships
   • Layer: Orchestration Cluster authentication

3. Apply authorizations

   • Input: CamundaAuthentication
   • Output: Application data, filtered by authorizations
   • Layer: Orchestration Cluster search and workflow engine

Typical failure points:

• Step 1: Invalid credentials (for example, failed Basic authentication).
• Step 2: Missing role or group memberships.
• Step 3: Authorizations not yet configured or missing.

To isolate the issue, use:

• Review logs
• Review the startup warnings
• Requests fail when an identity provider is unreachable
• Review data
• Review configuration
• Inspect the JWT
• Test the IdP directly

Review logs

Enable detailed logging to trace authentication decisions:

Application.yaml

logging.level:
  org.springframework.security: TRACE
  io.camunda:
    authentication: DEBUG
    security: DEBUG

Environment variables

LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY=TRACE
LOGGING_LEVEL_IO_CAMUNDA_AUTHENTICATION=DEBUG
LOGGING_LEVEL_IO_CAMUNDA_SECURITY=DEBUG

With these settings, you can trace request handling and how Spring Security filter chains determine authentication outcomes.

Review the startup warnings

The Orchestration Cluster checks its OIDC configuration at startup, without contacting the provider, and writes a warning for each problem it finds. It still starts, so a login can fail later for a problem that was already reported at startup. Read these warnings first.

• The logger io.camunda.security.spring.oidc.ScopedClientRegistrationFactory reports a missing client ID, an incomplete set of endpoints, an unusable scope, and a redirect URI that cannot expand to a usable callback URL. Each entry names the provider.
• The logger io.camunda.security.spring.oidc.OidcRedirectionEndpoint reports a redirect URI with no callback path, or with a path that has no leading slash. The cluster then uses {baseUrl}/sso-callback, and the login completes.

A redirect URI that is unusable in any other way stays as configured. See redirect URI.

These checks run once while the cluster starts. The cluster writes each warning one time, and it does not repeat or limit them. The configuration cannot change while the cluster runs, so a new warning needs a restart. A change on the identity provider, such as a different list of permitted redirect URIs, writes no warning at all. Use a synthetic login to detect such a change.

Requests fail when an identity provider is unreachable

The Orchestration Cluster contacts an OIDC provider at the first request that needs it, and not at startup. The cluster starts and serves traffic while a provider is unreachable. Only the requests that need that provider fail.

While a provider is unreachable:

• A request that needs a provider the cluster did not resolve yet fails with a server error, and not with an authentication error. This can include a browser login and an API request with a token from that provider.
• A session that the cluster authenticated before the outage keeps its access token until the token expires. The refresh that follows fails, the cluster ends the session, and the request gets an authentication error.
• All other requests succeed.
• Each new request tries again. The cluster serves the failed traffic again when the provider answers. You do not need to restart the cluster.
• The cluster holds no queue of failed requests, and it makes no attempt in the background. One request makes one attempt, so the load on the provider is the rate of the requests that need it. The cluster keeps the first result that it gets, so the attempts stop when the provider answers.
• A failed request writes a warning that names the step that failed — a client registration, the access-token decoder, or a UserInfo endpoint lookup — and the provider with its issuer. The cluster writes at most one warning each minute for each combination of step and provider. A minute without a failed request writes nothing.

An unreachable provider no longer stops the cluster from starting. For a provider that the cluster resolves through its issuer URI, this warning is your only signal that part of the authentication traffic fails. Monitor your log pipeline for WARN entries of the logger io.camunda.security.spring.oidc.DeferredOidcResolution. Each entry starts with Failed to resolve.

The warning follows the traffic, and it is not a health check of the provider. A cluster that gets no request for an unreachable provider writes no warning. Use a synthetic login or a synthetic API request if you must detect such an outage before a user does.

The warning gives the step that failed and the provider with its issuer. It does not give the endpoint that did not answer. Read the exception that the warning attaches to find that endpoint. For a provider that is configured with an issuer URI, this is the discovery endpoint <issuer-uri>/.well-known/openid-configuration. Then make sure that the cluster can reach that endpoint. See test the IdP directly.

A provider that sets jwk-set-uri or user-info-uri needs no discovery. A failure of these endpoints therefore gives a different signal:

• An unreachable jwk-set-uri fails the token validation, and it writes no warning or error of its own. Set LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY=DEBUG to see the cause. No log entry tells you about this failure at the default level, so use a synthetic API request with a valid token to detect it.
• An unreachable user-info-uri writes an ERROR entry of the logger io.camunda.security.spring.oidc.CachingOidcClaimsProvider that gives the issuer and the endpoint. The request then succeeds with the claims of the token only, so the user can lose the groups, roles, or tenants that the UserInfo response adds.

Review data

To review the assignment of users and clients to roles, groups, or tenants—as well as which authorizations are in place—you can use the Admin UI.

If you do not have access to the API, you can also check the same data in the following Elasticsearch/OpenSearch indexes:

• camunda-authorization
• camunda-group
• camunda-mapping-rule
• camunda-role
• camunda-tenant
• camunda-user
• camunda-web-session

Review configuration

To review the effective configuration of your Orchestration Cluster, you can call the Spring Boot Actuator endpoint at:

<server>:<port>/actuator/configprops

For example, with a Camunda 8 Run installation, this endpoint is available at http://localhost:9600/actuator/configprops.

In other setups, replace http://localhost:9600 with the URL to your Orchestration Cluster's actuator port and endpoint. Note that the actuator port differs from the Orchestration Cluster API port and may not always be accessible, depending on your deployment setup.

Here is an excerpt from an example installation:

{
  ...
  "camunda.security-io.camunda.application.commons.security.CamundaSecurityConfiguration$CamundaSecurityProperties": {
    "prefix": "camunda.security",
    "properties": {
      ...
      "authentication": {
        "method": "OIDC",
        "authenticationRefreshInterval": "PT30S",
        "unprotectedApi": false,
        "oidc": {
          "issuerUri": "https://myoidcprovider.example.com",
          "clientId": "my-oidc-client",
          "clientSecret": "******",
          "grantType": "authorization_code",
          "redirectUri": "http://localhost:8080/sso-callback",
          "scope": [
            "openid",
            "profile"
          ],
          "usernameClaim": "preferred_username",
          "clientIdClaim": "oid",
          "authorizeRequest": {}
        }
      }
      ...
    }
  }
}

In the response, review the settings in the camunda.security section, compare them against the configuration reference, and confirm they match your intended values.

This is especially useful if you are applying the configuration via Helm values or environment variables and want to double-check that your configuration was applied correctly.

Inspect the JWT

Most "insufficient permissions" or "empty results" issues at step 2 or 3 of the flow trace back to a mismatch between what's in the access token and what Camunda expects.

Decode the token presented to the Orchestration Cluster and check:

• Confirm the claim configured as usernameClaim or clientIdClaim is present and has the value you expect.
• Compare any claims your mapping rules match against with the claim name and value configured on each mapping rule. A wrong claim name, unexpected casing, or incorrect operator for an array claim can prevent a mapping rule from granting the expected role, group, or tenant.
• Confirm the aud claim matches the audience configured for that client.

Test the IdP directly

To determine whether a failure originates at your identity provider or within Camunda, request a token directly from the IdP, bypassing Camunda entirely:

curl -X POST '<token-endpoint>' \
  -d 'client_id=<client-id>' \
  -d 'client_secret=<client-secret>' \
  -d 'grant_type=client_credentials' \
  -d 'scope=openid'

• If the request fails or returns an error, investigate the IdP configuration, grant type, network, or firewall. The problem isn't specific to Camunda.
• If the request succeeds, decode the returned token as described in inspect the JWT and confirm it contains the claims Camunda expects. If the token contains the expected claims but Camunda still rejects the request, check Camunda's authorization configuration, including mapping rules, roles, and authorizations.

For interactive browser logins, complete the login flow directly on your IdP's hosted login page before troubleshooting Camunda. This confirms whether the user can authenticate with the IdP.