Organizations in tokens (client guide)¶
This page is for developers of an application that signs users in with HelixIAM and serves several customer organizations: how to learn which organization a user is working in, how to read all of their organizations, and how to switch silently.
The active organization¶
A sign-in settles on one active organization, in this order:
- the
organizationparameter on the authorization request (the organization's id or name); - the user's email domain, when it is a verified domain of an organization (an identifier-first step on the sign-in page);
- the organization picker, when the user is a member of more than one organization.
If the user has one membership, that organization is active. If there is none, there is no active organization and no organization claim. The issuer never changes: it is the realm's, whatever the organization.
The active organization is kept for the session and on the authorization, so a refresh token keeps it. Membership is checked again on every token: a user who is no longer a member of the active organization gets tokens without the claim, not an error.
Claims¶
organization: the active organization¶
Always present while there is an active organization (ID token, access token and userinfo), without any extra scope:
{
"iss": "https://id.example.com/realms/acme",
"sub": "…",
"organization": {
"id": "7c0d0d0e-…",
"name": "northwind-traders",
"roles": ["Org admin", "HR"]
}
}
roles are the organization roles the user holds there: direct grants plus the roles inherited through the units they belong to. A member without roles has "roles": [].
organizations: every membership (scope organizations)¶
The array of all of the user's organizations, in the same shape, is released only when the scope organizations is granted:
{
"organizations": [
{ "id": "7c0d0d0e-…", "name": "northwind-traders", "roles": ["Org admin", "HR"] },
{ "id": "b2e41a90-…", "name": "fabrikam-ltd", "roles": [] }
]
}
Every realm has a client scope named organizations. To receive the claim, the client must be allowed that scope (Client → Scopes) and request it. Both claim names are reserved: a claim mapping cannot overwrite them. Neither claim is issued on client_credentials tokens or in impersonation sessions.
The organizations claim needs the scope
A token carries organizations only when the scope organizations is granted. Upgrading from an installation where every token carried it: see the breaking changes.
Example: sign in to a given organization¶
GET https://id.example.com/realms/acme/oauth2/authorize
?response_type=code
&client_id=crm-web
&redirect_uri=https%3A%2F%2Fcrm.example.com%2Fcallback
&scope=openid%20profile%20email%20organizations
&organization=northwind-traders
&state=af0ifjsldkj
&nonce=n-0S6_WzA2Mj
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
The user signs in (or is already signed in). organization=northwind-traders makes that organization active and shows its branding. If the user is not a member of it:
- when the organization has
requireMembershipon, the request returns to yourredirect_uriwitherror=access_denied(and yourstate); - otherwise the organization is not made active (the sign-in falls back to the normal rules).
requireMembership also applies when the organization was determined by the user's email domain or the picker, so leaving the parameter out does not skip it.
After the code exchange at /realms/acme/oauth2/token, the ID token and access token carry organization (and organizations, since the scope was requested).
Switching the active organization silently¶
To move the user to another of their organizations without showing a page, repeat the authorization request with the other organization and prompt=none:
GET https://id.example.com/realms/acme/oauth2/authorize
?response_type=code
&client_id=crm-web
&redirect_uri=https%3A%2F%2Fcrm.example.com%2Fcallback
&scope=openid%20profile%20email
&organization=fabrikam-ltd
&prompt=none
&state=k3Jd82
&nonce=Zq91xA
&code_challenge=…
&code_challenge_method=S256
The active organization belongs to the SSO session, so a switch made by one client changes the organization of the session's other clients on their next token. Best done in a hidden iframe or a redirect your application handles. The result arrives at your redirect_uri:
| Outcome | Response |
|---|---|
The user is a member of fabrikam-ltd and its policy is met |
A new code; the tokens it yields carry organization for fabrikam-ltd. The SSO session stays. |
The user is not a member of fabrikam-ltd |
error=access_denied |
| The organization's policy needs more from the user (for example MFA they have not completed in this session) | error=interaction_required; repeat the request without prompt=none so the user can complete it |
| The user has no SSO session, or the organization's maximum session time is exceeded | error=login_required |
Handle interaction_required and login_required by sending the user through a normal (interactive) authorization request with the same organization parameter.
Pushed and signed authorization requests
With a pushed authorization request (PAR, request_uri), put organization and prompt in the pushed request: they are read from it, and the answer goes to its pushed redirect_uri with its pushed state. With a signed request object (request), put them in the request object. An unsigned organization or prompt added to the query string of such a request is ignored.
Using the claims safely¶
- Authorize inside your application by
organization.idandorganization.rolesof the access token the user is currently using, not by a client-side choice. - Treat
organization.nameas a label that can change; key your data onorganization.id. - A user with no
organizationclaim has no active organization: show your picker, or send them through an authorization request withorganization=.