Implementing “One-Login” for WordPress with Keycloak (Step-by-Step)

Powered by Nestict Cloud’s Managed Keycloak — https://www.authentication.nestict.africa/ (order at https://cloud.nestict.net)

TL;DR

You’ll: (1) set up a realm and client in Keycloak, (2) install an OIDC/SAML SSO plugin in WordPress, (3) paste a few URLs (issuer, authorize, token, userinfo/end-session), (4) map attributes/roles, and (5) test & enforce SSO. The fastest, modern route is OpenID Connect (OIDC).

Who is this for?

Site owners and admins who want a single, secure login (“1-Login”) across one or more WordPress sites—with MFA, central policy, and role control—without babysitting servers. Nestict Cloud runs Keycloak for you, with SSL, updates, backups, and scaling.

• Service overview: https://www.authentication.nestict.africa/
• Order managed Keycloak: https://cloud.nestict.net

Prerequisites

• A WordPress site with admin access.
• A managed Keycloak instance (e.g., from Nestict Cloud).
• One SSO plugin for WordPress (OIDC preferred; SAML also works).
• HTTPS enabled on your WordPress site.

Recommendation: Choose OIDC unless you specifically need SAML.

Step 1 — Create a Realm in Keycloak

1. Log in to your Keycloak admin console.
2. In the left menu, click Realm selector → Create realm.
3. Name it (e.g., wordpress-prod).
4. In Realm Settings → Login, keep Standard Flow enabled (for OIDC).

Step 2 — Create a Client (OIDC)

1. Go to Clients → Create client.
2. Client type: OpenID Connect.
3. Client ID: wp-mywebsite (any unique name).
4. Name (optional): “WordPress – My Website”.
5. Authentication flow: Standard.
6. Valid Redirect URIs: add your plugin’s callback URL(s), for example:
   • https://your-site.com/wp-login.php?oidc_callback=1
   • If you have multiple environments (staging, multisite), add each domain here.
7. Web Origins: set to + (or specify origin like https://your-site.com).
8. Save.
9. In Credentials, copy the Client Secret (if using a confidential client).

Useful OIDC endpoints (typical Keycloak format):

• Discovery (well-known):
  https://YOUR-KEYCLOAK/realms/YOUR_REALM/.well-known/openid-configuration
• Issuer:
  https://YOUR-KEYCLOAK/realms/YOUR_REALM
• Authorization endpoint:
  https://YOUR-KEYCLOAK/realms/YOUR_REALM/protocol/openid-connect/auth
• Token endpoint:
  https://YOUR-KEYCLOAK/realms/YOUR_REALM/protocol/openid-connect/token
• UserInfo endpoint:
  https://YOUR-KEYCLOAK/realms/YOUR_REALM/protocol/openid-connect/userinfo
• End-Session (logout):
  https://YOUR-KEYCLOAK/realms/YOUR_REALM/protocol/openid-connect/logout
• JWKS (keys):
  https://YOUR-KEYCLOAK/realms/YOUR_REALM/protocol/openid-connect/certs

If you’re on Nestict Cloud, your base will look like:
https://www.authentication.nestict.africa/realms/YOUR_REALM/...

Step 3 — Add Attribute & Role Mappers (Keycloak)

1. In Clients → wp-mywebsite → Client scopes / Mappers, add:
   • email → claim email
   • preferred_username → claim preferred_username (or username)
   • name / given_name / family_name (optional)
2. (Optional) Map Keycloak groups or roles to a custom claim (e.g., wp_roles) so WordPress can auto-assign roles.

Step 4 — Install & Configure the WordPress SSO Plugin

Choose one: an OIDC client plugin (preferred) or a SAML SP plugin. The fields below are common across popular plugins.

For OIDC plugins, provide:

• Issuer/Discovery URL: your realm’s well-known URL
• Client ID and Client Secret (from Keycloak)
• Redirect/Callback URL: paste the plugin’s generated URL into Keycloak → Valid Redirect URIs
• Scopes: openid email profile (typical)
• Login link text / Button placement: customize as preferred
• End-session URL: paste the Keycloak logout endpoint to enable single logout
• User Attribute Mapping:
  • Username: preferred_username (or email)
  • Email: email
  • Display Name: name (or given_name + family_name)
• Auto-create users: enable “create user if not exists”

(Alternative) For SAML plugins, provide:

• IdP Entity ID, SSO URL, SLO URL, Certificate from Keycloak’s IdP metadata
• SP Entity ID & ACS URL from the plugin into the Keycloak client (protocol: SAML)
• Attribute mapping for username, email, roles

Tip: Most OIDC plugins support a Discovery URL—paste it and many fields auto-fill.

Step 5 — Test the Login Flow

1. Log out of WordPress.
2. Click Login with Keycloak (or your custom label).
3. You should be redirected to Keycloak → authenticate → redirected back to WordPress.
4. Confirm the new user is auto-provisioned and assigned the expected WordPress role.
5. Test logout: ensure it also triggers Keycloak logout (and back to WP).

Step 6 — Enforce SSO (Optional but Recommended)

• In the plugin, enable Force Login via SSO (disable local WP passwords for normal users).
• Keep an emergency admin account with a private backdoor URL (many plugins offer bypass login or debug login URL). Store it safely.

Step 7 — Role & Access Design

• In Keycloak, create Groups (e.g., wp_admins, wp_editors, wp_members).
• Map Groups → Token claim (e.g., wp_roles).
• In the WP plugin, map wp_roles → WordPress roles (Administrator, Editor, Author, Subscriber).
• For multi-site: decide if each site uses a separate Keycloak client or one client with multiple redirect URIs.

Step 8 — Security Hardening

• Enforce HTTPS end-to-end (WordPress & Keycloak).
• Enable MFA (TOTP/WebAuthn) in Keycloak for sensitive roles.
• Set short token lifetimes and refresh token policies per your risk profile.
• Turn on brute-force protection and password policies in Keycloak.
• Limit who can self-register (disable if not needed).
• Regularly rotate the client secret and keep WordPress/plugin updated.

Step 9 — Common Troubleshooting

• Invalid redirect_uri: The callback URL must exactly match your Keycloak client’s Valid Redirect URIs.
• Invalid state/nonce: Usually caching or cookies—exclude wp-login.php from reverse-proxy/CDN caching.
• Clock skew: Ensure server times are synced (NTP).
• CORS errors (for headless/custom flows): Add the site origin under Web Origins in Keycloak.
• User not auto-created: Confirm “create user if not exists” is enabled and email/username mapping is correct.
• Logout doesn’t fully end session: Configure the End-Session URL and enable single logout in the plugin.

Multi-Site & Multi-App “One-Login”

• Multiple WordPress sites:
  • Option A: One Keycloak client, many Valid Redirect URIs.
  • Option B: One client per site (clearer audit & per-site secrets).
• Other apps (Nextcloud, Drupal, CRM, etc.): Add more Keycloak clients for each and reuse the same realm/users/policies → true “One-Login”.

Quick Checklist (Copy/Paste)

• Realm created (wordpress-prod)
• OIDC client (wp-mywebsite) with redirect URIs & web origins set
• Client Secret copied to WP plugin
• Discovery/Issuer/Auth/Token/UserInfo/End-Session URLs set in WP
• Attribute & role mappers added (email, preferred_username, name, wp_roles)
• Auto-provisioning on; role mapping tested
• SSO enforced; emergency admin bypass noted
• MFA + password & brute-force policies enabled
• Logout SSO verified

Launch with Nestict Cloud (Managed Keycloak)

Skip the server hassle and focus on your site:

• Start here: https://www.authentication.nestict.africa/
• Order now: https://cloud.nestict.net