Integrating Keycloak with WordPress allows you to offload authentication and authorization to a centralized Identity Provider (IdP), giving you features like Single Sign-On (SSO), Role-Based Access Control (RBAC), and user federation. Below is a step-by-step guide to fully integrate Keycloak and WordPress for both authentication and authorization.
✅ Prerequisites
- A running Keycloak server (on-premises or cloud).
- Admin access to your WordPress site.
- HTTPS enabled on both WordPress and Keycloak (SSO requires secure endpoints).
- A Keycloak realm configured.
🔧 Step-by-Step Integration Guide
Step 1: Install Required Plugin in WordPress
You'll need an OAuth or OpenID Connect plugin. Recommended:
Install:
- Go to
Plugins > Add New
- Search for:
miniOrange OAuth
- Click Install and then Activate
Step 2: Create a New Client in Keycloak
Go to your Keycloak Admin Console
Select your realm
Click on Clients > Create
Set the following:
Click Save
Step 3: Configure Client Settings in Keycloak
On the Settings tab:
Valid Redirect URIs:
https://your-wordpress-site.com/*
Base URL:
Admin URL: (optional)
Web Origins:
On the Credentials tab:
- Copy the Secret – you'll use this in the WordPress plugin.
Step 4: Set up Roles and Mappers in Keycloak (for Authorization)
🔹 Define WordPress Roles in Keycloak:
- Go to your Client →
Roles
- Create roles like:
editor, author, subscriber, etc.
🔹 Add Role Mapper:
Go to Client → Mappers
Click Create
Step 5: Configure miniOrange Plugin in WordPress
- Go to
miniOrange OAuth Client settings in WordPress
- Fill the following:
➤ Identity Provider Settings:
Step 6: Test SSO Login
- Visit
https://your-wordpress-site.com/wp-login.php
- You should now see a “Login with Keycloak” button.
- Clicking it should redirect to Keycloak → authenticate → redirect back to WordPress.
Step 7: Map Keycloak Roles to WordPress Roles (Authorization)
If you're using the premium version, you can:
- Go to
Role Mapping in miniOrange plugin
- Map Keycloak role names (like
editor, subscriber) to WordPress roles
Alternatively, write a custom PHP hook (free option):
add_filter('mo_oauth_map_user_role', 'map_keycloak_roles_to_wp', 10, 2);
function map_keycloak_roles_to_wp($roles, $user) {
if (in_array('editor', $user->roles)) {
$roles[] = 'editor';
} elseif (in_array('subscriber', $user->roles)) {
$roles[] = 'subscriber';
}
return $roles;
}
✅ Optional: Enable Auto-Registration
If the user doesn't exist in WordPress, enable:
Auto Create Users – so Keycloak users are automatically created in WordPress upon first login.
🔐 Optional: Secure WordPress with Only Keycloak Login
- In plugin settings, disable default WP login.
- Redirect all login access to Keycloak SSO.
🧪 Troubleshooting Tips
| Problem | Solution |
| ----------------------- | ----------------------------------------------------- |
| 403 error after login | Check redirect URI and web origin in Keycloak |
| Users not getting roles | Check if role mapper is added in Keycloak |
| No login button | Ensure plugin is activated and properly configured |
| "Invalid client secret" | Make sure WordPress secret matches Keycloak's |
🔄 Flow Diagram (SSO)
User → WP Login → Redirect to Keycloak
→ Keycloak Auth → Redirect back with token
→ WordPress uses token to fetch profile
→ Auto-login or auto-register user
🔚 Summary
| Feature | Handled by |
| --------------------- | ------------------------------------------ |
| Authentication (SSO) | Keycloak + OAuth Plugin |
| Authorization (Roles) | Keycloak Role Mapper + Plugin Role Mapping |
| User Management | Keycloak |
| Auto-provision | WordPress plugin settings |
Would you like me to provide a Docker-based local setup of WordPress + Keycloak for dev testing?