LFX One Authentication Flows

This directory contains sequence diagrams documenting the authentication flows used in LFX One.

Overview

The authentication architecture uses multiple Auth0 clients and flows to support different use cases:

• LFX One Client: Regular web application used for server-side rendering authentication with LFX v2 API access
• LFX One Profile Client: Regular web application used for social account linking, self-service Auth0 access (user profile updates), and passwordless email linking. This client supports both Authorization Code flow for Management API access and OTP grant type for passwordless flows.
• LFX V2 Auth Service Client: Machine-to-machine client used by Auth Service for reading user profiles

Authentication Flows

Flow	Description	Client Used	Audience	Purpose
Flow A	Auth Service M2M	Auth Service M2M	auth0_mgmt	Read user profiles and check email-to-username mappings
Flow B	LFX One Login (SSR OIDC)	LFX One	lfxv2	Authenticate users and obtain access tokens for LFX v2 API
Flow C	Self-Service Profile Updates	LFX One Profile	auth0_mgmt	Allow users to update their own profiles via Management API
Flow D	Social Identity Linking	LFX One Profile	None	Link social identities (Google, GitHub, etc.) to user accounts
Flow E	Email Identity Linking	LFX One Profile	None	Link additional email addresses using passwordless OTP verification

Client Descriptions

LFX One Client

The main server-side rendering client used for user authentication. This is a regular web application client that implements the authorization code flow with grant types authorization_code and refresh_token (plus password-realm in dev environments for Cypress testing). It obtains access tokens with the lfxv2 audience for accessing the LFX v2 API (Traefik/Heimdall). This client is used exclusively in Flow B for the initial user login.

LFX One Profile Client

A regular web application client (app_type: regular_web) used for Auth0 Management API access and passwordless flows. This client uses the authorization code flow for obtaining Management API access tokens that allow users to update their own profiles and link identities. It also supports the passwordless OTP grant type (http://auth0.com/oauth/grant-type/passwordless/otp) for email verification flows. This client implements a dual authentication pattern where users first authenticate with the main LFX One client, then use this client to obtain additional access tokens for specific audiences (Management API) or perform passwordless verification. Used in Flows C, D, and E.

LFX V2 Auth Service M2M Client

A machine-to-machine (M2M) client named "LFX V2 Auth Service" that uses the client credentials grant type. This client is granted the create:users, read:users, update:users, and delete:users scopes for the Auth0 Management API. In Flow A it performs read-only operations such as profile lookups and checking email-to-username mappings; the broader scopes support additional Auth Service management use cases.

Token Overview

Token	Audience	Scope	Used For
access_token_m2m_read	auth0_mgmt	create:users, read:users, update:users, delete:users (Flow A uses read:users)	Auth Service reading user profiles (Flow A)
access_token_lfxv2	lfxv2	LFX v2 API	Calling LFX v2 API endpoints (Flow B)
access_token_mgmt_self	auth0_mgmt	update:current_user_metadata (Flow C) / update:current_user_identities (Flow D, E)	User self-service: profile update (C); identity linking (D, E)
access_token_social	(default)	N/A	Ignored - returned from social auth (Flow D)
access_token_pwdless	(default)	N/A	Ignored - returned from passwordless (Flow E)
id_token_user	N/A	N/A	User identity from main login (Flow B)
id_token_mgmt	N/A	N/A	Ignored - returned from mgmt flow (Flow C)
id_token_social	N/A	N/A	Social provider identity (Flow D)
id_token_pwdless	N/A	N/A	Passwordless email identity (Flow E)

Note: auth0_mgmt and lfxv2 are conceptual audience labels used throughout these docs. The actual JWT aud claim is the Auth0 Management API URL (https://{domain}/api/v2/) for auth0_mgmt, and the configured LFX v2 API audience for lfxv2.

Key Architecture Patterns

NATS Pub/Sub

Auth Service uses NATS for communication with LFX One SSR, subscribing to subjects for:

• Profile lookup requests
• Profile update requests
• Email linking requests
• Social identity linking requests

Auth Service Abstraction

All Auth0 Management API calls are abstracted through the Auth Service, which communicates with LFX One via NATS. This provides:

• Centralized token management
• Simplified client-side code
• Better security (Management API credentials stay in Auth Service)

Flow Dependencies

• Flow C, D, E all depend on Flow B (user must be logged in first)
• Flow D and E both use access_token_mgmt_self from Flow C to perform identity linking operations
• Flow A is independent and used by Auth Service for background operations

Security Considerations

1. M2M Client Scopes: The Auth Service M2M client is granted full Management API user scopes (create:users, read:users, update:users, delete:users); Flow A performs only read operations
2. Subject Validation: Flow C validates token subjects match before allowing profile updates
3. Email Verification: Flow E validates the email in id_token_pwdless matches the requested email before linking
4. Token Scoping: Each access token is scoped to specific audiences and permissions
5. Abstraction Layer: Management API calls go through Auth Service, not directly from client