¶ Requirements, Specifications, and Design
The Authentication Server is the Identity Provider for Magic Toybox. It implements OAuth2 Authorization Code Flow + PKCE with optional OpenID Connect extensions.
flowchart TB
subgraph EntryPoints["OAuth/OpenID Endpoints"]
AUTHZ["/authorize"]
TOKEN["/token"]
USERINFO["/userinfo"]
JWKS["/jwks"]
INTROSPECT["/introspect"]
REVOKE["/revoke"]
DISC["/.well-known/openid-configuration"]
end
subgraph Logic["Auth Core Logic"]
LOGIN["Login / MFA"]
PKCE["PKCE Validator"]
CLIENT["Client Validator"]
SCOPES["Scope Resolver"]
SIG["JWT Signer"]
ROTATE["Refresh Rotation"]
REUSE["Reuse Detector"]
end
subgraph Storage["Storage Layers"]
DB[(Postgres<br/>users, clients,<br/>consents, tokens)]
RED_CODES{{Redis:<br/>auth codes}}
RED_REFRESH{{Redis:<br/>refresh tokens}}
RED_SESS{{Redis:<br/>session epochs}}
end
AUTHZ --> LOGIN --> PKCE --> CLIENT --> SCOPES --> RED_CODES
TOKEN --> RED_CODES --> ROTATE --> REUSE --> SIG --> TOKEN
USERINFO --> DB
INTROSPECT --> DB
REVOKE --> RED_REFRESH
JWKS --> SIG
DISC --> CLIENT
DB --> LOGIN
RED_REFRESH --> ROTATE
RED_SESS --> REUSE
- Create user accounts
- Store password hashes using Argon2id (m≥64–128MiB, t=3)
- Enforce unique email identity
- Support email verification
- Support MFA (TOTP + optional WebAuthn)
- Authorization endpoint
- Token endpoint
- UserInfo endpoint
- JWKS endpoint
- Introspection endpoint (for internal APIs)
- Revoke endpoint
- PKCE enforcement
- Strict redirect URI whitelisting
- Access token issuance (JWT)
- Refresh token issuance (opaque)
- Refresh rotation
- Reuse detection and token family invalidation
- Session epoch revocation
- Token TTL settings from env
-
CRUD for OAuth clients
-
Client metadata:
- Redirect URIs
- Allowed scopes
- Grant types
- Confidential/public client type
- Rotation policy
-
High availability (HA)
-
Stateless OAuth endpoints except for code and refresh storage
-
Secure signing key handling (env or KMS)
-
Ability to rotate keys
-
IdP must not store portal DB credentials
-
IdP must expose JWKS with configurable cache control
-
Rate-limiting (IP + client):
/authorize: moderate
/token: strict
/revoke: strict
/introspect: internal only
db_generic – RW identity DBdb_catalog – read-mostlydb_bot – health and minimal accessredis_sessions, redis_catalog, redis_bot
issuer (required)signing (RS256/ES256 preferred)access_ttl_secs (default: 600)refresh_ttl_secs (default: 14 days)enforce_pkcestrict_redirectsjwks_max_age_secs
auth_ns_codes – auth codesauth_ns_refresh – refresh tokensauth_ns_sessions – device/user session namespaces
authorize.rstoken.rsuserinfo.rsjwks.rsdiscovery.rsintrospect.rsrevoke.rs
users.rsclients.rstokens.rsconsents.rsrbac.rsstores.rs (persistence abstractions)
crypto.rs (key loading, signing)errors.rstypes.rshashes.rs (Argon2id policies)
- Login UI (optional)
- MFA setup & challenge
-
Format: JWT
-
Claims:
iss, sub, aud, iat, exp, jtiscope (space-delimited)amr (MFA factors)- Optional: device posture
-
Opaque string
-
Stored in DB/Redis
-
Fields:
family_id, token_id, user_idcreated_at, used_at, revokedip, ua (optional for heuristic risk)
- OIDC-compliant
- Optional for portals
- users (id, email, hash, mfa_enabled, email_verified)
- oauth_clients (id, secret, redirect_uris, scopes)
- auth_codes (code, client_id, user_id, code_challenge)
- refresh_tokens (id, family_id, user_id, issued_at, used_at, revoked)
- consents (user_id, client_id, scope)
- Strong Argon2id password hashing
- Email verification required
- MFA recommended/required for privileged scopes
- X-Forwarded-For trust boundary
- Rate limiting
- Session epoch / global logout
- Key rotation support
- Strict redirect validation
- PKCE enforced for all non-confidential clients
- Log: login failures, MFA attempts, token refresh, reuse detection
- Never log secrets or full tokens
- Behind HTTPS reverse proxy
- Same server may host static SPA for login UI
- Independent from user portals and vendor portals