Skip to content

Settings Reference

daggerhart edited this page Nov 20, 2026 · 5 revisions

Settings Reference

Complete reference for all OpenID Connect Generic plugin settings.

For WordPress Administrators: This guide explains every configuration option available in the plugin settings page (Dashboard > Settings > OpenID Connect Client).


Table of Contents


Client Settings

Settings that configure how the plugin communicates with your Identity Provider.

Login Type

Setting Name: login_type Environment Variable: OIDC_LOGIN_TYPE Location: Settings > OpenID Connect Client > Client Settings

Purpose: Controls how users access OpenID Connect authentication.

Options:

  • button - Adds "Login with OpenID Connect" button to WordPress login form (default)
  • auto - Auto Login (SSO) - Automatically redirects all users to IDP

Default: button

Example:

// Lock to auto-login via constant
define( 'OIDC_LOGIN_TYPE', 'auto' );

Security Implications:

  • Auto mode removes traditional WordPress login access - ensure you have a backup admin account or see Troubleshooting for bypass instructions
  • Button mode allows mixing OpenID Connect with traditional WordPress logins

Login Button Text

Setting Name: login_button_text Environment Variable: None Location: Settings > OpenID Connect Client > Client Settings

Purpose: Customize the text displayed on the OpenID Connect login button.

Default: "Login with OpenID Connect"

Example:

Login with Single Sign-On
Login with Company Account
Acme Corp Employee Login

Notes:

  • Only applies when Login Type is set to button
  • Leave empty to use default text
  • Can also be modified via the openid-connect-generic-login-button-text filter

Client ID

Setting Name: client_id Environment Variable: OIDC_CLIENT_ID Location: Settings > OpenID Connect Client > Client Settings

Purpose: The identifier your WordPress site uses when communicating with the Identity Provider.

Default: None (required)

Example:

my-wordpress-client-id
wordpress-production
acme-corp-wp

Setup:

  1. Register your WordPress site as an application in your IDP
  2. Copy the Client ID provided by your IDP
  3. Enter it here

Security Implications:

  • This is not secret - it's safe to store in the database
  • However, locking it via OIDC_CLIENT_ID constant prevents admin changes

Client Secret Key

Setting Name: client_secret Environment Variable: OIDC_CLIENT_SECRET Location: Settings > OpenID Connect Client > Client Settings

Purpose: The secret key that authenticates your WordPress site to the Identity Provider.

Default: None (required for most IDPs)

Example:

super-secret-key-from-your-idp
9x8c7v6b5n4m3q2w1e0r

Security Implications:

  • CRITICAL: This is highly sensitive - treat like a password
  • Recommendation: Use OIDC_CLIENT_SECRET constant to keep it out of the database
  • Never commit to version control or expose in logs
  • Some IDPs (using PKCE flow) may not require a client secret

Setup:

  1. When registering your WordPress site in your IDP, you'll receive a Client Secret
  2. Store it securely
  3. Configure via constant (recommended) or settings page

OpenID Scope

Setting Name: scope Environment Variable: OIDC_CLIENT_SCOPE Location: Settings > OpenID Connect Client > Client Settings

Purpose: Defines what information your application requests from the Identity Provider.

Default: openid email profile

Common Scopes:

  • openid - Required for OpenID Connect (must be included)
  • email - User's email address
  • profile - User's profile information (name, username, etc.)
  • offline_access - Enables refresh tokens (required if using Token Refresh)

Example:

openid email profile offline_access
openid email profile groups

Notes:

  • Scopes are space-separated
  • The openid scope is always required
  • Additional scopes depend on your IDP's configuration
  • Your IDP must be configured to allow the requested scopes

Login Endpoint URL

Setting Name: endpoint_login Environment Variable: OIDC_ENDPOINT_LOGIN_URL Location: Settings > OpenID Connect Client > Client Settings

Purpose: The IDP URL where users are sent to authenticate.

Default: None (required)

Example:

https://login.microsoftonline.com/tenant-id/oauth2/v2.0/authorize
https://accounts.google.com/o/oauth2/v2/auth
https://example.com/oauth2/authorize

Setup:

  • Found in your IDP's OpenID Connect configuration (often at /.well-known/openid-configuration)
  • Also called "authorization endpoint"

Userinfo Endpoint URL

Setting Name: endpoint_userinfo Environment Variable: OIDC_ENDPOINT_USERINFO_URL Location: Settings > OpenID Connect Client > Client Settings

Purpose: The IDP endpoint that provides user profile information.

Default: None (required)

Example:

https://graph.microsoft.com/oidc/userinfo
https://openidconnect.googleapis.com/v1/userinfo
https://example.com/oauth2/UserInfo

Notes:

  • Used after authentication to fetch user details
  • Returns claims like email, name, username, etc.
  • Found in IDP's .well-known/openid-configuration

Token Validation Endpoint URL

Setting Name: endpoint_token Environment Variable: OIDC_ENDPOINT_TOKEN_URL Location: Settings > OpenID Connect Client > Client Settings

Purpose: The IDP endpoint used to exchange authorization codes for tokens.

Default: None (required)

Example:

https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token
https://oauth2.googleapis.com/token
https://example.com/oauth2/token

Notes:

  • Critical endpoint for OAuth 2.0 flow
  • Also used for refresh token operations
  • Found in IDP's .well-known/openid-configuration

End Session Endpoint URL

Setting Name: endpoint_end_session Environment Variable: OIDC_ENDPOINT_LOGOUT_URL Location: Settings > OpenID Connect Client > Client Settings

Purpose: The IDP logout endpoint (optional).

Default: None (optional)

Example:

https://login.microsoftonline.com/tenant-id/oauth2/v2.0/logout
https://accounts.google.com/logout
https://example.com/oauth2/logout

Notes:

  • When configured, users are redirected to IDP logout when logging out of WordPress
  • Enables "single sign-out" - logging out of WordPress also logs out of IDP
  • Some IDPs don't provide this endpoint

JWKS URI

Setting Name: endpoint_jwks Environment Variable: OIDC_ENDPOINT_JWKS_URL Location: Settings > OpenID Connect Client > Client Settings

Purpose: The IDP endpoint providing public keys for JWT signature verification.

Default: None (optional but recommended)

Example:

https://login.microsoftonline.com/tenant-id/discovery/v2.0/keys
https://www.googleapis.com/oauth2/v3/certs
https://example.com/.well-known/jwks.json

Security Implications:

  • Highly recommended for production environments
  • Validates that ID tokens were actually issued by your IDP
  • Protects against token forgery attacks
  • Without JWKS, tokens are validated using only issuer and audience checks

Performance:

  • Keys are cached (see JWKS Cache TTL)
  • Usually found at /.well-known/jwks.json

Issuer

Setting Name: issuer Environment Variable: OIDC_ISSUER Location: Settings > OpenID Connect Client > Client Settings

Purpose: The expected issuer (iss) claim value in JWT tokens.

Default: Auto-derived from Login Endpoint URL

Example:

https://accounts.google.com
https://login.microsoftonline.com/tenant-id/v2.0
https://example.com

When to Configure:

  • Usually not needed - the plugin automatically derives the issuer from your Login Endpoint URL
  • Only configure if your IDP uses a different issuer value than the base URL of the login endpoint
  • Check your IDP's .well-known/openid-configuration for the actual issuer value

Security Implications:

  • Critical for JWT validation
  • Ensures tokens come from the expected identity provider
  • Mismatch causes authentication to fail

Example Scenario:

Login Endpoint: https://auth.example.com/oauth/authorize
Issuer in JWT:  https://issuer.example.com

In this case, you must set Issuer to: https://issuer.example.com

JWKS Cache TTL (seconds)

Setting Name: jwks_cache_ttl Environment Variable: None Location: Settings > OpenID Connect Client > Client Settings

Purpose: How long (in seconds) to cache JWKS keys before refreshing.

Default: 3600 (1 hour)

Example:

3600    = 1 hour (default)
7200    = 2 hours
86400   = 24 hours
1800    = 30 minutes

Performance Implications:

  • Longer cache = fewer requests to IDP, faster authentication
  • Shorter cache = more up-to-date keys, slightly slower authentication
  • IDPs rarely rotate keys more than once per day

Recommendations:

  • Most sites: Keep default (1 hour)
  • High-traffic sites: Increase to 4-24 hours to reduce IDP requests
  • Security-critical sites: Consider 30 minutes if IDP rotates keys frequently

ACR Values

Setting Name: acr_values Environment Variable: OIDC_ACR_VALUES Location: Settings > OpenID Connect Client > Client Settings

Purpose: Request a specific Authentication Context Class Reference from the IDP.

Default: None (optional)

Example:

urn:mace:incommon:iap:silver
phr

When to Use:

  • Your IDP supports multiple authentication methods (password, MFA, biometric)
  • You want to require a specific authentication strength
  • Your IDP documentation specifies ACR values

Notes:

  • This is an advanced feature - most sites don't need it
  • ACR values are IDP-specific
  • Consult your IDP's documentation for supported values

Identity Key

Setting Name: identity_key Environment Variable: None Location: Settings > OpenID Connect Client > Client Settings

Purpose: Specifies which claim in the user token identifies the user.

Default: preferred_username

Options:

  • preferred_username - Username from IDP (default)
  • email - User's email address
  • sub - Subject identifier (guaranteed unique, recommended if having issues)
  • Any custom claim from your IDP

Example:

preferred_username
sub
email
custom_user_id

When to Change:

  • Default causes issues: Try sub (most reliable)
  • Email-based identity: Use email
  • Custom IDP claim: Use your custom claim name

Nickname Key

Setting Name: nickname_key Environment Variable: None Location: Settings > OpenID Connect Client > Client Settings

Purpose: Specifies which claim provides the user's WordPress nickname.

Default: preferred_username

Example:

preferred_username
nickname
name
sub

Notes:

  • Sets the nickname field in WordPress user profile
  • Different IDPs provide different claims
  • Falls back to other available data if claim not found

Email Formatting

Setting Name: email_format Environment Variable: None Location: Settings > OpenID Connect Client > Client Settings

Purpose: Template for building the user's email address from IDP claims.

Default: {email}

Example:

{email}                           - Use email claim as-is (default)
{preferred_username}@example.com  - Build email from username
{sub}@company.local               - Build email from subject ID

When to Use:

  • Your IDP doesn't provide an email claim
  • You want to use internal email addresses instead of real emails
  • You need to transform email format

Template Syntax:

  • Use {claim_name} to insert any claim value
  • Literal text outside braces is preserved

Display Name Formatting

Setting Name: displayname_format Environment Variable: None Location: Settings > OpenID Connect Client > Client Settings

Purpose: Template for building the user's WordPress display name from IDP claims.

Default: None (uses WordPress defaults)

Example:

{given_name} {family_name}        - "John Smith"
{name}                            - Full name from IDP
{preferred_username}              - Username only
{email}                           - Email address
Dr. {family_name}                 - "Dr. Smith"

Template Syntax:

  • Use {claim_name} to insert any claim value
  • Combine multiple claims with literal text
  • Leave empty to let WordPress determine display name

Identify with User Name

Setting Name: identify_with_username Environment Variable: None Location: Settings > OpenID Connect Client > Client Settings

Purpose: Use username instead of email to match existing WordPress users.

Default: Unchecked (use email for identification)

When to Enable:

  • Your WordPress site has users without email addresses
  • Multiple users share the same email
  • You want username-based identity instead of email-based

Notes:


State Time Limit

Setting Name: state_time_limit Environment Variable: None Location: Settings > OpenID Connect Client > Client Settings

Purpose: How long (in seconds) the OAuth state parameter remains valid.

Default: 180 (3 minutes)

Example:

180     = 3 minutes (default)
300     = 5 minutes
600     = 10 minutes

Security Implications:

  • State parameter prevents CSRF attacks during OAuth flow
  • Shorter time = more secure but may timeout slow users
  • Longer time = more convenient but slightly less secure

Recommendations:

  • Most sites: Keep default (180 seconds)
  • Slow authentication flows: Increase to 300-600 seconds
  • High-security sites: Keep at 180 or lower

Notes:

  • Since 3.11.4, the state is tied to the browser that started the login (with the wp-openid_connect_generic_browser cookie; openid-connect-generic-browser in 3.11.4) and can only be used once

Use PKCE

Setting Name: enable_pkce Environment Variable: OIDC_ENABLE_PKCE Location: Settings > OpenID Connect Client > Client Settings

Purpose: Send a PKCE (S256) code challenge with each login and the matching code verifier when exchanging the authorization code for tokens.

Default: Checked for new installs. Unchecked for sites that updated from 3.11.3 or earlier.

Example:

define( 'OIDC_ENABLE_PKCE', true );

Security Implications:

  • PKCE stops a stolen authorization code from being exchanged for tokens by anyone except the browser session that started the login
  • Recommended by current OAuth 2.0 security guidance, even for clients with a Client Secret

When to Disable:

  • Only if your IDP rejects the login when PKCE parameters are sent. Most IDPs support it.

Notes:

  • Added in 3.11.4
  • After turning it on, log in once in a private window to confirm your IDP accepts it

Related Settings: Client Secret Key, State Time Limit


Token Refresh Enable

Setting Name: token_refresh_enable Environment Variable: None Location: Settings > OpenID Connect Client > Client Settings

Purpose: Enable support for refresh tokens to obtain new access tokens.

Default: Unchecked (disabled)

When to Enable:

  • You need long-lived sessions
  • Your IDP provides refresh tokens
  • You want to refresh access tokens without re-authentication

Requirements:

  • IDP must support refresh tokens
  • offline_access scope must be included in OpenID Scope setting

Notes:

  • Not all IDPs support refresh tokens
  • WordPress sessions are separate from IDP token expiration

HTTP Request Timeout

Setting Name: http_request_timeout Environment Variable: None Location: Settings > OpenID Connect Client > Client Settings

Purpose: Timeout (in seconds) for HTTP requests to the IDP.

Default: 5 seconds

Example:

5       = 5 seconds (default)
10      = 10 seconds
30      = 30 seconds

When to Increase:

  • Your IDP is slow to respond
  • You're experiencing timeout errors
  • Network latency is high

Performance Implications:

  • Longer timeout = more time for slow IDPs but longer wait if IDP is down
  • Shorter timeout = faster failure detection but may timeout valid requests

Recommendations:

  • Most sites: Keep default (5 seconds)
  • Slow IDPs: Increase to 10-30 seconds
  • High-performance sites: Consider reducing to 3 seconds

Disable SSL Verify

Setting Name: no_sslverify Environment Variable: None Location: Settings > OpenID Connect Client > Client Settings

Purpose: Disable SSL certificate verification for requests to IDP.

Default: Unchecked (SSL verification enabled)

⚠️ Security Warning:

  • ONLY works in development environments (WP_DEBUG=true and WP_ENVIRONMENT_TYPE=local)
  • Automatically disabled in production for security
  • Disabling SSL verification exposes you to man-in-the-middle attacks

When to Use:

  • Local development with self-signed certificates
  • Testing with development IDP that doesn't have valid SSL

Production Alternative:

  • DO NOT use this in production
  • Fix your SSL certificates instead
  • Add your CA certificate to your server's trusted store

Allow Internal IDP

Setting Name: allow_internal_idp Environment Variable: None Location: Settings > OpenID Connect Client > Client Settings

Purpose: Allow HTTP requests to internal/private network endpoints.

Default: Unchecked (disabled)

⚠️ Security Warning:

  • Disabling SSRF protection can expose your server to security risks
  • Only enable for legitimate use cases

When to Enable:

  • Local development with IDP on localhost
  • Corporate internal identity providers (10.x.x.x, 192.168.x.x, 172.16-31.x.x)
  • IDP is on internal network, not public internet

Blocked by Default:

  • localhost, 127.0.0.1
  • Private IP ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
  • Link-local addresses: 169.254.0.0/16

Security Implications:

  • SSRF (Server-Side Request Forgery) protection prevents attackers from scanning your internal network
  • Only enable if you trust your IDP configuration inputs
  • Consider firewall rules as additional protection

Authorization Settings

Settings that control access and redirects.

Enforce Privacy

Setting Name: enforce_privacy Environment Variable: OIDC_ENFORCE_PRIVACY Location: Settings > OpenID Connect Client > Authorization Settings

Purpose: Require users to be logged in to access any part of the site.

Default: Unchecked (public access allowed)

When to Enable:

  • Your site should only be accessible to authenticated users
  • You're building an intranet or private application
  • All content is private

Exceptions:

  • The login page is always accessible
  • May conflict with some plugins that need public access

Alternate Redirect URI

Setting Name: alternate_redirect_uri Environment Variable: None Location: Settings > OpenID Connect Client > Authorization Settings

Purpose: Use an alternate redirect URI method instead of admin-ajax.

Default: Unchecked (use admin-ajax method)

When to Enable:

  • Experiencing issues with the default admin-ajax redirect
  • Your server configuration blocks admin-ajax
  • Your IDP has strict redirect URI requirements

Important:

  • Must flush rewrite rules after changing - visit Settings > Permalinks and click Save
  • Changes the callback URL you register with your IDP
  • Check your site's redirect URI at Settings > OpenID Connect Client (shown at top)

User Settings

Settings that control user account creation and behavior.

Link Existing Users

Setting Name: link_existing_users Environment Variable: OIDC_LINK_EXISTING_USERS Location: Settings > OpenID Connect Client > User Settings

Purpose: Link IDP accounts to existing WordPress users with matching identity.

Default: Unchecked (don't link)

When to Enable:

  • You have existing WordPress users
  • You want to link them to IDP accounts automatically
  • User identity (email or username) matches between WordPress and IDP

Behavior:

  • If unchecked: Returns error if user exists but isn't linked
  • If checked: Links and logs in the matching user when the IDP sends email_verified: true
  • Never links when the IDP sends email_verified: false
  • Links when the IDP doesn't send email_verified, or when matching by user name, only if Link Users Without Verified Email is checked
  • An account already linked to a different IDP identity is only re-linked when the email is verified

Security Consideration:

  • Matching by email is only safe when the IDP verifies email addresses. The plugin checks the email_verified claim for this.

Related Settings: Link Users Without Verified Email, Identify with User Name


Link Users Without Verified Email

Setting Name: link_unverified_users Environment Variable: OIDC_LINK_UNVERIFIED_USERS Location: Settings > OpenID Connect Client > User Settings

Purpose: Let Link Existing Users link an account when the IDP doesn't send the email_verified claim, or when Identify with User Name is checked.

Default: Unchecked for new installs. Checked during the 3.11.4 update on sites that already had Link Existing Users on, with an admin notice asking you to review it.

When to Enable:

  • Your IDP doesn't send email_verified (for example, Microsoft Entra ID) and existing users can no longer log in
  • You link accounts by user name

Example:

define( 'OIDC_LINK_EXISTING_USERS', true );
define( 'OIDC_LINK_UNVERIFIED_USERS', true );

Security Implications:

  • Only enable this if your IDP stops people from using an email address or user name that belongs to someone else
  • Otherwise anyone who can sign in to the IDP could log in as an existing WordPress user, including administrators
  • Has no effect when the IDP sends email_verified: false; those accounts are never linked

Checking your IDP:

  1. Turn this setting off and turn on Enable Logging
  2. Create a WordPress test user whose email matches an IDP account that has never logged in to the site
  3. Log in with that IDP account
  4. If the login works, your IDP sends email_verified and you can leave this setting off. If the log shows link-requires-verified-email, your IDP doesn't send it.

Notes:

  • Added in 3.11.4
  • Only affects the first login that links an account. Users already linked to their IDP identity keep logging in either way.
  • Turning the setting off also clears the admin notice

Related Settings: Link Existing Users, Identify with User Name


Create user if does not exist

Setting Name: create_if_does_not_exist Environment Variable: OIDC_CREATE_IF_DOES_NOT_EXIST Location: Settings > OpenID Connect Client > User Settings

Purpose: Automatically create WordPress users for new IDP users.

Default: Checked (create new users)

Behavior:

  • If checked: New WordPress user created automatically on first login
  • If unchecked: Authentication fails if user doesn't exist in WordPress

When to Disable:

  • You want to pre-create all users manually
  • You need approval process before granting access
  • You want to control exactly who can access the site

Notes:

  • New users are created with Subscriber role by default
  • Use openid-connect-generic-user-creation-test filter for additional control
  • Use openid-connect-generic-user-create action to customize new users

Redirect Back to Origin Page

Setting Name: redirect_user_back Environment Variable: OIDC_REDIRECT_USER_BACK Location: Settings > OpenID Connect Client > User Settings

Purpose: Redirect users back to the page where they clicked the login button.

Default: Unchecked (don't redirect back)

Behavior:

  • If unchecked: Users go to WordPress admin dashboard after login
  • If checked: Users return to the page where they initiated login

When to Enable:

  • Using WooCommerce or other front-end login flows
  • You want users to continue their activity after logging in
  • You have custom login buttons on various pages

Examples:

  • User on "My Account" page → login → returns to "My Account" page
  • User on checkout page → login → returns to checkout

Redirect to the login screen when session is expired

Setting Name: redirect_on_logout Environment Variable: OIDC_REDIRECT_ON_LOGOUT Location: Settings > OpenID Connect Client > User Settings

Purpose: Automatically redirect to login page when access token expires.

Default: Unchecked (don't auto-redirect)

When to Enable:

  • You want users to re-authenticate when their token expires
  • You're enforcing session limits
  • You want seamless re-authentication flow

Notes:

  • Token expiration is separate from WordPress session expiration
  • Most sites don't need this unless token lifetimes are very short

Log Settings

Settings for debugging and troubleshooting.

Enable Logging

Setting Name: enable_logging Environment Variable: OIDC_ENABLE_LOGGING Location: Settings > OpenID Connect Client > Log Settings

Purpose: Enable simple logging for debugging authentication issues.

Default: Unchecked (logging disabled)

When to Enable:

  • Troubleshooting authentication problems
  • Investigating user creation issues
  • Debugging IDP integration

Log Location:

  • View logs at Settings > OpenID Connect Client > Logs section
  • Logs stored as WordPress option in database

⚠️ Performance Warning:

  • Logs can grow large and impact database performance
  • Only enable when actively troubleshooting
  • Disable after resolving issues

Log Limit

Setting Name: log_limit Environment Variable: OIDC_LOG_LIMIT Location: Settings > OpenID Connect Client > Log Settings

Purpose: Maximum number of log entries to keep in the database.

Default: 1000

Example:

100     = Keep last 100 entries
1000    = Keep last 1000 entries (default)
5000    = Keep last 5000 entries

Recommendations:

  • Most sites: Keep default (1000)
  • High-traffic sites: Consider reducing to 100-500
  • Active debugging: Temporarily increase to 5000

Notes:

  • Logs are stored in wp_options table
  • Older entries are automatically deleted when limit is reached
  • Reducing this value doesn't immediately delete old logs (next log event will trim)

Environment Variables & Constants

Many settings can be locked via PHP constants to prevent admin changes. See Configuration Environment Variables & Constants for complete list.

I Want To...

🔧 Configure the Plugin

🎨 Customize & Extend


Documentation

Clone this wiki locally