Skip to content

Commit b89f633

Browse files
alnrclaude
andcommitted
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) <noreply@anthropic.com>
1 parent 086d6d7 commit b89f633

1 file changed

Lines changed: 11 additions & 10 deletions

File tree

docs/hydra/guides/jwt.mdx

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -139,11 +139,13 @@ In the example above, the JWT is passed in the `assertion` parameter of the requ
139139
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
140140
valid, the OAuth2 token endpoint will issue an access token that can be used to access protected resources:
141141

142-
```json5 title="Example claims of JSON Web Token"
142+
```json5 title="Example claims of the issued access token"
143143
{
144144
iss: "https://$PROJECT_SLUG.projects.oryapis.com/",
145145
sub: "7146dd0b-f243-43ba-815c-7a00216b4823",
146146
scp: ["read"],
147+
// The assertion's "aud" (the authorization server) is not copied into the access token by default.
148+
// See "Do not use the assertion's aud value as the access token's aud value" below.
147149
// ...
148150
}
149151
```
@@ -158,7 +160,7 @@ through the following steps:
158160
- The JWT must contain a `sub` (subject) claim that identifies the principal as the subject of the JWT (e.g., the user ID). This
159161
value should match the `subject` value of the trust relationship unless `allow_any_subject` is `true`.
160162
- The JWT must contain an `aud` (audience) claim with a value that identifies the authorization server as an intended audience.
161-
The value should be the OAuth2 Token URL.
163+
The value should be the OAuth2 token endpoint URL.
162164
- The JWT must contain an `exp` (expiration time) claim that restricts the time window during which the JWT can be used. This can
163165
be controlled through the `/oauth2/grant/jwt/max_ttl` setting.
164166
- The JWT may contain an `nbf` (not before) claim that identifies the time before which the token must not be accepted for
@@ -185,30 +187,29 @@ ory patch oauth2-config \
185187
--replace "/oauth2/grant/jwt/max_ttl=1h"
186188
```
187189

188-
### Assertion audience in the access token
190+
### Do not use the assertion's `aud` value as the access token's `aud` value
189191

190192
Per [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523), the assertion's `aud` (audience) claim identifies the authorization server
191-
as the intended recipient of the JWT. It does not define the audience of the issued access token. By default, Ory therefore does
192-
**not** copy the assertion's `aud` values into the access token.
193+
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
194+
token is meant for. By default, Ory therefore does **not** copy the assertion's `aud` values into the access token.
193195

194-
The `omit_assertion_audience` setting controls this behavior:
196+
The `oauth2.grant.jwt.omit_assertion_audience` setting controls whether or not the assertion's `aud` value is copied to the access
197+
token:
195198

196199
```yaml title="hydra.yml"
197200
oauth2:
198201
grant:
199202
jwt:
200203
# true (default): the assertion audience is omitted from the access token.
201-
# false: the assertion audience is copied into the access token (legacy behavior).
204+
# false: the assertion audience is copied into the access token.
202205
omit_assertion_audience: true
203206
```
204207
205208
Set it to `false` if your clients rely on the assertion's `aud` values being present in the access token.
206209

207210
:::note
208211

209-
The default is `true` (omit) for self-hosted Ory Hydra (open source), Ory Enterprise License deployments, and Ory Network projects
210-
created after this change. Ory Network projects created earlier keep the previous behavior of copying the assertion audience; set
211-
`omit_assertion_audience` explicitly to change it.
212+
The default value is `true` (omit) for Ory Hydra (Ory OSS, Ory OEL, and Ory Network deployments).
212213

213214
:::
214215

0 commit comments

Comments
 (0)