Skip to content

Troubleshooting Common Issues

daggerhart edited this page Nov 20, 2026 · 6 revisions

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.


Table of Contents


Activation Errors

"Plugin could not be activated because it triggered a fatal error" (vendor/autoload.php)

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-dev in the plugin folder, then activate it. See Installing from Source.

Authentication Failures

"Authentication Failure: User not found in identity provider"

Cause: The IDP did not return user information.

Solutions:

  1. Check scope configuration:

    • Ensure openid scope is included (required)
    • Add email and profile scopes
    • Settings > OpenID Connect Client > OpenID Scope
  2. Verify IDP permissions:

    • Check that your IDP app has permission to read user data
    • Ensure required claims are configured in IDP
  3. Test userinfo endpoint:

    • Verify Userinfo Endpoint URL is correct
    • Test endpoint manually with a valid access token

"Authentication Failure: Existing user account already exists"

Cause: A WordPress user with the same email/username exists but isn't linked to IDP account.

Solutions:

  1. Enable Link Existing Users:

    • Settings > OpenID Connect Client > User Settings
    • Check "Link Existing Users"
    • This automatically links matching accounts
  2. Manually link accounts:

  3. Change user identity method:

    • Try different Identity Key value
    • Settings > OpenID Connect Client > Identity Key
    • Try: sub, email, or preferred_username

"Your login could not be linked to an existing account"

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 send email_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:

  1. Require verified email at the IDP so it sends email_verified: true
  2. 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
  3. For link-identity-mismatch: remove the old link by deleting the user's openid-connect-generic-subject-identity user meta, then log in again

"Invalid state" or "Missing state"

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:

  1. Increase state time limit:

    • Settings > OpenID Connect Client > State Time Limit
    • Default: 180 seconds (3 minutes)
    • Try: 300-600 seconds (5-10 minutes)
  2. 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
  3. 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.
  4. Browser taking too long:

    • Users may be sitting on IDP login page too long
    • Educate users to complete login promptly
  5. Clock synchronization:

    • Ensure server time is accurate (NTP)
    • Time skew can cause state expiration issues

Token Validation Errors

"Token validation failed: Invalid issuer"

Cause: The iss (issuer) claim in the token doesn't match expected value.

Solutions:

  1. 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
  2. Verify IDP issuer value:

    • Check IDP's .well-known/openid-configuration
    • Look for "issuer" field
    • Copy exact value to plugin's Issuer setting
  3. 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}
    

"Token validation failed: JWT signature verification failed"

Cause: Token signature cannot be verified using IDP's public keys.

Solutions:

  1. 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
  2. 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)
  3. 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
  4. Check Allow Internal IDP setting:

    • If JWKS endpoint is on internal network
    • Enable "Allow Internal IDP" setting
    • Settings > OpenID Connect Client > Allow Internal IDP

"Token validation failed: Invalid audience"

Cause: The aud (audience) claim doesn't match Client ID.

Solutions:

  1. Verify Client ID:

    • Settings > OpenID Connect Client > Client ID
    • Must exactly match Client ID configured in IDP
    • Case-sensitive, no extra spaces
  2. Check IDP configuration:

    • Ensure Client ID in IDP matches WordPress setting
    • Some IDPs use different audience values - check documentation

User Creation Issues

"User creation failed: Email already exists"

Cause: Email address is already used by another WordPress user.

Solutions:

  1. Enable Link Existing Users:

    • Settings > OpenID Connect Client > User Settings
    • Check "Link Existing Users"
  2. Change identity method:

    • Settings > OpenID Connect Client > Identify with User Name
    • Check this to use username instead of email for matching
  3. Customize email formatting:

    • Settings > OpenID Connect Client > Email Formatting
    • Use template to create unique emails: {sub}@company.local

"New users not being created"

Cause: User creation is disabled or blocked by filter.

Solutions:

  1. Enable user creation:

    • Settings > OpenID Connect Client > User Settings
    • Check "Create user if does not exist"
  2. Check filters:

    • Look for openid-connect-generic-user-creation-test filter in your theme/plugins
    • This filter can block user creation
    • Comment out or adjust filter logic
  3. Review PHP error logs:

    • User creation may be failing due to PHP errors
    • Check WordPress debug.log
    • Enable WP_DEBUG to see errors

"Users created with wrong role"

Cause: WordPress assigns Subscriber role by default.

Solutions:

  1. 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);
  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);
  3. See code examples:


SSL Certificate Problems

"SSL certificate problem: unable to get local issuer certificate"

Cause: WordPress cannot verify IDP's SSL certificate.

Solutions:

  1. 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
  2. Development only - Disable SSL Verify:

    • Settings > OpenID Connect Client > Disable SSL Verify
    • Only works with: WP_DEBUG=true and WP_ENVIRONMENT_TYPE=local
    • Automatically disabled in production
  3. 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

"Cannot connect to internal IDP (localhost, 192.168.x.x)"

Cause: SSRF protection blocks requests to internal/private networks.

Solutions:

  1. Enable Allow Internal IDP:

    • Settings > OpenID Connect Client > Allow Internal IDP
    • Security warning: Only enable for legitimate internal IDPs
  2. Use public URLs:

    • If possible, use public URLs even for development
    • Use ngrok or similar tools to expose local IDP

Login Button Not Appearing

"OpenID Connect button doesn't show on login page"

Cause: Login Type is set to Auto Login, or theme/plugin conflict.

Solutions:

  1. Check Login Type:

    • Settings > OpenID Connect Client > Login Type
    • Change from "Auto Login" to "OpenID Connect button"
  2. Test with default theme:

    • Switch to Twenty Twenty-Four or another default theme
    • If button appears, your theme has a custom login page
  3. 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

Redirect Issues

"Stuck in redirect loop after login"

Cause: Redirect URL misconfiguration or conflict.

Solutions:

  1. Try Alternate Redirect URI:

    • Settings > OpenID Connect Client > Alternate Redirect URI
    • Check the box
    • Important: Visit Settings > Permalinks and click Save (flush rewrites)
  2. Update IDP redirect URI:

    • Get correct redirect URI from Settings > OpenID Connect Client (shown at top)
    • Update in your IDP application configuration
  3. Check Enforce Privacy:

    • Settings > OpenID Connect Client > Enforce Privacy
    • If enabled, may cause loops with certain plugins
  4. Disable conflicting plugins:

    • Temporarily disable caching plugins
    • Disable security plugins that might interfere

"Returns to wrong page after login"

Cause: Redirect settings or WordPress defaults.

Solutions:

  1. Enable Redirect Back to Origin:

    • Settings > OpenID Connect Client > Redirect Back to Origin Page
    • Users return to page where they clicked login
  2. 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);

Session and Token Problems

"Users getting logged out unexpectedly"

Cause: Token expiration or session management issues.

Solutions:

  1. Enable Refresh Tokens:

    • Settings > OpenID Connect Client > Token Refresh Enable
    • Add offline_access to OpenID Scope
    • IDP must support refresh tokens
  2. Check WordPress session settings:

    • WordPress sessions are separate from IDP tokens
    • Default: 2 days (can be extended with plugins)
  3. Disable Redirect on Logout:

    • Settings > OpenID Connect Client > Redirect on Logout
    • Uncheck if users are being logged out too aggressively

Logging and Debugging

Enabling Debug Logging

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.log

Understanding Log Messages

Common 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"

Testing Endpoints Manually

Test IDP's discovery document:

curl https://your-idp.com/.well-known/openid-configuration

Should return JSON with all endpoints.

Test JWKS endpoint:

curl https://your-idp.com/.well-known/jwks.json

Should return JSON with public keys.


Bypassing Auto-Login

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_options table
  • Find openid_connect_generic_settings option
  • Change login_type from auto to button

Getting Help

Before Opening an Issue

  1. ✅ Enable logging and review logs
  2. ✅ Check this troubleshooting guide
  3. ✅ Review FAQ
  4. ✅ Test with default theme and no other plugins
  5. ✅ Check WordPress and PHP error logs

Opening a GitHub Issue

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

Report Issue on GitHub

I Want To...

🔧 Configure the Plugin

🎨 Customize & Extend


Documentation

Clone this wiki locally