WordPress SSO with Keycloak using OIDC

Introduction

WordPress does not natively support OpenID Connect. The OpenID Connect Generic plugin (by daggerhart) is the recommended open-source solution — it is actively maintained, supports PKCE, handles token refresh, and provides WordPress filter hooks for role mapping.

By the end of this guide, WordPress users will authenticate via Keycloak, existing accounts will be linked by email, and administrators can control which Keycloak groups receive which WordPress roles.

Prerequisites

• Keycloak 24+ with HTTPS
• WordPress 6.x (self-hosted — not WordPress.com)
• WordPress admin access
• Keycloak admin access

Step 1 — Install the plugin

In the WordPress admin panel:

1. Plugins → Add New Plugin
2. Search for OpenID Connect Generic
3. Click Install Now then Activate

WordPress Plugins page showing the OpenID Connect Generic plugin installed and active with version number and description

Screenshot coming soon

Step 2 — Create the Keycloak client

In the Keycloak admin console, navigate to your target realm and create a new client:

1. Clients → Create client
2. Client type: OpenID Connect
3. Client ID: wordpress-site
4. Click Next

Capability config:

• Standard flow: ON
• Client authentication: ON (confidential client)
• Direct access grants: OFF

Login settings — Valid redirect URIs:

https://example.com/wp-admin/admin-ajax.php?action=openid-connect-authorize

Replace example.com with your WordPress domain. Web origins: https://example.com.

Keycloak admin console: new confidential client wordpress-site with redirect URI pointing to wp-admin/admin-ajax.php

Screenshot coming soon

2.1 — Add the groups client scope

Navigate to Clients → wordpress-site → Client scopes → Add client scope → select groups → Default.

Keycloak admin console: Client scopes tab for wordpress-site showing groups scope added as Default alongside openid, profile, email

Screenshot coming soon

2.2 — Copy the client secret

Clients → wordpress-site → Credentials → copy the secret.

Step 3 — Configure the plugin

In WordPress: Settings → OpenID Connect Client.

WordPress Settings: OpenID Connect Client configuration page showing all OIDC fields including Login Type, Client ID, and endpoint URLs

Screenshot coming soon

Key settings:

Field	Value
Login Type	Auto Login – SSO or Button on Login Form
Client ID	wordpress-site
Client Secret Key	(paste from Keycloak)
OpenID Scope	openid email profile groups
Login Endpoint URL	https://keycloak.example.com/realms/YOUR_REALM/protocol/openid-connect/auth
Userinfo Endpoint URL	https://keycloak.example.com/realms/YOUR_REALM/protocol/openid-connect/userinfo
Token Validation Endpoint URL	https://keycloak.example.com/realms/YOUR_REALM/protocol/openid-connect/token
End Session Endpoint URL	https://keycloak.example.com/realms/YOUR_REALM/protocol/openid-connect/logout
Identity Key	preferred_username
Link Existing Users	✓ (links by email — essential for existing WordPress users)
Create user if they do not exist	✓
Redirect to the login screen	✓

Replace YOUR_REALM with your actual realm name.

Click Save Settings.

Step 4 — Map Keycloak groups to WordPress roles

Add the following to your theme's functions.php or a custom plugin:

add_filter( 'openid-connect-generic-user-creation-test', function( $result, $user_claim ) {
    // Deny login if user has no groups claim
    if ( empty( $user_claim['groups'] ) ) {
        return new WP_Error( 'no_group', 'No Keycloak group assigned' );
    }
    return $result;
}, 10, 2 );

add_filter( 'openid-connect-generic-update-user-using-current-claim', function( $user, $user_claim ) {
    if ( ! empty( $user_claim['groups'] ) ) {
        $groups = $user_claim['groups'];
        if ( in_array( '/wp-admins', $groups, true ) ) {
            $user->set_role( 'administrator' );
        } elseif ( in_array( '/wp-editors', $groups, true ) ) {
            $user->set_role( 'editor' );
        } else {
            $user->set_role( 'subscriber' );
        }
    }
    return $user;
}, 10, 2 );

Adjust the group paths (/wp-admins, /wp-editors) to match your Keycloak group structure.

Step 5 — Test the login flow

Open a new browser window and go to https://example.com/wp-login.php.

WordPress login page showing the standard username/password form and a Login with OpenID Connect button at the bottom

Screenshot coming soon

Click Login with OpenID Connect. You are redirected to Keycloak. After authenticating, Keycloak returns you to WordPress and you are logged in.

WordPress admin dashboard after successful Keycloak SSO login, showing the user's display name in the top-right corner

Screenshot coming soon

Step 6 — Configure single logout (SLO)

Keycloak supports OIDC back-channel logout. Configure the End Session Endpoint URL in the plugin settings (done in Step 3). When a user logs out of WordPress, the plugin will redirect to the Keycloak logout endpoint, which terminates the Keycloak SSO session.

To send the user back to WordPress after Keycloak logout, append ?post_logout_redirect_uri=https://example.com/wp-login.php to the end session URL — the plugin's Redirect Back After Logout field handles this automatically if filled in.

Step 7 — Troubleshooting common issues

Cookie/domain issues

If WordPress sets a cookie on .example.com but Keycloak runs on keycloak.example.com, browsers may reject the cookie. Ensure COOKIEHASH and COOKIE_DOMAIN are set correctly in wp-config.php.

CORS on AJAX

Some caching plugins or security plugins block admin-ajax.php. Add the OIDC callback URL to the allowlist in your security plugin.

Permalink conflicts

If WordPress Pretty Permalinks are enabled and the callback URL returns a 404, go to Settings → Permalinks and click Save (this flushes rewrite rules without changing the structure).

State cookie was missing

This error means the OIDC state cookie set before the redirect was not received on return. Common causes: HTTPS not enforced (cookies are Secure), or the Keycloak redirect added a port that WordPress did not expect. Enforce HTTPS end-to-end.

Step 8 — Production checklist

• HTTPS enforced on WordPress and Keycloak
• Link Existing Users enabled to avoid duplicate accounts
• Group → role mapping tested with a non-admin user
• Single logout tested: logging out of WordPress terminates the Keycloak session
• Caching plugin configured to exclude admin-ajax.php from cache
• openid-connect-generic plugin updates are monitored