OpenID Connect and Social Login in Frappe Framework v15
OpenID Connect in Frappe Framework v15 enables secure Single Sign-On (SSO) and social login using OAuth 2.0–compliant identity providers.
This guide explains how to configure OpenID Connect and social authentication in Frappe v15 for ERPNext and custom applications using verified framework components.
What Is OpenID Connect in Frappe?
OpenID Connect (OIDC) in Frappe is an identity layer built on OAuth 2.0 that allows external authentication through trusted providers.
It enables users to log in using:
- Google Workspace
- Microsoft Azure AD
- Keycloak
- Okta
- Custom OIDC servers
Frappe validates identity tokens and maps them to system users.
Why Use Social Login and SSO in ERPNext?
OpenID-based authentication improves security and usability by:
- Eliminating multiple passwords
- Enforcing centralized identity management
- Supporting enterprise SSO policies
- Reducing helpdesk load
- Improving user onboarding
It is ideal for corporate ERPNext deployments and SaaS platforms
Target Audience
- ERPNext Administrators
- Frappe Developers
- Identity & Access Engineers
- System Integrators
- IT Security Teams
Technical Prerequisites
Before configuring OpenID Connect, ensure:
| Requirement | Description |
| Framework | Frappe v15 |
| SSL | HTTPS enabled |
| Access | System Manager role |
| Provider | OIDC-compliant IdP |
| Network | Public redirect access |
How Does OpenID Connect Work in Frappe v15?
Frappe implements the standard Authorization Code Flow defined by OpenID Connect.
Authentication flow:
- User clicks external login
- Redirected to Identity Provider
- User authenticates
- Provider issues ID token
- Frappe validates token
- User session created
Tokens are verified using provider metadata and JWKS endpoints.
How to Configure OpenID Connect in Frappe v15
Step 1: Register Application with Identity Provider
Create an application in your IdP console and obtain:
- Client ID
- Client Secret
- Issuer URL
- Authorization Endpoint
- Token Endpoint
- UserInfo Endpoint
Set redirect URI:
https://your-site/api/method/frappe.integrations.oauth2.login
Step 2: Create Social Login Key in Frappe
Navigate to:
Desk → Social Login Key → New
Step 3: Configure Provider Settings
Fill the following fields:
| Field | Value |
| Provider Name | Example: Keycloak |
| Client ID | From IdP |
| Client Secret | From IdP |
| Base URL | Issuer URL |
| Authorize URL | Authorization endpoint |
| Access Token URL | Token endpoint |
| User Info URL | UserInfo endpoint |
| Icon | Provider icon |
| Enabled | ✔ |
Step 4: Enable OpenID Connect
Check:
Enable Social Login
and ensure scopes include:
openid profile email
These scopes are mandatory for OIDC.
How Social Login Works in Frappe v15
Frappe uses the Social Login Key DocType to manage external authentication providers.
When a user logs in:
- Identity email is extracted
- User is matched by email
- New user is created if allowed
- Roles assigned automatically
Mapping is handled by frappe.integrations.oauth2.
Example: Integrating Keycloak with Frappe
Provider Configuration
| Setting | Value |
| Issuer | https://auth.company.com/realms/erp |
| Auth URL | /protocol/openid-connect/auth |
| Token URL | /protocol/openid-connect/token |
| UserInfo | /protocol/openid-connect/userinfo |
Scopes
openid email profile
Result
Employees can log in using corporate credentials.
Best Practices for OpenID Integration
- Enforce HTTPS everywhere
- Use confidential clients only
- Validate issuer metadata
- Restrict auto-user creation
- Rotate secrets annually
- Enable MFA at IdP level
- Monitor login logs
Common Issues & Troubleshooting
Invalid Redirect URI
Cause: URI mismatch
Fix: Match exactly:
/api/method/frappe.integrations.oauth2.login
Email Not Returned
Cause: Missing email scope
Fix: Add email in scopes
Token Validation Failed
Cause: Incorrect issuer URL
Fix: Verify .well-known/openid-configuration
OpenID vs Social Login vs Token Auth
| Feature | OpenID | Social Login | Token Auth |
| SSO | ✅ | ✅ | ❌ |
| API Access | ❌ | ❌ | ✅ |
| Passwordless | ✅ | ✅ | ❌ |
| Enterprise Use | ✅ | ⚠️ | ⚠️ |
Use OpenID for workforce authentication and tokens for system APIs.
Integration Patterns
Common Architectures
User → IdP → OIDC → Frappe → ERPNext
Use Cases
- Corporate SSO
- SaaS login portals
- Partner portals
- Vendor access systems
- Mobile authentication
Advanced: Custom OpenID Provider Integration
Using Custom Metadata Endpoint
Frappe supports dynamic discovery via:
/.well-known/openid-configuration
When available, endpoints are auto-resolved.
Custom Claim Mapping (Server-Side)
Administrators may override mappings using hooks:
# hooks.py
social_login_pipeline = [
"frappe.integrations.oauth2.custom_pipeline"
]
Use only when default mapping is insufficient.
Technical Categories & Tags
- Frappe Framework v15
- OpenID Connect
- OAuth2 Authentication
- ERPNext SSO
- Identity Management
Official References
- Frappe Docs – OpenID Connect
- Frappe GitHub v15 – integrations/oauth2
- OpenID Foundation Specification
Summary
OpenID Connect and Social Login in Frappe Framework v15 provide secure, scalable, and standards-compliant Single Sign-On for ERPNext environments.
By integrating trusted identity providers, organizations can centralize authentication, enhance security, and streamline user access management.
