🎫 JWT Authentication Flow
Token-based authentication and multi-tenant claims architecture
Executive Summary
AIUsagePlatform uses JWT (JSON Web Token) bearer authentication with RS256 (RSA + SHA256) signing. Tokens carry identity claims including UserId, OrganizationId, Role, and Permissions for distributed validation without database lookups.
✅ RS256 Signing
Asymmetric keys, key rotation ready
Asymmetric keys, key rotation ready
✅ Short-Lived
Access token: 15 min, Refresh: 7 days
Access token: 15 min, Refresh: 7 days
✅ Tenant Context
OrganizationId embedded in claims
OrganizationId embedded in claims
⚠️ No Token Revocation
Compromised tokens valid until expiry
Compromised tokens valid until expiry
🔄 Authentication Flow
JWT Authentication Flow
═══════════════════════════════════════════════════════════════════════════════
┌──────────┐ ┌─────────────────────────────┐
│ Client │ │ Identity Server │
│ (Angular)│ │ (AuthController) │
└────┬─────┘ └──────────────┬──────────────┘
│ │
│ POST /api/auth/login │
│ { email, password } │
│────────────────────────────────────────────────────────►│
│ │
│ ┌────────────────────┐ │
│ │ Validate Password │ │
│ │ Check User Status │ │
│ │ Load Roles/Perms │ │
│ └─────────┬──────────┘ │
│ │ │
│ ┌─────────▼──────────┐ │
│ │ Generate Tokens │ │
│ │ ─────────────── │ │
│ │ Access Token (JWT)│ │
│ │ • Exp: 15 min │ │
│ │ • Claims: sub, │ │
│ │ org, role, perm │ │
│ │ │ │
│ │ Refresh Token │ │
│ │ • Exp: 7 days │ │
│ │ • Stored in DB │ │
│ └─────────┬──────────┘ │
│ │ │
│ { accessToken, refreshToken, user } │ │
│◄───────────────────────────────────────│ │
│ │
─────┴────────────────────────────────────────────────────────┴──────────────
SUBSEQUENT API CALLS:
───────────────────────────────────────────────────────────────────────────────
│ GET /api/admindashboard │
│ Authorization: Bearer eyJhbGciOiJSUzI1Ni... │
│────────────────────────────────────────────────────────►│
│ │
│ ┌────────────────────┐ │
│ │ [Authorize] │ │
│ │ Validate JWT: │ │
│ │ • Signature (RS256)│ │
│ │ • Expiration │ │
│ │ • Issuer/Audience │ │
│ └─────────┬──────────┘ │
│ │ │
│ ┌─────────▼──────────┐ │
│ │ Extract Claims: │ │
│ │ • sub: user-id │ │
│ │ • org: org-id │ │
│ │ • role: Admin │ │
│ │ • perm: [...] │ │
│ └─────────┬──────────┘ │
│ │ │
│ ┌─────────▼──────────┐ │
│ │ MultiTenantMiddleware│ │
│ │ Validate org access │ │
│ │ Attach tenant context│ │
│ └─────────┬──────────┘ │
│ │ │
│ { dashboard data } │ │
│◄───────────────────────────────────────│ │
│ │
📋 JWT Claims Structure
| Claim | Type | Description | Example |
|---|---|---|---|
sub | string (GUID) | Subject (User ID) | usr_12345678-... |
email | string | User email address | admin@acme.com |
org | string (GUID) | Organization ID (tenant) | org_87654321-... |
role | string | Primary role name | Admin |
role_level | integer | Role hierarchy level | 50 |
permissions | JSON array | Granted permissions | ["Users.View", "Reports.Create"] |
iss | string | Token issuer | AIUsagePlatform |
aud | string | Token audience | AIUsagePlatform.API |
exp | Unix timestamp | Expiration time | 1704067200 |
iat | Unix timestamp | Issued at time | 1704066300 |
jti | string (GUID) | Unique token ID | tok_abc123... |
🔐 Token Security Properties
Access Token
- Lifetime: 15 minutes
- Algorithm: RS256 (RSA 2048-bit)
- Key ID: kid header for rotation
- Storage: Memory only (Angular)
Refresh Token
- Lifetime: 7 days
- Storage: HTTP-only secure cookie
- Database: Hashed in RefreshTokens table
- Rotation: New token on each use
Security Headers
-
Strict-Transport-Security -
X-Content-Type-Options: nosniff -
X-Frame-Options: DENY -
Content-Security-Policy
✅ Token Validation Pipeline
JWT Validation Pipeline (ASP.NET Core)
═══════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────┐
│ ASP.NET Core Middleware Pipeline │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Authentication Middleware │
│ ├── Extract Bearer token from Authorization header │
│ ├── Parse JWT headers (alg, typ, kid) │
│ ├── Fetch public key from JWKS endpoint (cached) │
│ ├── Verify RS256 signature │
│ └── Build ClaimsPrincipal from JWT claims │
│ │
│ 2. MultiTenantIsolationMiddleware │
│ ├── Extract "org" claim from Identity │
│ ├── If SuperAdmin: Bypass tenant checks (special handling) │
│ ├── Validate organization exists and is Active │
│ ├── Check subscription status (not Expired/Suspended) │
│ └── Attach X-Tenant-* headers to response │
│ │
│ 3. Authorization Middleware │
│ ├── [Authorize] → Check authenticated │
│ ├── [Authorize(Roles="Admin")] → Check role claim │
│ └── [HasPermission] → Check permissions claim │
│ │
│ 4. Rate Limiting Middleware │
│ ├── Identify client by UserId from claims │
│ ├── Check rate limit counters (Redis) │
│ └── Reject if exceeded (429 Too Many Requests) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
⚠️ Security Concerns
No Token Revocation List
Compromised tokens remain valid until expiry. Need Redis blacklist for logout/scenarios.
Refresh Token Long Lifetime
7-day refresh token increases window of compromise. Consider shorter (1-3 days) with sliding.
RS256 Asymmetric Signing
Private key on server only. Public key can be rotated without client changes. Good practice.
HTTP-Only Refresh Token
Refresh token stored in secure, HTTP-only cookie prevents XSS theft.
💡 Recommended Enhancements
Token Revocation (Redis)
Store revoked token JTIs in Redis with TTL matching token expiry. Check on each request.
Recommended High
Device Fingerprinting
Bind tokens to device fingerprint (hash). Reject if fingerprint mismatch (token theft detection).
Recommended Medium
Concurrent Session Limit
Enforce max 3-5 concurrent sessions per user. Invalidate oldest on new login.
Recommended Medium