WordPress Configuration

This page explains how to configure the Auth0 WordPress plugin through the WordPress admin dashboard. It covers entering Auth0 application credentials, enabling authentication, and configuring basic user management settings.

Note: This page assumes you have already created and configured an Auth0 Application as described in Auth0 Application Setup. For information about advanced configuration options, see Configuration Options.

Overview

After activating the Auth0 plugin, configuration is performed entirely through the WordPress admin dashboard. The plugin adds an "Auth0" menu item to the sidebar with four sub-pages:

• Options (General Settings) - Auth0 credentials and user account settings
• Sync - User synchronization configuration
• Advanced - Session management and security options
• Tools - Administrative utilities

This page focuses on the essential configuration required to get the plugin operational: entering credentials and enabling authentication.

Admin Menu Structure

The plugin registers its admin interface during WordPress initialization through the Configuration::onMenu() method.

Sources: src/Actions/Configuration.php477-535

The menu is created with priority 70 by default, which can be overridden using the AUTH0_ADMIN_MENU_POSITION constant. Each sub-page triggers a corresponding WordPress action that renders the settings interface.

Entering Auth0 Credentials

The plugin requires three essential credentials from your Auth0 Application to operate. These are entered on the Options page under the "Application Configuration" section.

Required Credentials

Setting	Option Name	Type	Description
Domain	auth0_client[domain]	text	Your Auth0 tenant domain (e.g., example.us.auth0.com)
Client ID	auth0_client[id]	text	The application's Client ID
Client Secret	auth0_client[secret]	password	The application's Client Secret

These values are stored in the WordPress options table under the auth0_client option group and are sanitized on save using the Configuration::onUpdateClient() method.

Sources: src/Actions/Configuration.php84-107 src/Actions/Configuration.php766-814

Credential Validation

The domain field uses Sanitize::domain() which:

1. Accepts domains with or without protocol prefix
2. Extracts only the hostname portion
3. Validates that it has at least two parts (domain + TLD)
4. Requires the TLD to be at least 2 characters

The Client ID and Secret use Sanitize::string() which trims whitespace and sanitizes via sanitize_text_field().

Sources: src/Utilities/Sanitize.php72-112 src/Utilities/Sanitize.php139-148

Enabling Authentication

After entering valid credentials, authentication must be explicitly enabled through the "Enable Authentication" option.

Sources: src/Actions/Configuration.php29-38 src/Plugin.php182-219

The "Enable Authentication" field is only enabled when Plugin::isReady() returns true, which requires:

• Valid domain value
• Valid clientId value
• Valid clientSecret value
• Valid cookieSecret (auto-generated on activation)

The setting is stored as the string 'true' or 'false' in auth0_state[enable] and checked by Plugin::isEnabled().

Sources: src/Plugin.php174-177

User Account Settings

The Options page includes several settings that control how WordPress users are matched to Auth0 connections and what happens when no match is found.

Connection Matching Strategy

Setting	Option Path	Values	Description
Connection Matching	auth0_accounts[matching]	'flexible' or 'strict'	Controls how Auth0 identities are matched to WordPress users

• Flexible: Matches verified email addresses across different connection types, allowing users to sign in with social providers that use the same email
• Strict: Only matches the specific Auth0 sub (connection identifier), requiring users to sign in with the exact same method each time

Sources: src/Actions/Configuration.php45-54

Missing User Behavior

Setting	Option Path	Values	Description
Missing Users	auth0_accounts[missing]	'reject' or 'create'	What to do when authentication succeeds but no WordPress user exists

• Reject: Deny access, preventing login
• Create: Automatically create a new WordPress user account

Sources: src/Actions/Configuration.php55-64

Default Role for New Users

Setting	Option Path	Values	Description
Default Role	auth0_accounts[default_role]	WordPress role slug	The role assigned to newly created users

This setting is populated with all available WordPress roles via Configuration::getRoleOptions() and defaults to WordPress's configured default role.

Sources: src/Actions/Configuration.php65-71

Settings Storage Architecture

All plugin settings are stored in the WordPress options table, organized by option groups. Each group corresponds to a settings section on the admin pages.

Sources: src/Actions/Configuration.php537-686

Settings Structure Definition

The PAGES constant defines the complete structure of all settings pages in a hierarchical array format:

PAGES
├── auth0_configuration (General/Options Page)
│ ├── state section
│ │ └── enable option
│ ├── accounts section
│ │ ├── matching option
│ │ ├── missing option
│ │ ├── default_role option
│ │ └── passwordless option
│ └── client section
│ ├── id option
│ ├── secret option
│ └── domain option
├── auth0_sync (Sync Page)
├── auth0_advanced (Advanced Page)
└── auth0_tools (Tools Page)

Sources: src/Actions/Configuration.php21-438

Each option definition includes:

• title - Display label
• type - Input type (text, password, boolean, number, textarea)
• sanitizer - Sanitization method name (optional)
• description - Help text
• enabled - Method name that determines if field is enabled
• select - Array of options for select fields

Retrieving Configuration Values

The Plugin class provides type-safe methods for retrieving configuration values throughout the plugin:

Method	Return Type	Usage
getOption($group, $key, $default)	mixed	Retrieves raw value or default
getOptionString($group, $key)	?string	Returns string or null
getOptionInteger($group, $key)	?int	Returns integer or null
getOptionBoolean($group, $key)	?bool	Returns boolean or null

Example retrieving the domain:

Sources: src/Plugin.php113-159

These methods are used throughout the plugin to access configuration. For example, the SDK configuration builder uses them to construct the SdkConfiguration object:

Sources: src/Plugin.php274-329

Configuration Form Rendering

Settings fields are rendered using the Render::option() utility method, which generates appropriate HTML based on the field type.

Sources: src/Actions/Configuration.php652-675

The rendering process:

1. Retrieves current values from WordPress options using get_option($sectionId, [])
2. Determines if field should be disabled based on enabled callback (e.g., isPluginReady())
3. Generates unique element IDs using uniqid()
4. Calls Render::option() with all parameters
5. WordPress automatically handles CSRF protection via nonces

Sanitization and Validation

All user input is sanitized through dedicated callback methods before being stored. Each option group has a corresponding onUpdate* method:

Option Group	Sanitization Method	Key Sanitizers Used
auth0_client	onUpdateClient()	Sanitize::string(), Sanitize::domain()
auth0_state	onUpdateState()	Sanitize::boolean()
auth0_accounts	onUpdateAccounts()	Sanitize::string(), Sanitize::boolean()
auth0_sync	onUpdateSync()	Sanitize::string(), Sanitize::integer()

Sources: src/Actions/Configuration.php693-814

The sanitization flow:

1. WordPress calls the registered sanitization callback with POST data
2. Callback extracts and sanitizes each field individually
3. Empty values are filtered out using array_filter()
4. Sanitized array is returned to WordPress for storage

Example from onUpdateClient():

Sources: src/Actions/Configuration.php766-814

This multi-layer approach ensures that invalid or malicious input cannot corrupt the plugin's configuration, as WordPress provides CSRF protection and the plugin provides type-specific sanitization.

Sources: src/Utilities/Sanitize.php1-160