Scopes & Claims

What an application may ask for, and what ends up in the token

Back to Documentation

The mental model

Four concepts, in the order they apply to a request:

ConceptQuestion it answersWhere it lives
ScopeWhat may this application ask for?Application → Allowed Scopes
ConsentWhat has the user (or org) agreed to release?Consent screen / Manage Consents
ClaimsWhat data does each granted scope actually release?Scope → Claims field
Claim sourceWhere 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:

FormExampleUsed for
Display@acme/billing:readWhat you type and see in the UI, tokens, consent
Global idlogin.example.com/acme/billing:readUniqueness across servers (server host is the authority)
Verifiedacme.com/billing:readOnce the org verifies a domain — portable across servers
Both forms always work. A scope created before namespacing can be requested bare (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:

PrefixExampleValue comes from
noneemailBuilt-in user/org field, else a static per-user Custom Claim
meta:meta:departmentUser metadata (app-scoped value wins over org-wide)
expr:expr:is_premiumA computed Claim Definition (sandboxed expression)
ext:ext:billingAn 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.

Reserved names. The built-ins above plus protocol claims (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.

SettingChoices
RequiredOptional; 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 byThe 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 registrationShown on the registration pages; only for what the person gives. Always on for attributes required always.
Shared with other organisationsOff 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.

ClaimReleased byMeaning
org_idevery tokenThe PublicId of the organisation the user belongs to at issuance. Unique on the server and never changed. Make every organisation-dependent decision on it.
rolesrolesThe 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_nameorganisationThe organisation's display name. Not unique, may change: display only.
org_adminorganisationA 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_handleevery token that carries a claim the organisation definesThe scope handle of the user's organisation, under which those claims are issued (@handle/name). Reserved. Fixed once the organisation has a custom scope.
Only 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

FieldMeaning
NameThe scope identifier, e.g. orders:read. Namespaced automatically.
Display NameHuman label on the consent screen.
DescriptionThe sentence the user reads when consenting.
ClaimsSpace-separated claim names this scope releases (see above).
RequiredAlways included in tokens for the app, whether or not requested.
StandardMarks 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.

  1. Set the metadata on users: Roles & Claims → member → Metadata → department = Engineering.
  2. Define a computed claim: Claims → New → name is_manager, type Boolean, expression contains(roles, "Manager").
  3. Create the scope: Scopes → New → name staff, Claims meta:department expr:is_manager.
  4. 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 scope claim.
  • 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.
OAuth & OIDC All Documentation