Auth Return

Key Features

• App Isolation: Each app has its own Cognito user pool - users, passwords, and sessions are completely separate
• Zero Password Storage: Auth Return never sees passwords - credentials go directly to AWS Cognito
• Stateless Authentication: Uses JWT tokens - no server-side session storage required
• Automatic Pool Management: User pools are created automatically when you register an app
• Embedded Components: Drop-in authentication UI components for login/signup
• API Key Management: Centralized API key system for service-to-service authentication

Why This Matters

If apps shared a user pool, the same email would have the same password everywhere. Compromise one app, compromise them all.

With separate pools: same email, different passwords, different user IDs. Each app is a security boundary. Even if an attacker gains access to one app's user database, they cannot use those credentials to access other apps.

JWT Structure

Three parts separated by dots: header.payload.signature

{
  "header": {
    "alg": "RS256",           // Signing algorithm
    "kid": "key-id..."        // Which key signed it
  },
  "payload": {
    "sub": "a438f478-9061...", // User ID (unique per pool)
    "email": "user@example.com",
    "aud": "1bb0d4cj0pqb...",  // Client ID (which app)
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxx",
    "iat": 1767485656,         // Issued at (unix timestamp)
    "exp": 1767489255          // Expires at (1 hour later)
  },
  "signature": "..." // Proves token wasn't tampered with
}

Stateless Authentication

JWTs are stateless - the server doesn't track sessions. On each request:

1. Client sends token in Authorization: Bearer <token> header
2. Server verifies signature using Cognito's public key (fetched from JWKS endpoint)
3. Server checks expiry time from exp field
4. Server verifies aud matches your app's client ID
5. If valid, request proceeds - no database lookup required

The token contains everything needed to verify the user. This makes authentication scalable and fast - no session storage, no database queries.

Key Features

• Format: Keys use ar_ prefix followed by 32 bytes of random data
• Storage: Keys are hashed with bcrypt - only the prefix is stored for identification
• One-Time Display: Full key is shown only once at creation - store it securely
• Verification: Public endpoint at POST /api/keys/verify (rate-limited)
• Revocation: Keys can be revoked immediately - verification will fail after revocation
• Usage Tracking: Last used timestamp is updated on each successful verification

Verification Flow

Service receives request with X-API-Key header
  ↓
Calls POST /api/keys/verify with the key
  ↓
Auth Return:
  1. Looks up by prefix (fast indexed lookup)
  2. Verifies against bcrypt hash
  3. Checks if revoked
  4. Updates last_used_at
  ↓
Returns { valid: true, app_id, user_id, ... } or { valid: false }

The Tradeoff of Stateless Auth

Because JWTs are stateless, once issued, a token is valid until it expires. There's no server-side session to invalidate. This is both a feature (scalability) and a limitation (immediate logout is difficult).

To force logout, you'd need:

Practical reality: A compromised token works for up to 1 hour. Design your security model accordingly. For sensitive operations, require re-authentication or use shorter-lived tokens.

Frontend Components

• Auth Component: Embedded login/signup UI (auth_component.js)
• Auth Header Component: User menu with logout (auth_header_component.js)
• Dashboard: App management interface for creating and configuring apps

Backend Services

• Auth Return Server: Flask app providing API endpoints and dashboard
• Cognito Service: Wrapper for AWS Cognito operations (pool creation, user management)
• Token Verification: JWT signature verification using Cognito's JWKS endpoint
• API Key Management: Key generation, hashing, and verification system

Database

• Apps Table: Stores app configuration, Cognito pool IDs, API keys
• API Keys Table: Stores hashed API keys with metadata (app_id, name, last_used_at)
• Rate Limits Table: Tracks rate limit attempts for security