Repository navigation
Troubleshooting Common Issues
Solutions to common problems when configuring and using the OpenID Connect Generic plugin.
For WordPress Administrators: This guide helps you diagnose and fix authentication issues, configuration problems, and integration challenges.
- Activation Errors
- Authentication Failures
- Token Validation Errors
- User Creation Issues
- SSL Certificate Problems
- Login Button Not Appearing
- Redirect Issues
- Session and Token Problems
- Logging and Debugging
Symptoms: Activation fails with a warning like require_once(.../openid-connect-generic/vendor/autoload.php): failed to open stream: No such file or directory.
Cause: The plugin was installed from the GitHub source code (the repository or its "Download ZIP" button), which doesn't include the vendor/ folder.
Solution:
- Install the plugin from WordPress.org (Plugins > Add New), which includes everything it needs.
- Or, to run it from source, run
composer install --no-devin the plugin folder, then activate it. See Installing from Source.
Cause: The IDP did not return user information.
Solutions:
-
Check scope configuration:
- Ensure
openidscope is included (required) - Add
emailandprofilescopes - Settings > OpenID Connect Client > OpenID Scope
- Ensure
-
Verify IDP permissions:
- Check that your IDP app has permission to read user data
- Ensure required claims are configured in IDP
-
Test userinfo endpoint:
- Verify Userinfo Endpoint URL is correct
- Test endpoint manually with a valid access token
Cause: A WordPress user with the same email/username exists but isn't linked to IDP account.
Solutions:
-
Enable Link Existing Users:
- Settings > OpenID Connect Client > User Settings
- Check "Link Existing Users"
- This automatically links matching accounts
-
Manually link accounts:
- Use a plugin hook to link accounts programmatically
- See Hooks & Filters Reference
-
Change user identity method:
- Try different Identity Key value
- Settings > OpenID Connect Client > Identity Key
- Try:
sub,email, orpreferred_username
Cause: Since 3.11.4, Link Existing Users only links an account when the IDP confirms the email address is verified. With Enable Logging on, the log shows which check failed:
-
link-email-not-verified: the IDP says the email address is not verified. Verify it at the IDP. -
link-requires-verified-email: the IDP doesn't sendemail_verified(for example, Microsoft Entra ID), or you link by user name. -
link-identity-mismatch: the WordPress account is already linked to a different IDP identity.
Solutions:
-
Require verified email at the IDP so it sends
email_verified: true -
For
link-requires-verified-email: if your IDP stops people from using an email address or user name that belongs to someone else, check Link Users Without Verified Email -
For
link-identity-mismatch: remove the old link by deleting the user'sopenid-connect-generic-subject-identityuser meta, then log in again
Cause: The login state is missing, expired, already used, or was started in a different browser. Since 3.11.4 the state is tied to the browser that started the login with a cookie, named wp-openid_connect_generic_browser since 3.11.5 (openid-connect-generic-browser in 3.11.4).
Find the cause: enable logging (Settings > OpenID Connect Client > Enable Logging), try the login again, and look for a log entry of type invalid-state (3.11.5 and later). It says which check failed:
- "State not found or expired." - see solutions 1, 2 and 4
- "Browser cookie missing from the request." - see solution 3
- "Browser cookie does not match the state." or "State is not linked to a browser." - the login was finished in a different browser, or the login page was served from a cache
Solutions:
-
Increase state time limit:
- Settings > OpenID Connect Client > State Time Limit
- Default: 180 seconds (3 minutes)
- Try: 300-600 seconds (5-10 minutes)
-
Check for caching interference:
- Object caching (Redis, Memcached) may be flushing transients too aggressively
- Add exception for
openid-connect-generic-state--*transients - Page caching must not cache
wp-login.php(including?openid-connect-generic-start=URLs) or the callback URL
-
Cookie blocked or login finished in another browser:
- The login cookie must reach the callback URL. Some managed hosts (such as Pantheon) only pass cookies with WordPress-style names to PHP; 3.11.4 used a name they strip, so update to 3.11.5 or later.
- If a proxy, CDN or host still strips the cookie, change its name with the openid-connect-generic-browser-cookie-name filter.
- Users must finish the login in the browser they started it in. Copying a login URL into a different browser fails.
-
Browser taking too long:
- Users may be sitting on IDP login page too long
- Educate users to complete login promptly
-
Clock synchronization:
- Ensure server time is accurate (NTP)
- Time skew can cause state expiration issues
Cause: The iss (issuer) claim in the token doesn't match expected value.
Solutions:
-
Check issuer configuration:
- Settings > OpenID Connect Client > Issuer
- Leave blank to auto-derive from Login Endpoint URL
- Or set explicitly to match IDP's issuer claim
-
Verify IDP issuer value:
- Check IDP's
.well-known/openid-configuration - Look for
"issuer"field - Copy exact value to plugin's Issuer setting
- Check IDP's
-
Common issuer patterns:
Azure AD: https://login.microsoftonline.com/{tenant-id}/v2.0 Google: https://accounts.google.com Keycloak: https://keycloak.example.com/realms/{realm-name}
Cause: Token signature cannot be verified using IDP's public keys.
Solutions:
-
Configure JWKS URI:
- Settings > OpenID Connect Client > JWKS URI
- Find endpoint in IDP's
.well-known/openid-configuration - Usually:
https://your-idp.com/.well-known/jwks.json
-
Clear JWKS cache:
- Keys may be cached and outdated
- Deactivate and reactivate plugin to clear cache
- Or wait for cache TTL to expire (default 1 hour)
-
Verify JWKS endpoint accessibility:
- Test URL in browser - should return JSON with keys
- Ensure WordPress server can reach the URL
- Check firewall and network restrictions
-
Check Allow Internal IDP setting:
- If JWKS endpoint is on internal network
- Enable "Allow Internal IDP" setting
- Settings > OpenID Connect Client > Allow Internal IDP
Cause: The aud (audience) claim doesn't match Client ID.
Solutions:
-
Verify Client ID:
- Settings > OpenID Connect Client > Client ID
- Must exactly match Client ID configured in IDP
- Case-sensitive, no extra spaces
-
Check IDP configuration:
- Ensure Client ID in IDP matches WordPress setting
- Some IDPs use different audience values - check documentation
Cause: Email address is already used by another WordPress user.
Solutions:
-
Enable Link Existing Users:
- Settings > OpenID Connect Client > User Settings
- Check "Link Existing Users"
-
Change identity method:
- Settings > OpenID Connect Client > Identify with User Name
- Check this to use username instead of email for matching
-
Customize email formatting:
- Settings > OpenID Connect Client > Email Formatting
- Use template to create unique emails:
{sub}@company.local
Cause: User creation is disabled or blocked by filter.
Solutions:
-
Enable user creation:
- Settings > OpenID Connect Client > User Settings
- Check "Create user if does not exist"
-
Check filters:
- Look for
openid-connect-generic-user-creation-testfilter in your theme/plugins - This filter can block user creation
- Comment out or adjust filter logic
- Look for
-
Review PHP error logs:
- User creation may be failing due to PHP errors
- Check WordPress debug.log
- Enable WP_DEBUG to see errors
Cause: WordPress assigns Subscriber role by default.
Solutions:
-
Use user creation hook:
add_action('openid-connect-generic-user-create', function($user, $user_claim) { // Assign role based on IDP claim if (!empty($user_claim['role'])) { $user->set_role($user_claim['role']); } }, 10, 2);
-
Use update user hook:
add_action('openid-connect-generic-update-user-using-current-claim', function($user, $user_claim) { // Update role on every login if (!empty($user_claim['groups']) && in_array('admins', $user_claim['groups'])) { $user->set_role('administrator'); } }, 10, 2);
-
See code examples:
Cause: WordPress cannot verify IDP's SSL certificate.
Solutions:
-
Fix SSL certificates (production):
- Do not disable SSL verification in production
- Install proper SSL certificates on IDP
- Or add IDP's CA certificate to server's trusted store
-
Development only - Disable SSL Verify:
- Settings > OpenID Connect Client > Disable SSL Verify
-
Only works with:
WP_DEBUG=trueandWP_ENVIRONMENT_TYPE=local - Automatically disabled in production
-
Update CA certificates:
# Ubuntu/Debian sudo apt-get update sudo apt-get install ca-certificates sudo update-ca-certificates # CentOS/RHEL sudo yum update ca-certificates
Cause: SSRF protection blocks requests to internal/private networks.
Solutions:
-
Enable Allow Internal IDP:
- Settings > OpenID Connect Client > Allow Internal IDP
- Security warning: Only enable for legitimate internal IDPs
-
Use public URLs:
- If possible, use public URLs even for development
- Use ngrok or similar tools to expose local IDP
Cause: Login Type is set to Auto Login, or theme/plugin conflict.
Solutions:
-
Check Login Type:
- Settings > OpenID Connect Client > Login Type
- Change from "Auto Login" to "OpenID Connect button"
-
Test with default theme:
- Switch to Twenty Twenty-Four or another default theme
- If button appears, your theme has a custom login page
-
Check for login page customization:
- Some plugins (WooCommerce, custom login plugins) replace wp-login.php
- Use shortcode instead:
[openid_connect_generic_login_button] - See Shortcodes for details
Cause: Redirect URL misconfiguration or conflict.
Solutions:
-
Try Alternate Redirect URI:
- Settings > OpenID Connect Client > Alternate Redirect URI
- Check the box
- Important: Visit Settings > Permalinks and click Save (flush rewrites)
-
Update IDP redirect URI:
- Get correct redirect URI from Settings > OpenID Connect Client (shown at top)
- Update in your IDP application configuration
-
Check Enforce Privacy:
- Settings > OpenID Connect Client > Enforce Privacy
- If enabled, may cause loops with certain plugins
-
Disable conflicting plugins:
- Temporarily disable caching plugins
- Disable security plugins that might interfere
Cause: Redirect settings or WordPress defaults.
Solutions:
-
Enable Redirect Back to Origin:
- Settings > OpenID Connect Client > Redirect Back to Origin Page
- Users return to page where they clicked login
-
Use redirect hook:
add_action('openid-connect-generic-redirect-user-back', function($redirect_url, $user) { // Custom redirect logic if ($user->has_cap('edit_posts')) { wp_redirect(admin_url('edit.php')); exit; } }, 10, 2);
Cause: Token expiration or session management issues.
Solutions:
-
Enable Refresh Tokens:
- Settings > OpenID Connect Client > Token Refresh Enable
- Add
offline_accessto OpenID Scope - IDP must support refresh tokens
-
Check WordPress session settings:
- WordPress sessions are separate from IDP tokens
- Default: 2 days (can be extended with plugins)
-
Disable Redirect on Logout:
- Settings > OpenID Connect Client > Redirect on Logout
- Uncheck if users are being logged out too aggressively
1. Enable plugin logging:
- Settings > OpenID Connect Client > Log Settings
- Check "Enable Logging"
- Set Log Limit (default 1000)
- View logs at bottom of settings page
2. Enable WordPress debugging:
// Add to wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);3. Check debug.log:
tail -f wp-content/debug.logCommon log entries:
- "Authentication request started" - User clicked login button
- "Retrieved authentication token" - Got token from IDP
- "Retrieved user claim" - Got user information from IDP
- "Existing user found" - Matched to WordPress user
- "New user created" - Created new WordPress account
- "User logged in" - Authentication complete
Error indicators:
- "Token validation failed"
- "User creation failed"
- "Authentication failure"
Test IDP's discovery document:
curl https://your-idp.com/.well-known/openid-configurationShould return JSON with all endpoints.
Test JWKS endpoint:
curl https://your-idp.com/.well-known/jwks.jsonShould return JSON with public keys.
If Auto-Login (SSO) is enabled and you need to access WordPress admin:
Method 1: Direct admin URL with parameter:
https://yoursite.com/wp-?oidc_auto_login=0
Method 2: Define bypass constant:
// Add to wp-config.php temporarily
define('OIDC_AUTO_LOGIN_BYPASS', true);Method 3: Database access:
- Update
wp_optionstable - Find
openid_connect_generic_settingsoption - Change
login_typefromautotobutton
- ✅ Enable logging and review logs
- ✅ Check this troubleshooting guide
- ✅ Review FAQ
- ✅ Test with default theme and no other plugins
- ✅ Check WordPress and PHP error logs
Include:
- WordPress version
- PHP version
- Plugin version
- IDP type (Azure AD, Google, Keycloak, etc.)
- Relevant log entries (redact secrets!)
- Steps to reproduce
- Expected vs actual behavior
- 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