This document provides a high-level introduction to the Auth0 WordPress plugin, explaining its purpose, architectural approach, and integration model with WordPress. For detailed feature descriptions, see Key Features and Capabilities. For installation and setup instructions, see Getting Started. For in-depth architectural documentation, see Architecture.
The Auth0 WordPress plugin is a production-ready authentication integration that replaces WordPress's native login system with Auth0's Universal Login experience. The plugin operates as a self-contained system built on top of the Auth0-PHP SDK (v8.18+), providing secure authentication, user synchronization, and session management without requiring custom code development.
Important Architectural Note: The plugin is not a Software Development Kit. Its internal APIs are not intended for direct extension or modification. Developers requiring custom Auth0 integrations should use the wpAuth0()->getSdk() method to access the underlying Auth0-PHP SDK instance rather than extending plugin classes.
Sources: README.md10-18 wpAuth0.php1-90
The plugin implements a complete replacement of WordPress's authentication flow by intercepting the wp-login.php page and redirecting users to Auth0's Universal Login. Upon successful authentication, the plugin creates or matches WordPress user accounts, establishes sessions, and maintains synchronization between WordPress and Auth0 user databases.
Sources: README.md10-12 High-level architecture diagrams (Diagram 3)
The plugin follows a singleton-based, action-oriented architecture with clear separation between initialization, business logic, and data persistence. The entry point wpAuth0.php1-90 defines the wpAuth0() global function that returns a singleton instance of the Auth0\WordPress\Plugin class.
The plugin implements the singleton pattern through the wpAuth0() function:
On first invocation, wpAuth0() instantiates the Plugin class, which loads configuration from WordPress options and initializes the Auth0-PHP SDK. Subsequent calls return the cached instance. This pattern ensures a single point of access throughout WordPress's execution lifecycle.
Sources: wpAuth0.php72-89 High-level architecture (Diagram 2)
The plugin is organized into four distinct layers:
| Layer | Purpose | Key Components |
|---|---|---|
| Core Layer | Initialization and SDK management | Plugin class, wpAuth0() function, SdkConfiguration builder |
| Action Layer | Business logic and WordPress integration | Authentication, Configuration, Sync, Updates action classes |
| Data Layer | Persistence and data access | Database class, custom tables (auth0_accounts, auth0_sync) |
| Infrastructure Layer | WordPress integration | Hooks system, PSR-4 autoloading (Auth0\WordPress namespace) |
Sources: High-level architecture (Diagram 1), wpAuth0.php34-38
The plugin integrates with WordPress through several well-defined interfaces:
During activation wpAuth0.php40-67 the plugin generates cryptographic secrets stored in WordPress options:
auth0_cookies['secret']: Session cookie encryption (128 hex characters)auth0_backchannel_logout['secret']: Back-channel logout verification (128 hex characters)auth0_authentication['fallback_secret']: Fallback authentication secret (128 hex characters)The Plugin::run() method registers action classes that hook into WordPress events:
init, login_form, wp_logout)user_register, profile_update, delete_user)admin_menu, admin_init)wp_loaded for cron scheduling)The plugin uses WordPress's wpdb class for database operations and stores configuration in the wp_options table with the auth0_ prefix:
| Option Key | Purpose |
|---|---|
auth0_client | Auth0 application credentials (domain, client ID, client secret) |
auth0_authentication | Authentication settings and fallback secret |
auth0_cookies | Session cookie configuration and encryption secret |
auth0_backchannel_logout | Back-channel logout configuration and secret |
auth0_sync | Background synchronization settings |
auth0_sessions | Session management configuration |
Sources: wpAuth0.php40-67 High-level architecture (Diagram 1, Diagram 6)
Handles the complete authentication lifecycle including redirect to Auth0 Universal Login, callback processing, token exchange, and session establishment. See Authentication Flow for details.
Provides WordPress admin interface for plugin settings, validates input, and persists configuration to the wp_options table. See Configuration Management for details.
Maintains bidirectional synchronization between WordPress users and Auth0 users using a queue-based approach with the auth0_sync table. Background processing occurs via WordPress Cron. See User Synchronization for details.
Implements two custom tables:
auth0_accounts: Maps WordPress user IDs to Auth0 connection identifiers (the sub claim)auth0_sync: Queues synchronization events for background processingSee Database Schema for complete table definitions.
Sources: High-level architecture (Diagrams 3, 4, 5, 6)
The plugin requires PSR-18 (HTTP Client) and PSR-17 (HTTP Factories) implementations for the Auth0-PHP SDK. When installed via Composer, these dependencies must be explicitly required:
composer require symfony/http-client nyholm/psr7 auth0/wordpress:^5.0
The plugin supports two autoloading modes:
vendor/scoper-autoload.php with namespaces prefixed to Auth0\WordPress\Vendor\* to prevent conflictsvendor/autoload.php for development or Composer-managed environmentsThe autoloader selection logic is implemented in wpAuth0.php34-38
Sources: README.md56-77 wpAuth0.php34-38 High-level architecture (Diagram 1)
| Component | Requirement |
|---|---|
| PHP Version | 8.1 or higher |
| WordPress Version | 6.0 or higher |
| Database | MySQL/MariaDB with table creation permissions |
| Auth0-PHP SDK | 8.18 or higher |
| HTTP Client | PSR-18 compatible implementation |
| HTTP Factories | PSR-17 compatible implementation |
For complete requirements and version support policy, see Requirements and Dependencies.
Sources: README.md22-28 wpAuth0.php7-11
The plugin follows this initialization sequence:
wpAuth0.php, Composer dependencies are autoloadedwpAuth0() creates singleton, builds SDK configuration, initializes Auth0-PHP SDKFor detailed initialization documentation, see Plugin Initialization and Bootstrap.
Sources: wpAuth0.php40-70 High-level architecture (Diagram 2)
Current plugin version: 5.5.0 (as defined in wpAuth0.php7 and wpAuth0.php26)
Version history and changelog available in CHANGELOG.md1-72
Sources: wpAuth0.php7 wpAuth0.php26 CHANGELOG.md1-72
Refresh this wiki