fix(identity): add known limitation aud required

[leiicamundi]

Description

Related to camunda/camunda#44650 (comment), this PR documents the known limitation of oidc providers missing the aud field.

This pull request updates the documentation for configuring OpenID Connect (OIDC) providers with Camunda 8 Self-Managed, clarifying the requirement for the aud (audience) claim in access tokens and documenting known limitations with certain OIDC providers, especially AWS Cognito. The changes aim to help users avoid misconfiguration and authentication issues related to missing audience claims in tokens.

Key documentation updates:

OIDC Audience Claim Requirement:

• Added a note in the setup instructions emphasizing that the OIDC provider must include the aud (audience) claim in access tokens, with a reference to a new limitations section for providers that do not meet this requirement. [1] [2]

Known Limitations Section:

• Introduced a new "OIDC provider known limitations" section explaining that Camunda requires the aud claim for token validation, as per the OpenID Connect specification. It highlights that some providers, particularly in machine-to-machine (M2M) flows, may not include this claim. [1] [2]
• Added specific documentation about AWS Cognito's behavior: Cognito omits the aud claim in M2M access tokens (using client_id instead), which causes authentication failures with Camunda. The section also notes that this limitation applies to any OIDC provider that does not supply the aud claim and provides troubleshooting guidance and a link to a related GitHub issue. [1] [2]

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support. (add bug or support label)
• This is already available but undocumented and should be released within a week. (add available & undocumented label)
• This is on a specific schedule and the assignee will coordinate a release with the Documentation team. (create draft PR and/or add hold label)
• This is part of a scheduled alpha or minor. (add alpha or minor label)
• There is no urgency with this change (add low prio label)

PR Checklist

• The commit history of this PR is cleaned up, using {type}(scope): {description} commit message(s)

• My changes are for an upcoming minor release and are in the /docs directory (version 8.9).
• My changes are for an already released minor and are in a /versioned_docs directory.

• I added a DRI, team, or delegate as a reviewer for technical accuracy and grammar/style:
  • Engineering team review
  • Technical writer review via @camunda/tech-writers unless working with an embedded writer.

[Copilot]

Pull request overview

Updates the Management Identity “Connect to an OIDC provider” documentation to clarify that Camunda’s OIDC integration requires access tokens with an aud claim, and to document known provider limitations (notably AWS Cognito) that can break M2M authentication.

Changes:

• Added a prerequisite note that access tokens must contain an aud claim.
• Added an “OIDC provider known limitations” section describing aud enforcement and AWS Cognito’s M2M behavior.
• Applied the same documentation updates to both “next” docs and the versioned 8.8 docs.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docs/self-managed/components/management-identity/configuration/connect-to-an-oidc-provider.md	Adds aud-claim prerequisite note and new limitations section (incl. AWS Cognito).
versioned_docs/version-8.8/self-managed/components/management-identity/configuration/connect-to-an-oidc-provider.md	Mirrors the same aud/limitations documentation for v8.8.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[leiicamundi]

Thanks for the review @npepinpe @christinaausley and @StevePascoe.

I made the suggested modifications. Regarding the matrix of tested providers, I agree but consider it should be backed by @camunda/qa-engineering

[github-actions]

The preview environment relating to the commit af3ade9 has successfully been deployed. You can access it at https://preview.docs.camunda.cloud/pr-7874/

[christinaausley]

Approving from a tech writers perspective, though there may be engineering adjustments.