This document defines the complete functional and security requirements for the Magic Toybox Authentication System.
The Authentication System acts as a centralized Identity Provider (IdP) for all Magic Toybox applications and services, including:
It is responsible for identity, session lifecycle, token issuance, and consent, while resource servers remain stateless and rely on cryptographic verification.
The Authentication Server is the only system that:
All other systems trust the Authentication Server but do not replicate its logic.
| Method | Type | Status |
|---|---|---|
| Email + Password | Native login | Required |
| Google OAuth | SSO | Required |
| iOS (Apple ID) | SSO | Required |
| Function | Module | Description |
|---|---|---|
| Email Login | Auth | Standard login using email. If 2FA enabled, 2FA is triggered by successful authentication of password |
| Password Reset Email sent | Auth | Send password email to requesting user at email of record |
| Password Reset | Auth | Receives and processes email change |
| Send Account Verification Email | Auth | Account verification code sent to new registered user |
| Account Verification | Auth | Receives submission of correct verification signal, and activates account |
| Logout | Auth | Standard logout for SSO and non-SSO authenticated user |
| 2FA Verification | Auth | Standard 2FA verification process |
| 2FA Set Method | Settings | Set method of 2fa contact as email or phone |
| Function | Module | Description |
|---|---|---|
| Google SSO Login | Auth | |
| Logout | Auth |
| Function | Module | Description |
|---|---|---|
| Apple SSO Login | Auth | |
| Logout | Auth |
This list refers to environmental variables distinct to this design, in contrast with those generic variables present in all apps (i.e. DATABASE_URL, STATIC_DIRECTOR, BASE_IP, BASE_PORT, etc)
Internal designates values defined by the company itself
| Variable | Module | Source | Function |
|------|------------|-------|
|APPLE_CLIENT_ID|Auth||
|APPLE_TEAM_ID|Auth||
|APPLE_KEY_ID|Auth||
|APPLE_PRIVATE_KEY|Auth||
|APPLE_REDIRECT_URI|Auth||
|ENFORCE_PKCE|||
|STRICT_REDIRECTS|||
|PUBLIC_BASE_URL|||
|ISSUER|||
|SENDGRID_API_KEY|Sendgrid||
|SENDER_EMAIL|Internal||
sid cookieHttpOnlySecure (non-dev)SameSite=Lax{
"uid": "<user_uuid>",
"exp": <unix_timestamp>
}
Below is a production-grade requirements document, written as a single Markdown file, suitable for direct inclusion in your repo (e.g. projects/authentication-portal/requirements.md).
It is exhaustive, maps handlers → features, and clearly explains sessions, tokens, MDM interaction, and post-auth traffic flow.
# Magic Toybox Authentication System
**Full Requirements & Feature Mapping**
---
## 1. Purpose & Scope
This document defines the **complete functional and security requirements** for the Magic Toybox Authentication System.
The Authentication System acts as a **centralized Identity Provider (IdP)** for all Magic Toybox applications and services, including:
- Web portals
- Mobile apps (iOS / Android)
- Multiple MDM (Mobile Device Management / Resource API) servers
It is responsible for **identity, session lifecycle, token issuance, and consent**, while **resource servers remain stateless** and rely on cryptographic verification.
---
## 2. System Role in the Overall Architecture
### 2.1 High-Level Role
The Authentication Server is the **only system that**:
- Verifies user credentials
- Issues sessions and tokens
- Owns signing keys
- Manages consent and authorization grants
- Publishes JWKS
- Validates refresh token rotation
- Dispatches email and 2FA challenges
All other systems **trust** the Authentication Server but **do not replicate its logic**.
---
## 3. Supported Authentication Methods
| Method | Description | Status |
|------|------------|-------|
| Email + Password | Native login | Required |
| Email Verification | Account activation | Required |
| Password Reset | Token-based reset | Required |
| Google OAuth | Social login | Required |
| iOS (Apple ID) | (Future) | Planned |
| Two-Factor Authentication (2FA) | Email/SMS-based | Required |
| Refresh Tokens | Sliding session continuity | Required |
---
## 4. Core Concepts
### 4.1 Sessions (Browser / App Sessions)
- Implemented using **Redis-backed sessions**
- Identified by a `sid` cookie
- Cookie properties:
- `HttpOnly`
- `Secure` (non-dev)
- `SameSite=Lax`
- Session payload stored in Redis:
```json
{
"uid": "<user_uuid>",
"exp": <unix_timestamp>
}
Sessions are only used for:
They are not used by MDM servers.
Short-lived (5–10 minutes)
Signed by IdP (RS256 in production)
Claims:
| Claim | Meaning |
|---|---|
iss |
Issuer (Auth server) |
sub |
User ID |
aud |
Resource server (MDM) |
scope |
Granted scopes |
amr |
Authentication methods |
azp |
Client ID (if applicable) |
Used only by MDM / API servers.
Opaque (non-JWT)
Stored server-side only
Bound to:
Rotated on every use
Reuse invalidates entire token family
/authorizeClient redirects to /authorize
Auth server:
Authorization code issued
Client exchanges code via /token
Tokens issued
PKCE is mandatory for all clients.
resourceaud is set to resourceConsent is stored per:
Supports:
| Feature | Route | Handler |
|---|---|---|
| Login | POST /api/auth/login |
login_handler |
| Logout | POST /api/auth/logout |
logout_handler |
| Refresh Session | POST /api/auth/refresh |
refresh_handler |
| Feature | Route | Handler |
|---|---|---|
| Register | POST /api/auth/register |
register_handler |
| Verify Email | GET /api/auth/verify-email |
verify_email_handler |
| Resend Verification | POST /api/auth/resend-verification |
resend_verification_handler |
| Feature | Route | Handler |
|---|---|---|
| Request Reset | POST /api/auth/request-reset |
request_reset_handler |
| Reset Password | POST /api/auth/reset-password |
reset_password_handler |
| Change Password | POST /api/auth/change-password |
change_password_handler |
| Feature | Route | Handler |
|---|---|---|
| Verify 2FA | POST /api/auth/verify-2fa |
verify_2fa_handler |
| Dispatch 2FA | Internal | send_2fa_code_hook |
| Provider | Route | Handler |
|---|---|---|
POST /api/auth/google-login |
login_google_handler |
|
| Apple (iOS) | POST /api/auth/apple-login |
login_apple_handler |
| Endpoint | Route | Handler |
|---|---|---|
| Discovery | /.well-known/openid-configuration |
openid_configuration |
| JWKS | /jwks.json |
jwks |
| Authorize | /authorize |
authorize |
| Token | /token |
token |
| UserInfo | /userinfo |
userinfo |
| Introspect | /introspect |
introspect |
| Revoke | /revoke |
revoke |
| Feature | Route | Handler |
|---|---|---|
| Submit Consent | POST /api/consent/submit |
consent_submit |
| Revoke Consent | POST /api/consent/revoke |
consent_revoke |
| List Consents | GET /api/consent/list |
consent_list |
| Admin Snapshot | GET /api/admin/consents |
admin_consent_snapshot |
MDM servers do not authenticate users
Clients authenticate with Auth Server
Auth Server issues access token with:
aud = mdm-server-idOnce authenticated:
Client sends requests directly to MDM
MDM:
aud + scopeAuth Server is not involved in normal traffic
The Auth Server is contacted again only when:
This Authentication System provides:
It is production-ready by design.
---
If you want, next I can:
- Split this into **linked sub-documents** (JWT, JWKS, Sessions, OAuth, Consent)
- Generate **Mermaid diagrams** referenced in the doc
- Create a **developer training / onboarding version**
- Produce a **compliance & threat-model appendix**
Just tell me the next deliverable.