docs: document opt-in OIDC userinfo claim augmentation for bearer tokens

[Ben-Sheppard]

Context

A new opt-in feature has been added to the Orchestration Cluster to augment bearer-token claims from the configured OIDC provider's /userinfo endpoint. This closes a gap where IdPs that only return group membership (or other authorization-relevant claims) on /userinfo — not in the JWT access token — could not drive group-based authorizations on bearer-auth flows.

Shipping in:

• main — PR feat: opt-in OIDC userinfo augmentation for bearer tokens camunda#51537 (targets 9.0)
• stable/8.9 — PR feat(8.9): opt-in OIDC userinfo augmentation for bearer tokens camunda#51549
• stable/8.8 — PR feat(8.8): opt-in OIDC userinfo augmentation for bearer tokens camunda#51547

ADR: docs/monorepo-docs/architecture/components/identity/adr/0006-userinfo-claim-augmentation-for-bearer-tokens.md (mirrored at docs/adr/identity/0003-userinfo-claim-augmentation-for-bearer-tokens.md on 8.8/8.9).

Feature is disabled by default and fail-open at runtime.

What to document

1. New section in "Special OIDC configuration cases"

Target files (all three versioned copies):

• docs/self-managed/components/orchestration-cluster/admin/special-oidc-cases.md (main / next)
• versioned_docs/version-8.9/self-managed/components/orchestration-cluster/admin/special-oidc-cases.md
• versioned_docs/version-8.8/self-managed/components/orchestration-cluster/identity/special-oidc-cases.md

Proposed section: "Augment bearer-token claims from UserInfo"

Points to cover:

• When to use it: IdP returns groups (or other claims) on /userinfo but not in the JWT access token, and you need group-based authorizations to work for bearer-auth API calls. Primary driver: SaaS IdPs where groups are a UserInfo-only claim.
• Before reaching for this: Prefer configuring the IdP to include the missing claim directly in the access token. This feature exists for deployments where that is not an option.
• Enablement: opt-in via camunda.security.authentication.oidc.user-info-augmentation.enabled=true.
• Behaviour:
  • Every bearer-auth request triggers a /userinfo call on cache miss.
  • Responses are cached per-token (keyed by iss+jti, or iss+sub+iat+exp when jti absent). Tokens that provide neither key shape bypass the cache.
  • JWT-wins merge: UserInfo cannot overwrite JWT claims. OIDC Core §5.3.2 sub integrity check: if /userinfo returns a different sub, the response is discarded and only JWT claims are used.
  • Fail-open at runtime: IdP 4xx/5xx, parse failure, sub mismatch → log ERROR, serve JWT-only claims, cache the degraded entry for negative-cache-ttl to dampen retry traffic during outages.
  • Fail-fast at startup: misconfiguration (augmentation enabled but no provider exposes a userinfo_endpoint) → application fails to start.
  • Tokens without the openid scope skip augmentation (M2M / client-credentials tokens don't benefit from /userinfo).
  • Signed UserInfo responses (application/jwt) are not supported; configure the IdP to return application/json.
• TLS trust: if the IdP exposes /userinfo behind a corporate CA, the HTTP client will automatically use a Spring SSL bundle named oidc-userinfo if one is configured. Syntax for declaring a bundle is standard Spring Boot — see Spring Boot SSL bundles reference.
• Metrics (exposed via /actuator/prometheus):
  • camunda.oidc.userinfo.cache — Caffeine cache metrics (hits, misses, evictions, size)
  • camunda.oidc.userinfo.fetch — fetch outcome counters (success, IdP error, parse failure, sub mismatch) and latency

2. Config reference additions

Target file:

• docs/self-managed/components/orchestration-cluster/core-settings/configuration/partials/_security.md

Append to the camunda.security.authentication.oidc table:

Property	Description	Default
camunda.security.authentication.oidc.user-info-augmentation.enabled	Opt-in: augment bearer-token claims from the OIDC /userinfo endpoint. Use when group (or other authorization-relevant) claims are returned on UserInfo but not in the JWT access token.	false
camunda.security.authentication.oidc.user-info-augmentation.cache-ttl	TTL for cached UserInfo responses. Tune down to propagate IdP-side membership changes faster; tune up to reduce load on the IdP. Format: ISO 8601 duration.	PT5M
camunda.security.authentication.oidc.user-info-augmentation.cache-max-size	Maximum number of cached UserInfo responses. Size for peak concurrent active tokens.	10000
camunda.security.authentication.oidc.user-info-augmentation.negative-cache-ttl	TTL for "degraded" cache entries — JWT-only claims held because the UserInfo fetch or merge failed. Lower values recover faster once the IdP returns; higher values dampen retry traffic harder during an outage. Format: ISO 8601 duration.	PT5S

3. Troubleshooting note (optional but recommended)

Target file:

• docs/self-managed/components/orchestration-cluster/admin/debugging-authentication.md (and the 8.8/8.9 equivalents)

Add a short entry: "Group-based authorization fails on bearer-auth API calls even though the user is in the right group in the IdP" → explain that some IdPs only return group membership on /userinfo and link to the new section above.

Example configs to include in the docs

Minimal enablement (YAML):

camunda:
  security:
    authentication:
      oidc:
        user-info-augmentation:
          enabled: true

Minimal enablement (env vars):

CAMUNDA_SECURITY_AUTHENTICATION_OIDC_USERINFOAUGMENTATION_ENABLED=true

Tuned for high-traffic deployment:

camunda:
  security:
    authentication:
      oidc:
        user-info-augmentation:
          enabled: true
          cache-ttl: PT10M
          cache-max-size: 50000
          negative-cache-ttl: PT30S

Versioning

All three versioned doc trees need the same content (with the 8.8 path quirk that OIDC pages live under identity/ rather than admin/):

• docs/ (main / next)
• versioned_docs/version-8.9/
• versioned_docs/version-8.8/