VOOZH about

URL: https://deepwiki.com/auth0/wordpress/1.2-key-features-and-capabilities

⇱ Key Features and Capabilities | auth0/wordpress | DeepWiki

Loading...
Loading...
Menu

Key Features and Capabilities

This document describes the major capabilities provided by the Auth0 WordPress Plugin. It focuses on what the plugin can do at a feature level, with references to key code components. For configuration details, see Configuration Options. For implementation architecture, see Architecture.

For information about system requirements and dependencies, see Requirements and Dependencies.

Authentication Features

The plugin replaces WordPress's native authentication with Auth0's Universal Login, enabling modern authentication methods.

Universal Login

All login attempts redirect to Auth0's hosted Universal Login page instead of WordPress's wp-login.php form. The Authentication::onLogin() method in src/Actions/Authentication.php433-550 intercepts WordPress's login_form_login action and redirects to the Auth0-PHP SDK's login() method.

Key Capabilities:

  • Hosted authentication page with Auth0 branding or custom domains
  • OAuth 2.0 / OIDC compliant flow
  • Authorization code exchange for tokens via SDK::exchange()
  • Callback handling at wp-login.php?code=...&state=...
  • Optional fallback to WordPress native login with secret URL parameter (?auth0_fb={secret})

Configuration Points:

  • auth0_state[enable] - Enables/disables authentication replacement
  • auth0_authentication[allow_fallback] - Controls native WordPress login access
  • auth0_authentication[fallback_secret] - Cryptographic secret for fallback URL

Sources: README.md12 src/Actions/Authentication.php433-550 src/Actions/Configuration.php29-228

Multi-Factor Authentication (MFA)

The plugin supports all MFA methods configured in your Auth0 tenant without additional plugin configuration:

  • Time-based One-Time Passwords (TOTP via authenticator apps)
  • SMS-based verification codes
  • Email-based verification codes
  • Push notifications (Auth0 Guardian, Duo)
  • WebAuthn/FIDO2 security keys
  • Voice-based authentication

MFA enforcement policies and methods are configured in the Auth0 Dashboard. The plugin's Authentication::onLogin() method handles MFA transparently through the authorization code flow.

Sources: README.md12 src/Actions/Authentication.php484-501

Single Sign-On (SSO)

Auth0's Universal Login provides SSO capabilities across multiple applications sharing the same Auth0 tenant and configuration. When a user authenticates with one application, subsequent logins to other applications can skip credential entry.

SSO Session Behavior:

  • SSO sessions are managed by Auth0, not the plugin
  • Session duration controlled by Auth0 tenant settings
  • Silent authentication available when SSO session is active
  • No additional plugin configuration required

Sources: README.md12

Social Login Connections

All social identity providers configured in your Auth0 tenant are automatically available through Universal Login. Common providers:

  • Google
  • Facebook
  • Apple
  • GitHub
  • Microsoft
  • LinkedIn
  • Twitter/X
  • Any OAuth 2.0 or OIDC provider

The Authentication::resolveIdentity() method in src/Actions/Authentication.php660-724 handles users from any connection type identically, mapping them to WordPress users through the auth0_accounts table.

Sources: README.md12 src/Actions/Authentication.php660-724 src/Database.php101-118

Passwordless Authentication

Passwordless authentication allows users to log in without traditional passwords using email or SMS:

Email Passwordless:

  • Magic link sent to user's email address
  • One-time code sent to user's email address

SMS Passwordless:

  • One-time code sent to user's mobile phone

Configuration:

Sources: README.md12 src/Actions/Configuration.php72-81

Passkey Support

The plugin supports WebAuthn/FIDO2 passkeys when configured in your Auth0 tenant:

  • Platform authenticators (Windows Hello, Touch ID, Face ID)
  • Hardware security keys (YubiKey, Titan)
  • Biometric authentication
  • Device-bound credentials

Passkey authentication flows through the standard authorization code flow with no additional plugin configuration required.

Sources: README.md12

Enterprise Connections

All enterprise identity providers configured in Auth0 are supported:

  • SAML 2.0 connections
  • WS-Federation
  • OpenID Connect (OIDC)
  • LDAP/Active Directory (via Auth0 AD/LDAP Connector)
  • Azure Active Directory
  • Google Workspace
  • Any SAML or OIDC enterprise provider

Sources: README.md12

Authentication Flow Overview

Diagram: Authentication Method Support



Sources: src/Actions/Authentication.php433-724 src/Database.php101-118




User Management Features


The plugin provides flexible strategies for mapping Auth0 identities to WordPress user accounts.


Flexible Identifiers


Flexible identifiers (introduced in v5) allow users to authenticate with multiple connection types without requiring account linking configuration. The plugin automatically handles users who sign in with different providers using the same email address.


Capabilities:


    

  • Users can sign in with Google, then later with email/password using the same account
    • 

  • Automatic account linking based on verified email addresses
    • 

  • No additional Auth0 configuration required for basic linking scenarios
    • 

  • Controlled by auth0_accounts[matching] configuration option
    • 



Sources: README.md12 CHANGELOG.md62-68


Identity Resolution Strategies


The Authentication::resolveIdentity() method in src/Actions/Authentication.php660-724 implements a three-stage resolution process:


Stage 1: Auth0 Subject Lookup


    

  • Queries auth0_accounts table via getAccountByConnection(sub)
    • 

  • Returns matched WordPress user if connection exists
    • 

  • Proceeds to Stage 2 if no match found
    • 



Stage 2: Email-Based Matching


    

  • Requires verified email (email_verified: true in ID token)
    • 

  • Queries WordPress via get_user_by('email', $email)
    • 

  • Behavior controlled by auth0_accounts[matching] setting:

      

    • flexible: Links existing WordPress user to Auth0 connection
      • 

    • strict: Rejects login unless connection pre-exists
      • 

    

    • 



Stage 3: Auto-Creation


    

  • Only executes if auth0_accounts[missing] is set to create
    • 

  • Creates new WordPress user via wp_create_user()
    • 

  • Assigns role from auth0_accounts[default_role] configuration
    • 

  • Generates random password (unused; authentication always via Auth0)
    • 



Identity Resolution Configuration





































SettingValuesBehavior
matchingflexibleLink existing WordPress users by verified email
strictRequire explicit Auth0 connection; reject email-only matches
missingcreateAuto-create WordPress user for new Auth0 identities
rejectReject login if no WordPress user exists
default_roleWordPress roleRole assigned to auto-created users (e.g., subscriber)


Sources: src/Actions/Authentication.php660-724 src/Actions/Configuration.php44-71


Organization Support


The plugin supports Auth0 Organizations (added in v5.1.0), enabling multi-tenant applications:


Capabilities:


    

  • Organization ID and Organization Name claims in tokens
    • 

  • Organization-based access control via auth0_client_advanced[organization] configuration
    • 

  • Automatic organization context during authentication
    • 

  • Organization membership validation during token exchange
    • 



Configuration:



Sources: CHANGELOG.md41 src/Actions/Configuration.php245-254


Account Connection Management


The auth0_accounts table (schema in src/Database.php101-118) maintains mappings between WordPress users and Auth0 identities:


Table Schema:


    

  • id - Primary key
    • 

  • site - Network site ID (multisite support)
    • 

  • blog - Blog ID (multisite support)
    • 

  • user - WordPress user ID (foreign key to wp_users.ID)
    • 

  • auth0 - Auth0 connection identifier (sub claim from ID token)
    • 



Key Operations:



Diagram: Identity Resolution Flow




Sources: src/Actions/Authentication.php660-724 src/Database.php101-118




Synchronization Features


The plugin provides bidirectional synchronization between WordPress and Auth0 user databases using a queue-based background processing system (introduced in v5).


Background Synchronization


User changes in WordPress are queued and processed asynchronously via WordPress cron, preventing performance degradation on user-facing requests:


Supported Event Types:


    

  • User creation - edit_user_created_user hook → Sync::eventUserCreated()
    • 

  • User updates - profile_update hook → Sync::eventUserUpdated()
    • 

  • User deletion - deleted_user hook → Sync::eventUserDeleted()
    • 



Configuration:


    

  • auth0_sync_events[user_creation] - Enable/disable user creation sync
    • 

  • auth0_sync_events[user_updates] - Enable/disable user update sync
    • 

  • auth0_sync_events[user_deletion] - Enable/disable user deletion sync
    • 

  • auth0_sync[schedule] - Cron interval in seconds (300-604800)
    • 

  • auth0_sync[database] - Auth0 database connection ID for new users
    • 



Sources: README.md62-68 src/Actions/Configuration.php110-190 src/Actions/Sync.php76-186


Event Queue System


The auth0_sync table (schema in src/Database.php121-140) queues synchronization events for background processing:


Table Schema:


    

  • id - Primary key
    • 

  • site - Network site ID (multisite support)
    • 

  • blog - Blog ID (multisite support)
    • 

  • created - Unix timestamp of event creation
    • 

  • payload - JSON-encoded event data
    • 

  • hashsum - SHA256 checksum for deduplication
    • 

  • locked - Processing lock flag
    • 



Queue Processing:


    

  1. WordPress user event fires (create/update/delete)
    2. 

  2. Event handler serializes event data to JSON with checksum
    3. 

  3. Event inserted into auth0_sync table via Database::insertRow()
    4. 

  4. AUTH0_CRON_SYNC cron job processes up to 10 events per execution
    5. 

  5. Sync::onBackgroundSync() dispatches events to handlers src/Actions/Sync.php214-254
    6. 

  6. Successfully processed events deleted from queue
    7. 



Sources: src/Database.php121-140 src/Actions/Authentication.php270-350 src/Actions/Sync.php214-254


Sync Operation Handlers


User Creation (src/Actions/Sync.php76-115):


    

  • Checks for existing Auth0 user via management()->usersByEmail()->get()
    • 

  • Creates Auth0 user via management()->users()->create() in configured database connection
    • 

  • Sends password reset email via management()->tickets()->createPasswordChange()
    • 

  • Records connection in auth0_accounts table
    • 



User Updates (src/Actions/Sync.php140-186):


    

  • Retrieves all Auth0 connections for WordPress user ID
    • 

  • Updates each connection via management()->users()->update()
    • 

  • Triggers email verification if email address changed
    • 



User Deletion (src/Actions/Sync.php117-138):


    

  • Verifies connection ownership (not claimed by another WordPress user)
    • 

  • Deletes Auth0 user via management()->users()->delete()
    • 

  • Removes orphaned records from auth0_accounts table
    • 



Diagram: Synchronization Architecture




Sources: src/Actions/Authentication.php270-350 src/Actions/Sync.php76-254 src/Database.php121-140


Maintenance Tasks


The plugin runs periodic maintenance via the AUTH0_CRON_MAINTENANCE cron job (5-minute interval):


    

  • Cleans orphaned records from auth0_accounts table
    • 

  • Removes stale locked events from auth0_sync table
    • 

  • Handled by Sync::onBackgroundMaintenance() in src/Actions/Sync.php188-212
    • 



Sources: src/Actions/Sync.php188-268




Session Management Features


The plugin provides enhanced session management capabilities (introduced in v5) including session pairing, token refresh, and back-channel logout.


Session Pairing


Session pairing (added in v5) enforces consistency between WordPress sessions and Auth0 authentication state. The Authentication::onInit() method in src/Actions/Authentication.php353-431 validates sessions on every WordPress request.


Pairing Modes:



























ModeValueBehavior
Administrators Exempt0Enforces pairing for non-admin users; allows admin fallback
All Users (Recommended)1Enforces pairing for all users including administrators
Disabled2No session validation; legacy compatibility mode


Validation Process:


    

  1. Executes on every request via WordPress init hook
    2. 

  2. Retrieves Auth0 credentials via SDK::getCredentials()
    3. 

  3. Verifies WordPress user matches Auth0 sub via getAccountByConnection()
    4. 

  4. Clears mismatched sessions: wp_logout() + SDK::clear()
    5. 

  5. Attempts token refresh if access token expired (when refresh tokens enabled)
    6. 



Configuration:



Sources: CHANGELOG.md62-68 src/Actions/Authentication.php353-431 src/Actions/Configuration.php201-211


Token Refresh


The plugin automatically refreshes expired access tokens when refresh tokens are enabled:


Refresh Process:


    

  • Triggered when SDK::getCredentials()->accessTokenExpired returns true
    • 

  • Executes SDK::renew() to exchange refresh token for new access token
    • 

  • Falls back to forced re-authentication if refresh fails
    • 

  • Handled in src/Actions/Authentication.php413-428
    • 



Configuration:


    

  • auth0_sessions[refresh_tokens] - Enable refresh token support
    • 

  • Requires enabling "Refresh Token" grant in Auth0 Application settings
    • 



Sources: src/Actions/Authentication.php413-428 src/Actions/Configuration.php289-298


Rolling Sessions


Rolling sessions extend session lifetime on each request, preventing expiration during active use:


Implementation:


    

  • Authentication::onShutdown() executes on WordPress send_headers hook
    • 

  • Calls $store->setState(true) on Auth0 session storage
    • 

  • Updates WordPress auth cookie via wp_set_auth_cookie()
    • 

  • Defined in src/Actions/Authentication.php573-589
    • 



Configuration:


    

  • auth0_sessions[rolling_sessions] - Enable/disable rolling sessions
    • 



Sources: src/Actions/Authentication.php573-589 src/Actions/Configuration.php299-308


Back-Channel Logout


OIDC Back-Channel Logout (added in v5.2.0) enables Auth0 to terminate sessions server-side via webhook:


Capabilities:


    

  • Remote session termination initiated by Auth0
    • 

  • Validates logout tokens via JWT signature verification
    • 

  • Terminates all matching WordPress and Auth0 sessions
    • 

  • Supports logout propagation across multiple applications
    • 



Implementation:


    

  1. Auth0 POSTs logout token to wp-login.php?auth0_bcl={secret}
    2. 

  2. Plugin validates URL secret matches auth0_backchannel_logout[secret]
    3. 

  3. Calls SDK::handleBackchannelLogout($logoutToken) in src/Actions/Authentication.php454-468
    4. 

  4. SDK validates JWT and clears matching sessions
    5. 



Webhook URL Format:


https://example.com/wp-login.php?auth0_bcl={backchannel_logout_secret}



Configuration:


    

  • auth0_backchannel_logout[enabled] - Enable/disable back-channel logout
    • 

  • auth0_backchannel_logout[secret] - Validation secret (auto-generated at activation)
    • 

  • auth0_backchannel_logout[ttl] - Logout token expiration (0-2592000 seconds)
    • 

  • Defined in src/Actions/Configuration.php391-431
    • 



Sources: CHANGELOG.md32 src/Actions/Authentication.php454-468 src/Actions/Configuration.php391-431


Session Storage


The plugin supports two session storage mechanisms:


Cookie Storage:


    

  • Encrypted cookies using auth0_cookies[secret]
    • 

  • Cookie expiration controlled by auth0_cookies[ttl] (0-2592000 seconds)
    • 

  • Cookie secret generated during plugin activation
    • 



PHP Session Storage (Recommended):


    

  • Uses native PHP sessions
    • 

  • Session expiration controlled by auth0_sessions[session_ttl] (0-2592000 seconds)
    • 

  • Recommended for production due to better security and scalability
    • 



Configuration:



Sources: src/Actions/Configuration.php273-326 wpAuth0.php43-49




Security Features


Cryptographic Secret Management


The plugin generates three cryptographic secrets during activation (see wpAuth0.php activation hook):































SecretOption KeyPurposeGeneration
Cookie Secretauth0_cookies[secret]Encrypts session cookiesbin2hex(random_bytes(64)) - 128 hex chars
Back-Channel Secretauth0_backchannel_logout[secret]Validates BCL webhooksbin2hex(random_bytes(64)) - 128 hex chars
Fallback Secretauth0_authentication[fallback_secret]WordPress login fallbackbin2hex(random_bytes(64)) - 128 hex chars


Important Characteristics:


    

  • Generated once during activation, never regenerated
    • 

  • Stored in WordPress options table
    • 

  • Changing cookie secret logs out all users
    • 

  • Secrets are idempotent (same activation won't regenerate)
    • 



Sources: src/Actions/Configuration.php223-429


Input Sanitization


The Sanitize utility class in src/Utilities/Sanitize.php provides type-specific sanitization:










































MethodUse CaseImplementation
alphanumeric()Client IDs, tokensRegex [^A-Za-z0-9 ] removal
boolean()Boolean optionsConverts to 'true'/'false' strings
domain()Auth0 domainsParse and validate host component
integer()Numeric configsRange validation with min/max
string()General textWordPress sanitize_text_field()
textarea()Multi-line textWordPress sanitize_textarea_field()


All configuration updates in src/Actions/Configuration.php693-1044 pass through sanitization methods before database storage.


Sources: src/Utilities/Sanitize.php src/Actions/Configuration.php693-1044


Session Validation


Multiple validation hooks ensure session integrity:


WordPress Cookie Validation (src/Actions/Authentication.php183-262):


    

  • auth_cookie_malformed: Clear Auth0 session on malformed cookie
    • 

  • auth_cookie_expired: Clear Auth0 session on expiration
    • 

  • auth_cookie_bad_username: Clear Auth0 session on invalid username
    • 

  • auth_cookie_bad_session_token: Clear Auth0 session on bad token
    • 

  • auth_cookie_bad_hash: Clear Auth0 session on hash mismatch
    • 



Auth0 Token Validation:


    

  • JWT signature verification via Auth0-PHP SDK
    • 

  • Token expiration checking via accessTokenExpired flag
    • 

  • Organization/audience claim validation in SDK configuration
    • 



Sources: src/Actions/Authentication.php183-262




WordPress Integration Features


Login Flow Replacement


The plugin completely replaces WordPress's native authentication:


Disabled WordPress Features:



Enabled Auth0 Features:


    

  • Universal Login redirect on all login attempts
    • 

  • OAuth 2.0 / OIDC authentication flow
    • 

  • Token-based session establishment
    • 

  • Optional WordPress fallback via ?auth0_fb={secret} parameter
    • 



Sources: src/Actions/Authentication.php433-571


WordPress Cron Integration


Two background jobs are scheduled via WordPress cron (src/Actions/Sync.php39-43):




























Job ConstantSchedule ConstantIntervalHandlerPurpose
AUTH0_CRON_SYNCAUTH0_SYNCConfigurable (300-604800s)onBackgroundSync()Process sync queue
AUTH0_CRON_MAINTENANCEAUTH0_MAINTENANCE300s (5 minutes)onBackgroundMaintenance()Clean orphaned connections


Schedule Registration (src/Actions/Sync.php261-268):




Sources: src/Actions/Sync.php39-268


Custom Database Tables


The plugin uses custom tables instead of WordPress options for performance:


Accounts Table (src/Database.php101-118):




Sync Queue Table (src/Database.php121-140):




Performance Benefits:


    

  • Indexed lookups for user-to-connection mapping
    • 

  • Efficient queue processing (SELECT + DELETE operations)
    • 

  • Reduced WordPress options table bloat
    • 

  • Optimized for high-traffic sites
    • 



Table Creation:


    

  • Triggered on first use via prepDatabase() in src/Actions/Authentication.php645-658
    • 

  • Uses WordPress maybe_create_table() for idempotent creation
    • 

  • Respects WordPress multisite architecture (site/blog columns)
    • 



Sources: src/Database.php101-140 src/Actions/Authentication.php645-658




Feature Configuration Matrix


The following table maps plugin capabilities to their configuration locations:




Sources: src/Actions/Configuration.php21-438
Refresh this wiki
On this page