VOOZH about

URL: https://deepwiki.com/auth0/wordpress/5.1-configuration-options

⇱ Configuration Options | auth0/wordpress | DeepWiki

Loading...
Loading...
Menu

Configuration Options

This page provides a comprehensive reference for all configuration options available in the Auth0 WordPress plugin. These options control authentication behavior, user management, synchronization, session handling, and security features.

For information about using the plugin API to access these options programmatically, see Plugin API Reference. For details on how configuration is loaded during plugin initialization, see Plugin Initialization and Bootstrap.

Overview

The Auth0 WordPress plugin uses a declarative configuration system defined in the PAGES constant src/Actions/Configuration.php21-438 All configuration options are stored in WordPress's wp_options table with keys prefixed by auth0_. The configuration is organized hierarchically into pages, sections, and fields:

  • Pages: Top-level admin pages (General, Sync, Advanced, Tools)
  • Sections: Logical groupings of related options within a page (e.g., client, accounts, authentication)
  • Fields: Individual configuration values with specific data types and validation rules

The Configuration action class manages admin UI rendering, input sanitization, and storage using WordPress Settings API src/Actions/Configuration.php537-686

Sources: src/Actions/Configuration.php16-686 src/Plugin.php95-122

Configuration Storage Structure

Configuration data is stored in wp_options with section-level granularity. Each section corresponds to one option row in the database, and fields within that section are stored as an array.



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




Configuration Pages


The plugin organizes configuration into four admin pages:





































Page ConstantPage SlugMenu TitlePurpose
CONST_PAGE_GENERALauth0_configurationOptionsCore application settings, user management, and client configuration
CONST_PAGE_SYNCauth0_syncSyncBackground synchronization settings and event configuration
CONST_PAGE_ADVANCEDauth0_advancedAdvancedSession handling, tokens, cookies, and back-channel logout
CONST_PAGE_TOOLSauth0_toolsToolsUtility page for administrative tools


Sources: src/Actions/Configuration.php440-458 src/Actions/Configuration.php477-535




Configuration Sections Reference


Section: state


Option Key: auth0_state

Page: General

Purpose: Controls whether Auth0 authentication is enabled





















FieldTypeDescriptionValuesDefault
enablebooleanMaster switch for Auth0 authentication"true", "false""false"


Validation: Sanitized as boolean string src/Actions/Configuration.php829-863


Usage Example:




Sources: src/Actions/Configuration.php25-40 src/Actions/Configuration.php829-863 src/Plugin.php174-177




Section: accounts


Option Key: auth0_accounts

Page: General

Purpose: Controls user account matching, creation, and default roles










































FieldTypeDescriptionValuesNotes
matchingtextConnection matching strategy"flexible", "strict"Flexible allows email-based matching; strict requires unique connection identifiers
missingtextAction when no WordPress user exists"reject", "create"Database connection "Disable Sign Ups" overrides "create"
default_roletextDefault role for new usersAny WordPress role slugUses getRoleOptions() to populate choices
passwordlessbooleanAllow passwordless authentication"true", "false"Requires passwordless connections configured in Auth0


Validation: src/Actions/Configuration.php693-707


    

  • All fields sanitized as strings
    • 

  • Boolean fields converted to "true"/"false" strings
    • 

  • Empty values filtered out
    • 



Usage in Identity Resolution:
The matching setting controls how resolveIdentity() matches Auth0 users to WordPress users src/Actions/Authentication.php660-724:


    

  • When matching is "flexible": Allows matching by verified email address
    • 

  • When matching is "strict": Only matches by Auth0 connection identifier (sub claim)
    • 



Sources: src/Actions/Configuration.php41-83 src/Actions/Configuration.php693-707 src/Actions/Authentication.php660-724




Section: client


Option Key: auth0_client

Page: General

Purpose: Core Auth0 application credentials (required)



































FieldTypeSanitizerDescriptionRequired
idtextstringAuth0 Client IDYes
secretpasswordstringAuth0 Client SecretYes
domaintextdomainAuth0 Domain (e.g., tenant.auth0.com)Yes


Validation: src/Actions/Configuration.php766-779


    

  • id and secret: Sanitized as string
    • 

  • domain: Sanitized using Sanitize::domain() which extracts hostname src/Utilities/Sanitize.php72-112
    • 

  • Empty values filtered out
    • 



Configuration Check:
The Plugin::isReady() method verifies these three fields are populated before allowing authentication src/Plugin.php182-219


Sources: src/Actions/Configuration.php84-107 src/Actions/Configuration.php766-779 src/Plugin.php182-219




Section: client_advanced


Option Key: auth0_client_advanced

Page: Advanced

Purpose: Additional Auth0 application configuration for custom domains, APIs, and organizations



































FieldTypeSanitizerDescriptionFormat
custom_domaintextdomainCustom domain for Auth0 authenticationHostname only
apistextareastring + validationAuth0 API Audiences (one per line)3-64 chars, starts with lowercase letter
organizationstextareaorgs + validationOrganization IDs (one per line)4-64 chars, starts with org_


Validation: src/Actions/Configuration.php786-827


The validation process:


    

  1. Textarea input sanitized with Sanitize::textarea()
    2. 

  2. Split by newlines
    3. 

  3. Individual entries validated:

      

    • APIs: Must be 3-64 characters, start with lowercase letter, alphanumeric with hyphens/underscores
      • 

    • Organizations: Must be 4-64 characters, start with org_, alphanumeric with underscores
      • 

    

    4. 

  4. Duplicates removed with Sanitize::arrayUnique()
    5. 

  5. Stored as space-separated string (not newline-separated)
    6. 



UI Transformation:
When rendering the edit form, space-separated values are converted back to newlines src/Actions/Configuration.php642-644


SDK Usage:
Values are split by space and passed to SdkConfiguration as arrays src/Plugin.php276-281


Sources: src/Actions/Configuration.php230-256 src/Actions/Configuration.php786-827 src/Plugin.php276-281




Section: authentication


Option Key: auth0_authentication

Page: Advanced

Purpose: Authentication behavior and fallback configuration



































FieldTypeDescriptionValuesNotes
pair_sessionsintSession pairing enforcement level0 (non-admins only), 1 (all users), 2 (disabled)Affects Authentication::onInit() behavior
allow_fallbackbooleanEnable WordPress login fallback"true", "false"Requires secret URL parameter
fallback_secretpasswordSecret for fallback login URLAuto-generated 128-character hex stringFormat: wp-login.php?auth0_fb={secret}


Validation: src/Actions/Configuration.php714-733


    

  • pair_sessions: Clamped to 0-2 range
    • 

  • fallback_secret: Auto-generates 128-char hex string if empty
    • 

  • Sets transient auth0_updated_fallback to notify user
    • 



Session Pairing Logic:
Used in Authentication::onInit() src/Actions/Authentication.php353-431:


    

  • Value 0: Enforces pairing for non-administrator users
    • 

  • Value 1: Enforces pairing for all users (recommended)
    • 

  • Value 2: Disables session pairing entirely
    • 



Fallback Login:
Checked in Authentication::onLogin() src/Actions/Authentication.php443-452 to allow standard WordPress login when ?auth0_fb={secret} parameter matches


Sources: src/Actions/Configuration.php197-229 src/Actions/Configuration.php714-733 src/Actions/Authentication.php353-431 src/Actions/Authentication.php443-452




Section: tokens


Option Key: auth0_tokens (rendered) or auth0_tokens (actual storage not shown in PAGES)

Page: Advanced

Purpose: JSON Web Token handling configuration





















FieldTypeDescriptionValuesPerformance Impact
cachingtextJWKS caching strategy"wp_object_cache", "disable"Disabling degrades performance


SDK Integration:
When not set to "disable", a WpObjectCachePool instance is configured for token and back-channel logout caching src/Plugin.php322-326


Sources: src/Actions/Configuration.php257-272 src/Plugin.php278 src/Plugin.php322-326




Section: sessions


Option Key: auth0_sessions

Page: Advanced

Purpose: Session storage and expiration configuration










































FieldTypeDescriptionValuesDefault
methodtextDevice storage method"cookies", "sessions""sessions" (PHP native sessions recommended)
session_ttlintSession lifetime in seconds0 (default), 1800, 3600, 21600, 43200, 86400, 172800, 345600, 604800, 1209600, 25920000 uses WordPress default
rolling_sessionsbooleanUpdate expiration on each request"true", "false"Extends session lifetime with activity
refresh_tokensbooleanUse refresh tokens"true", "false"Requires "Allow Offline Access" in Auth0 API


Validation: src/Actions/Configuration.php865-878


    

  • session_ttl: Integer clamped to max 2,592,000 seconds (30 days)
    • 

  • Boolean fields sanitized to "true"/"false" strings
    • 



Rolling Sessions Implementation:
Handled in Authentication::onShutdown() src/Actions/Authentication.php573-589 When enabled, the cookie store state is set and auth cookie is renewed on each request.


Refresh Token Usage:
Checked in Authentication::onInit() src/Actions/Authentication.php413-428 when access token expires. Calls getSdk()->renew() to refresh credentials.


Sources: src/Actions/Configuration.php273-327 src/Actions/Configuration.php865-878 src/Actions/Authentication.php573-589 src/Actions/Authentication.php413-428




Section: cookies


Option Key: auth0_cookies

Page: Advanced

Purpose: Cookie-based session storage configuration
























































FieldTypeSanitizerDescriptionNotes
secretpasswordstringCookie encryption secretRequired; auto-generated during activation
domaintextstringCookie domain scopeDefaults to current domain if empty
pathtextcookiePathCookie path scopeDefaults to /
securebooleanbooleanRequire HTTPS for cookiesEnable only for HTTPS-only sites
samesitetextstringSameSite attribute"lax", "strict", "none"
ttlnumberintegerCookie expiration in seconds0 (immediate) to 2592000 (30 days)


Validation: src/Actions/Configuration.php880-921


    

  • secret: Auto-generates 128-character hex string if empty during initial save
    • 

  • path: Sanitized with Sanitize::cookiePath() src/Utilities/Sanitize.php59-70
    • 

  • ttl: Clamped to 0-2,592,000 range
    • 

  • Sets transient auth0_updated_cookie when secret changes
    • 



SDK Configuration Mapping:
These values map directly to SdkConfiguration constructor parameters src/Plugin.php312-317:


    

  • cookieSecret ← cookies.secret
    • 

  • cookieDomain ← cookies.domain
    • 

  • cookiePath ← cookies.path (defaults to /)
    • 

  • cookieExpires ← cookies.ttl
    • 

  • cookieSecure ← cookies.secure (auto-detects SSL via is_ssl())
    • 

  • cookieSameSite ← cookies.samesite
    • 



Auth Cookie Expiration:
The ttl value is used by Authentication::onAuthCookieAssignExpiration() src/Actions/Authentication.php183-192 to set WordPress auth cookie lifetime when "remember me" is enabled.


Sources: src/Actions/Configuration.php328-390 src/Actions/Configuration.php880-921 src/Plugin.php282-317 src/Actions/Authentication.php183-192




Section: backchannel_logout


Option Key: auth0_backchannel_logout

Page: Advanced

Purpose: OIDC Back-Channel Logout configuration



































FieldTypeDescriptionValuesNotes
enabledbooleanEnable back-channel logout"true", "false"Must also configure Auth0 tenant
ttlintLogout token expiration0 (default=30 days), 1800, 3600, 21600, 43200, 86400, 172800, 345600, 604800, 1209600, 2592000How long unclaimed tokens remain valid
secretpasswordLogout endpoint secretAuto-generated 128-character hex stringUsed in callback URL authentication


Validation: src/Actions/Configuration.php740-759


    

  • enabled: Note that line 747 has a bug - it checks secret field instead of enabled field for the enabled value
    • 

  • secret: Auto-generates 128-char hex string if empty
    • 

  • ttl: Clamped to max 2,592,000 seconds
    • 

  • Sets transient auth0_updated_backchannel to notify user
    • 



Endpoint Format:
Back-channel logout callbacks are handled at wp-login.php?auth0_bcl={secret} src/Actions/Authentication.php454-469


Token Handling:
The secret is used to validate incoming logout tokens, which are then processed by getSdk()->handleBackchannelLogout() src/Actions/Authentication.php462


Sources: src/Actions/Configuration.php391-431 src/Actions/Configuration.php740-759 src/Actions/Authentication.php454-469




Section: sync


Option Key: auth0_sync

Page: Sync

Purpose: Background synchronization configuration



































FieldTypeSanitizerDescriptionValues
databasetextstringDatabase connection ID for syncMust start with con_
schedulenumberintegerSync frequency in seconds0 (disabled), 300, 900, 1800, 3600, 21600, 43200, 86400, 172800, 345600, 604800
pushbooleanstringOn-demand change synchronization"disable", "enable_email", "enable"


Validation: src/Actions/Configuration.php923-942


    

  • database: Must start with con_ prefix (Auth0 connection ID format)
    • 

  • schedule: Integer value determining cron interval
    • 

  • push: Three-state option (disabled, email-only, all changes)
    • 



Cron Schedule Registration:
The schedule value is registered as a custom cron interval via Sync::updateCronSchedule() src/Sync.php261-268:




Background Sync Execution:
Sync jobs are processed by Sync::onBackgroundSync() src/Actions/Sync.php214-254 which reads events from the auth0_sync table and syncs them to the configured database connection.


Sources: src/Actions/Configuration.php113-155 src/Actions/Configuration.php923-942 src/Actions/Sync.php214-254 src/Actions/Sync.php261-268




Section: sync_events


Option Key: auth0_sync_events

Page: Sync

Purpose: Controls which user events are synchronized between WordPress and Auth0



































FieldTypeDescriptionDefaultImplementation
user_creationbooleanSync user creation events"true"Creates Auth0 user when WordPress user created
user_deletionbooleanSync user deletion events"true"Deletes Auth0 user when WordPress user deleted
user_updatesbooleanSync user update events"true"Updates Auth0 user when WordPress user updated


Validation: src/Actions/Configuration.php944-963


    

  • All fields are boolean strings ("true"/"false")
    • 



Event Queuing:
User events are queued in the auth0_sync table by:



Event Processing:
Events are checked against these flags in Sync::onBackgroundSync() src/Actions/Sync.php225-249:




Sources: src/Actions/Configuration.php156-191 src/Actions/Configuration.php944-963 src/Actions/Sync.php225-249




Configuration Flow Diagram




Sources: src/Actions/Configuration.php537-963 src/Utilities/Sanitize.php1-160 src/Plugin.php113-122 src/Plugin.php274-329




Accessing Configuration Options


The Plugin class provides helper methods for retrieving configuration values with type safety:


Method: getOption()




Retrieves a raw option value from the specified section src/Plugin.php113-122


Method: getOptionString()


Returns the value as a string or null src/Plugin.php150-159


Method: getOptionBoolean()


Converts "true"/"1" to true, all else to false src/Plugin.php124-133


Method: getOptionInteger()


Converts numeric values to integers src/Plugin.php135-148


Usage Example




Sources: src/Plugin.php113-159 src/Plugin.php174-177




Validation and Sanitization


All configuration input is sanitized through dedicated onUpdate*() methods that correspond to each section. The validation process follows this pattern:




Common Sanitizers















































FunctionPurposeReturns
Sanitize::string()Basic text sanitization?string
Sanitize::domain()Extract hostname from URL?string
Sanitize::boolean()Convert to "true"/"false" string?string
Sanitize::integer()Convert and clamp to range?int
Sanitize::textarea()Sanitize multi-line text?string
Sanitize::alphanumeric()Allow only specified characters?string
Sanitize::arrayUnique()Remove duplicates from arrayarray


Sources: src/Utilities/Sanitize.php1-160 src/Actions/Configuration.php693-963




Configuration Update Methods Reference


Each section has a dedicated update method that handles sanitization and validation:















































































SectionMethodLine RangeKey Validations
stateonUpdateState()829-863Boolean conversion
accountsonUpdateAccounts()693-707String sanitization, boolean conversion
clientonUpdateClient()766-779Domain extraction, required fields
client_advancedonUpdateClientAdvanced()786-827API format (3-64 chars, starts lowercase), Org format (4-64 chars, starts org_)
authenticationonUpdateAuthentication()714-733Integer clamping (0-2), auto-generate fallback secret
cookiesonUpdateCookies()880-921Path sanitization, auto-generate secret, TTL clamping
sessionsonUpdateSessions()865-878TTL clamping (max 30 days)
tokensonUpdateTokens()965-973String validation
backchannel_logoutonUpdateBackchannelLogout()740-759Auto-generate secret, TTL clamping
synconUpdateSync()923-942Database connection format (con_ prefix)
sync_eventsonUpdateSyncEvents()944-963Boolean conversion


Sources: src/Actions/Configuration.php693-973




Configuration to SDK Mapping


The Plugin::importConfiguration() method transforms stored options into an SdkConfiguration object:













































































Configuration PathSdkConfiguration ParameterTransformation
client.domaindomainDirect pass-through
client.idclientIdDirect pass-through
client.secretclientSecretDirect pass-through
client_advanced.custom_domaincustomDomainDirect pass-through
client_advanced.apisaudienceSplit by space into array
client_advanced.organizationsorganizationSplit by space into array
cookies.secretcookieSecretDirect pass-through
cookies.domaincookieDomainDirect pass-through
cookies.pathcookiePathDefaults to / if empty
cookies.ttlcookieExpiresDirect pass-through
cookies.securecookieSecureAuto-detects via is_ssl() if not set
cookies.samesitecookieSameSiteDirect pass-through
tokens.cachingsetTokenCache()Configures WpObjectCachePool if not disabled


Cron Context Handling:
When invoked from WP_Cron (DOING_CRON defined), the SDK uses STRATEGY_NONE to avoid session initialization src/Plugin.php285-298


Sources: src/Plugin.php274-329




Configuration Option Groups Summary















































































wp_options KeyAdmin PageNumber of FieldsPrimary Purpose
auth0_stateGeneral1Master enable/disable switch
auth0_accountsGeneral4User matching and creation policies
auth0_clientGeneral3Auth0 application credentials (required)
auth0_client_advancedAdvanced3Custom domain, API audiences, organizations
auth0_authenticationAdvanced3Session pairing and fallback login
auth0_cookiesAdvanced6Cookie storage configuration
auth0_sessionsAdvanced4Session lifetime and refresh behavior
auth0_tokensAdvanced1JWKS caching strategy
auth0_backchannel_logoutAdvanced3OIDC back-channel logout
auth0_syncSync3Background sync frequency and connection
auth0_sync_eventsSync3Event type toggles (create/update/delete)


Total Configuration Fields: 34


Sources: src/Actions/Configuration.php21-438




Special Configuration Behaviors


Auto-Generated Secrets


Three configuration secrets are auto-generated during plugin activation wpAuth0.php27-53 and auto-regenerate if deleted:


    

  1. auth0_cookies.secret: 128-character hex string for cookie encryption
    2. 

  2. auth0_backchannel_logout.secret: 128-character hex string for logout endpoint authentication
    3. 

  3. auth0_authentication.fallback_secret: 128-character hex string for fallback login URL
    4. 



Transient Notifications


When sensitive secrets are updated, temporary transients are set to notify users:



These transients expire after 60 seconds and can be used to display admin notices.


Textarea to Space-Separated Transformation


The apis and organizations fields accept newline-separated input in the UI but store values as space-separated strings src/Actions/Configuration.php798-824:


Input (textarea):


org_abc123
org_def456
org_ghi789



Stored (database):


org_abc123 org_def456 org_ghi789



Rendered (SDK array):




This transformation is reversed when rendering the form src/Actions/Configuration.php642-644


Sources: wpAuth0.php27-53 src/Actions/Configuration.php642-644 src/Actions/Configuration.php717-759 src/Actions/Configuration.php798-824 src/Actions/Configuration.php880-921