Skip to content

Configuration Environment Variables Constants

daggerhart edited this page Nov 17, 2026 · 10 revisions

Configuration: Environment Variables & Constants

The plugin supports setting many core plugin settings via PHP constants defined in wp-config.php or when using a library such as PHP dotenv.

For WordPress Administrators: This method is recommended for production environments to lock down security-sensitive settings and prevent admin changes.


Why Use Constants?

Benefits:

  • Security: Keep sensitive values (Client Secret) out of the database
  • Consistency: Prevent accidental admin changes to critical settings
  • Version Control: Manage configuration across environments (dev, staging, production)
  • Deployment: Configure settings in code instead of clicking through admin UI

Precedence: When a setting is defined as a constant, it overrides the database value and the setting field is disabled in the admin UI. This prevents administrators from changing the value through the settings page.


Available Constants

Client Settings

  • Login Type: OIDC_LOGIN_TYPE ('button' or 'auto')
  • Client ID: OIDC_CLIENT_ID
  • Client Secret Key: OIDC_CLIENT_SECRET
  • OpenID Scope: OIDC_CLIENT_SCOPE (space-separated)
  • Login Endpoint URL: OIDC_ENDPOINT_LOGIN_URL
  • Userinfo Endpoint URL: OIDC_ENDPOINT_USERINFO_URL
  • Token Validation Endpoint URL: OIDC_ENDPOINT_TOKEN_URL
  • End Session Endpoint URL: OIDC_ENDPOINT_LOGOUT_URL
  • JWKS Endpoint URL: OIDC_ENDPOINT_JWKS_URL
  • Issuer: OIDC_ISSUER
  • ACR values: OIDC_ACR_VALUES
  • Use PKCE: OIDC_ENABLE_PKCE (boolean)

Authorization Settings

  • Enforce Privacy: OIDC_ENFORCE_PRIVACY (boolean)

User Settings

  • Create user if does not exist: OIDC_CREATE_IF_DOES_NOT_EXIST (boolean)
  • Link Existing Users: OIDC_LINK_EXISTING_USERS (boolean)
  • Link Users Without Verified Email: OIDC_LINK_UNVERIFIED_USERS (boolean). Only set to true if your IDP stops people from using an email address or user name that belongs to someone else; see Settings Reference.
  • Redirect User Back to Origin Page: OIDC_REDIRECT_USER_BACK (boolean)
  • Redirect on Logout: OIDC_REDIRECT_ON_LOGOUT (boolean)

Log Settings

  • Enable Logging: OIDC_ENABLE_LOGGING (boolean)
  • Log Limit: OIDC_LOG_LIMIT (integer)

Example: Basic Configuration

Define these in your wp-config.php file:

// Client credentials
define('OIDC_CLIENT_ID', 'my-wordpress-client-id');
define('OIDC_CLIENT_SECRET', 'super-secret-key-from-your-idp');

// IDP endpoints
define('OIDC_ENDPOINT_LOGIN_URL', 'https://example.com/oauth2/authorize');
define('OIDC_ENDPOINT_USERINFO_URL', 'https://example.com/oauth2/UserInfo');
define('OIDC_ENDPOINT_TOKEN_URL', 'https://example.com/oauth2/token');
define('OIDC_ENDPOINT_LOGOUT_URL', 'https://example.com/oauth2/logout');
define('OIDC_ENDPOINT_JWKS_URL', 'https://example.com/.well-known/jwks.json');

// Scope (space-separated)
define('OIDC_CLIENT_SCOPE', 'openid email profile offline_access');

Example: Production Security Configuration

Recommended settings for production environments:

// Required: Client credentials (keep secret out of database)
define('OIDC_CLIENT_ID', 'prod-wordpress-client');
define('OIDC_CLIENT_SECRET', 'your-production-secret');

// Required: IDP endpoints
define('OIDC_ENDPOINT_LOGIN_URL', 'https://login.example.com/oauth2/authorize');
define('OIDC_ENDPOINT_USERINFO_URL', 'https://login.example.com/oauth2/UserInfo');
define('OIDC_ENDPOINT_TOKEN_URL', 'https://login.example.com/oauth2/token');
define('OIDC_ENDPOINT_JWKS_URL', 'https://login.example.com/.well-known/jwks.json');

// Security: Issuer validation (if your IDP uses different issuer)
define('OIDC_ISSUER', 'https://issuer.example.com');

// Scope
define('OIDC_CLIENT_SCOPE', 'openid email profile');

// Security: PKCE
define('OIDC_ENABLE_PKCE', true);

// Enforce SSO for entire site
define('OIDC_LOGIN_TYPE', 'auto');
define('OIDC_ENFORCE_PRIVACY', true);

// User management
define('OIDC_CREATE_IF_DOES_NOT_EXIST', true);
define('OIDC_LINK_EXISTING_USERS', true);
define('OIDC_REDIRECT_USER_BACK', true);

// Logging (disable in production)
define('OIDC_ENABLE_LOGGING', false);

Example: Using Environment Variables with PHP dotenv

For even better security, use PHP dotenv to load from .env file:

# 1. Install
composer require vlucas/phpdotenv

# 2. Create .env file (add to .gitignore!)
OIDC_CLIENT_ID=my-client-id
OIDC_CLIENT_SECRET=my-super-secret
OIDC_ENDPOINT_LOGIN_URL=https://example.com/oauth2/authorize
# ... additional settings
// 3. Load in wp-config.php (before ABSPATH)
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

// Define constants from environment variables
define('OIDC_CLIENT_ID', $_ENV['OIDC_CLIENT_ID']);
define('OIDC_CLIENT_SECRET', $_ENV['OIDC_CLIENT_SECRET']);
// ... define remaining constants

Boolean Values

For boolean settings, use true or false:

define('OIDC_ENFORCE_PRIVACY', true);  // Enable
define('OIDC_ENABLE_LOGGING', false);  // Disable

Settings Without Constants

Some settings cannot be defined via constants and must be configured in the admin UI:

  • Login Button Text
  • JWKS Cache TTL
  • Identity Key
  • Nickname Key
  • Email Format
  • Display Name Format
  • Identify with User Name
  • State Time Limit
  • Token Refresh Enable
  • HTTP Request Timeout
  • Disable SSL Verify
  • Allow Internal IDP
  • Alternate Redirect URI
  • Redirect on Logout

For complete documentation of all settings, see Settings Reference.


Troubleshooting

Constants not taking effect:

  • Ensure constants are defined before require_once(ABSPATH . 'wp-settings.php'); in wp-config.php
  • Check for typos in constant names (they are case-sensitive)
  • Clear any object caching (Redis, Memcached, etc.)

Settings page shows "Disabled":

  • This is expected when a constant is defined - it means the setting is locked
  • To change the value, update the constant in wp-config.php

Need to temporarily override:

  • Comment out the constant definition in wp-config.php
  • Configure via admin UI
  • Re-enable constant when testing is complete

Related Documentation

I Want To...

🔧 Configure the Plugin

🎨 Customize & Extend


Documentation

Clone this wiki locally