Repository navigation
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).
Settings that configure how the plugin communicates with your Identity Provider.
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
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-textfilter
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:
- Register your WordPress site as an application in your IDP
- Copy the Client ID provided by your IDP
- Enter it here
Security Implications:
- This is not secret - it's safe to store in the database
- However, locking it via
OIDC_CLIENT_IDconstant prevents admin changes
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_SECRETconstant 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:
- When registering your WordPress site in your IDP, you'll receive a Client Secret
- Store it securely
- Configure via constant (recommended) or settings page
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
openidscope is always required - Additional scopes depend on your IDP's configuration
- Your IDP must be configured to allow the requested scopes
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"
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
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
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
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
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-configurationfor 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
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
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
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
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
nicknamefield in WordPress user profile - Different IDPs provide different claims
- Falls back to other available data if claim not found
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
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
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:
- Affects how the plugin links IDP accounts to WordPress accounts
- Most sites should leave this unchecked
- Since 3.11.4, Link Existing Users only links by user name when Link Users Without Verified Email is also checked
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_browsercookie;openid-connect-generic-browserin 3.11.4) and can only be used once
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
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_accessscope must be included in OpenID Scope setting
Notes:
- Not all IDPs support refresh tokens
- WordPress sessions are separate from IDP token expiration
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
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)
-
ONLY works in development environments (
WP_DEBUG=trueandWP_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
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)
- 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
Settings that control access and redirects.
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
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)
Settings that control user account creation and behavior.
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_verifiedclaim for this.
Related Settings: Link Users Without Verified Email, Identify with User Name
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:
- Turn this setting off and turn on Enable Logging
- Create a WordPress test user whose email matches an IDP account that has never logged in to the site
- Log in with that IDP account
- If the login works, your IDP sends
email_verifiedand you can leave this setting off. If the log showslink-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
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-testfilter for additional control - Use
openid-connect-generic-user-createaction to customize new users
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
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
Settings for debugging and troubleshooting.
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
- Logs can grow large and impact database performance
- Only enable when actively troubleshooting
- Disable after resolving issues
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_optionstable - Older entries are automatically deleted when limit is reached
- Reducing this value doesn't immediately delete old logs (next log event will trim)
Many settings can be locked via PHP constants to prevent admin changes. See Configuration Environment Variables & Constants for complete list.
- Home - Overview & Quick Start
- Settings & Configuration - Complete settings reference
- Identity Providers - IDP setup guidance
- Troubleshooting - Common issues & solutions
- Hooks Reference - All filters and actions
- FAQ - Frequently asked questions