docs: document omit_assertion_audience for the JWT bearer grant#2628
Open
alnr wants to merge 3 commits into
Open
docs: document omit_assertion_audience for the JWT bearer grant#2628alnr wants to merge 3 commits into
alnr wants to merge 3 commits into
Conversation
Describe the new oauth2.grant.jwt.copy_assertion_audience toggle in the JWT profile guide. The option controls whether the assertion JWT's audience is copied into the resulting access token and defaults to true. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Documents the new oauth2.grant.jwt.copy_assertion_audience toggle for the urn:ietf:params:oauth:grant-type:jwt-bearer flow in the Hydra JWT guide, explaining the default audience-copy behavior and how to disable it.
Changes:
- Add a new section describing how assertion
audvalues are copied into the resulting access token by default. - Document how to disable this behavior via
copy_assertion_audience: falseinhydra.yml. - Note the default value and availability (self-hosted OSS + Enterprise License deployments).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…ault Update the JWT profile guide for the renamed oauth2.grant.jwt.omit_assertion_audience setting. Per RFC 7523, the assertion audience is no longer copied into the access token by default. Document the new default and the Ory Network migration behavior for existing vs new projects. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
alnr
changed the title
unatasha8
requested changes
Jun 16, 2026
Apply technical-writing review feedback on the JWT profile guide: - Reframe the heading and intro to contrast the assertion's "aud" (the authorization server) with the access token's "aud" (the resource servers / APIs the token is for). - Use the fully qualified setting key oauth2.grant.jwt.omit_assertion_audience. - State the default is true (omit) for Ory OSS, OEL, and Ory Network, dropping the temporal "before/after this change" wording (migration details live in the release notes). - Clarify the assertion "aud" is the OAuth2 token endpoint URL, and note in the issued-token example that the assertion "aud" is not copied by default. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the
oauth2.grant.jwt.omit_assertion_audiencesetting in the JWT profile guide (docs/hydra/guides/jwt.mdx).Per RFC 7523, the assertion's
audclaim identifies the authorization server, not the audience of the issued access token. Ory therefore omits the assertion audience from the access token by default.true(omit) for self-hosted Ory Hydra (OSS), Ory Enterprise License, and new Ory Network projects.omit_assertion_audience: falseto restore the legacy behavior of copying the assertion audience.This is a breaking change. Documents the behavior introduced in ory/hydra#4076 (mirrored in ory-corp/cloud#11236).
🤖 Generated with Claude Code