VOOZH about

URL: https://deepwiki.com/auth0/wordpress

⇱ auth0/wordpress | DeepWiki

Loading...
Loading...
Menu

Overview

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.

Purpose and Scope

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

Authentication Replacement Model

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)




Core Architecture Paradigm


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.


Singleton Pattern


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)




Layered System Organization


The plugin is organized into four distinct layers:
































LayerPurposeKey Components
Core LayerInitialization and SDK managementPlugin class, wpAuth0() function, SdkConfiguration builder
Action LayerBusiness logic and WordPress integrationAuthentication, Configuration, Sync, Updates action classes
Data LayerPersistence and data accessDatabase class, custom tables (auth0_accounts, auth0_sync)
Infrastructure LayerWordPress integrationHooks system, PSR-4 autoloading (Auth0\WordPress namespace)




Sources: High-level architecture (Diagram 1), wpAuth0.php34-38




WordPress Integration Points


The plugin integrates with WordPress through several well-defined interfaces:


Plugin Activation Hook


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)
    • 



Action and Filter Hooks


The Plugin::run() method registers action classes that hook into WordPress events:


    

  • Login/logout flow (init, login_form, wp_logout)
    • 

  • User management (user_register, profile_update, delete_user)
    • 

  • Admin interface (admin_menu, admin_init)
    • 

  • Background tasks (wp_loaded for cron scheduling)
    • 



Database Integration


The plugin uses WordPress's wpdb class for database operations and stores configuration in the wp_options table with the auth0_ prefix:



































Option KeyPurpose
auth0_clientAuth0 application credentials (domain, client ID, client secret)
auth0_authenticationAuthentication settings and fallback secret
auth0_cookiesSession cookie configuration and encryption secret
auth0_backchannel_logoutBack-channel logout configuration and secret
auth0_syncBackground synchronization settings
auth0_sessionsSession management configuration


Sources: wpAuth0.php40-67 High-level architecture (Diagram 1, Diagram 6)




Key Subsystems


Authentication Subsystem


Handles the complete authentication lifecycle including redirect to Auth0 Universal Login, callback processing, token exchange, and session establishment. See Authentication Flow for details.


Configuration Subsystem


Provides WordPress admin interface for plugin settings, validates input, and persists configuration to the wp_options table. See Configuration Management for details.


Synchronization Subsystem


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.


Database Subsystem


Implements two custom tables:


    

  • auth0_accounts: Maps WordPress user IDs to Auth0 connection identifiers (the sub claim)
    • 

  • auth0_sync: Queues synchronization events for background processing
    • 



See Database Schema for complete table definitions.


Sources: High-level architecture (Diagrams 3, 4, 5, 6)




Dependency Management


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:


    

  1. Scoped build (preferred): Uses vendor/scoper-autoload.php with namespaces prefixed to Auth0\WordPress\Vendor\* to prevent conflicts
    2. 

  2. Standard build: Uses vendor/autoload.php for development or Composer-managed environments
    3. 



The autoloader selection logic is implemented in wpAuth0.php34-38


Sources: README.md56-77 wpAuth0.php34-38 High-level architecture (Diagram 1)




System Requirements



































ComponentRequirement
PHP Version8.1 or higher
WordPress Version6.0 or higher
DatabaseMySQL/MariaDB with table creation permissions
Auth0-PHP SDK8.18 or higher
HTTP ClientPSR-18 compatible implementation
HTTP FactoriesPSR-17 compatible implementation


For complete requirements and version support policy, see Requirements and Dependencies.


Sources: README.md22-28 wpAuth0.php7-11




Plugin Lifecycle Overview


The plugin follows this initialization sequence:


    

  1. Activation Phase: WordPress triggers activation hook, plugin generates cryptographic secrets
    2. 

  2. Bootstrap Phase: WordPress loads wpAuth0.php, Composer dependencies are autoloaded
    3. 

  3. Initialization Phase: First call to wpAuth0() creates singleton, builds SDK configuration, initializes Auth0-PHP SDK
    4. 

  4. Runtime Phase: Plugin registers action classes with WordPress hooks system
    5. 

  5. Operation Phase: Action classes handle authentication, configuration, and synchronization events
    6. 



For detailed initialization documentation, see Plugin Initialization and Bootstrap.


Sources: wpAuth0.php40-70 High-level architecture (Diagram 2)




Version Information


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