Keycloak Integration with Frappe (v14) - Step-by-Step Guide

Overview

This wiki documents the step-by-step process to install, configure, and integrate Keycloak as an authentication provider with Frappe (v14), including common challenges faced and how they were resolved.

1. Prerequisites

• Frappe/ERPNext v14 installed and running.

• A working Keycloak instance (v26+ recommended).

• Domain: xcel.techfinite.com configured and accessible.

2. Install Keycloak (Bare Metal)

Step 1: Download and Extract

wget https://github.com/keycloak/keycloak/releases/download/26.2.5/keycloak-26.2.5.zip
unzip keycloak-26.2.5.zip
cd keycloak-26.2.5

Step 2: Bootstrap Admin User

export KC_BOOTSTRAP_ADMIN_USERNAME=username
export KC_BOOTSTRAP_ADMIN_PASSWORD=your_password
bin/kc.sh bootstrap-admin user --no-prompt

Step 3: Start Keycloak

bin/kc.sh start

3. Configure Keycloak for Frappe

Step 1: Create a Realm

• Go to Admin Console: http://localhost:8080/admin

• Use realm selector → Create Realm → Name: Office

Step 2: Create a Client

• Clients → Create → Client ID: office-web

• Access Type: Confidential

• Valid Redirect URIs:

https://xcel.techfinite.com/api/method/frappe.integrations.oauth2_logins.custom/keycloak

• Web Origins:

https://xcel.techfinite.com

• Save the client and note the Client Secret

Step 3: Enable Email Verification (optional but recommended)

• Users → Select User → Attributes → email_verified: true

4. Configure Frappe Social Login

Step 1: Open Social Login Keys

• Go to: Settings → Integrations → Social Login Key

Step 2: Fill the Details

Step 3: Save and Test

• Log out and navigate to your Frappe login page.

• Click the Keycloak login button and authenticate.

5. Common Issues & Resolutions

Issue: Admin locked out of Keycloak

• Cause: Removed all roles from admin account.

• Fix:

bin/kc.sh bootstrap-admin user --username tempadmin --password temp123 --no-prompt

• Login via CLI and restore roles to original admin:

bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user tempadmin --password temp123
bin/kcadm.sh add-roles -r master --uusername administrator --rolename admin --rolename create-realm

Issue: Keycloak login returns blank {}

• Cause: User’s email is not verified.

• Fix: Ensure email_verified is true in user attributes.

Issue: Redirect URI not accepted

• Cause: Mismatch in redirect URI configured in Keycloak.

• Fix: Make sure Frappe's redirect URI exactly matches Keycloak's client setting, including case.

Match Redirect URL to Social Login Key Name

• Ensure the Redirect URL in Frappe’s Social Login Key is:

  swift
  /api/method/frappe.integrations.oauth2_logins.custom/<keycloak>

  where <keycloak> exactly matches the name of the Social Login Key doctype. A mismatch (e.g., using realm name) prevents Frappe from routing correctly to login_via_oauth2

Use Full URLs for All Keycloak Endpoints

• API Endpoint must be fully qualified, not relative:

  perl
  https://<keycloak>/realms/<realm>/protocol/openid-connect/userinfo

• Likewise, Base URL must include https://….

This avoids passing None to the OAuth2 session and causing the startswith error discuss.frappe.io Include Required Scopes & Enable Standard Flow

• In Auth URL Data, ensure:

  json
  {"response_type":"code","scope":"openid profile email"}

• In Keycloak client settings, enable Standard flow and verify Valid redirect URIs include your Frappe callback github.

This guarantees code and essential user info (email_verified) are returned.

Add Keycloak User Info Mappers

To include claims like email_verified and groups/roles in the userinfo response:

1. In Keycloak Admin → Client or Client Scopes → Mappers, add:

   • User Realm Role mapper with Add to userinfo enabled.

   • Also ensure email_verified is included via appropriate mappers if missing .

This ensures Frappe can validate email_verified and fetch user info correctly.

Restart & Re-Test Login Flow

1. Save all Social Login Key and Keycloak configurations.

2. Run bench restart to reload settings.

3. Attempt login again:

   • You should be redirected to /api/method/frappe.integrations.oauth2_logins.custom/keycloak?code=…&state=…

   • No NoneType errors should occur, and Frappe proceeds to userinfo endpoint and logs in the user.