 |
VOOZH | about |
|
VOOZH | about |
This section provides a step-by-step guide for installing, configuring, and testing the Auth0 WordPress plugin for the first time. It covers the initial setup process from installation through your first successful authentication test.
For detailed architectural information about how the plugin works internally, see Architecture. For specific configuration options, see Configuration Options.
This guide walks through:
Each step is covered in detail in the child pages:
The plugin requires:
| Requirement | Version | Notes |
|---|---|---|
| PHP | 8.1+ | See Support Policy for version lifecycle |
| WordPress | 6+ | Only the most recent actively-supported release |
| Database Permissions | Table creation | Required for custom tables |
| Composer | Latest | For dependency management |
| PSR-18 Implementation | Any | HTTP client (e.g., symfony/http-client) |
| PSR-17 Implementation | Any | HTTP factory (e.g., nyholm/psr7) |
Sources: README.md22-29
The following diagram illustrates the complete setup journey from initial installation through first successful login:
Diagram 1: Complete Getting Started Flow
Sources: README.md20-168
This diagram maps the setup process to the actual code files and WordPress hooks that execute during each phase:
Diagram 2: Setup Steps to Code Entity Mapping
Sources: wpAuth0.php1-100 README.md56-168
When you activate the plugin through the WordPress admin interface, a specific sequence of operations occurs to prepare the plugin for use:
Diagram 3: Activation Process Code Flow
The activation function performs the following operations:
Secret Generation: Creates three cryptographically secure secrets using random_bytes(64) (producing 64 random bytes, converted to 128-character hexadecimal strings):
auth0_cookie_secret: Used for cookie encryptionauth0_backchannel_logout_secret: Used to validate back-channel logout webhooksauth0_fallback_secret: Used for authentication fallback scenariosIdempotent Design: The function checks if secrets already exist before generating new ones. If secrets are present from a previous activation, they are not regenerated. This ensures that deactivating and reactivating the plugin does not invalidate existing sessions or configurations.
Persistent Storage: All secrets are stored in the WordPress options table using add_option(), making them available across all requests.
Sources: wpAuth0.php1-50 README.md92-99
During the first request after activation (when Plugin::run() is called), the plugin creates two custom database tables if they don't already exist:
| Table Name | Purpose | Key Columns |
|---|---|---|
auth0_accounts | Maps WordPress users to Auth0 identities | user_id, sub (Auth0 subject identifier), connection |
auth0_sync | Queues user synchronization events for background processing | id, type, user_id, data, created_at |
These tables are created using the database credentials configured for WordPress. The user must have CREATE TABLE privileges.
Why Custom Tables?: The plugin uses dedicated tables instead of WordPress options or post meta for performance reasons. Custom tables support efficient indexing and querying for user identity lookups and event queue processing, which are performance-critical operations.
Sources: README.md157-162
The plugin schedules two WordPress cron jobs:
auth0_cron_sync: Processes the event queue to synchronize user data with Auth0auth0_cron_maintenance: Performs cleanup operations on the auth0_accounts tableBy default, WordPress's cron system runs on page load, which is inefficient for production environments. The plugin documentation recommends configuring a system cron job to trigger WordPress cron periodically:
This ensures reliable, predictable execution of background synchronization tasks.
Sources: README.md163-168
The plugin stores configuration in WordPress options, organized into groups:
| Option Group | Stored In | Purpose |
|---|---|---|
auth0_client | WordPress options table | Auth0 credentials (Domain, Client ID, Client Secret) |
auth0_authentication | WordPress options table | Authentication settings (Enable, Auto-create users, Default role) |
auth0_sync | WordPress options table | Synchronization settings (Schedule, Events to sync) |
auth0_accounts | WordPress options table | Session pairing and advanced authentication settings |
These options are managed through the WordPress admin interface at WordPress Dashboard > Auth0.
Sources: README.md147-154
The Auth0 application must be configured with specific settings for the plugin to function correctly:
Diagram 4: Auth0 Application Required Settings
Sources: README.md100-145
| Issue | Symptom | Solution |
|---|---|---|
| Missing PSR implementations | Composer installation fails | Install symfony/http-client and nyholm/psr7 or compatible alternatives |
| Database permission error | Activation fails or admin error notice | Grant CREATE TABLE privilege to WordPress database user |
| "Invalid state" error during login | Login fails after Auth0 redirect | Ensure wp-login.php is not cached; verify callback URL matches exactly |
| Missing secrets after activation | Authentication doesn't work | Deactivate and reactivate plugin to generate secrets |
| WordPress URL mismatch | Callback fails or session issues | Ensure WordPress Address and Site Address match actual visitor-facing URLs |
| Cron jobs not running | User sync doesn't occur | Configure system cron instead of relying on WP-Cron on page load |
Sources: README.md120-145
Once the basic setup is complete and you've successfully tested a login:
For extending functionality or custom development, use the Auth0-PHP SDK instance via wpAuth0()->getSdk() rather than extending plugin classes directly. See Extending the Plugin for details.
Sources: README.md169-185
Refresh this wiki