 |
VOOZH | about |
|
VOOZH | about |
The Auth0 WordPress Plugin replaces the standard WordPress login flow with Auth0's Universal Login experience, enabling enterprise-grade authentication features such as Multi-Factor Authentication (MFA), Single Sign-On (SSO), Passwordless, and PassKey authentication. This document explains the plugin's core purpose, the problems it solves, and its relationship to the Auth0-PHP SDK.
Sources: README.md10-12 wpAuth0.php3-6
The Auth0 WordPress Plugin is a WordPress integration that replaces wp-login.php with a redirect to Auth0's Universal Login page. When users attempt to log in, they are sent to Auth0 for authentication, then redirected back to WordPress with a secure token. The plugin exchanges this token for user information and creates or updates the corresponding WordPress user account.
| Function | Implementation |
|---|---|
| Replace WordPress Login | Intercepts wp-login.php requests and redirects to Auth0 Universal Login |
| Process Authentication Callbacks | Handles OAuth/OIDC authorization code exchange and token validation |
| Synchronize User Data | Maintains bidirectional sync between WordPress wp_users table and Auth0 user profiles |
| Manage Sessions | Pairs WordPress authentication cookies with Auth0 sessions for consistent state |
| Store Connection Mappings | Maps WordPress user IDs to Auth0 identities in the auth0_accounts custom table |
The plugin is built on the Auth0\SDK\Auth0 class from the Auth0-PHP SDK v8.18+, which handles all Auth0 protocol implementation and API communication.
Sources: README.md10-12 wpAuth0.php22-24 README.md171-172
WordPress's native authentication system has significant limitations for modern web applications. The Auth0 WordPress Plugin addresses these problems by delegating authentication to Auth0's platform:
| WordPress Limitation | Auth0 Solution | Plugin Implementation |
|---|---|---|
| Password-only authentication | MFA, Passwordless, PassKey, biometric options | Configured in Auth0 tenant; plugin handles all authentication flows |
| No built-in MFA | SMS, Email, Authenticator app, Push notifications | Auth0 enforces MFA policies; plugin receives authenticated users |
| Vulnerable password reset flow | Secure passwordless authentication and magic links | Plugin redirects all authentication to Auth0 |
| No SSO capability | Enterprise SSO with SAML, OAuth, OIDC connections | Plugin receives SSO session tokens from Auth0 |
| Limited social login support | 30+ social identity providers (Google, GitHub, Apple, etc.) | Plugin maps social identities to WordPress users |
| No adaptive authentication | Risk-based authentication, anomaly detection, bot detection | Auth0 tenant policies apply to all plugin logins |
| Manual user provisioning | Just-in-time provisioning from enterprise directories | Plugin creates WordPress users automatically from Auth0 identities |
Organizations with compliance, security, or user experience requirements cannot rely on WordPress's basic authentication. The plugin enables:
Sources: README.md10-12 CHANGELOG.md28-35
The Auth0 WordPress Plugin is not a Software Development Kit. Its internal classes, methods, and APIs are explicitly marked as internal and will change without backward compatibility guarantees.
| API Surface | Stability | Usage |
|---|---|---|
wpAuth0() global function defined in wpAuth0.php79-89 | Public/Stable | Safe to call from any WordPress code |
Auth0\WordPress\Plugin::getSdk() method | Public/Stable | Returns configured Auth0\SDK\Auth0 instance |
All other Auth0\WordPress\* classes and methods | Internal/Unstable | Will change without notice - do not use |
Sources: README.md14-15 README.md169-184 wpAuth0.php79-89
The plugin operates as an integration layer between WordPress and Auth0, with a clear separation of responsibilities across three tiers:
| Layer | File/Class Location | Purpose |
|---|---|---|
| Entry Point | wpAuth0.php1-90 | Defines plugin metadata, registers activation hook, loads autoloader |
| Plugin Core | src/Plugin.php | Singleton orchestrator; initializes SDK; registers action classes |
| Action Classes | src/Actions/*.php | Internal handlers for authentication, configuration, synchronization |
| Auth0 SDK | Auth0\SDK\Auth0 (external dependency) | Implements OAuth/OIDC protocols and Auth0 API clients |
| Custom Tables | Created by src/Database.php | Store Auth0-WordPress user mappings and sync event queues |
The plugin's internal classes (Auth0\WordPress\*) are not designed for extension. Custom development must use the SDK layer (Auth0\SDK\Auth0) accessed via wpAuth0()->getSdk().
Sources: wpAuth0.php1-90 README.md171-172
WordPress loads the plugin through wpAuth0.php1-90 which performs three bootstrap operations:
The scoped autoloader prefixes all vendor dependencies under Auth0\WordPress\Vendor\* to prevent namespace conflicts with other WordPress plugins.
Generates three cryptographic secrets (128 hex characters each) stored in wp_options:
auth0_cookies['secret'] - encrypts session cookiesauth0_backchannel_logout['secret'] - validates BCL webhook signaturesauth0_authentication['fallback_secret'] - fallback authentication validationThe wpAuth0() function implements a singleton pattern, returning the same Auth0\WordPress\Plugin instance on every call. The first invocation creates the instance, initializes the Auth0\SDK\Auth0 object, and registers WordPress hooks via wpAuth0()->run() at wpAuth0.php70
Sources: wpAuth0.php34-90
The plugin maintains a connection mapping between WordPress user accounts and Auth0 identities using the custom auth0_accounts database table:
When a user authenticates through Auth0 and returns to WordPress:
Auth0\WordPress\Actions\Authentication class receives the Auth0 sub claim (e.g., auth0|507f1f77bcf86cd799439011)auth0_accounts table for matching connection column valueuser_idwp_users and new row in auth0_accounts| Table | Column | Purpose |
|---|---|---|
auth0_accounts | user_id | Foreign key to wp_users.ID |
auth0_accounts | connection | Auth0 sub claim (identity provider + unique ID) |
auth0_accounts | created_at | Timestamp when mapping was created |
This mapping allows a single WordPress user to have multiple Auth0 identities (e.g., Google social login and enterprise SAML connection), all linking to the same WordPress account.
Sources: README.md157-161
The Auth0 WordPress Plugin requires both WordPress components and external PHP libraries:
| Requirement | Version | Verified By |
|---|---|---|
| WordPress Core | 6.0+ | wpAuth0.php8 |
| PHP Runtime | 8.1, 8.2, or 8.3 | wpAuth0.php11 |
| Database Privileges | Table creation permissions | Required during activation |
| WordPress Cron | Configured for background tasks | Required for sync operations |
The plugin is built on the Auth0-PHP SDK v8.18+:
When installed via Composer (recommended), the plugin requires PSR-18 and PSR-17 implementations. The README.md64-66 example uses:
symfony/http-client (PSR-18 HTTP Client)nyholm/psr7 (PSR-17 HTTP Factories)Other compatible implementations can be substituted. See Installation for Composer dependency details.
Production builds use PHP Scoper to prefix all vendor dependencies under Auth0\WordPress\Vendor\* namespace, preventing conflicts with other WordPress plugins that may use different versions of the same libraries.
Sources: wpAuth0.php8-11 wpAuth0.php22-24 README.md64-77
The plugin creates two custom tables in the WordPress database during activation:
Stores the mapping between WordPress user IDs and Auth0 identity providers:
| Column | Type | Purpose |
|---|---|---|
id | Primary Key | Auto-incrementing row identifier |
user_id | Foreign Key | References wp_users.ID |
connection | VARCHAR | Auth0 sub claim (e.g., `auth0 |
created_at | TIMESTAMP | When the mapping was created |
Queues user synchronization events for background processing by WordPress Cron:
| Column | Type | Purpose |
|---|---|---|
id | Primary Key | Auto-incrementing row identifier |
event_type | VARCHAR | Event type: user_created, user_updated, user_deleted |
user_id | Integer | WordPress user ID that triggered the event |
payload | JSON | Event data to sync to Auth0 |
status | VARCHAR | Processing status: pending, processing, completed, failed |
created_at | TIMESTAMP | When event was queued |
processed_at | TIMESTAMP | When event was processed (NULL if pending) |
The auth0_sync table enables bidirectional synchronization between WordPress and Auth0. When WordPress user accounts are created, updated, or deleted, events are queued here and processed by the background sync system, which calls the Auth0 Management API to replicate changes.
Sources: README.md157-161 README.md163-168
The Auth0 WordPress Plugin is a WordPress integration, not an extensible SDK. It replaces WordPress's default login system with Auth0's Universal Login while maintaining compatibility with WordPress's user database through connection mapping and synchronization.
Key Characteristics:
wpAuth0.php bootstrap fileAuth0\WordPress\Plugin singletonwpAuth0()->getSdk() returns the configured SDK instanceauth0_accounts, auth0_sync) plus WordPress optionsDevelopers seeking to customize authentication behavior should use the Auth0-PHP SDK directly through the provided getSdk() method, not by extending the plugin's internal classes.
Sources: README.md10-15 README.md169-184 Diagram 1, Diagram 2
Refresh this wiki