This guide shows how to integrate Keycloak (as Identity Provider / IdP) with WordPress (as Service Provider / SP) using the miniOrange SAML Single Sign-On plugin. It’s written to be shared with teams and includes prerequisites, exact steps, validation, and troubleshooting.

---

0) Overview & Flow

What you’ll build: Users log in to WordPress via Keycloak. WordPress trusts assertions issued by Keycloak over SAML 2.0.

SAML Login Flow (high level):

User → WordPress (SP) → [Redirect] → Keycloak (IdP) → [Authenticate] → SAML Response → WordPress (SP) → User logged in

---

1) Prerequisites

• WordPress site with admin access.
• HTTPS enabled on WordPress (strongly recommended for SAML).
• Keycloak admin access to the correct Realm.
• A test user in Keycloak with valid email, firstName, lastName.
• Install and activate the miniOrange SAML Single Sign-On – SAML SSO Login plugin in WordPress.
  • WP Admin → Plugins → Add New → search “SAML Single Sign On – SAML SSO Login (miniOrange)” → Install → Activate.
• Optional (if you plan SLO or role mappings): appropriate plugin edition that supports those features.

Tip: If WordPress is behind a proxy/load balancer, ensure correct HTTPS offload and Site URL/Home URL definitions.

---

2) Collect WordPress SP (Service Provider) Metadata

In WordPress Admin:

1. Go to miniOrange SAML SSO → Service Provider (SP) Metadata.
2. Copy the values displayed for your site. You’ll paste these into Keycloak:
   • SP Entity ID / Issuer
   • ACS (Assertion Consumer Service) URL
   • (Optional) SLO (Single Logout) URL if you plan to enable SLO
3. Keep this tab open; you’ll need these exact values.

Note: These URLs are generated for your exact site domain. Use them as-is (watch http vs https and trailing slashes).

---

3) Create a SAML Client in Keycloak (WordPress = SP)

In Keycloak Admin Console (select your Realm):

1. Clients → Create (or Create client in newer UI).
2. Client type / Protocol: SAML.
3. Client ID: paste the SP Entity ID / Issuer from WordPress.
4. Continue / Save, then configure:
   • Valid Redirect URIs: paste the ACS URL from WordPress (exact match).
   • Base URL / Root URL: optional; you may set to your WordPress base URL.
   • NameID Format: choose Email (recommended). Optionally enable Force NameID format.
   • Client Signature Required: OFF for simplest setup (you can enable later if you want signed AuthnRequests and manage certificates accordingly).
   • Fine Grain SAML Endpoints (Advanced):
     • Assertion Consumer Service POST Binding URL: set to your ACS URL.
     • Logout Service Redirect Binding URL: set to your WordPress SLO URL if enabling SLO.
5. Save.

Alternative (Stricter Security): Enable signatures/encryption (IdP signing, SP signing, encrypted assertions). If you do, exchange and upload the correct certificates into the plugin.

---

4) Send User Attributes in SAML (Keycloak Mappers)

You’ll want to pass at least email, firstName, and lastName so WordPress can create/update user profiles.

In Keycloak → Clients → [your SAML client] → Mappers:

1. Click Add predefined (or Add builtin). Add:
   • X500 email
   • X500 givenName
   • X500 surname
2. If needed, open each mapper and set SAML Attribute Name to match what you prefer in WordPress (e.g., email, firstName, lastName).
3. (Optional) Add a Role list or Group list mapper if you plan to map Keycloak roles/groups to WordPress roles.
4. (Optional) Add username mapper: By configuration → User Property mapping username → SAML attribute username.

---

5) Export IdP Metadata from Keycloak

You can provide WordPress the IdP metadata via URL or XML file:

• Realm Settings → General → Endpoints → “SAML 2.0 Identity Provider Metadata”.
  • Click to open the XML and download it, or copy the metadata URL.

Keep this URL/XML handy for the next step.

---

6) Configure WordPress (SP) to Trust Keycloak (IdP)

In WordPress Admin → miniOrange SAML SSO → Service Provider Setup:

1. Option A – By Metadata URL:
   • Paste the Keycloak IdP Metadata URL and Fetch.
2. Option B – By Metadata XML:
   • Upload or paste the Keycloak IdP metadata XML content.
3. If you choose Manual configuration:
   • IdP Entity ID/Issuer – from the XML
   • SAML Login URL – from the XML (HTTP-Redirect or HTTP-POST SSO endpoint)
   • X.509 Certificate – IdP signing certificate from the XML
4. Save the IdP configuration.
5. Click Test Configuration in the plugin to initiate a live SSO test.
   • You will be redirected to Keycloak, authenticate, and see a result with attributes returned.

If the test shows attributes (email, firstName, lastName), proceed. If not, revisit Keycloak mappers.

---

7) Attribute & Role Mapping in WordPress

Open miniOrange SAML SSO → Attribute/Role Mapping:

7.1 Attribute Mapping

• In the free edition, NameID typically becomes the WordPress username/email. Set NameID Format = Email in Keycloak for best results.
• In higher editions, map attributes explicitly:
  • Email → attribute email
  • First Name → attribute firstName
  • Last Name → attribute lastName
• Use the exact attribute keys as shown by Test Configuration.

7.2 Role Mapping (Optional)

• Set a Default Role for new SSO users.
• If supported by your plugin edition, map Keycloak Roles/Groups (e.g., SAML attribute Roles or groups) to WordPress roles (Subscriber, Editor, Administrator, etc.).

---

8) Decide How Users Start SSO

• Show SSO button on wp-login.php (available in free edition).
• Auto-redirect all unauthenticated users to Keycloak (redirection features typically require Standard+ editions). Configure under Redirection & SSO Links.
• Optionally add an SSO link/button in your site menus.

---

9) Single Logout (SLO) — Optional

If your edition supports SLO:

1. WordPress (SP) SLO URL is in SP Metadata. Make sure it’s configured in Keycloak (Logout Service Redirect Binding URL).
2. In the plugin, set IdP Logout URL (from Keycloak metadata). Enable SLO under plugin’s advanced settings.
3. Test that logging out of WordPress also logs out of Keycloak (and vice versa, depending on flow supported).

SLO is optional; coordinate expectations with stakeholders, as browsers and inter-application SLO behaviors vary.

---

10) User Provisioning & Matching Strategy

• Just-In-Time (JIT) Provisioning: New WordPress user accounts can be created automatically on first successful SSO if enabled.
• User Matching: Typically by email. Ensure Keycloak delivers a verified email. Avoid collisions: if an existing local WP user has the same email, confirm your plugin setting for account linking/auto-creation.

---

11) End‑to‑End Validation Checklist

1. Logout of WordPress (and Keycloak).
2. Visit https://YOUR-SITE/wp-login.php and click the SSO button (or open any protected page if auto-redirect is enabled).
3. Authenticate on Keycloak with the test user.
4. Confirm in WordPress:
   • You are logged in.
   • Your username/email is correct.
   • First/last name populated (if mapped).
   • Role matches your mapping/default role.
5. (Optional) Test SLO: logout in WordPress and verify session handling with Keycloak.

---

12) Troubleshooting (Common Errors)

• Invalid SAML Response / Signature Error
  • If you left Client Signature Required = OFF in Keycloak, keep it off in SP settings. If you enable signatures, you must configure certificates on both sides accordingly.
  • Verify IdP certificate in the WP plugin matches the Keycloak realm’s signing key.
• Login Loop or 404 on Return
  • ACS URL and Valid Redirect URIs must exactly match (protocol, host, path, trailing slash).
  • Ensure site URL is correct behind proxies/load balancers.
• Attributes Missing in Test
  • Re-check Keycloak mappers; ensure X500 email/givenName/surname are added and enabled.
  • Verify the test user actually has email, firstName, lastName in Keycloak.
• User Not Created
  • Enable JIT provisioning and confirm attribute mapping for email/username.
  • Resolve email collisions with existing local users.
• SLO Not Working
  • Confirm Logout endpoints on both sides and that your plugin edition supports SLO.
  • Browser/session peculiarities can affect global logout—align behavior expectations.

---

13) Security Hardening (Recommended)

• Always use HTTPS for WordPress and Keycloak endpoints.
• Clock sync (NTP) across servers to avoid SAML assertion expiry issues.
• Limit audience/recipient conditions if your plugin supports it.
• Enable signed and/or encrypted assertions once the basic flow works and you’ve exchanged certificates.
• Rotate signing certificates in Keycloak on a schedule; track validity and update the SP (plugin) certificate promptly.
• Restrict who can log in (by group/role filters in Keycloak + role mapping in WordPress).

---

14) Maintenance & Operations

• Document current settings: screenshots of Keycloak client, WP plugin config, and mapping tables.
• Backup plugin config before updates.
• Monitor login success/failure rates after rollout.
• Plan key rotation: keep a calendar reminder for Keycloak realm keys; update WP plugin certificate as needed.
• Regression test after WordPress/plugin updates.

---

15) Rollback Plan

• Keep local WordPress login accessible (e.g., a separate admin account with password) in case SSO misconfiguration blocks access.
• If SSO breaks:
  1. Temporarily disable auto-redirect (if enabled) using WP-CLI or database access.
  2. Fix configuration; re-test in staging.
  3. Re-enable SSO features once validated.

---

16) Appendix A — Field Name Glossary

Location	Field	What to Use
WP → SP Metadata	SP Entity ID / Issuer	Paste into Keycloak Client ID
WP → SP Metadata	ACS URL	Paste into Keycloak Valid Redirect URIs and ACS POST Binding URL
WP → SP Metadata	SLO URL (optional)	Paste into Keycloak Logout Service Redirect Binding URL
Keycloak → Realm Settings → Endpoints	SAML 2.0 IdP Metadata	Provide to WP (as URL or XML)
Keycloak Client → Settings	NameID Format	Email (recommended)
Keycloak Client → Settings	Client Signature Required	OFF for simplest setup; enable later if desired
Keycloak Client → Mappers	X500 email/givenName/surname	Supplies email/firstName/lastName to WP

---

17) Appendix B — Example Attribute Mapping

In Keycloak (Mappers):

• X500 email → SAML Attribute Name: email
• X500 givenName → SAML Attribute Name: firstName
• X500 surname → SAML Attribute Name: lastName
• (Optional) User Property → username → SAML Attribute Name: username
• (Optional) Role list / Group list → SAML Attribute Name: Roles or groups

In WordPress (Attribute Mapping):

• Email: email (or NameID if using free edition)
• First Name: firstName
• Last Name: lastName
• (Optional) Map Roles/groups to WordPress roles (edition-dependent)

---