Skip to content

Commit acf25a2

Browse files
authored
fix: org_id claim docs (#2676)
1 parent 7982dbe commit acf25a2

2 files changed

Lines changed: 27 additions & 0 deletions

File tree

docs/kratos/organizations/organizations.mdx

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -306,6 +306,18 @@ If the identity's `organization_id` points to an organization that was deleted,
306306
scoped flow. This keeps account recovery and self-service settings working for users who were offboarded from a deleted
307307
organization.
308308

309+
## Organization ID in OAuth2 and OpenID Connect tokens
310+
311+
When an organization member signs in through an Ory OAuth2 / OpenID Connect flow using the hosted consent screen (Account
312+
Experience), the issued tokens carry the identity's organization ID:
313+
314+
- `organization_id` in the ID token claims.
315+
- `organization_id` in the access token session data, surfaced under `ext` in JWT access tokens and promotable to a top-level
316+
claim.
317+
318+
Identities that don't belong to an organization get no such claim. For configuration details and behavior, see
319+
[Organization ID claim](../../oauth2-oidc/jwt-access-token.mdx#organization-id-claim).
320+
309321
## SAML
310322

311323
SAML (Security Assertion Markup Language) is an XML-based open standard used for exchanging authentication and authorization data

docs/oauth2-oidc/jwt-access-token.mdx

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -239,3 +239,18 @@ Without `preserve_ext_claims`, `another_claim` would not appear in the token.
239239

240240
This setting has no effect when `mirror_top_level_claims` is `true`, because mirroring already includes all custom claims in
241241
`ext`.
242+
243+
## Organization ID claim
244+
245+
For Ory Network projects that use [organizations](../kratos/organizations/organizations.mdx) for B2B SSO, tokens issued through
246+
the hosted consent screen (Account Experience) include the member's organization ID:
247+
248+
- **ID token:** `organization_id` is added to the ID token claims.
249+
- **Access token:** `organization_id` is added to the session data. In JWT access tokens it appears under `ext`, and you can
250+
promote it to a top-level claim by adding it to [`allowed_top_level_claims`](#add-custom-claims-to-top-level).
251+
252+
Identities that don't belong to an organization get no `organization_id` claim. The claim is omitted, not set to `null`.
253+
254+
Claims are snapshotted at consent time. Refresh token grants reuse the stored session, so a change to an identity's organization
255+
takes effect on the next authorization flow. Projects with a custom consent UI control their own session claims and are
256+
unaffected. Client credentials flows have no identity and never include the claim.

0 commit comments

Comments
 (0)