docs: document omit_assertion_audience for the JWT bearer grant by alnr · Pull Request #2628 · ory/docs

alnr · 2026-06-15T21:13:23Z

Summary

Documents the oauth2.grant.jwt.omit_assertion_audience setting in the JWT profile guide (docs/hydra/guides/jwt.mdx).

Per RFC 7523, the assertion's aud claim identifies the authorization server, not the audience of the issued access token. Ory therefore omits the assertion audience from the access token by default.

Default true (omit) for self-hosted Ory Hydra (OSS), Ory Enterprise License, and new Ory Network projects.
Existing Ory Network projects keep the previous copy behavior unless they set the option explicitly.
Set omit_assertion_audience: false to 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

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>

Copilot

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 aud values are copied into the resulting access token by default.
Document how to disable this behavior via copy_assertion_audience: false in hydra.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.

alnr · 2026-06-16T19:58:35Z

+By default, Ory copies the `aud` (audience) values from the assertion JWT into the access token it issues. The audience of the
+resulting access token then includes every value from the assertion's `aud` claim, including the OAuth2 token URL.


Fixed — the validation requirement now says "OAuth2 token endpoint URL".

alnr · 2026-06-16T19:58:37Z

+To stop the assertion's audience from being granted to the access token, set `copy_assertion_audience` to `false`. Ory then issues
+the access token without the audience values from the assertion:


Fixed — the guide now uses the fully qualified key oauth2.grant.jwt.omit_assertion_audience.

…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>

unatasha8 · 2026-06-16T01:40:07Z

  --replace "/oauth2/grant/jwt/max_ttl=1h"
 ```

+### Assertion audience in the access token


Suggested change

### Assertion audience in the access token

### Do not use the assertion's 'aud' value as the access token's 'aud' value.

Applied — reframed the heading to contrast the assertion's aud (the authorization server) with the access token's aud. Used code formatting for aud to match the rest of the guide.

unatasha8 · 2026-06-16T01:43:27Z

+### Assertion audience in the access token
+
+Per [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523), the assertion's `aud` (audience) claim identifies the authorization server
+as the intended recipient of the JWT. It does not define the audience of the issued access token. By default, Ory therefore does


Suggested change

as the intended recipient of the JWT. It does not define the audience of the issued access token. By default, Ory therefore does

as the intended recipient of the JWT. The issued access token's `aud` value should be the resource server(s) or the APIs that the token is meant for. By default, Ory therefore does

Applied your suggestion verbatim.

unatasha8 · 2026-06-16T01:45:57Z

+
+:::note
+
+The default is `true` (omit) for self-hosted Ory Hydra (open source), Ory Enterprise License deployments, and Ory Network projects


Suggested change

The default is `true` (omit) for self-hosted Ory Hydra (open source), Ory Enterprise License deployments, and Ory Network projects

The default value is `true` (omit) for Ory Hydra (Ory OSS, Ory OEL, and Ory Network deployments).

Applied verbatim.

unatasha8 · 2026-06-16T01:48:54Z

+:::note
+
+The default is `true` (omit) for self-hosted Ory Hydra (open source), Ory Enterprise License deployments, and Ory Network projects
+created after this change. Ory Network projects created earlier keep the previous behavior of copying the assertion audience; set


Wording like 'after' or 'before' this change is confusing to readers. How would they know when the change occurred? This type of info (breaking changes) are best communicated via release notes or other comms where a date can be referenced. The Documentation should cover what is currently true and accurate.

Agreed — removed the 'before/after this change' wording. The note now states only the current default; the migration behavior for existing Ory Network projects is covered in the release notes / changelog.

unatasha8 · 2026-06-16T01:55:38Z

+as the intended recipient of the JWT. It does not define the audience of the issued access token. By default, Ory therefore does
+**not** copy the assertion's `aud` values into the access token.
+
+The `omit_assertion_audience` setting controls this behavior:


Suggested change

The `omit_assertion_audience` setting controls this behavior:

The `omit_assertion_audience` setting controls whether or not the assertion's 'aud' value is copied to the access token:

Applied, and used the fully qualified key oauth2.grant.jwt.omit_assertion_audience (also addresses Copilot's note).

unatasha8 · 2026-06-16T02:01:38Z

+Per [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523), the assertion's `aud` (audience) claim identifies the authorization server
+as the intended recipient of the JWT. It does not define the audience of the issued access token. By default, Ory therefore does
+**not** copy the assertion's `aud` values into the access token.
+


I suggest the https://www.ory.com/docs/hydra/guides/jwt#exchanging-jwt-assertion-for-access-token topic is updated to clearly show the distinction between the assertion 'aud' and the access token's 'aud' values

Under 'Exchanging JWT assertion for access token,' in the Sample call/JWT used/Scopes in JWT tabs: Change 'Example claims of JSON Web Token' to 'Example claims of the issued access token'
Update the example to include the access token's 'aud' value that clearly shows it is the resource server(s) / the APIs the token is meant for and not the authorization server.

Renamed the example to 'Example claims of the issued access token' and added a comment there clarifying the assertion's aud is not copied by default. I did not add a resource-server aud to the example because, with the default (omit), Ory does not currently populate the access token's aud from the request — wiring the standard audience/resource request parameter into this grant is tracked separately in ory-corp/cloud#12362. Once that lands I'll update the example to show a resource-server aud. Let me know if you'd prefer an aspirational example in the meantime.

Sounds good!

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

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>

Copilot AI review requested due to automatic review settings June 15, 2026 21:13

alnr requested review from aeneasr, unatasha8 and vinckr as code owners June 15, 2026 21:13

github-actions Bot added the Needs Triage label Jun 15, 2026

ory-bot assigned alnr Jun 15, 2026

Copilot started reviewing on behalf of alnr June 15, 2026 21:13 View session

Copilot AI reviewed Jun 15, 2026

View reviewed changes

vercel Bot deployed to Preview June 15, 2026 21:20 View deployment

github-actions Bot removed the Needs Triage label Jun 15, 2026

alnr changed the title ~~docs: document copy_assertion_audience for the JWT bearer grant~~ docs: document omit_assertion_audience for the JWT bearer grant Jun 15, 2026

vercel Bot deployed to Preview June 15, 2026 22:54 View deployment

unatasha8 requested changes Jun 16, 2026

View reviewed changes

alnr requested a review from Copilot June 16, 2026 12:27

Copilot started reviewing on behalf of alnr June 16, 2026 12:27 View session

Copilot AI reviewed Jun 16, 2026

View reviewed changes

alnr requested a review from unatasha8 June 16, 2026 19:58

vercel Bot deployed to Preview June 16, 2026 20:05 View deployment

		By default, Ory copies the `aud` (audience) values from the assertion JWT into the access token it issues. The audience of the
		resulting access token then includes every value from the assertion's `aud` claim, including the OAuth2 token URL.

		To stop the assertion's audience from being granted to the access token, set `copy_assertion_audience` to `false`. Ory then issues
		the access token without the audience values from the assertion:

	### Assertion audience in the access token
	### Do not use the assertion's 'aud' value as the access token's 'aud' value.

	as the intended recipient of the JWT. It does not define the audience of the issued access token. By default, Ory therefore does
	as the intended recipient of the JWT. The issued access token's `aud` value should be the resource server(s) or the APIs that the token is meant for. By default, Ory therefore does


		:::note

		The default is `true` (omit) for self-hosted Ory Hydra (open source), Ory Enterprise License deployments, and Ory Network projects

	The default is `true` (omit) for self-hosted Ory Hydra (open source), Ory Enterprise License deployments, and Ory Network projects
	The default value is `true` (omit) for Ory Hydra (Ory OSS, Ory OEL, and Ory Network deployments).

	The `omit_assertion_audience` setting controls this behavior:
	The `omit_assertion_audience` setting controls whether or not the assertion's 'aud' value is copied to the access token:

Conversation

alnr commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

unatasha8 Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

alnr commented Jun 15, 2026 •

edited

Loading

unatasha8 Jun 17, 2026 •

edited

Loading