OAuth 2.0 / OpenID Connect

Endpoints, grant types, tokens, scopes, and consent

Back to Documentation

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

GET /oauth/{org}/.well-known/openid-configuration Discovery
GET /oauth/{org}/authorize Authorization
POST /oauth/{org}/token Token
GET /oauth/{org}/userinfo UserInfo
POST /oauth/{org}/revoke Revocation
POST /oauth/{org}/device Device Authorization
GET /oauth/{org}/end_session Logout
POST /oauth/{org}/introspect Introspection
GET /oauth/{org}/.well-known/jwks.json JWKS

Grant Types

1

Authorization Code + PKCE

The recommended flow for web applications and SPAs. PKCE is required by default.

Browser → GET /oauth/{org}/authorize?response_type=code&client_id=...&code_challenge=...
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 }
2

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.

Client → POST /oauth/{org}/token (grant_type=refresh_token, refresh_token=...)
Orion → Validates refresh token (not expired, not revoked)
Orion → Issues new access_token + new refresh_token
Orion → Old refresh token is invalidated (rotation)
3

Client Credentials

Machine-to-machine authentication with no user context. The client authenticates using its client_id and client_secret.

Client → POST /oauth/{org}/token (grant_type=client_credentials, client_id=..., client_secret=...)
Orion → Validates client credentials
Orion → Returns { access_token } (no refresh token, no id_token)
4

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.

Device → POST /oauth/{org}/device (client_id=..., scope=...)
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 posts logout_token=<JWT> to the URI. The token is typed logout+jwt, signed with the same key as ID tokens, from the same issuer, for your client id, and carries sub, sid and 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_supported and backchannel_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.
email 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 = false skip 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 as aud;
  • carry B's PublicId in org_id, the names of B's roles the user holds in roles, 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.

← Authentication Next: Applications →