Skip to content

WordPress

This comprehensive guide walks you through integrating WordPress with Keycloak for single sign-on (SSO) authentication. WordPress offers multiple plugin options for OAuth/OpenID Connect integration, each with different strengths and use cases.

Overview

Section titled “Overview”

WordPress Keycloak integration enables:

  • Single Sign-On (SSO) - Users authenticate once across all systems
  • Centralized User Management - Manage users in Keycloak, not WordPress
  • Role-Based Access Control - Map Keycloak roles to WordPress roles
  • Enhanced Security - Leverage Keycloak’s advanced security features
  • Unified User Experience - Seamless authentication across applications

Plugin Options

Section titled “Plugin Options”
Section titled “1. miniOrange OAuth Single Sign On (Recommended for Enterprise)”

Best for: Enterprise environments requiring comprehensive features and professional support.

Key Features:

  • ✅ Native Keycloak support with pre-configured templates
  • ✅ Advanced role-based access control (RBAC)
  • ✅ 24/7 professional support
  • ✅ Unlimited users in free version
  • ✅ Multiple identity providers support

Installation:

# Via WordPress Admin
# 1. Go to Plugins > Add New
# 2. Search for "OAuth Single Sign On – SSO (OAuth Client)"
# 3. Install and activate

# Via WP-CLI
wp plugin install miniorange-login-with-eve-online-google-facebook --activate
Section titled “2. OpenID Connect Generic Client (Recommended for Developers)”

Best for: Developers who want a lightweight, free solution with full control.

Key Features:

  • ✅ Completely free with no premium limitations
  • ✅ Clean, minimalist implementation
  • ✅ Active open-source development
  • ✅ Developer-friendly with customization hooks
  • ✅ Reliable and battle-tested

Installation:

# Via WordPress Admin
# 1. Go to Plugins > Add New
# 2. Search for "OpenID Connect Generic Client"
# 3. Install and activate

# Via WP-CLI
wp plugin install openid-connect-generic --activate

3. WP OAuth Server (For Complex Architectures)

Section titled “3. WP OAuth Server (For Complex Architectures)”

Best for: Complex multi-system architectures where WordPress needs to act as an identity provider.

Key Features:

  • ✅ WordPress as OAuth provider
  • ✅ Bidirectional authentication with Keycloak
  • ✅ Federation scenarios
  • ✅ Advanced integration patterns

Quick Start

Section titled “Quick Start”

Step 1: Create Application in Skycloak

Section titled “Step 1: Create Application in Skycloak”
  1. In Skycloak, navigate to your cluster → Applications
  2. Click Create Application and configure:
    • Name: wordpress-sso (or your preferred name)
    • Type: Confidential
    • Grant Types: Authorization Code + Refresh Token
    • Redirect URIs: You’ll add these in Step 2 after configuring your WordPress plugin
  3. After creation, copy the Client ID and Client Secret — you’ll need these for WordPress

Step 2: Configure WordPress Plugin

Section titled “Step 2: Configure WordPress Plugin”

Choose your plugin and follow the specific configuration:

miniOrange Configuration:

  1. Go to Settings → miniOrange OAuth → Configure OAuth
  2. Select “Keycloak” from the application dropdown
  3. Enter your configuration:
    • Client ID: Your Keycloak client ID
    • Client Secret: From Keycloak credentials tab
    • Scope: openid email profile roles
  4. Configure endpoints (auto-populated for Keycloak)
  5. Set up attribute mapping:
    • Username: preferred_username
    • Email: email
    • First Name: given_name
    • Last Name: family_name
  6. Configure role mapping in the Role Mapping tab

Redirect URI for Keycloak:

https://your-site.com/wp-content/plugins/miniorange-login-with-eve-online-google-facebook/mo_oauth_callback.php

Add this URL to your application’s Redirect URIs in Skycloak’s Applications page.

Step 3: Test Integration

Section titled “Step 3: Test Integration”
  1. Logout from WordPress completely
  2. Clear browser cache and cookies
  3. Navigate to your WordPress login page
  4. Click the SSO login button
  5. Authenticate in Keycloak
  6. Verify you’re redirected back and logged into WordPress

Role Mapping

Section titled “Role Mapping”

Keycloak Configuration

Section titled “Keycloak Configuration”

Create role mappers in your Keycloak client:

  1. Go to Clients → Your Client → Mappers → Create
  2. Configure the mapper:
    • Name: wordpress-roles
    • Mapper Type: User Realm Role
    • Token Claim Name: roles
    • Add to ID token: ON
    • Add to access token: ON

WordPress Role Mapping

Section titled “WordPress Role Mapping”

miniOrange Plugin:

Role mapping is handled through the plugin’s UI:

  1. Go to Settings → miniOrange OAuth → Role Mapping
  2. Map Keycloak roles to WordPress roles:
    • admin → Administrator
    • editor → Editor
    • author → Author
    • user → Subscriber

Login Experience

Section titled “Login Experience”

Automatic Integration

Section titled “Automatic Integration”

Both plugins automatically add SSO login buttons to the WordPress login page. No additional configuration is needed.

Custom Login Buttons

Section titled “Custom Login Buttons”

Shortcode Integration:

Add SSO login to any page or post:

<!-- OpenID Connect Generic -->
[openid_connect_generic_login_button]

<!-- miniOrange (use plugin's shortcode generator) -->
[miniorange_sso_login]

Custom Styling

Section titled “Custom Styling”

Style your SSO login buttons:

.openid-connect-login-button {
    background-color: #007cba;
    color: white;
    padding: 10px 20px;
    text-decoration: none;
    border-radius: 5px;
    display: inline-block;
    margin: 10px 0;
    font-weight: bold;
}

.openid-connect-login-button:hover {
    background-color: #005a87;
    color: white;
}

Security Best Practices

Section titled “Security Best Practices”

SSL/TLS Configuration

Section titled “SSL/TLS Configuration”
// Add to wp-config.php
define('FORCE_SSL_ADMIN', true);
define('FORCE_SSL_LOGIN', true);

// Enable HSTS (in .htaccess or server config)
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"

Secure Credential Storage

Section titled “Secure Credential Storage”
// Use environment variables
define('OPENID_CONNECT_CLIENT_SECRET', $_ENV['KEYCLOAK_CLIENT_SECRET']);

// Or use wp-config.php constants (not database)
define('OPENID_CONNECT_CLIENT_SECRET', 'your-secret-here');

Optional: Disable WordPress Login

Section titled “Optional: Disable WordPress Login”
// Force SSO-only authentication
add_filter('wp_authenticate_user', function($user) {
    if (!is_wp_error($user) && !current_user_can('manage_options')) {
        return new WP_Error('sso_only', 'Please use SSO to login');
    }
    return $user;
}, 10, 1);

Token Security

Section titled “Token Security”
  • Use short access token lifetimes (15-30 minutes)
  • Implement refresh token rotation in Keycloak
  • Enable token validation and signature verification
  • Monitor for suspicious authentication patterns

Troubleshooting

Section titled “Troubleshooting”

Common Issues

Section titled “Common Issues”

“Invalid Client” Error:

  • ✅ Verify client ID and secret are correct
  • ✅ Check client authentication is enabled in Keycloak
  • ✅ Ensure no extra spaces in credentials
  • ✅ Verify client exists in the correct realm
  • ✅ Check client is not disabled

Debug Steps:

# Test client credentials
curl -X POST \
  https://your-keycloak/realms/your-realm/protocol/openid-connect/token \
  -d "grant_type=client_credentials" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret"

Debug Logging

Section titled “Debug Logging”

Enable debug logging to troubleshoot issues:

// Add to wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

// For OpenID Connect Generic plugin
define('OPENID_CONNECT_GENERIC_LOG', true);

Check logs at /wp-content/debug.log for detailed error information.

Production Deployment

Section titled “Production Deployment”

Pre-Deployment Checklist

Section titled “Pre-Deployment Checklist”

Security Review:

  • ✅ All credentials stored securely (not in database)
  • ✅ SSL/TLS properly configured
  • ✅ Role mappings audited and tested
  • ✅ Redirect URIs restricted to necessary paths
  • ✅ Security headers enabled
  • ✅ WordPress and plugins updated
  • ✅ Monitoring and alerting configured
// Security hardening checklist
define('FORCE_SSL_ADMIN', true);
define('FORCE_SSL_LOGIN', true);
define('DISALLOW_FILE_EDIT', true);
define('WP_DEBUG', false);
define('WP_DEBUG_LOG', false);
define('WP_DEBUG_DISPLAY', false);

Advanced Configuration

Section titled “Advanced Configuration”

Multi-site WordPress

Section titled “Multi-site WordPress”

For WordPress multisite installations:

// Network-wide SSO configuration
define('OPENID_CONNECT_GENERIC_SETTINGS', serialize([
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret',
    'scope' => 'openid email profile',
    // ... other settings
]));

// Per-site role mapping
add_filter('openid_connect_generic_user_creation', function($user_data, $claims) {
    $site_id = get_current_blog_id();
    
    // Site-specific role mapping logic
    switch ($site_id) {
        case 1:
            $user_data['role'] = 'administrator';
            break;
        case 2:
            $user_data['role'] = 'editor';
            break;
        default:
            $user_data['role'] = 'subscriber';
    }
    
    return $user_data;
}, 10, 2);

WooCommerce Integration

Section titled “WooCommerce Integration”

For WooCommerce stores:

// Map Keycloak roles to WooCommerce roles
add_action('openid-connect-generic-update-user-using-current-claim', function($user, $user_claim) {
    if (!empty($user_claim['roles'])) {
        $roles = $user_claim['roles'];
        
        if (in_array('shop-manager', $roles)) {
            $user->set_role('shop_manager');
        } elseif (in_array('customer', $roles)) {
            $user->set_role('customer');
        }
    }
}, 10, 2);

// Sync customer data
add_action('openid-connect-generic-update-user-using-current-claim', function($user, $user_claim) {
    if (!empty($user_claim['billing_address'])) {
        update_user_meta($user->ID, 'billing_address_1', $user_claim['billing_address']['street']);
        update_user_meta($user->ID, 'billing_city', $user_claim['billing_address']['city']);
        // ... other billing fields
    }
}, 10, 2);

Support and Resources

Section titled “Support and Resources”

Documentation

Section titled “Documentation”

Professional Support

Section titled “Professional Support”

For enterprise deployments, consider:

  • WordPress VIP support
  • Keycloak Red Hat support
  • miniOrange enterprise support
  • Custom development services
  • Email Skycloak support at support@skycloak.io

Conclusion

Section titled “Conclusion”

WordPress Keycloak integration provides a robust foundation for centralized authentication and user management. Choose the plugin that best fits your needs:

  • miniOrange for enterprise features and support
  • OpenID Connect Generic for developer flexibility and control
  • WP OAuth Server for complex federation scenarios

Follow the security best practices and testing procedures outlined in this guide to ensure a successful production deployment.

© 2026 Skycloak. All Rights Reserved. Design by Yasser SolimanKeycloak™ is a trademark of the Linux Foundation. Skycloak is not affiliated with the Keycloak project.