 |
VOOZH | about |
|
VOOZH | about |
This document describes the security mechanisms implemented by the Auth0 WordPress plugin to protect user authentication and authorization. The security model encompasses cryptographic secret generation, session pairing between WordPress and Auth0, token lifecycle management, back-channel logout coordination, and secure cookie configuration.
For information about the authentication flow itself, see Authentication Flow. For configuration options related to security settings, see Configuration Options.
The plugin implements multiple layers of security to protect user sessions and prevent unauthorized access:
| Security Layer | Purpose | Configuration Section |
|---|---|---|
| Cryptographic Secrets | Generate secure random keys for cookie encryption and authentication | auth0_cookies, auth0_backchannel_logout, auth0_authentication |
| Session Pairing | Ensure WordPress and Auth0 sessions remain synchronized | auth0_authentication[pair_sessions] |
| Token Management | Validate and refresh authentication tokens | auth0_sessions[refresh_tokens] |
| Back-Channel Logout | Coordinate session termination across devices | auth0_backchannel_logout |
| Fallback Authentication | Provide emergency access mechanism | auth0_authentication[allow_fallback] |
| Cookie Security | Protect session cookies from interception | auth0_cookies |
Sources: wpAuth0.php40-67 src/Actions/Authentication.php353-431 src/Actions/Configuration.php328-431
During plugin activation, three cryptographic secrets are automatically generated using PHP's random_bytes() function with 64 bytes of entropy (128 hexadecimal characters):
Secret Generation During Plugin Activation
| Secret | Option Key | Purpose |
|---|---|---|
| Cookie Secret | auth0_cookies[secret] | Encrypts session data stored in cookies or PHP sessions |
| Back-Channel Logout Secret | auth0_backchannel_logout[secret] | Authenticates back-channel logout requests from Auth0 |
| Fallback Secret | auth0_authentication[fallback_secret] | Provides emergency WordPress login access via secret URL parameter |
The cookie secret is required for the plugin to function and is passed to the Auth0-PHP SDK's SdkConfiguration during initialization. Changing the cookie secret logs out all users.
Sources: wpAuth0.php40-67 src/Plugin.php312 src/Actions/Configuration.php332-336
Session pairing ensures that WordPress and Auth0 sessions remain synchronized. When enabled, users must maintain valid sessions in both systems or they will be logged out.
Session Pairing Validation Flow
The Authentication::onInit() method performs session pairing validation on every request. The pairing behavior is controlled by the auth0_authentication[pair_sessions] setting:
When pairing is enforced, the system:
sub claim matches the WordPress user's linked connectionSources: src/Actions/Authentication.php353-431
The plugin supports two methods for storing session data:
| Method | Configuration Value | Security Considerations |
|---|---|---|
| Encrypted Cookies | cookies | Data stored client-side, encrypted with cookie secret; works across load-balanced servers |
| PHP Native Sessions | sessions (Recommended) | Data stored server-side; requires proper PHP session configuration for security |
The storage method is configured via auth0_sessions[method]. PHP sessions are recommended but require external configuration to work securely and reliably across server environments.
Sources: src/Actions/Configuration.php277-286 src/Plugin.php300-320
When rolling sessions are enabled (auth0_sessions[rolling_sessions] = true), session expiration times are updated on each request, extending the user's authenticated session. This is implemented in the Authentication::onShutdown() method:
Rolling Session Update Flow
Rolling sessions prevent users from being logged out due to inactivity while actively using the site.
Sources: src/Actions/Authentication.php573-589 src/Actions/Configuration.php306-315
The plugin manages JSON Web Token (JWT) validation and lifecycle through the Auth0-PHP SDK:
Token Lifecycle Management
When access tokens expire and refresh tokens are enabled, the plugin attempts to obtain new access tokens without requiring user reauthentication:
Authentication::onInit() method detects expired access tokens via $session->accessTokenExpiredauth0_sessions[refresh_tokens] = true, the plugin calls $this->getSdk()->renew()Refresh tokens must be enabled in the Auth0 Application settings ("Allow Offline Access") for this feature to work.
Sources: src/Actions/Authentication.php413-428 src/Actions/Configuration.php316-326
The plugin caches JSON Web Key Sets (JWKS) used to validate JWT signatures. Caching is controlled by auth0_tokens[caching]:
wp_object_cache (Recommended): Uses WordPress's object caching systemdisable: Disables caching (negatively impacts performance)When caching is enabled, the WpObjectCachePool class provides PSR-6 compatible caching to the Auth0-PHP SDK.
Sources: src/Plugin.php322-326 src/Actions/Configuration.php261-271
Back-Channel Logout enables Auth0 to notify the WordPress plugin when a user's session is terminated elsewhere (e.g., from another device or the Auth0 dashboard).
Back-Channel Logout Request Handling
To enable back-channel logout:
Set auth0_backchannel_logout[enabled] = true in the plugin
Configure the back-channel logout URL in the Auth0 Application settings:
https://yoursite.com/wp-login.php?auth0_bcl={secret}
Where {secret} is the value from auth0_backchannel_logout[secret]
Optionally configure auth0_backchannel_logout[ttl] to control how long unclaimed logout tokens remain valid (default: 1 month)
The back-channel logout secret authenticates requests from Auth0, preventing unauthorized session termination attempts.
Sources: src/Actions/Authentication.php454-469 src/Actions/Configuration.php391-431 src/Plugin.php325
The fallback authentication mechanism provides emergency access to the standard WordPress login form when Auth0 authentication is unavailable or misconfigured.
When auth0_authentication[allow_fallback] = true, administrators can access the WordPress login form by appending a secret parameter:
https://yoursite.com/wp-login.php?auth0_fb={fallback_secret}
The Authentication::onLogin() method validates the fallback secret before allowing access:
Fallback Authentication Validation
The fallback secret is automatically generated during plugin activation and can be regenerated from the Advanced Options page. Administrators should store this URL securely for emergency access.
Sources: src/Actions/Authentication.php443-452 src/Actions/Configuration.php212-228 wpAuth0.php59-65
The plugin provides granular control over cookie security attributes to protect session data from interception and unauthorized access.
| Setting | Option Key | Purpose | Recommended Value |
|---|---|---|---|
| Secret | auth0_cookies[secret] | Encrypts cookie contents | Auto-generated 128-char hex |
| Domain | auth0_cookies[domain] | Restricts cookie to specific domain | Site's domain |
| Path | auth0_cookies[path] | Restricts cookie to URL path | / (default) |
| Secure | auth0_cookies[secure] | Requires HTTPS for cookie transmission | true for HTTPS sites |
| SameSite | auth0_cookies[samesite] | Prevents CSRF attacks | lax (suggested) |
| Expires | auth0_cookies[ttl] | Cookie lifetime in seconds | Based on security policy |
Cookie Configuration Architecture
The SameSite cookie attribute protects against Cross-Site Request Forgery (CSRF) attacks:
lax (Suggested): Cookies sent with top-level navigations and same-site requestsstrict: Cookies only sent with same-site requests (most secure, but may break some flows)none: Cookies sent with all requests (requires secure flag)Sources: src/Actions/Configuration.php328-390 src/Plugin.php282-320
All user input from configuration forms is sanitized to prevent injection attacks and ensure data integrity. The Sanitize utility class provides specialized sanitization methods:
| Method | Purpose | Usage |
|---|---|---|
Sanitize::string() | Basic text sanitization | Client IDs, secrets, general text |
Sanitize::domain() | Domain validation | Auth0 domain, custom domain |
Sanitize::alphanumeric() | Alphanumeric filtering | API audiences, organization IDs |
Sanitize::integer() | Integer validation with bounds | TTL values, numeric settings |
Sanitize::boolean() | Boolean normalization | Toggle settings |
Sanitize::textarea() | Multi-line text sanitization | Organization lists, API audience lists |
The Configuration action class applies sanitization in onUpdate*() methods before storing settings:
Configuration Update Sanitization Flow
For example, the onUpdateClient() method sanitizes client credentials:
Sanitize::string() removes non-printable charactersSanitize::string() removes non-printable charactersSanitize::domain() validates domain format and extracts hostnameAPI audiences and organization IDs receive additional validation to ensure proper format (e.g., organization IDs must start with org_).
Sources: src/Utilities/Sanitize.php src/Actions/Configuration.php688-828
When deploying the plugin in production environments, follow these security best practices:
auth0_cookies[secure] = true only on sites served exclusively over HTTPSauth0_authentication[pair_sessions] = 1 (All Users) for maximum securityauth0_sessions[refresh_tokens] = true to maintain sessions without reauthenticationauth0_tokens[caching] = wp_object_cache for performance and reduced API loadSources: src/Actions/Configuration.php src/Actions/Authentication.php
Refresh this wiki