Authentication Schemes

Legacy Federation (Cookie/Redirect)

The original authentication mechanism. The client application's OrionFederationFilter (with FilterType = UserFederated) intercepts unauthenticated requests and initiates a redirect-based flow.

Flow Diagram

[1] User hits protected page
Client App → OrionFederationFilter detects no session cookie

[2] Redirect to Orion
Browser → https://login.shanecraven.com/federation/Login?appId=xxx&returnUrl=yyy

[3] User authenticates (email + password + optional 2FA)
Orion → Creates session key (orion_key) in database

[4] Redirect back to client
Browser → returnUrl?orion_key=abc123

[5] SDK validates key via API call
Client App → https://login.shanecraven.com/legacy/api/auth/validate?key=abc123

[6] Set session cookie
Client App → Sets encrypted cookie containing user data
User is now authenticated as OrionPrincipal

Key characteristics:

Session state stored in cookies on the client
No JWTs — relies on server-side key validation
Best for existing .NET applications already using the SDK
Supports optional federation (users can access pages without authentication)

OAuth 2.0 Federated Login

The modern authentication method. Uses FilterType = OAuthFederated. The SDK handles the full OAuth authorization code flow with PKCE, token exchange, and JWT validation.

Flow Diagram

[1] User hits protected page
Client App → OrionFederationFilter (OAuthFederated) detects no session

[2] Redirect to authorize endpoint
Browser → https://login.shanecraven.com/oauth/{org}/authorize?response_type=code&client_id=...&code_challenge=...

[3] User authenticates + consents
Orion → Issues authorization code, redirects to redirect_uri

[4] Token exchange (server-side)
Client App → POST https://login.shanecraven.com/oauth/{org}/token (code + code_verifier)

[5] Response contains JWT tokens
Orion → { access_token, id_token, refresh_token }

[6] SDK validates JWT and sets session
Client App → Verifies signature via JWKS, sets encrypted cookie
User is now authenticated as OrionPrincipal

Key characteristics:

Standards-compliant OAuth 2.0 / OIDC
PKCE enforced by default (prevents authorization code interception)
JWTs are self-contained — no server-side validation call needed
Supports refresh token rotation for long-lived sessions
Works with any OAuth 2.0 library (not limited to .NET)

HMAC API Authentication

For machine-to-machine communication where no browser is involved. System accounts authenticate using a public key identifier and an HMAC-SHA256 signature. Handled by the OrgStandard / OrganisationStandard authentication scheme.

Request Format

// HTTP request with HMAC authentication
POST https://login.shanecraven.com/legacy/api/users/get HTTP/1.1
Content-Type: application/json
Authorization: {PublicKey}:{HMAC-SHA256-Signature}

// The signature is computed as:
// HMAC-SHA256(SecretKey, RequestBody)
// Both keys are issued when creating a System Account
{
  "email": "user@example.com"
}

Flow Diagram

[1] Client prepares request
Service → Serialises request body to JSON

[2] Compute signature
Service → HMAC-SHA256(secretKey, requestBody) → Base64

[3] Set Authorization header
Service → Authorization: {publicKey}:{signature}

[4] Orion validates
Server → Looks up secret key by public key
Server → Recomputes HMAC, compares to provided signature
Server → Checks system account has permission on target application

[5] Request proceeds
Authenticated as system account with application context

Key characteristics:

No tokens to manage — every request is independently authenticated
Secret key never leaves the server (only the signature is transmitted)
System accounts are scoped to applications via permission grants
Supports cross-application access when permissions are explicitly granted

How to Choose

Scenario	Method	SDK FilterType
Web app with browser (new project)	OAuth 2.0	OAuthFederated
Web app (existing SDK integration)	Legacy Federation	UserFederated
API consumed by browser SPA	OAuth Bearer	OAuthUserBearer
Backend service calling Orion API	HMAC	SystemAccountExternal
Machine-to-machine (OAuth)	client_credentials	N/A (standard OAuth client)