OAuth 2.0 / OpenID Connect
Endpoints, grant types, tokens, scopes, and consent
Discovery
Orion publishes an OpenID Connect Discovery document per organisation. All compliant clients can auto-configure by fetching this URL:
GET https://login.shanecraven.com/oauth/{org}/.well-known/openid-configuration
The response includes all endpoint URIs, supported grant types, signing algorithms, and scopes.
Endpoints
/oauth/{org}/.well-known/openid-configuration
Discovery
/oauth/{org}/authorize
Authorization
/oauth/{org}/token
Token
/oauth/{org}/userinfo
UserInfo
/oauth/{org}/revoke
Revocation
/oauth/{org}/device
Device Authorization
/oauth/{org}/end_session
Logout
/oauth/{org}/introspect
Introspection
/oauth/{org}/.well-known/jwks.json
JWKS
Grant Types
Authorization Code + PKCE
The recommended flow for web applications and SPAs. PKCE is required by default.
Orion → User authenticates, consents
Orion → Redirect to redirect_uri?code=ABC&state=XYZ
Client → POST /oauth/{org}/token (grant_type=authorization_code, code=ABC, code_verifier=...)
Orion → Returns { access_token, id_token, refresh_token }
Refresh Token (with Rotation)
Obtain a new access token without re-authentication. Orion supports refresh token rotation: each use issues a new refresh token and invalidates the old one.
Orion → Validates refresh token (not expired, not revoked)
Orion → Issues new access_token + new refresh_token
Orion → Old refresh token is invalidated (rotation)
Client Credentials
Machine-to-machine authentication with no user context. The client authenticates using its client_id and client_secret.
Orion → Validates client credentials
Orion → Returns { access_token } (no refresh token, no id_token)
Device Authorization
For devices without a browser (CLI tools, smart TVs, IoT). The device polls for completion while the user authenticates on a separate device.
Orion → Returns { device_code, user_code, verification_uri, interval }
User → Visits verification_uri, enters user_code, authenticates
Device → Polls POST /oauth/{org}/token (grant_type=urn:ietf:params:oauth:grant-type:device_code)
Orion → Returns authorization_pending until user approves
Orion → Returns { access_token, refresh_token } on approval
Token Lifetimes
Token lifetimes are configurable per application in the Management UI:
- Access Token: Default 3600 seconds (1 hour). Configurable via
AccessTokenLifetimeSeconds. - Refresh Token: Default 86400 seconds (24 hours). Configurable via
RefreshTokenLifetimeSeconds. - Authorization Code: 10 minutes (not configurable). Single-use.
- Device Code: 15 minutes (not configurable). Expires if user does not approve.
- ID Token: Same lifetime as the access token.
Back-Channel Logout
Orion implements OpenID Connect Back-Channel Logout 1.0, so an application learns when the Orion session someone signed in to it with has ended, without the browser being involved.
- Register a Back-Channel Logout URI on the application's OAuth settings: absolute
https, no fragment, never Orion's own host or a private address. - ID tokens carry
sid, the session's identifier. Keep it with your own session. - When the session ends (signing out at
end_session, an administrator ending it, or a credential event: a factor removed, a password reset, a recovery), Orion postslogout_token=<JWT>to the URI. The token is typedlogout+jwt, signed with the same key as ID tokens, from the same issuer, for your client id, and carriessub,sidand the back-channel logout event, never a nonce. Validate it as the specification says, end the matching session, and answer 200. - Delivery is tried three times (at once, after five seconds, after thirty); an answer of 400 is not retried. A token that is never accepted is recorded as Back-channel logout failed in the organisation's activity.
- Only sessions signed in to after the URI was registered are announced. Discovery advertises
backchannel_logout_supportedandbackchannel_logout_session_supported.
Scopes
Orion supports standard OIDC scopes and custom scopes defined per organisation.
Standard Scopes
| openid | Required for OIDC. Returns sub claim. |
| profile | Returns name, preferred_username, given_name, family_name. |
Returns the email claim. The address is set by the user's organisation and not verified by Orion (no email_verified is issued). |
|
| phone | Returns phone_number claim. |
| roles | Returns roles: the names of the user's roles in their own organisation. |
| organisation | Returns org_name and org_admin (whether the user is an administrator of the organisation in org_id). The application's Allowed Scopes must include it. |
| offline_access | Issues a refresh token for long-lived access. |
Custom scopes can be created via the Management UI under OAuth → Manage Scopes. Custom scopes can include additional claims that are added to the access token and userinfo response.
Consent Model
Who agrees to a sign-in depends on which organisation the user belongs to.
Members of the application's own organisation:
- User Consent: Each user is prompted to approve requested scopes on first use. Consent is remembered per user per client per scope set.
- Organisation-Wide Consent: An administrator grants consent on behalf of all members of the application's organisation. No individual user prompt is shown.
- Pre-authorization: Applications with
RequireConsent = falseskip the consent screen entirely (first-party apps).
Members of other organisations can sign in only to an application whose organisation lets members of any organisation sign in (see Applications), and then the member's own organisation decides, by its policy for applications published by other organisations (App Approvals in the OAuth administration pages):
- Organisation approval (the policy "Administrator approval required", the default): an administrator of the member's organisation approves the application, on the approval screen at their own first sign-in or ahead of time by its client ID. Every member may then sign in.
- Member consent (the policy "Members may consent for themselves"): each member allows the application for themselves on a consent screen; an administrator's approval still covers everyone.
- Blocked: no member may sign in to applications of other organisations.
An approval or member consent covers the scopes it recorded and the claim names those scopes released
when it was given. If the application asks for another scope, or its organisation changes a scope to
release more, the grant stops covering the request until it is approved again. The application
organisation's consents, pre-authorizations, RequireConsent = false and access roles never
apply to members of other organisations.
Consents can be revoked at any time via the Management UI or the Management API. Revoking a user's consent, or a user withdrawing their own on Authorized applications, signs that user out of the application; revoking an organisation's approval signs out every member it covered.
Members of Other Organisations
When a member of organisation B signs in to organisation A's application, the tokens:
- keep A's issuer (
{base}/oauth/{A}), A's signing key and the application's client ID asaud; - carry B's
PublicIdinorg_id, the names of B's roles the user holds inroles, and B's values for every other claim, and release only the claim names B's grant recorded; - are checked again at every refresh, at userinfo and at introspection: a withdrawn grant, a user who left B or a disabled account stops them at once. A JWT access token stays valid until it expires.
The device authorization grant serves members of the application's own organisation only, and
client_credentials tokens are unchanged: they always describe the issuing organisation.
Refusals
When a member may not sign in, Orion shows a page that says why. Its Return button sends the
application error=access_denied with a fixed English error_description and an
orion_reason; with prompt=none that redirect happens at once. An administrator
who could approve, or a member who could consent, gets error=consent_required under
prompt=none instead.
| organisation_approval_required | The user's organisation has not approved the application, or its grant no longer covers the request. |
| organisation_blocked | The user's organisation does not allow applications published by other organisations. |
| no_organisation | The account belongs to no organisation. |
| organisation_not_approved | The user's organisation is pending approval by a platform administrator (ORION_REQUIRE_ORG_APPROVAL=true). Applies to every application but the management portal, administrators included. |
| not_a_member | The consent form of an application that admits only its own organisation was posted by someone outside it. |
orion_reason values are stable identifiers an application may branch on;
error_description is display text and must not be parsed. A refused home member who lacks the
application's access roles, or whose account is disabled, gets a bare access_denied as before.
invalid_scope and PKCE errors are also error redirects to the redirect_uri,
with state, and a request with no scope is treated as openid.
A sign-in that must first ask the person for details their organisation requires (see
profile attributes) is not a refusal: Orion asks on a short page and
the sign-in carries on. Under prompt=none it answers
error=interaction_required. A refresh never asks.
Client Secrets
Orion supports multiple active client secrets per application for zero-downtime rotation:
- Multiple secrets: Each application can have multiple active secrets simultaneously.
- Labels: Secrets can be named (e.g. "Production 2025-Q1") for tracking.
- Expiry: Secrets can have an optional expiry date. Expired secrets are automatically rejected.
- Revocation: Secrets can be manually revoked at any time without affecting other active secrets.
- Hashing: Secrets are stored as SHA-256 hashes. The plaintext is shown exactly once at creation time.
Manage secrets in the Application Manager under the OAuth section.