How to add OpenID to WordPress with Keycloak

July 14, 2022 

Adding OpenID to WordPress allows for existing users on a domain to connect without having to manage another account. In this setup, we will be using Keycloak to provide the existing accounts which the OpenID plugin will use.

There are a few plugins for WordPress that allow this functionality, but we will be using OpenID-Connect-Generic by Daggerhart.

Keycloak Client Setup

First step is to create a client in Keycloak. In the Keycloak web UI, create an openid-connect client by going to Clients and click Create.

There are a few settings to take note:

  • Client ID: Whatever is set for this needs to be added to the plugin's client ID
  • Access Type: set to confidential (this will create a new Credentials tab once saved)
  • Valid Redirect URIs: At the bottom of the OpenID Connect Client settings page in WordPress shows the specific redirect uri if you do not wish to use wildcards. The plugin injects parameters which could be an issue with Keycloak so we can use wildcards. For example:*
  • Secret: This is found in the credentials tab after saving with the access type set to confidential

Endpoint Configuration or /auth/realms/{REALM}/.well-known/openid-configuration. These will be used in the next steps.

OpenID Connect - Generic Client Setup

Next, the actual plugin needs to be installed and activated in WordPress. The plugin can be installed like any other plugin by going to Plugins -> Add New. Once this has finished, there will be a new settings page located under Settings -> OpenID Connect Client.

The settings are straightforward and have a nice description under each field to describe the expected values. Most of the setting values needed are found on the Keycloak endpoint page mentioned above.

The main changes needed are as follows:

  • Client ID: The same ID used in the Keycloak client configuration
  • Client Secret Key: This is provided by the Keycloak Credentials tab in the client configuration
  • OpenID Scope: Make sure to add openid. Example: email profile roles openid
  • Login Endpoint URL: Same as authorization_endpoint
  • Userinfo Endpoint URL: Same as userinfo_endpoint
  • Token Validation Endpoint URL: Same as authorization_endpoint
  • End Session Endpoint URL: Same as end_session_endpoint
  • Identify with User Name: Leave unchecked as we want to match identity by e-mail
  • Link Existing Users: Checked as we want to link existing accounts
  • Create user if does not exist: Checked and take note that there seems to be an issue with linking with existing users without this checked. See Issue #249. If you do not wish to create the users, then there seems to be a workaround mentioned using hooks.

Congratulations! There should now be a button at the wp-admin login to redirect to a Keycloak login page. The plugin also has a debug log that can be enabled to help troubleshoot any problems.

Samuli Seppänen
Ricky Cousins
Author archive