Configuration Management

Purpose and Scope

This document explains how the Auth0 WordPress plugin manages its configuration settings through the WordPress admin interface. The Configuration system handles the declaration, rendering, validation, and persistence of all plugin settings.

For information about the specific configuration options available to users, see Configuration Options. For details about how configuration is consumed during plugin initialization, see Plugin Initialization and Bootstrap.

Sources: src/Actions/Configuration.php1-1700

---

Architectural Overview

The Configuration system uses a declarative architecture where all admin pages, settings sections, and individual fields are defined in a single data structure (PAGES constant), then processed by registration methods that integrate with WordPress's Settings API. This approach separates configuration structure from rendering logic and validation behavior.

Core Components

Component	Location	Purpose
Configuration Action Class	src/Actions/Configuration.php16	Main class orchestrating configuration management
PAGES Constant	src/Actions/Configuration.php21-438	Declarative definition of all configuration structure
onMenu() Method	src/Actions/Configuration.php477-535	Registers admin menu pages
onSetup() Method	src/Actions/Configuration.php537-686	Registers settings with WordPress Settings API
onUpdate*() Methods	src/Actions/Configuration.php688	Validation and sanitization callbacks
Sanitize Utility	src/Utilities/Sanitize.php1-160	Input sanitization functions
Plugin::importConfiguration()	src/Plugin.php274-329	Reads configuration and builds SDK config

Sources: src/Actions/Configuration.php1-1700 src/Plugin.php1-330

---

Configuration Lifecycle

Title: Configuration System Lifecycle from Declaration to SDK Initialization

Sources: src/Actions/Configuration.php537-686 src/Plugin.php274-329

---

The PAGES Constant Structure

The PAGES constant src/Actions/Configuration.php21-438 is a multi-dimensional array that declaratively defines the entire configuration interface structure. Each page contains sections, and each section contains fields with their properties.

Title: PAGES Constant Hierarchical Structure

Sources: src/Actions/Configuration.php21-438

---

Field Definition Schema

Each field in the PAGES structure follows a consistent schema:

Title: Field Configuration Properties

Property	Type	Purpose	Example
title	string	Display label for field	"Client ID"
type	string	HTML input type	"text", "password", "boolean"
sanitizer	string	Sanitization method name	"string", "domain"
description	string or array	Help text or callback	['getOptionDescription', 'enable']
select	array or string	Dropdown options or method name	['false' => 'Disabled', 'true' => 'Enabled']
enabled	string	Method returning boolean for enable condition	"isPluginReady"

Sources: src/Actions/Configuration.php21-438

---

Admin Menu Registration

The onMenu() method src/Actions/Configuration.php477-535 registers the Auth0 menu structure in the WordPress admin sidebar using WordPress's add_menu_page() and add_submenu_page() functions.

Title: Admin Menu Registration and Callback Flow

The menu registration uses action callbacks that trigger custom actions (auth0_ui_*), which are then handled by corresponding render methods in the Configuration class. Priority values can be customized using constants like AUTH0_ADMIN_MENU_POSITION.

Sources: src/Actions/Configuration.php477-535 src/Actions/Configuration.php468-475

---

Settings Registration Process

The onSetup() method src/Actions/Configuration.php537-686 processes the PAGES constant and registers everything with WordPress's Settings API during the admin_init hook.

Title: Settings Registration Algorithm Flow

Dynamic Callback Resolution

The system supports dynamic callbacks for descriptions, placeholders, and select options src/Actions/Configuration.php610-640:

Title: Dynamic Callback Resolution Pattern

For example, 'description' => ['getOptionDescription', 'enable'] calls $this->getOptionDescription('enable') to generate dynamic help text.

Sources: src/Actions/Configuration.php537-686

---

Input Validation and Sanitization

Each section has a corresponding onUpdate*() method that validates and sanitizes user input before storage. These methods are registered as sanitize_callback in the Settings API src/Actions/Configuration.php564

Title: Input Validation and Sanitization Pipeline

Sanitization Methods

The Sanitize utility class src/Utilities/Sanitize.php1-160 provides specialized methods:

Method	Purpose	Example Use
string()	Basic text sanitization	Client ID, Client Secret
domain()	URL/domain validation	Auth0 Domain, Custom Domain
boolean()	Normalize to 'true'/'false'	Enable switches
integer()	Range-bounded integers	TTL values, expiration times
alphanumeric()	Whitelist characters	API audiences, organizations
textarea()	Multi-line text	Organizations list
arrayUnique()	Deduplicate arrays	Audience lists

Validation Example: Client Advanced Options

src/Actions/Configuration.php786-827 demonstrates complex validation:

Title: Advanced Validation for API Audiences and Organizations

Sources: src/Actions/Configuration.php688-1700 src/Utilities/Sanitize.php1-160

---

Storage in wp_options

Configuration data is stored in WordPress's wp_options table using prefixed option names. Each section becomes a separate option with an array of field values.

Option Naming Convention

Section	Option Name	Example Keys
accounts	auth0_accounts	matching, missing, default_role, passwordless
authentication	auth0_authentication	pair_sessions, allow_fallback, fallback_secret
backchannel_logout	auth0_backchannel_logout	enabled, secret, ttl
client	auth0_client	id, secret, domain
client_advanced	auth0_client_advanced	custom_domain, apis, organizations
cookies	auth0_cookies	secret, domain, path, secure, samesite, ttl
sessions	auth0_sessions	method, session_ttl, rolling_sessions, refresh_tokens
state	auth0_state	enable
sync	auth0_sync	database, schedule, push
sync_events	auth0_sync_events	user_creation, user_deletion, user_updates
tokens	auth0_tokens	caching

Storage Format

Each option is stored as a serialized PHP array:

Sources: src/Actions/Configuration.php21-438 src/Actions/Configuration.php537-686

---

Configuration Import and SDK Initialization

The Plugin::importConfiguration() method src/Plugin.php274-329 reads stored configuration from the database and builds an SdkConfiguration object for the Auth0 SDK.

Title: Configuration Import and SDK Initialization Sequence

Configuration Mapping

The following table maps configuration options to SdkConfiguration parameters:

Option Path	SdkConfiguration Parameter	Processing
client.domain	domain	Direct string
client.id	clientId	Direct string
client.secret	clientSecret	Direct string
client_advanced.custom_domain	customDomain	Direct string or NULL
client_advanced.apis	audience	Space-separated → array
client_advanced.organizations	organization	Space-separated → array
cookies.secret	cookieSecret	Direct string
cookies.domain	cookieDomain	Direct string or NULL
cookies.path	cookiePath	Default: /
cookies.ttl	cookieExpires	Integer
cookies.secure	cookieSecure	Boolean or is_ssl()
cookies.samesite	cookieSameSite	String

Special Cases

WP_Cron Context src/Plugin.php285-298: When DOING_CRON is defined, the SDK is initialized with STRATEGY_NONE to avoid session handling during background tasks.

Caching src/Plugin.php322-326: If token caching is not disabled, a WpObjectCachePool instance is configured for JWKS and back-channel logout token caching.

Sources: src/Plugin.php274-329 src/Plugin.php113-159

---

Reading Configuration Values

The Plugin class provides helper methods for reading configuration:

Title: Configuration Value Accessor Methods

Usage Examples

Throughout the codebase, configuration values are accessed using these methods:

Sources: src/Plugin.php113-159 src/Actions/Authentication.php1-726 src/Actions/Sync.php1-283

---

Page Constants and Registry

The Configuration class defines constants for page identification and a registry for hook mappings:

Title: Configuration Class Constants and Hook Registry

The registry array src/Actions/Configuration.php468-475 maps WordPress hooks to Configuration class methods, which are automatically registered when the plugin initializes via Base::register() src/Actions/Base.php89-96

Sources: src/Actions/Configuration.php440-475 src/Actions/Base.php1-122

---

Extensibility and Customization

Priority Constants

The Configuration system supports customization through environment-defined constants for hook priorities src/Actions/Base.php57-70:

The getPriority() method checks for these constants before using defaults.

Conditional Field Enabling

Fields can be conditionally enabled/disabled based on plugin state src/Actions/Configuration.php630-634:

• 'enabled' => 'isPluginReady': Field only enabled when plugin has minimum viable configuration
• Methods like isPluginReady() src/Actions/Base.php83-87 check Plugin::isReady() which validates that Client ID, Client Secret, Domain, and Cookie Secret are all configured

Dynamic Option Generation

Some fields use method callbacks to generate options dynamically src/Actions/Configuration.php636-640:

• 'select' => 'getRoleOptions': Calls method to fetch WordPress roles for the default role dropdown
• 'description' => ['getOptionDescription', 'enable']: Generates context-sensitive help text

Sources: src/Actions/Configuration.php537-686 src/Actions/Base.php57-87

---

Relationship to Other Systems

Title: Configuration System Relationships

The Configuration system sits at the foundation of the plugin architecture:

1. Configuration Action manages the admin UI and stores settings to wp_options
2. Plugin class reads those settings and builds SdkConfiguration
3. Auth0 SDK is initialized with the configuration
4. Other action classes (Authentication, Sync) access configuration through Plugin methods and use the initialized SDK

Sources: src/Actions/Configuration.php1-1700 src/Plugin.php1-330 src/Actions/Authentication.php1-726 src/Actions/Sync.php1-283