ADR-010: Passwordless-First Authentication & Authorization Simplification

Status

Proposed — Pending engineering team review

Context

Authentication and authorization is one of the most complex and tightly coupled parts of the platform. Passwordless authentication is already the primary login method — Magic Link (email/SMS) is how fans and experts access the platform. However, this critical capability is buried inside a custom Keycloak SPI, making it fragile, hard to extend, and version-coupled. The #1 priority is to make passwordless authentication a first-class, standalone capability that can evolve independently and expand to modern standards (passkeys, WebAuthn, biometrics).

Keycloak 26.3.2 serves as the identity hub for all 28+ production services across 4 tenants. The current setup includes:

Current Auth Architecture

Passwordless: Current State & Limitations

The platform already relies on passwordless as its primary authentication method, but the implementation is constrained:

The core problem: Passwordless is the platform’s competitive UX advantage (no passwords = lower friction for fans) but it’s trapped inside the most fragile part of the stack (custom Keycloak SPIs). Every Keycloak upgrade puts passwordless at risk.

Other Auth Problems

Decision

Simplify authentication and authorization through four targeted changes, with passwordless authentication as the #1 priority: build a standalone passwordless authentication service, consolidate to single Keycloak instance with shared realm, eliminate the users service, and adopt centralized authorization policies.

Change 1: Passwordless Authentication Service (TOP PRIORITY)

Current: Magic Link is a custom Keycloak SPI (Java code compiled into Keycloak Docker image). Tightly coupled to Keycloak internals. Must be rebuilt for every Keycloak version. Cannot be extended with modern passwordless methods.

Target: A standalone passwordless-auth-service that owns all passwordless authentication methods and works alongside Keycloak. This is not just “extracting Magic Link” — it’s building a passwordless platform that can grow.

Passwordless Method Roadmap

Architecture: Passwordless Auth Service

sequenceDiagram
    participant User
    participant App as Web/Mobile App
    participant PAS as Passwordless Auth Service
    participant KC as Keycloak
    participant SMS as Twilio
    participant Email as Email Service
    participant Redis as Redis (tokens)

    Note over PAS: MVP: Magic Link
    User->>App: Request passwordless login
    App->>PAS: POST /auth/passwordless {method: "magic-link", email/phone}
    PAS->>Redis: Store one-time token (15min TTL)
    PAS->>PAS: Rate limit check (per email/phone)
    alt Email
        PAS->>Email: Send Magic Link email
    else SMS
        PAS->>SMS: Send Magic Link SMS via Twilio
    end
    User->>App: Click magic link / deep link
    App->>PAS: POST /auth/passwordless/verify {token}
    PAS->>Redis: Validate + consume token
    PAS->>KC: Admin API: authenticate user (direct grant)
    KC->>PAS: Access token + refresh token
    PAS->>App: Return Keycloak tokens
    App->>App: Store tokens, proceed as authenticated

    Note over PAS: Phase 2: Passkeys
    User->>App: Register passkey (WebAuthn)
    App->>PAS: POST /auth/passkey/register {attestation}
    PAS->>PAS: Store public key credential
    User->>App: Login with passkey
    App->>PAS: POST /auth/passkey/authenticate {assertion}
    PAS->>PAS: Verify signature against stored credential
    PAS->>KC: Admin API: authenticate user
    KC->>PAS: Tokens
    PAS->>App: Return Keycloak tokens

Passwordless Auth Service Capabilities

Passwordless Auth Service Stack

• Java 21 / Spring Boot 3.x (same as all other services, uses core-lib patterns)
• Redis for token storage (15-minute TTL for Magic Links, longer for passkey challenges)
• Twilio for SMS delivery
• Email service for email delivery
• WebAuthn4J for passkey/FIDO2 support (Phase 2)
• Keycloak Admin API for token exchange
• PostgreSQL for passkey credential storage (Phase 2)

Mobile Passwordless Flow (ADR-009 Integration)

sequenceDiagram
    participant User
    participant RN as React Native App
    participant PAS as Passwordless Auth Service
    participant KC as Keycloak
    participant SS as SecureStore

    Note over User,SS: First Login (Magic Link)
    User->>RN: Tap "Sign In"
    RN->>PAS: POST /auth/passwordless {method: "magic-link", email}
    PAS-->>User: Email with deep link
    User->>RN: Tap deep link (Universal Link)
    RN->>PAS: POST /auth/passwordless/verify {token}
    PAS->>KC: Authenticate user
    KC->>PAS: Tokens
    PAS->>RN: Return tokens
    RN->>SS: Store tokens + enable biometric

    Note over User,SS: Returning User (Biometric)
    User->>RN: Open app
    RN->>RN: Check biometric enrollment
    RN->>User: Face ID / Touch ID prompt
    User->>RN: Biometric success
    RN->>SS: Retrieve refresh token
    RN->>KC: Refresh token exchange
    KC->>RN: New access token
    RN->>RN: Authenticated session

Why passwordless is #1 priority: Every user hits authentication on every session. A poor passwordless experience directly impacts engagement, conversion, and retention. Extracting this from Keycloak SPI unblocks: Keycloak upgrades, passkey support, mobile deep linking, and delivery analytics — all of which are blocked today.

Change 2: Single Keycloak Instance with Multi-Tenant Realm

Current: Separate Keycloak instances per tenant, each with its own realm.

Target: Single Keycloak instance (regional HA) with a shared realm and tenant-scoped groups.

graph TB
    subgraph "Current: Per-Tenant Keycloak"
        KC1[Keycloak<br/>agilenetwork realm]
        KC2[Keycloak<br/>nilgameplan realm]
        KC3[Keycloak<br/>vtnil realm]
        KC4[Keycloak<br/>speedofai realm]
    end

    subgraph "Target: Shared Keycloak"
        KC[Single Keycloak 26.x<br/>Regional HA]
        R1[Realm: platform]
        G1[Group: agilenetwork]
        G2[Group: nilgameplan]
        G3[Group: vtnil]
        G4[Group: speedofai]
        KC --> R1
        R1 --> G1
        R1 --> G2
        R1 --> G3
        R1 --> G4
    end

Benefits: - Single Keycloak to maintain, upgrade, and monitor - Users can exist across tenants (future: single login for multiple brands) - Client configs managed once, scoped by group - Zero custom SPIs (passwordless externalized in Change 1) - Simpler Terraform (1 instance, not 4+)

Tenant isolation: Keycloak groups + custom claims in JWT. Token includes tenant: "agilenetwork". Services validate tenant claim matches request context. Keycloak authorization services enforce tenant-scoped access.

Migration approach: 1. Export realm configs from all 4 Keycloak instances 2. Create unified platform realm with tenant groups 3. Import users into unified realm (Keycloak user IDs are UUIDs — preserve them) 4. Update Istio routing to point to single Keycloak 5. Update all service issuer-uri configs 6. Run parallel for validation period 7. Decommission per-tenant instances

Change 3: Eliminate Users Service

Current: The users service is a GraphQL wrapper around the Keycloak Admin API. Operations like createRole, addRoleToUser, searchUsers are direct pass-throughs.

Target: Absorb users service functionality into the identity-service (ADR-001) and the magic-link-service.

Benefit: Eliminates an entire microservice. Identity-service (celebrity + fan + users merged per ADR-001) handles all identity operations. Magic link gets its own lightweight service because it has a distinct lifecycle (stateless, Redis-backed, can scale independently).

Change 4: Centralized Authorization with OPA/Cedar

Current: Each service independently parses JWT claims and checks roles in application code. Authorization logic is scattered across 28+ services.

Target: Centralized authorization policy engine using OPA (Open Policy Agent) or Cedar, evaluated at the Istio sidecar level.

graph LR
    subgraph "Request Flow"
        CLIENT[Client<br/>JWT Bearer token]
        ISTIO[Istio Sidecar<br/>+ ExtAuthz filter]
        OPA[OPA / Cedar<br/>Policy Engine]
        SVC[Backend Service]
    end

    CLIENT -->|Request + JWT| ISTIO
    ISTIO -->|AuthZ check| OPA
    OPA -->|Allow/Deny| ISTIO
    ISTIO -->|Allowed request| SVC

Policy Example (OPA/Rego):

package authz

default allow = false

# Fans can view content
allow {
    input.method == "POST"
    input.path == "/api/content/graphql"
    input.token.realm_access.roles[_] == "fan"
    input.body.operationName == "queryContent"
}

# Experts can manage their own profile
allow {
    input.path == "/api/celebrity/graphql"
    input.token.realm_access.roles[_] == "celebrity"
    input.token.sub == input.body.variables.celebrityUserId
}

# Admins can access admin endpoints
allow {
    input.token.realm_access.roles[_] == "admin"
}

# Tenant isolation
allow {
    input.token.tenant == input.headers["x-tenant-id"]
}

Benefits: - Authorization logic defined in one place (policy files), not scattered across 28+ services - Policies can be tested independently (OPA has a built-in test framework) - Tenant isolation enforced at the mesh level, not in application code - Services become simpler — they trust that requests reaching them are authorized - Policy changes don’t require service redeployment

Implementation approach: 1. Deploy OPA as an Istio ExternalAuthorization provider 2. Start with coarse-grained policies (role-based, tenant-scoped) 3. Gradually move fine-grained authorization from services to OPA 4. Services keep JWT validation as defense-in-depth but delegate authorization

Combined Architecture

graph TB
    subgraph "Passwordless Layer (Priority #1)"
        PAS[Passwordless Auth Service<br/>Magic Link + Passkeys + Biometric<br/>Spring Boot + Redis]
    end

    subgraph "Identity Provider"
        KC[Single Keycloak 26.x<br/>Multi-tenant realm<br/>Regional HA]
    end

    subgraph "Authorization Layer"
        OPA[OPA Policy Engine<br/>Istio ExtAuthz]
    end

    subgraph "Identity Domain (ADR-001)"
        ID[identity-service<br/>celebrity + fan + users merged<br/>Profile management + Keycloak Admin API]
    end

    subgraph "All Other Services"
        SVC1[payment-service]
        SVC2[content-service]
        SVC3[notification-service]
        SVCN[... other services]
    end

    subgraph "Clients"
        WEB[Next.js Web]
        MOB[React Native Mobile]
    end

    WEB -->|Magic Link / Passkey| PAS
    MOB -->|Magic Link deep link / Biometric| PAS
    WEB -->|OAuth2 PKCE fallback| KC
    MOB -->|OAuth2 PKCE fallback| KC
    PAS -->|Token exchange| KC

    WEB -->|GraphQL + JWT| OPA
    MOB -->|GraphQL + JWT| OPA
    OPA -->|Authorized| SVC1
    OPA -->|Authorized| SVC2
    OPA -->|Authorized| SVC3
    OPA -->|Authorized| SVCN
    OPA -->|Authorized| ID

    ID -->|Admin API| KC

Simplification Summary

Hypothesis Background

Primary: Building a standalone passwordless authentication service that decouples passwordless flows from Keycloak SPIs will unlock passkey/WebAuthn support, mobile deep linking, and delivery analytics — while reducing auth complexity by ~60% through Keycloak consolidation, users service elimination, and centralized authorization.

• Evidence: Passwordless (Magic Link) is the primary login method for all users today, but it’s trapped in a custom Keycloak SPI that must be rebuilt for every Keycloak upgrade.
• Evidence: Modern passwordless standards (FIDO2/WebAuthn, passkeys) cannot be added without building yet another custom Keycloak SPI. Externalizing passwordless to a standard service makes these methods additive, not invasive.
• Evidence: H11 (L2) confirms all tenant differentiation is config-only. There’s no reason for separate Keycloak instances per tenant — a shared realm with tenant groups achieves the same isolation with less operational overhead.
• Evidence: The users service is a thin wrapper (15 GraphQL operations, most are Keycloak Admin API pass-throughs). Eliminating it removes a deployment, CI pipeline, Helm chart, and monitoring surface.

Alternative 1: Replace Keycloak with Auth0/Okta. - Rejected: Auth0 has native passwordless but at significant cost per MAU, and would require migrating all client configs, updating 28+ service issuer-uri configs, and reimplementing theme customization. Keycloak 26.x is mature and actively maintained. The problem isn’t Keycloak — it’s how passwordless is coupled to it via custom SPIs.

Alternative 2: Keep Magic Link as Keycloak SPI, add passkeys as another SPI. - Rejected: This doubles down on the coupling problem. Every Keycloak upgrade would now require rebuilding two custom SPIs. The SPI lifecycle (compile → build Docker image → deploy) is far heavier than a standalone service deployment.

Alternative 3: Use Keycloak’s built-in WebAuthn support. - Partially viable but insufficient: Keycloak 26.x has WebAuthn authenticator support, but it’s configured through the admin UI and authentication flows, not through APIs that the mobile app can call directly. A standalone passwordless service gives full API control for both web and React Native clients.

Alternative 4: Skip OPA, keep per-service authorization. - Not fully rejected — can be deferred. OPA adds infrastructure complexity. However, with 18 consolidated services (ADR-001) all needing tenant isolation (ADR-004), centralizing authorization prevents repeating the same tenant-check logic in every service.

Falsifiability Criteria

Passwordless-specific: - If passwordless-auth-service adds >1s latency to Magic Link login flow compared to current Keycloak SPI → optimize token exchange or implement caching - If Magic Link delivery rates drop below current levels after migration → investigate email/SMS delivery pipeline differences - If WebAuthn4J passkey registration fails on >5% of target devices (iOS 16+, Android 9+, Chrome 100+) → evaluate alternative FIDO2 libraries - If mobile deep linking (Universal Links / App Links) fails to open native app >10% of the time → implement fallback web flow with app banner - If passwordless-auth-service cannot handle peak authentication load (measure: >500 concurrent logins) → scale horizontally or add connection pooling

Infrastructure-specific: - If single Keycloak realm with tenant groups cannot enforce sufficient isolation (users seeing cross-tenant data) → revert to per-tenant realms within single instance - If OPA policy evaluation adds >50ms to request latency → simplify policies or move to application-level authorization - If migrating 4 realm configs to 1 unified realm loses user data or breaks existing sessions → extend parallel-run period - If React Native / Next.js Keycloak PKCE integration proves unreliable → implement BFF (Backend-for-Frontend) token exchange

Evidence Quality

Overall: L1 (WLNK capped by user migration testing L0 and passwordless delivery baseline L0)

Bounded Validity

• Scope: All authentication and authorization across all tenants and services. Affects every service that validates JWT tokens.
• Expiry: Re-evaluate if Keycloak introduces breaking changes to realm/group model, or if the platform needs federating with external identity providers (e.g., enterprise SSO for organization tenants).
• Review trigger: If auth-related incidents increase after consolidation, or if OPA policy complexity exceeds what the team can maintain.
• Monitoring: Passwordless login funnel (send → deliver → click → login success rate), auth latency (login flow p99), passkey registration/auth success rate, token validation latency, OPA decision latency, failed auth rate, deep link open rate (mobile).

Consequences

Positive: - Passwordless becomes a first-class, independently deployable capability - Path to passkeys, biometrics, and modern passwordless standards without Keycloak SPI changes - Mobile deep linking for Magic Links (direct native app launch) - Full passwordless analytics funnel (delivery, click-through, login success) - 80% fewer Keycloak instances to manage (5 → 1) - Zero custom Keycloak SPIs (removes version coupling — Keycloak becomes upgradeable) - One fewer microservice (users eliminated) - Centralized authorization logic (testable, auditable) - Simpler Terraform (1 Keycloak deployment, not 5) - Foundation for cross-brand user accounts - Aligns with ADR-004 (shared cluster), ADR-008 (web auth), and ADR-009 (mobile auth)

Negative: - Passwordless-auth-service is a new service (though simpler than the Keycloak SPI it replaces) - Passkey credential storage adds a data management responsibility - Single Keycloak instance is a bigger blast radius (mitigated by regional HA) - OPA adds a new technology to the stack (learning curve) - User migration from 4 realms to 1 requires careful planning and a maintenance window - Tenant isolation relies on claims and policies rather than physical separation

Mitigated by: Passwordless-auth-service follows existing core-lib patterns and is stateless (Redis + Keycloak). Passkey credentials can be stored in the identity database (ADR-005). Regional HA Keycloak eliminates SPOF. OPA policies are declarative and testable. User migration can be done per-tenant with parallel running. Istio + OPA provides defense-in-depth for tenant isolation.

Decision date: 2026-01-31 Review by: 2026-07-31