Installation

This page details the process of installing the Auth0 WordPress plugin, including dependency management, activation procedures, and initial setup. For information about configuring Auth0 credentials after installation, see WordPress Configuration. For Auth0 application setup requirements, see Auth0 Application Setup.

Prerequisites

Before installing the plugin, ensure your environment meets the following requirements:

Requirement	Specification	Notes
PHP Version	8.1 or higher	See Requirements and Dependencies for support policy
WordPress Version	6.x (most recent release)	Only the actively supported WordPress version is supported
PHP Extensions	ext-json, ext-openssl	Required for cryptographic operations and data handling
Database Permissions	Table creation privileges	Plugin creates custom tables auth0_accounts and auth0_sync
Composer	Latest stable version	Required for dependency management

The plugin uses custom database tables for high-performance user connection tracking and event queue management. Your WordPress database user must have CREATE TABLE permissions.

Sources: README.md22-29 composer.json35-40

Installation Method

Composer Installation

The plugin is distributed via Composer and is compatible with WPackagist. This is the only supported installation method as of v5.

Installation Location

The installation directory depends on your WordPress setup:

• Bedrock installations: Run from the root WordPress installation directory
• Standard WordPress installations: Run from the wp-content/plugins/ subdirectory

Installation Command

This command installs three packages:

1. auth0/wordpress - The Auth0 WordPress plugin
2. symfony/http-client - PSR-18 HTTP Client implementation
3. nyholm/psr7 - PSR-17 HTTP Factory implementation

Sources: README.md56-66

Installation Flow Diagram

Sources: README.md56-78 composer.json35-41

PSR Dependency Requirements

The plugin depends on the Auth0-PHP SDK (v8.17+), which requires implementations of PHP Standard Recommendations (PSR) for HTTP communication:

Required PSR Interfaces

PSR Standard	Purpose	Example Implementation
PSR-18	HTTP Client interface	symfony/http-client
PSR-17	HTTP Factory interface (for creating requests/responses)	nyholm/psr7
PSR-6	Caching interface	psr/cache (included)

Alternative Implementations

While the installation command above uses symfony/http-client and nyholm/psr7, you may substitute any compatible implementations:

PSR-18 Providers: Visit Packagist PSR-18 providers for alternatives

PSR-17 Providers: Visit Packagist PSR-17 providers for alternatives

Bedrock Optimization

If you are using Bedrock or another Composer-based WordPress configuration, you may attempt to install only auth0/wordpress without explicitly requiring PSR implementations, as they may already be satisfied by other installed packages:

If Composer reports missing PSR implementations, add them as needed.

Sources: README.md68-77 composer.json35-41

Package Structure

After installation, the plugin files are located in the Composer vendor directory:

Sources: composer.json61-64

Activation Process

After installing via Composer, the plugin must be activated in the WordPress Dashboard.

Activation Steps

1. Navigate to the WordPress Dashboard
2. Select Plugins → Installed Plugins from the sidebar
3. Locate "Auth0" in the plugin list
4. Click Activate beneath the plugin name

Activation Sequence

Sources: README.md92-99

Post-Activation Operations

Upon activation, the plugin performs the following operations:

1. Secret Generation

The activation hook generates three cryptographic secrets using PHP's random_bytes() function. Each secret is 64 random bytes converted to a 128-character hexadecimal string:

• auth0_cookie_secret: Used for encrypting cookie data in session management
• auth0_backchannel_logout_secret: Validates back-channel logout webhook requests from Auth0
• auth0_authentication_secret: Fallback authentication secret for session validation

These secrets are stored in the WordPress wp_options table and are never regenerated on subsequent activations (idempotent design).

2. Database Table Creation

The plugin creates two custom database tables using the same database credentials configured for WordPress:

Table Name	Purpose	See Also
auth0_accounts	Maps WordPress user IDs to Auth0 subject identifiers (sub)	Database Schema
auth0_sync	Queues user synchronization events for background processing	User Synchronization

The table creation process is idempotent - if tables already exist, no action is taken.

Sources: README.md:157-162, Diagram 2 from high-level architecture

Database Permission Requirements

The WordPress database user must have the following privileges:

• CREATE - For creating the auth0_accounts and auth0_sync tables
• SELECT, INSERT, UPDATE, DELETE - For normal table operations
• ALTER - For potential schema migrations in future versions

If your database user lacks these permissions, contact your hosting provider or database administrator.

Sources: README.md157-162

Verification

After successful installation and activation, verify the plugin is operational:

1. Check Plugin Status

Navigate to Plugins → Installed Plugins and confirm the Auth0 plugin shows as "Active".

2. Verify Admin Menu

A new "Auth0" menu item should appear in the WordPress Dashboard sidebar. This menu provides access to plugin configuration pages.

3. Check Database Tables

Connect to your WordPress database and verify the custom tables exist:

You should see:

• wp_auth0_accounts (or similar, depending on table prefix)
• wp_auth0_sync

4. Verify Secrets

Check that activation secrets were generated by running:

You should see three option entries with the generated secrets.

Sources: README.md149-154

Common Installation Issues

Composer Dependency Conflicts

Issue: Composer reports conflicts with existing packages.

Solution: If other plugins or themes have locked incompatible versions of dependencies, try:

1. Review composer.json for version constraints
2. Update conflicting packages to compatible versions
3. Use composer why-not to diagnose specific conflicts

Database Permission Errors

Issue: Plugin activation fails with database error messages.

Solution: Verify database user has CREATE TABLE privileges. Contact hosting provider if you cannot grant these permissions.

Missing PSR Implementations

Issue: Plugin fails to initialize with "PSR-18 implementation not found" errors.

Solution: Ensure PSR-18 and PSR-17 implementations are installed:

Autoloader Not Found

Issue: WordPress shows "Fatal error: Class 'Auth0\WordPress\Plugin' not found"

Solution: Ensure Composer's autoloader is properly included. For standard WordPress installations, the plugin's bootstrap file should handle this automatically. For custom setups, verify vendor/autoload.php is accessible.

Sources: README.md68-77

Next Steps

After successful installation and activation:

1. Configure Auth0 Application: See Auth0 Application Setup for creating and configuring your Auth0 application
2. Enter Credentials: See WordPress Configuration for entering Auth0 credentials in the plugin settings
3. Test Authentication: See First Login Test for testing the authentication flow

The plugin will not handle authentication until you complete these configuration steps. For detailed architecture information about what happens during the authentication flow, see Authentication Flow.

Sources: README.md100-154