From 9aae716712b09c04b201aaaa8f6d44137abbea83 Mon Sep 17 00:00:00 2001 From: Arne Luenser Date: Mon, 15 Jun 2026 23:13:06 +0200 Subject: [PATCH 1/3] docs: document copy_assertion_audience for the JWT bearer grant 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) --- docs/hydra/guides/jwt.mdx | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/hydra/guides/jwt.mdx b/docs/hydra/guides/jwt.mdx index 68aba4f2fc..ea7b843437 100644 --- a/docs/hydra/guides/jwt.mdx +++ b/docs/hydra/guides/jwt.mdx @@ -185,6 +185,24 @@ ory patch oauth2-config \ --replace "/oauth2/grant/jwt/max_ttl=1h" ``` +### Copying the assertion audience into the access token + +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: + +```yaml title="hydra.yml" +oauth2: + grant: + jwt: + copy_assertion_audience: false +``` + +The setting defaults to `true`, which preserves the previous behavior. It's available in self-hosted Ory Hydra (open source) and +Ory Enterprise License deployments. + ## JWTs for client authentication Ory provides support for OAuth 2.0 Client Authentication with RSA and ECDSA private/public key pairs and supports signing From 75359b6a7923bda95e801d38b303316880c14848 Mon Sep 17 00:00:00 2001 From: Arne Luenser Date: Tue, 16 Jun 2026 00:46:55 +0200 Subject: [PATCH 2/3] docs: omit_assertion_audience now omits the assertion audience by default 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) --- docs/hydra/guides/jwt.mdx | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/hydra/guides/jwt.mdx b/docs/hydra/guides/jwt.mdx index ea7b843437..824ff419f4 100644 --- a/docs/hydra/guides/jwt.mdx +++ b/docs/hydra/guides/jwt.mdx @@ -185,23 +185,32 @@ ory patch oauth2-config \ --replace "/oauth2/grant/jwt/max_ttl=1h" ``` -### Copying the assertion audience into the access token +### Assertion audience in the access token -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. +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. -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: +The `omit_assertion_audience` setting controls this behavior: ```yaml title="hydra.yml" oauth2: grant: jwt: - copy_assertion_audience: false + # true (default): the assertion audience is omitted from the access token. + # false: the assertion audience is copied into the access token (legacy behavior). + omit_assertion_audience: true ``` -The setting defaults to `true`, which preserves the previous behavior. It's available in self-hosted Ory Hydra (open source) and -Ory Enterprise License deployments. +Set it to `false` if your clients rely on the assertion's `aud` values being present in the access token. + +:::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 +`omit_assertion_audience` explicitly to change it. + +::: ## JWTs for client authentication From 787a274bc84be2fc06828f8dcefafc945a434429 Mon Sep 17 00:00:00 2001 From: Arne Luenser Date: Tue, 16 Jun 2026 21:57:34 +0200 Subject: [PATCH 3/3] docs: address review on the assertion-audience section 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) --- docs/hydra/guides/jwt.mdx | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/hydra/guides/jwt.mdx b/docs/hydra/guides/jwt.mdx index 824ff419f4..ca1e0e4544 100644 --- a/docs/hydra/guides/jwt.mdx +++ b/docs/hydra/guides/jwt.mdx @@ -139,11 +139,13 @@ In the example above, the JWT is passed in the `assertion` parameter of the requ The OAuth2 token endpoint will then verify the signature of the JWT and check the claims to ensure that it is valid. If the JWT is valid, the OAuth2 token endpoint will issue an access token that can be used to access protected resources: -```json5 title="Example claims of JSON Web Token" +```json5 title="Example claims of the issued access token" { iss: "https://$PROJECT_SLUG.projects.oryapis.com/", sub: "7146dd0b-f243-43ba-815c-7a00216b4823", scp: ["read"], + // The assertion's "aud" (the authorization server) is not copied into the access token by default. + // See "Do not use the assertion's aud value as the access token's aud value" below. // ... } ``` @@ -158,7 +160,7 @@ through the following steps: - The JWT must contain a `sub` (subject) claim that identifies the principal as the subject of the JWT (e.g., the user ID). This value should match the `subject` value of the trust relationship unless `allow_any_subject` is `true`. - The JWT must contain an `aud` (audience) claim with a value that identifies the authorization server as an intended audience. - The value should be the OAuth2 Token URL. + The value should be the OAuth2 token endpoint URL. - The JWT must contain an `exp` (expiration time) claim that restricts the time window during which the JWT can be used. This can be controlled through the `/oauth2/grant/jwt/max_ttl` setting. - The JWT may contain an `nbf` (not before) claim that identifies the time before which the token must not be accepted for @@ -185,20 +187,21 @@ ory patch oauth2-config \ --replace "/oauth2/grant/jwt/max_ttl=1h" ``` -### Assertion audience in the access token +### Do not use the assertion's `aud` value as the access token's `aud` value 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. +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 **not** copy the assertion's `aud` values into the access token. -The `omit_assertion_audience` setting controls this behavior: +The `oauth2.grant.jwt.omit_assertion_audience` setting controls whether or not the assertion's `aud` value is copied to the access +token: ```yaml title="hydra.yml" oauth2: grant: jwt: # true (default): the assertion audience is omitted from the access token. - # false: the assertion audience is copied into the access token (legacy behavior). + # false: the assertion audience is copied into the access token. omit_assertion_audience: true ``` @@ -206,9 +209,7 @@ Set it to `false` if your clients rely on the assertion's `aud` values being pre :::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 -`omit_assertion_audience` explicitly to change it. +The default value is `true` (omit) for Ory Hydra (Ory OSS, Ory OEL, and Ory Network deployments). :::