Scopes & Claims
What an application may ask for, and what ends up in the token
The mental model
Four concepts, in the order they apply to a request:
| Concept | Question it answers | Where it lives |
|---|---|---|
| Scope | What may this application ask for? | Application → Allowed Scopes |
| Consent | What has the user (or org) agreed to release? | Consent screen / Manage Consents |
| Claims | What data does each granted scope actually release? | Scope → Claims field |
| Claim source | Where does each claim's value come from? | Built-ins, metadata, expressions, providers |
A scope is a label on a bundle of claims. Requesting profile does not
magically add a name to the token — it does so because the profile scope's Claims
field lists name given_name family_name preferred_username. Change that field and you
change what the scope releases.
Scope names and namespaces
Standard OIDC scopes are bare and reserved: openid, profile,
email, phone, offline_access, roles,
organisation. A standard scope's name always means the standard definition: a custom
scope cannot be created or renamed to a standard name, one that already shares it adds nothing to it,
and only platform administrators can edit the standard scopes.
Scopes your organisation defines are namespaced by your organisation handle, so two
organisations can both define orders:read without colliding:
# anatomy @acme/billing:read └─ namespace └─ resource : action
Each scope has three forms — you normally only type the first:
| Form | Example | Used for |
|---|---|---|
| Display | @acme/billing:read | What you type and see in the UI, tokens, consent |
| Global id | login.example.com/acme/billing:read | Uniqueness across servers (server host is the authority) |
| Verified | acme.com/billing:read | Once the org verifies a domain — portable across servers |
billing:read) or qualified (@acme/billing:read) — Orion treats them as the
same scope when matching. Scope strings you send are never rewritten, so anything that compares
token scope values literally keeps working.
The Claims field
A scope's Claims field is a space-separated list of claim names. Each name is routed to a claim source by its prefix — this is the part that is easy to miss:
| Prefix | Example | Value comes from |
|---|---|---|
| none | email | Built-in user/org field, else a static per-user Custom Claim |
meta: | meta:department | User metadata (app-scoped value wins over org-wide) |
expr: | expr:is_premium | A computed Claim Definition (sandboxed expression) |
ext: | ext:billing | An external Claim Provider, called live or synced |
Claims your organisation defines are issued under its handle. meta:department appears in
the token as @acme/department, where acme is the scope handle of the user's own
organisation, and so do computed claims, a provider's claims and static user claims. A token that carries one
also carries org_handle ("acme"), so an application used by several organisations
reads "@" + org_handle + "/department". Nothing that starts with @ is a standard
claim, so these can never pose as one, and no organisation can issue a claim under another organisation's
handle: a member of another organisation brings their own organisation's values, under its handle.
An organisation whose scopes released such claims before this naming existed also issues the unprefixed name
(department) to its own members, as before, until an administrator stops it on the
Scopes page. Members of other organisations never receive unprefixed names. An organisation with no
usable handle (only possible for an old public id) issues unprefixed names to its own members, and none to
other organisations' applications, until it has one. Standard scopes are shared by every organisation, so they
list only the built-in claims below; release your own claims from a custom scope.
Built-in claim names
sub, name, given_name, family_name,
preferred_username, email, phone_number,
org_id, org_name, org_admin, roles.
iss, aud,
exp, iat, jti, scope, client_id, …)
can never be produced by metadata, expressions, or external providers — a provider cannot overwrite
sub and impersonate a user. Neither can names relying parties authorise on although Orion
does not emit them (role, groups, entitlements,
permissions, scp, upn, oid, …).
sub and org_id are emitted once by the server itself.
Claim names you author — metadata keys, user claims, claim definitions, a provider's allowlist and
every claim a scope lists — are 1 to 64 letters, digits, ., _ or -,
and not reserved. That keeps out every URI-form claim type, such as
http://schemas.microsoft.com/ws/2008/06/identity/claims/role, which ASP.NET Core reads as a
role with no mapping at all. Editors refuse any other name, and tokens never carry one.
Profile attributes
An organisation decides what it asks its people for on its Profile page
(/oauth/manage/{org}/profile, beside Scopes). Each attribute has a key, a label and help text,
a type (text, email, phone, web address, number, date, yes/no, one choice or several), and rules for text
(length, a pattern). Values are the person's organisation-wide metadata, so an attribute keyed
department is released by any scope that lists meta:department and arrives as
@acme/department, typed: yes/no as true/false, a number as a
number, several choices as an array. The key never changes once created, because scopes and tokens name it.
| Setting | Choices |
|---|---|
| Required | Optional; when requested: before an application whose requested scopes release it gets a token; always: at everyone's next sign-in, to an application or to Orion itself. A missing value is asked for on a short page during sign-in, and the sign-in then carries on (consent included). At Orion's own pages an administrator of the person's organisation can choose "Not now", so a mistake in an attribute never locks them out; nobody else can skip it. Never at a token refresh or in the device flow. |
| Filled in by | The person (registration, their account page, the sign-in step); the person, once (they give it once, then only administrators change it); an administrator (the people page; the person sees it); the directory (copied from a named claim of the Entra token at every directory sign-in); a claim provider (a sync provider writes it). Only what the person gives is ever asked for, at registration or at sign-in. |
| Ask at registration | Shown on the registration pages; only for what the person gives. Always on for attributes required always. |
| Shared with other organisations | Off by default: the value stays out of tokens issued by other organisations' applications, and their approval screens say it is not shared. |
preferred_username (Username) and phone_number (Mobile number) can be added as
standard attributes: their values stay on the account, and they keep their built-in names and scopes
(profile, phone). An attribute with values can be archived (no longer asked for,
values kept) or deleted with its values. The legacy register API takes an optional Profile
object of key to value; it checks what it is sent and never refuses because something is missing.
Organisation claims
Every claim describes the user's own organisation, which is not always the application's: an application can let members of other organisations sign in (see Applications). The application's organisation's scope definitions decide which claims a scope releases; the user's organisation supplies the values.
| Claim | Released by | Meaning |
|---|---|---|
org_id | every token | The PublicId of the organisation the user belongs to at issuance. Unique on the server and never changed. Make every organisation-dependent decision on it. |
roles | roles | The names of the user's roles in the org_id organisation. Any organisation can create a role with any name, so compare org_id too before trusting one. |
org_name | organisation | The organisation's display name. Not unique, may change: display only. |
org_admin | organisation | A boolean: true exactly when the user is an administrator of the org_id organisation. Reserved, never derived from a role name. Recognise an organisation's administrator by org_id together with org_admin == true. |
org_handle | every token that carries a claim the organisation defines | The scope handle of the user's organisation, under which those claims are issued (@handle/name). Reserved. Fixed once the organisation has a custom scope. |
sub, org_id, roles and org_admin carry guarantees.
email, name, preferred_username and phone_number are set by
the user's own organisation, are not verified by Orion and are not unique across organisations. Key accounts
on sub and never find or merge an account by email (see
Security).
Username and mobile number are optional. Orion no longer asks for either at registration or invents one.
preferred_username is the account's username when it has one; otherwise it is the email address,
but only in a token that also releases email, so it is absent from a token granted
profile without email for an account with no username. phone_number is
present only when the account holds a number, and is never verified (there is no
phone_number_verified). Treat both as optional.
Grants bind claim names. For a member of another organisation, Orion releases only the claim names their organisation's approval (or their own consent) recorded when it was given. Adding a claim to a scope the application requests, or requesting another scope, makes those grants stop covering the request until each organisation approves again, so coordinate such changes with the organisations that use the application.
The discovery document lists org_admin in claims_supported exactly when the server
supports applications used by other organisations; a relying party may treat its absence as "not
supported".
Scope fields explained
| Field | Meaning |
|---|---|
| Name | The scope identifier, e.g. orders:read. Namespaced automatically. |
| Display Name | Human label on the consent screen. |
| Description | The sentence the user reads when consenting. |
| Claims | Space-separated claim names this scope releases (see above). |
| Required | Always included in tokens for the app, whether or not requested. |
| Standard | Marks the built-in OIDC scopes. Standard scopes cannot be deleted. |
Scopes with no Claims are resource scopes — they release no data, they authorise an action.
devices:provision is one: holding it lets an application call the device provisioning
API. Consent still applies; the API additionally checks a provisioning grant.
Worked example
An organisation wants applications to see a user's department and whether they are a manager.
- Set the metadata on users: Roles & Claims → member → Metadata →
department = Engineering. - Define a computed claim: Claims → New → name
is_manager, type Boolean, expressioncontains(roles, "Manager"). - Create the scope: Scopes → New → name
staff, Claimsmeta:department expr:is_manager. - Allow it on the application: Applications → app → OAuth settings → Allowed Scopes.
A token issued for that scope then contains:
{
"sub": "62B3…",
"scope": "openid @acme/staff",
"@acme/department": "Engineering",
"@acme/is_manager": true,
"org_handle": "acme"
}
Claim values resolve at issuance, so changing a user's metadata or roles affects the next token without touching the scope. With Orion Verified tokens it affects the very next request.
If a claim is missing
- Is the scope in the application's Allowed Scopes? If not the request fails with
invalid_scope. - Was the scope actually requested and consented to? Check the token's
scopeclaim. - Is the claim name listed in the scope's Claims field, with the right prefix?
- Is the application reading the name under the user's organisation's handle (
@handle/name)? Unprefixed names reach only the organisation's own members, and only while it still issues them. - Does the value exist — metadata set for that user, expression returning non-null, provider reachable?
- Is the name reserved, or outside the claim-name rule? Dynamic sources are filtered from both, and the server logs each claim it drops.
- Check
https://login.shanecraven.com/oauth/{org}/userinfo— it resolves through the same pipeline as tokens.