Last indexed: 20 December 2025 (be493d)

Authentication Flow

This page details the complete authentication process in the Auth0 WordPress plugin, from initial login redirect through token exchange, user resolution, and session establishment. This covers how users authenticate via Auth0 Universal Login and how their identity is synchronized with WordPress.

For information about plugin initialization and SDK configuration, see Plugin Initialization and Bootstrap. For details about background user synchronization, see User Synchronization.

Overview

The authentication flow is managed primarily by the Authentication action class, which registers hooks for login, logout, session validation, and account management. The flow follows the OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange), coordinating between WordPress, Auth0's cloud platform, and the plugin's custom database tables.

Sources: src/Actions/Authentication.php1-726 README.md10-13

Authentication Entry Points

The plugin intercepts authentication at multiple WordPress hooks:

Hook	Method	Purpose
`init`	`onInit()`	Validates and maintains active sessions on every request
`login_form_login`	`onLogin()`	Handles wp-login.php access and callback processing
`auth0_login_callback`	`onLogin()`	Custom hook for programmatic login initiation
`login_form_logout`	`onLogout()`	Processes logout requests
`auth0_logout`	`onLogout()`	Custom hook for programmatic logout

The registry of these hooks is defined in the Authentication class's $registry property.

Sources: src/Actions/Authentication.php22-51

Complete Login Flow

Title: Complete Authentication Flow Sequence

Sources: src/Actions/Authentication.php433-551 src/Actions/Authentication.php660-724

Token Exchange Process

The token exchange happens in the onLogin() method when the callback URL contains both code and state query parameters.

Exchange Parameters Detection

Title: Token Exchange Decision Flow

The exchange process occurs at src/Actions/Authentication.php474-501:

Code and State Extraction: Retrieved via getSdk()->getRequestParameter('code') and getSdk()->getRequestParameter('state')
Exchange Call: getSdk()->exchange(code, state) exchanges the authorization code for tokens
Error Handling: If exchange fails, auth0_token_exchange_failed hook is triggered at line 499
Session Creation: The SDK stores the resulting tokens in session storage (cookies or PHP sessions)

Sources: src/Actions/Authentication.php474-501 src/Actions/Authentication.php553-558

User Identity Resolution

The resolveIdentity() method determines which WordPress user corresponds to an authenticated Auth0 identity. This is a critical security boundary.

Title: User Identity Resolution Decision Tree

Resolution Strategy

The resolution follows a strict priority order defined in src/Actions/Authentication.php660-724:

Connection-Based Lookup (lines 667-674): Check auth0_accounts table for exact sub match
Email-Based Lookup (lines 676-701): If email_verified is true, lookup by email address
- Flexible Mode (default): Match any verified email to existing WordPress user
- Strict Mode: Reject email matches; require explicit connection in auth0_accounts
- Admin Bypass: Administrators with pair_sessions=0 can bypass strict mode
User Creation (lines 703-721): If accounts.missing='create', create new WordPress user
- Username extracted from email prefix or Auth0 sub identifier
- Random password generated via wp_generate_password()
- Default role assigned from accounts.default_role configuration

Sources: src/Actions/Authentication.php660-724 src/Actions/Configuration.php41-82

Account Connection Mapping

The auth0_accounts table maintains the relationship between WordPress user IDs and Auth0 connection identifiers (the sub claim).

Database Schema

Column	Type	Description
`id`	BIGINT	Auto-increment primary key
`site`	TINYINT	WordPress network ID (for multisite)
`blog`	BIGINT	WordPress blog ID (for multisite)
`user`	BIGINT	WordPress user ID (foreign key to `wp_users.ID`)
`auth0`	TEXT	Auth0 connection identifier (user's `sub` claim)

Sources: src/Database.php101-118

Connection Management Operations

Title: Account Connection Management Operations

Connection Creation

The createAccountConnection() method at src/Actions/Authentication.php53-88 stores the mapping:

Cache Check: Queries wp_cache with key auth0_account_{hash(connection)}
Transient Check: Verifies if a recent lookup cached the result
Database Query: SELECT from auth0_accounts to check for existing mapping
Insert: If no mapping exists, INSERT new row with user, site, blog, and auth0 values
Cache Update: Store result in both wp_cache and transient for 120 seconds

Connection Lookup

The getAccountByConnection() method at src/Actions/Authentication.php111-154 retrieves users:

Uses same caching strategy as creation
Queries: SELECT user FROM {prefix}auth0_accounts WHERE site=%d AND blog=%d AND auth0="%s"
Returns WP_User object or null

Sources: src/Actions/Authentication.php53-154 src/Database.php101-118

Session Validation and Pairing

The onInit() method runs on every WordPress request to validate session consistency between WordPress and Auth0.

Title: Session Validation Flow (onInit)

Session Pairing Modes

The authentication.pair_sessions configuration controls session validation strictness:

Value	Constant	Behavior
`0`	Non-administrators	Pairing enforced for all users except administrators
`1`	All users (Recommended)	Pairing enforced for all users including administrators
`2`	Disabled	No session pairing validation

When pairing is enforced:

WordPress session without Auth0 session → wp_logout() called
Auth0 session without WordPress session → getSdk()->clear() called
Mismatched user identities → Both sessions invalidated
Expired token with refresh enabled → Automatic getSdk()->renew() attempted

Sources: src/Actions/Authentication.php353-431 src/Actions/Configuration.php200-211

Session Storage Methods

The plugin supports two session storage mechanisms configured via sessions.method:

Encrypted Cookies (Default)

Session data is stored in encrypted browser cookies using the CookieStore implementation from the Auth0 SDK. The cookie secret from cookies.secret is used for encryption.

Configuration: src/Plugin.php312-318

PHP Native Sessions

Session data is stored in PHP's native session mechanism. This requires proper PHP session configuration for security and reliability.

Sources: src/Actions/Configuration.php273-326

Rolling Sessions

When sessions.rolling_sessions is enabled (not 'false'), the onShutdown() method extends session lifetime on each request:

Title: Rolling Session Update Flow

This ensures both the Auth0 SDK session and WordPress authentication cookie are refreshed on every request, preventing premature expiration during active use.

Sources: src/Actions/Authentication.php573-589 src/Actions/Configuration.php306-315

WordPress Cookie Validation Hooks

The plugin registers handlers for WordPress's cookie validation hooks to maintain session consistency:

Hook	Handler	Action Taken
`auth_cookie_malformed`	`onAuthCookieMalformed()`	Clear Auth0 SDK session
`auth_cookie_expired`	`onAuthCookieExpired()`	Clear Auth0 SDK session
`auth_cookie_bad_username`	`onAuthCookieBadUsername()`	Clear Auth0 SDK session
`auth_cookie_bad_session_token`	`onAuthCookieBadSessionToken()`	Clear Auth0 SDK session
`auth_cookie_bad_hash`	`onAuthCookieBadHash()`	Clear Auth0 SDK session

All handlers call getSdk()->clear() to invalidate the Auth0 session when WordPress detects an invalid authentication cookie.

Sources: src/Actions/Authentication.php194-262

Logout Flow

The logout process clears both WordPress and Auth0 sessions:

Title: Logout Sequence

The onLogout() method at src/Actions/Authentication.php560-565:

Calls wp_logout() to destroy the WordPress session
Calls getSdk()->logout(get_site_url()) to get Auth0's logout URL
Redirects to Auth0 logout endpoint with returnTo parameter set to the WordPress site URL

Sources: src/Actions/Authentication.php560-565

Fallback Authentication

The plugin supports bypassing Auth0 login via a secret URL parameter for emergency access:

When authentication.allow_fallback is enabled and the correct authentication.fallback_secret is provided, the onLogin() method returns early, allowing WordPress's native login form to be displayed.

Configuration: src/Actions/Authentication.php443-452 src/Actions/Configuration.php212-227

Sources: src/Actions/Authentication.php443-452

Back-Channel Logout

The plugin supports OIDC Back-Channel Logout for coordinated session termination:

When a back-channel logout request is received with valid credentials, getSdk()->handleBackchannelLogout() processes the logout token and terminates the session.

Configuration: src/Actions/Configuration.php391-430

Sources: src/Actions/Authentication.php454-469 CHANGELOG.md28-35

Error Handling

Token Exchange Failures

When getSdk()->exchange() throws an exception at src/Actions/Authentication.php492-501:

Error is logged via error_log()
Custom hook auth0_token_exchange_failed is triggered
onExchangeFailed() handler redirects to homepage

Authentication Errors

When Auth0 returns an error (via ?error query parameter), the user is redirected to the homepage without attempting authentication.

Sources: src/Actions/Authentication.php492-558

Refresh this wiki

URL: https://deepwiki.com/auth0/wordpress/3.3-authentication-flow