Identity Provider Configuration: Keycloak

IDP Reference Resources

• Keycloak Server Administration Guide - Creating an OpenID Connect Client
• Keycloak Server Administration OpenID Connect Clients Guide
• Keycloak Securing Apps - Other OpenID Connect Libraries
• Apache APISIX Keycloak OpenID Connect Client Creation

Overview

The settings outline in this guide are a starting point reference of a known working Keycloak OpenID Connect Client configuration for the OpenID Connect Generic plugin. As with all Identity Providers many other configuration options within the platform could effect how these settings work. This setup was performed using the Keycloak on Docker setup with a basic setup and creating a new realm, not using the default Master realm.

Keycloak OpenID Connect Client Configuration

A. Create the OpenID Connect Client

1. The first step is to login to the Keycloak Administration Console and switch to the realm you will use for authentication. After logging in navigate to "Clients", and click "Create".
   
2. Next enter in a "Client ID", this must be a unique ID with no spaces, that will identify the WordPress site that will be authenticating to the Keycloak server. As well as the "Root URL".
   

B. Configure the OpenID Connect Client

1. Configure the client per the screenshot. The key items to be set are: "Access Type" set to "confidential", "Standard Flow Enabled" set to "On", "Direct Access Grants Enabled" set to "Off".
   
2. The additional items to not are the setup of "Root URL", "Valid Redirect URIs", "Base URL", "Admin URL", and "Backchannel Logout Session Required" should be "Off".
   
3. The OpenID Connect Compatibility Modes should be setup to allow Refresh Tokens.
   

C. Setup Client Scopes

Setup the Assigned Default and Assigned Optional Scopes with a minimum of Assigned Scopes being email and profile, others can be included as needed.

WordPress OpenID Connect Generic Plugin Configuration

When setting up the plugin on the WordPress site most of the key client configuration can be found from the Keycloak Realm OpenID Connect configuration endpoint.

Example: https://<keycloak-domain>/auth/realms/<realm-id>/.well-known/openid-configuration

This will provide all of the endpoints needed for configuring the plugin, as well as the supported claims that are the attributes to be used for matching & creating user accounts.

1. Copy the Client Secret from the "Credentials" tab within Keycloak for the configured client. The "Client ID" is what was initial created and listed on the "Settings" tab and the "Client Secret Key" is the "Secret" on the "Credentials" tab.
2. Enter the "Client ID" & "Client Secret Key" into the plugin settings screen.
3. Enter in the "OpenID Scopes" with the recommended list of email profile openid offline_access.
4. Enter in all of the endpoints as found when viewing the client configuration endpoint URL.
5. "Identity Key" work when using email.
6. "Nickname Key" can be configured with preferred_username, name, or sub as they are generally all valid claims. You can confirm these in the client configuration endpoint.
7. "Email Formatting" should work as {email}.
8. "Display Name Formatting" should work as {given_name} {family_name} but confirm these claims exist int eh client configuration endpoint.
9. "Enable Refresh Token" should be checked.

With this setup you should now be able to login with your Keycloak server as the IDP and logout of WordPress & Keycloak resulting with being taken back to the WordPress login screen.