Overview

YorAuth acts as an OpenID Connect Identity Provider (IdP), issuing RS256-signed ID tokens that allow your application (the Relying Party) to verify user identity. The implementation follows OIDC Core 1.0 and OAuth 2.0 RFC 6749.

Architecture

text

User Browser
     │
     │  1. Redirect to /oidc/authorize
     ▼
YorAuth Hosted Login (oidc.authorize → oidc.login → oidc.consent)
     │
     │  2. Redirect back with ?code=...
     ▼
Your Application Backend
     │
     │  3. POST /oidc/token
     ▼
YorAuth Token Endpoint → returns id_token (+ refresh_token if offline_access)
     │
     │  4. Verify id_token using JWKS
     ▼
Public JWKS endpoint: /.well-known/jwks.json

The hosted login UI is a Blade-rendered multi-step flow managed by session state. Your application never handles user credentials — YorAuth handles login, registration, MFA, and social login within the flow.

Discovery Document

All OIDC client libraries support automatic configuration via the discovery document:

text

GET https://api.yorauth.com/.well-known/openid-configuration

Example response:

json

{
  "issuer": "https://api.yorauth.com",
  "authorization_endpoint": "https://api.yorauth.com/oidc/authorize",
  "token_endpoint": "https://api.yorauth.com/oidc/token",
  "userinfo_endpoint": "https://api.yorauth.com/oidc/userinfo",
  "jwks_uri": "https://api.yorauth.com/.well-known/jwks.json",
  "end_session_endpoint": "https://api.yorauth.com/oidc/logout",
  "scopes_supported": ["openid", "profile", "email", "offline_access"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "token_endpoint_auth_methods_supported": ["client_secret_post"],
  "claims_supported": ["sub", "iss", "aud", "exp", "iat", "email", "email_verified", "name", "picture"],
  "code_challenge_methods_supported": ["S256"]
}

The discovery and JWKS endpoints are public — no authentication is required.

Supported Flows

Flow	Supported
Authorization Code + PKCE	Yes
Implicit	No
Client Credentials	No
Device Authorization	No

Only response_type=code is accepted. PKCE with code_challenge_method=S256 is mandatory for all authorization requests.

Supported Scopes

Scope	Claims Included
`openid`	`sub`, `iss`, `aud`, `iat`, `exp` — required
`profile`	`name`, `picture`
`email`	`email`, `email_verified`
`offline_access`	Causes a `refresh_token` to be issued

The openid scope is required in every request. Additional scopes must be configured in your OIDC client's allowed_scopes list.

ID Token Claims

ID tokens are signed using RS256 (RSA + SHA-256). The token payload contains:

Claim	Type	Description
`iss`	string	Issuer — your YorAuth instance URL
`sub`	string (UUID)	Subject — the user's unique ID
`aud`	string	Audience — the `client_id` of the requesting client
`iat`	integer	Issued-at timestamp (Unix epoch)
`exp`	integer	Expiration timestamp (default: `iat` + 3600 seconds)
`scope`	string	Space-separated list of granted scopes
`nonce`	string	Present if included in the authorization request
`at_hash`	string	Access token hash, if an access token is issued
`email`	string	Present when `email` scope is granted
`email_verified`	boolean	Present when `email` scope is granted
`name`	string	Present when `profile` scope is granted
`picture`	string	Present when `profile` scope is granted

JSON Web Key Set (JWKS)

Your application verifies ID tokens using the public RSA key published at the JWKS endpoint:

text

GET https://api.yorauth.com/.well-known/jwks.json

json

{
  "keys": [
    {
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "kid": "yorauth-key-1",
      "n": "<base64url-encoded modulus>",
      "e": "AQAB"
    }
  ]
}

Most OIDC client libraries fetch and cache the JWKS automatically using the discovery document. The kid field in the ID token header matches the kid in the JWKS entry.

Token Lifetimes

Token	Default Lifetime
Authorization code	10 minutes (600 seconds)
ID token	1 hour (3600 seconds)
Refresh token	7 days (604800 seconds)

These can be adjusted via environment variables (OIDC_AUTH_CODE_LIFETIME, OIDC_ID_TOKEN_LIFETIME, OIDC_REFRESH_TOKEN_LIFETIME).

Client Authentication

The token endpoint uses client_secret_post — credentials are sent as form body parameters (client_id and client_secret). client_secret_basic (HTTP Basic Auth) is not supported.

RP-Initiated Logout

To log a user out and optionally redirect back to your application:

text

GET https://api.yorauth.com/oidc/logout
  ?id_token_hint=<id_token>
  &post_logout_redirect_uri=https://yourapp.com/logged-out
  &state=optional-state

YorAuth verifies the id_token_hint, revokes the user's OIDC refresh tokens for that client, and redirects to post_logout_redirect_uri if it is a registered redirect URI for the client.