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.

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 email and email_verified claims.
phone Returns phone_number claim.
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

Orion supports multiple consent modes per application:

  • 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 users in the organisation. No individual user prompt is shown.
  • Pre-authorization: Applications with RequireConsent = false skip the consent screen entirely (first-party apps).

Consents can be revoked at any time via the Management UI or the Management API.

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 →