Setting Up SSO for WordPress Using Keycloak and OpenID Connect

Introduction

Managing user identities across multiple web applications quickly becomes a burden. Every application introduces another set of credentials, password policies, authentication settings, and user accounts to maintain.

Single Sign-On (SSO) helps address this problem by separating identity management from individual applications.

In this How-To guide, we will configure a WordPress website to authenticate users against a self-hosted identity provider using OpenID Connect (OIDC).

For the Identity Provider (IdP), we will use Keycloak. It is a free, open-source identity and access management solution that enables organizations to manage user authentication, single sign-on, and access policies without relying on proprietary identity services. By allowing organizations to host and control their own identity infrastructure, Keycloak promotes digital sovereignty, reduces vendor lock-in, and gives organizations greater control over their users’ identities and authentication data.

Our setup also depends on OpenID Connect Generic Client, which is a free and open-source WordPress plugin, that is used by tens of thousands worldwide. No commercial plugin or subscription is required.

By the end of this guide, users will be able to authenticate to WordPress using their Keycloak credentials. Keycloak will handle identity verification, while WordPress will continue to manage application-specific permissions and roles.

We will use the following environment as our example:

ComponentConfiguration
WordPress websitemywebsite.com
Keycloak serverauth.mywebsite.com
Keycloak realmmywebsite
Keycloak clientmywebsite-wordpress
Authentication protocolOpenID Connect
Authentication flowAuthorization Code Flow
WordPress pluginOpenID Connect Generic Client

Understanding the Architecture

Our goal is to establish a trust relationship between WordPress and Keycloak.

Keycloak acts as the Identity Provider (IdP), responsible for authenticating users. WordPress acts as the OIDC client, delegating authentication to Keycloak.

The authentication process works as follows:

  1. A visitor opens the WordPress login page.
  2. The visitor chooses to authenticate through Keycloak.
  3. WordPress redirects the browser to Keycloak.
  4. Keycloak authenticates the visitor, applying any configured authentication policies.
  5. Keycloak redirects the browser to WordPress with a short-lived authorization code.
  6. WordPress exchanges that code for tokens through a server-to-server request.
  7. WordPress validates the identity information, identifies the corresponding user, and establishes a WordPress session.

Importantly, WordPress does not need to receive or store the user’s Keycloak password.

But Why OpenID Connect? OpenID Connect is an authentication protocol built on OAuth 2.0. It provides a standardized mechanism for applications to verify user identities and retrieve identity-related information. For this integration, we will use the Authorization Code Flow with a confidential client.

This approach provides several advantages:

  • Authentication credentials are handled centrally by Keycloak.
  • The WordPress application does not need to implement its own identity provider.
  • Keycloak can enforce multifactor authentication and other security policies.
  • The same Keycloak deployment can provide authentication for additional applications.
  • Identity tokens can be validated cryptographically using the provider’s public signing keys.

SSO does not eliminate all WordPress security responsibilities. In particular, WordPress remains responsible for assigning appropriate permissions to authenticated users, and also for all other users configured on WordPress and that are not managed centrally on Keycloak.

Prerequisites

We will assume that the WordPress instance is properly configured on mywebsite.com and is accessible over HTTPS, and that KeyCloak is properly configured on auth.mywebsite.com, and is accessible over HTTPS, and that the TLS certificates are valid and mutually trusted by their respective clients on both sites.

Create a Dedicated Keycloak Realm

Keycloak organizes identities, clients, authentication policies, and sessions into logical security domains called realms. Each realm maintains its own users, clients, groups, roles, and authentication configuration.

For this example, we will create a dedicated realm called: mywebsite

This can be done on Keycloak, by logging in to https://auth.mywebsite.com as an admin, then selecting “Create realm” from the realm selector at the top of the administration interface, then chosing the name for the realm.

That will create a new realm at: https://auth.mywebsite.com/realms/mywebsite

This URL is important because it identifies the authority issuing the OpenID Connect tokens.

Generally speaking, a dedicated realm is useful when an organization requires independent identity policies, user administration, or application access. at the same time, realm separation also introduces administrative overhead. For organizations already maintaining one realm for multiple applications, reusing that realm may be preferable. A realm should represent an intentional identity-management boundary, not necessarily one individual application.

Configure Basic Realm Settings

Now Let’s configure the new realm’s basic authentication policies.

Configuring realm login options

From Realm settings, select the login tab,

SettingRecommendation
User registrationDisabled
Forgot passwordEnabled after configuring email
Remember meBased on organizational policy
Login with emailEnabled
Verify emailEnabled
Duplicate emailsDisabled

Disabling open registration means accounts must be created by administrators or provisioned through an approved identity-management process.

Email verification is particularly important when email addresses are used to associate identities across different systems.

Configure email

If users need password recovery or email verification, Keycloak must be able to send email.

Select the Email tab in Realm settings.

Configure the SMTP server, sender address, authentication credentials, and TLS settings appropriate for your mail infrastructure.

Use Keycloak’s email test functionality to verify delivery.

Of course, this step is not strictly required to establish the OIDC integration, but it is necessary for a reliable self-service password recovery experience. Obviously, self-service functionality means less headache for system admins.

Configure multifactor authentication

Keycloak supports multiple authentication methods and authentication flows.

Multifactor authentication is not a recommendation. In this age and time, it is a must, especially for accounts with administrative or editorial privileges. Make sure the newly created realm requires an additional authentication factor.

The precise configuration depends on the organization’s requirements, but WebAuthn or time-based one-time passwords are common options.

Configure the required authenticators through Authentication → Required actions and the applicable browser authentication flow.

Do not assume that enabling an authentication method automatically makes it mandatory. Verify the actual authentication flow and test with a dedicated account.

Register WordPress as an OpenID Connect Client

We will now create the Keycloak client representing the WordPress website.

Create the client

In the mywebsite realm:

  1. Navigate to Clients.
  2. Click Create client.
  3. Choose OpenID Connect as the client type.
  4. Enter mywebsite-wordpress as the Client ID.
  5. Enter WordPress - mywebsite.com as the display name.
  6. Continue to the capability configuration.

Configure authentication capabilities

Use the following settings:

SettingValue
Client authenticationOn
AuthorizationOff
Standard flowOn
Implicit flowOff
Direct access grantsOff
Service accounts rolesOff

Enabling Client authentication creates a confidential OIDC client.

A confidential client authenticates itself when communicating with the token endpoint. This is appropriate because WordPress executes server-side PHP code and can securely store a client secret, provided the server itself is properly protected.

Standard flow enables the Authorization Code Flow.

We do not need Implicit Flow, password-based Direct Access Grants, or client service accounts for this integration.

Configure the client URLs

Configure the following values:

FieldValue
Root URLhttps://mywebsite.com
Home URLhttps://mywebsite.com/
Valid Redirect URIshttps://mywebsite.com/wp-admin/admin-ajax.php?action=openid-connect-authorize
Web OriginsLeave empty initially

The redirect URI is particularly important.

After authenticating the user, Keycloak redirects the browser to the callback URL registered by the WordPress plugin.

The default callback is:

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

Keycloak compares the requested redirect URI against the client’s configured allowlist.

An incorrect URI will cause authentication to fail with an error such as:

Invalid redirect uri

Avoid broad wildcard redirect rules such as:

https://mywebsite.com/*

An exact callback URL is more restrictive and easier to audit.

The Web Origins setting is not generally needed for the server-side authorization code exchange used here. It should not be confused with the Valid Redirect URIs setting.

Save the client configuration.

Obtain the client secret

Open the client’s Credentials tab.

Keycloak generates a client secret for confidential clients.

Copy the secret (to the clipboard), or store it securely in a password manager. We will need it when configuring WordPress.

Verify client scopes

Open the client’s Client scopes tab.

Make sure the client has access to the standard OIDC scopes:

  • openid — Enables OpenID Connect authentication.
  • profile — Provides standard user profile information.
  • email — Provides email-related claims.

The plugin will request these scopes explicitly. Keycloak must be configured to permit them.

For this tutorial, we do not need additional custom scopes or roles in the issued tokens.

Create a Test User in Keycloak

Before configuring WordPress, create a dedicated test user.

In the mywebsite realm:

  1. Navigate to Users.
  2. Click Add user.
  3. Enter a username, such as sso-test.
  4. Provide a valid email address.
  5. Set the user’s first and last names.
  6. Save the user.

Open the user’s Credentials tab and configure a password.

If appropriate, enable the requirement to change the password at first login.

Ensure the account is enabled and satisfies any required authentication actions.

Using a separate test account helps distinguish problems in the identity provider from account-mapping problems involving existing WordPress administrators.

Install OpenID Connect Generic Client in WordPress

We are now ready to configure WordPress.

The plugin is available through the official WordPress plugin repository:

After installing and activation it, the configuration page should be accessible under:

Settings → OpenID Connect Client

The exact menu wording may vary slightly across releases.

Obtain the Keycloak OpenID Connect Endpoints

Keycloak publishes its OpenID Connect configuration through a standardized discovery endpoint.

For our realm, the discovery URL is:

https://auth.mywebsite.com/realms/mywebsite/.well-known/openid-configuration

Open the URL in your browser.

The endpoint returns a JSON document describing the realm’s authentication endpoints and supported capabilities.

From a terminal, you can inspect the relevant values using curl and jq:

curl -fsSL \
  'https://auth.mywebsite.com/realms/mywebsite/.well-known/openid-configuration' \
  | jq '{
      issuer,
      authorization_endpoint,
      token_endpoint,
      userinfo_endpoint,
      end_session_endpoint,
      jwks_uri
    }'

The expected endpoints for this environment are:

PurposeEndpoint
Issuerhttps://auth.mywebsite.com/realms/mywebsite
Authorization/realms/mywebsite/protocol/openid-connect/auth
Token/realms/mywebsite/protocol/openid-connect/token
UserInfo/realms/mywebsite/protocol/openid-connect/userinfo
Logout/realms/mywebsite/protocol/openid-connect/logout
JWKS/realms/mywebsite/protocol/openid-connect/certs

The relative paths in the table use https://auth.mywebsite.com as their base.

It is preferable to retrieve the values from Keycloak’s discovery document rather than manually constructing URLs, especially in deployments with reverse proxies or nonstandard path configurations.

Configure the WordPress Plugin

Navigate to Settings → OpenID Connect Client.

The plugin includes several configuration sections. We will configure the client identity, authentication endpoints, user mapping, and login behavior.

Configure client credentials

Enter the following values:

Plugin settingValue
Client IDmywebsite-wordpress
Client Secret KeySecret generated by Keycloak
OpenID Scopeopenid profile email

The Client ID must match the identifier registered in Keycloak.

Do not add offline_access unless the application specifically requires offline tokens and the implications of long-lived credentials have been evaluated.

Configure the endpoints

Set the following values:

Login Endpoint URL

https://auth.mywebsite.com/realms/mywebsite/protocol/openid-connect/auth

Userinfo Endpoint URL

https://auth.mywebsite.com/realms/mywebsite/protocol/openid-connect/userinfo

Token Validation Endpoint URL

https://auth.mywebsite.com/realms/mywebsite/protocol/openid-connect/token

Despite the plugin’s field name, this is the OAuth token endpoint used to exchange authorization codes for tokens.

End Session Endpoint URL

https://auth.mywebsite.com/realms/mywebsite/protocol/openid-connect/logout

JWKS URI

https://auth.mywebsite.com/realms/mywebsite/protocol/openid-connect/certs

Issuer

https://auth.mywebsite.com/realms/mywebsite

The JWKS endpoint provides the public cryptographic keys used to verify signed identity tokens.

The Issuer setting specifies which identity provider is expected to have issued the tokens.

Both values should match the corresponding fields published in Keycloak’s discovery document.

Important: Recent versions of the plugin support explicit issuer configuration and JWT signature validation using JWKS. These checks should be correctly configured and verified before using the integration in production.

Configure user information mapping

The plugin needs to determine which WordPress user corresponds to a successfully authenticated Keycloak identity.

For a new installation, the following settings are a useful starting point:

SettingValue
Identity Keysub
Nickname Keypreferred_username
Email Formatting{email}
Display Name Formatting{given_name} {family_name}

The sub claim is the OpenID Connect subject identifier. It is intended to provide a stable identifier for a user within the issuer’s identity namespace.

Unlike an email address or username, it is not normally changed as part of ordinary user profile updates.

This makes it a good choice for identifying external identities over time.

However, the selected Identity Key and account-linking behavior should be tested carefully, especially when integrating an existing WordPress user database.

Changing the identity key after accounts have already been linked can break existing associations.

Configure login behavior

For the initial deployment, choose:

Login Type: Login Button

This adds an OpenID Connect authentication option to the WordPress login form.

It allows administrators to test SSO without immediately redirecting every login attempt to Keycloak.

Once the integration has been thoroughly tested, the plugin can optionally be switched to automatic SSO login.

I recommend retaining button mode initially because it provides a simpler recovery path if the identity provider becomes unavailable.

Configure account provisioning

Two plugin options deserve particular attention:

Create user if does not exist

When enabled, the plugin can create a local WordPress account after successful OIDC authentication.

For a controlled organization website, I recommend keeping this disabled until the intended onboarding policy has been established.

For the first test, you can enable it temporarily to confirm that new accounts are provisioned correctly, provided the test realm’s access is tightly controlled.

New users are normally created with the WordPress Subscriber role unless another customization changes this behavior.

Link Existing Users

This option allows existing WordPress users to be linked to authenticated external identities.

It can simplify migrations, but it introduces an account-takeover risk if identity matching is not sufficiently trustworthy.

Do not enable automatic linking simply because two accounts share the same email address. Ensure that email ownership has been verified and that the organization has a reliable identity-matching process.

For production deployments, user provisioning and account linking should follow an explicit organizational policy.

Save the settings.

Test the Authentication Flow

At this point, the basic integration should be configured.

Keep your existing administrator session open in one browser window.

Open a separate private or incognito browser window and navigate to:

https://mywebsite.com/wp-login.php

Click the OpenID Connect login button.

The browser should redirect to Keycloak.

Authenticate using the test user created earlier.

After successful authentication, Keycloak redirects the browser to WordPress.

WordPress then processes the authentication response and attempts to find or create the corresponding user account according to the plugin configuration.

For the first test, verify:

  1. The browser reaches the correct Keycloak realm.
  2. Keycloak successfully authenticates the user.
  3. The browser returns to the registered WordPress callback URL.
  4. WordPress accepts the identity token.
  5. The account is linked or created as intended.
  6. The authenticated user receives the correct WordPress role.

A successful redirect alone is not sufficient to prove that the integration is secure.

Also verify that a newly created user cannot access administrative functionality beyond their assigned role.

Testing logout

Log out of WordPress and observe the behavior.

Depending on the plugin’s logout settings, WordPress may also initiate logout at Keycloak.

Test whether the browser still has an active Keycloak session and whether logging in again requires credentials.

WordPress logout and Keycloak logout are separate session-management operations. Their behavior should be verified rather than assumed.

Secure the Integration for Production

Authentication is a security-critical function. A working SSO integration is only the starting point.

The following controls are particularly important.

Make sure the scheme is HTTPS

Both WordPress and Keycloak must use valid HTTPS certificates.

Do not disable TLS certificate verification to make the integration work.

If WordPress cannot establish a trusted TLS connection to Keycloak, correct the certificate or certificate-authority configuration.

Protect the client secret

The client secret grants WordPress the ability to authenticate as the registered OIDC client.

Store it outside the public web root and never include it in version-controlled configuration files.

The plugin supports configuration through PHP constants. For server-managed deployments, this provides a useful alternative to entering the secret through the WordPress administration interface.

In PHP-FPM environments, additional configuration may be required because environment variables are not always forwarded to worker processes.

Do not commit the actual secret to Git.

Validate identity tokens

Configure the JWKS endpoint and expected issuer.

The application should validate the identity token’s signature, issuer, intended audience, expiration, and other required OIDC properties.

The plugin’s recent security releases introduced stronger token-validation controls. Using an older release or leaving relevant validation settings incomplete can undermine the authentication model.

Use least-privilege WordPress roles

Successful Keycloak authentication should not automatically grant WordPress administrative privileges.

Authentication answers the question:

Who is this user?

Authorization answers a different question:

What is this user permitted to do?

Keep these responsibilities separate.

Assign WordPress roles based on organizational needs and use explicit, reviewed mechanisms if role synchronization from Keycloak is required.

Enforce strong authentication in Keycloak

For privileged users, consider requiring MFA.

Administrative accounts should use stronger authentication policies than ordinary low-privilege accounts.

Also protect the Keycloak server. Add brute-force protection, session lifetimes, login event logging, and account recovery settings.

Keep an administrative recovery procedure

An identity provider outage or configuration mistake can prevent administrators from authenticating.

Retain a documented recovery mechanism, such as an emergency WordPress administrator account and SSH access with WP-CLI.

If automatic SSO redirection is eventually enabled, test the recovery procedure before relying on it.

Keep software updated

Maintain current, security-supported versions of WordPress, the OIDC plugin, Keycloak, PHP, and the underlying operating system.

Authentication libraries are particularly sensitive to vulnerabilities involving token validation, identity confusion, redirects, and account linking.

After applying updates, perform a basic SSO regression test.

Verifying the Configuration from the Command Line

For administrators comfortable with the command line, several checks can help confirm the configuration.

Check the discovery endpoint

curl -fsSL \
  'https://auth.mywebsite.com/realms/mywebsite/.well-known/openid-configuration' \
  | jq .

A valid response should contain the issuer and OIDC endpoints.

Check the signing keys endpoint

curl -fsSL \
  'https://auth.mywebsite.com/realms/mywebsite/protocol/openid-connect/certs' \
  | jq '.keys[] | {kid, kty, alg, use}'

This should return information about the public keys Keycloak makes available for token verification.

The private signing keys must never be exposed through this endpoint.

Verify the WordPress plugin

From the WordPress installation directory:

wp plugin status daggerhart-openid-connect-generic

Inspect WordPress users

wp user list \
  --fields=ID,user_login,user_email,roles

This is useful for confirming whether accounts were created during testing and which permissions were assigned to them.

Be careful when collecting troubleshooting logs. Authorization codes, tokens, cookies, and client secrets should not be included in publicly shared diagnostic material.

14. Extending the Integration

Once the basic SSO integration works, Keycloak can provide a common identity system for additional applications.

For example, the same realm could serve:

  • WordPress websites.
  • Odoo installations.
  • Internal web applications.
  • Collaboration platforms.
  • Custom applications supporting OpenID Connect.

Each application should receive its own client registration, credentials, and redirect URI allowlist.

Avoid sharing one confidential client secret across multiple independent applications.

A centralized identity provider also creates opportunities to standardize authentication policies, MFA requirements, account deactivation, and audit logging.

However, it introduces a shared dependency. If Keycloak becomes unavailable, applications relying on it may be unable to authenticate new sessions.

For production environments, Keycloak availability, backups, monitoring, security patching, and disaster recovery should be treated as essential infrastructure responsibilities.

Conclusion

Integrating WordPress with Keycloak through OpenID Connect provides a practical way to centralize authentication without depending on a proprietary identity service or a paid WordPress SSO plugin.

The OpenID Connect Generic Client plugin supports the Authorization Code Flow, standard identity claims, and cryptographic token verification using an identity provider’s public keys.

The essential steps are straightforward: establish a Keycloak realm, register WordPress as a confidential client, configure the OIDC endpoints, and define how authenticated identities map to WordPress accounts.

The more important engineering decisions concern security and operations: restrictive redirect URIs, validated identity tokens, controlled account provisioning, least-privilege roles, strong authentication, and reliable recovery procedures.

For organizations already operating self-hosted infrastructure, this integration is another useful building block toward managing their own digital identity services.

It allows organizations to retain control over their identity infrastructure while taking advantage of standardized, interoperable authentication protocols.


References

  1. Keycloak — Server Administration Guide
  2. OpenID Connect Generic Client — WordPress Plugin
  3. OpenID Connect Generic Client — GitHub Repository
  4. OpenID Connect Generic Client — Configuration Documentation
  5. OpenID Connect Generic Client — Releases and Security Changes
  6. OpenID Connect Core 1.0 Specification
  7. RFC 6749 — The OAuth 2.0 Authorization Framework

Leave a Reply