The authentication system provides a centralized, secure, standards-compliant Identity Provider (IdP) for all Magic Toybox services. It replaces all per-application login logic with a single authority responsible for:
- Identity verification
- MFA (TOTP/WebAuthn)
- OAuth2 + OpenID Connect (OIDC) token issuance
- Refresh token rotation and revocation
- Client registration and redirect validation
- JWKS key distribution
- Session epoch invalidation
- Optional device risk/attestation integration
This system ensures consistency, security, interoperability, and enables multiple independent services—web portals, mobile apps, backend services—to authenticate through a unified standard.
Overview
Requirements
Generic Modules
Onboarding
UI/UX Diagrams
Pre-launch
Core
Auth
RBAC
Email
Profile
Settings
Authentication Server
Authentication Client
flowchart TD
subgraph User["User Devices"]
A1["Web Browser"]
A2["Mobile App"]
end
subgraph Portal["Client Portals"]
P1["mt_user_portal"]
P2["mt_vendor_portal"]
P3["admin_console"]
end
subgraph IDP["Authentication Server (IdP)"]
L["Login + MFA"]
OAUTH["OAuth2 / OIDC Engine"]
TOK["Token Service<br/>Access + Refresh + ID token"]
JWKS["JWKS Keys"]
CONS["Client Registry"]
end
subgraph Backend["Resource APIs"]
API1["mt_user_api"]
API2["mt_vendor_api"]
API3["admin_api"]
end
A1 -->|Redirect /authorize| IDP
A2 -->|Redirect /authorize| IDP
IDP -->|Authorization Code| Portal
Portal -->|Token Exchange /token| IDP
IDP -->|Tokens| Portal
Portal -->|Access Token| Backend
Backend -->|JWKS Verify| IDP
IDP -.-> JWKS
IDP -.-> CONS
flowchart LR
subgraph Portal["Client Portal"]
MW["JWT Middleware<br/>(Validates Access Token)"]
REFRESH["Refresh Handler<br/>(/auth/refresh)"]
COOKIE["Secure Cookies<br/>AT + RT"]
RS["Portal Routes"]
end
subgraph IdP["Authentication Server"]
OIDC["OAuth/OIDC Endpoints"]
JWKS["JWKS Public Keys"]
end
subgraph Infra["Portal Infrastructure"]
DB1[(Portal DB)]
R1{{Portal Redis Cache}}
end
RS --> MW --> RS
RS --> REFRESH --> OIDC
COOKIE --> MW
MW --> JWKS
REFRESH --> COOKIE
RS --> DB1
RS --> R1
flowchart TB
subgraph Clients["Clients"]
Browser["Web Browser"]
Mobile["Mobile App"]
end
subgraph Portals["Portals"]
UserPortal["mt_user_portal"]
VendorPortal["mt_vendor_portal"]
AdminPortal["admin_console"]
end
subgraph IDP["Authentication Server (IdP)"]
AUTHZ_EP["/authorize"]
TOKEN_EP["/token"]
JWKS_EP["/jwks"]
USERINFO_EP["/userinfo"]
INTROSPECT_EP["/introspect"]
REVOKE_EP["/revoke"]
end
subgraph Resources["Protected Backend APIs"]
UserAPI["user_api"]
VendorAPI["vendor_api"]
AdminAPI["admin_api"]
end
Browser --> UserPortal
Mobile --> UserPortal
UserPortal --> AUTHZ_EP
VendorPortal --> AUTHZ_EP
AdminPortal --> AUTHZ_EP
Portals --> TOKEN_EP
Portals --> REVOKE_EP
UserPortal --> UserAPI
VendorPortal --> VendorAPI
AdminPortal --> AdminAPI
UserAPI --> JWKS_EP
VendorAPI --> JWKS_EP
AdminAPI --> JWKS_EP
IDP -.-> JWTKeys["JWKS Public Keys"]
JWTKeys -.-> Resources
-
Authentication Server (IdP)
- Responsible for user identity, password verification, MFA, email verification, OAuth2/OIDC flows, token issuance, revocation, introspection.
- Hosts its own DB and Redis namespaces for codes, tokens, MFA sessions, and consent management.
- Exports JWKS for all clients.
- Never shares private signing keys.
-
Client/Portal Applications
- Treat the IdP as an external OAuth2/OIDC provider.
- Hold no passwords, signing keys, or identity logic.
- Use secure cookies for access tokens, refresh tokens, and session renewal.
- Validate
issuer, audience, and JWKS keys when inspecting access tokens.
-
Resource Servers (APIs)
- Receive the access token from portals or mobile clients.
- Validate JWTs locally via JWKS.
- Enforce scopes and role-based authorization.
- Asymmetric signing (RS256/ES256)
- Short access tokens (5–10 min)
- Refresh token rotation & reuse detection
- PKCE enforced for all public clients
- Strict redirect URI matching
- Mandatory MFA for privileged scopes
- JWKS caching with max-age control
- Per-client scopes and granularity
- No password or signing key sharing with portal apps
- JWT
- Short-lived
- Audience-bound (
aud=web-portal, aud=mt_vendor_portal, etc.)
- Opaque
- Stored only server-side in Redis-backed database
- Rotated on every use
- Reuse detection revokes entire token family
- Optional for portals needing user display info
- Contains profile basics (
email_verified, sub, amr, etc.)
- Portal redirects user to IdP
/authorize
- Login + MFA (IdP)
- Authorization code returned to portal
- Portal exchanges code for
access_token and refresh_token
- Portal stores refresh token in HttpOnly Secure cookie
- Portal injects
IdpCfg into middleware for JWT validation
- Portal presents
access_token to resource APIs
- APIs validate the token using JWKS
- Expired access tokens are silently renewed via
/refresh
-
Server Auth lives in its own service:
- DB:
server_authentication_db
- Redis DBs: 0,1,2 (sessions, catalog, bot)
-
Portals (e.g. mt_user_portal, mt_vendor_portal, admin_console):
- Each maintains its own DB, Redis, and configuration
- Each registers a unique OAuth client entry in the IdP
-
Resource APIs:
- Stateless
- Validate tokens using JWKS
- Centralized identity
- Zero password sharing
- Zero signing key sharing
- Strong revocation
- Strong MFA
- Multi-portal / multi-client scalability
- Modular expansion toward device attestation and risk scoring
- Full conformance with OAuth2 + OIDC Core