Social Login Key Configuration in Frappe Framework v15
Social Login Key in Frappe Framework v15 enables secure OAuth 2.0–based authentication using third-party identity providers such as Google, GitHub, and Microsoft.
This guide explains how to configure, manage, and secure social login providers in ERPNext and custom Frappe applications using native framework components.
What Is Social Login Key in Frappe?
Social Login Key is a system DocType in Frappe that stores OAuth credentials for external authentication providers.
It allows administrators to:
- Register third-party login services
- Configure client credentials
- Control authentication scopes
- Enable Single Sign-On (SSO)
Each provider is managed independently using this DocType.
Why Use Social Login in ERPNext & Frappe?
Social login improves platform security and usability by:
- Eliminating password fatigue
- Enabling centralized identity management
- Reducing account recovery requests
- Improving onboarding speed
- Supporting enterprise SSO policies
It is widely adopted in SaaS-based ERPNext deployments.
Target Audience
- ERPNext Administrators
- Frappe Framework Developers
- Identity & Access Engineers
- SaaS Platform Managers
- IT Security Teams
Technical Prerequisites
Before configuring Social Login Key, ensure:
| Requirement | Description |
| Framework | Frappe v15 |
| SSL | HTTPS enabled |
| Access | System Manager role |
| Provider | OAuth2-compliant IdP |
| Network | Public redirect access |
How Does Social Login Work in Frappe v15?
Frappe uses OAuth 2.0 Authorization Code Flow to authenticate users via external providers.
Authentication lifecycle:
- User selects social provider
- Redirect to provider login page
- User grants permission
- Provider issues authorization code
- Frappe exchanges code for token
- User session created
All steps are handled by frappe.integrations.oauth2.
How to Configure Social Login Key in Frappe v15 (Step-by-Step)
Step 1: Register Application with Provider
Create an application in the provider’s developer portal and obtain:
- Client ID
- Client Secret
- Redirect URI
Use this redirect URI:
https://your-site/api/method/frappe.integrations.oauth2.login
Step 2: Create Social Login Key
Navigate to:
Desk → Social Login Key → New
Step 3: Configure Provider Credentials
Fill in the following fields:
| Field | Description |
| Provider Name | Example: Google |
| Client ID | From provider |
| Client Secret | From provider |
| Base URL | Provider auth domain |
| Icon | Provider logo |
| Enabled | ✔ |
Step 4: Configure OAuth Endpoints
Depending on provider, fill:
| Field | Purpose |
| Authorize URL | Authorization endpoint |
| Access Token URL | Token endpoint |
| User Info URL | Profile endpoint |
These endpoints are verified during login.
Step 5: Define OAuth Scopes
Example scopes:
email profile openid
Scopes determine what user data is accessible.
Step 6: Enable Social Login
Ensure:
Enable Social Login = Checked
in System Settings.
Example: Google Login Configuration
How User Mapping Works in Frappe
Frappe links social accounts to users using verified email addresses.
Rules:
- Existing users are matched by email
- New users may be auto-created
- Default roles assigned
- Login history recorded
This ensures identity consistency.
Best Practices for Social Login Security
- Use HTTPS only
- Restrict auto user creation
- Enable MFA at provider level
- Rotate secrets yearly
- Monitor login logs
- Disable unused providers
Common Issues & Troubleshooting
Redirect URI Mismatch
Cause: Incorrect callback URL
Fix: Verify:
/api/method/frappe.integrations.oauth2.login
Provider Not Showing on Login Page
Cause: Disabled provider
Fix: Enable Social Login Key record
User Email Not Returned
Cause: Missing scope
Fix: Add email scope
Social Login vs OpenID vs Token Auth
| Feature | Social Login | OpenID | Token Auth |
| SSO | ✅ | ✅ | ❌ |
| API Access | ❌ | ❌ | ✅ |
| Passwordless | ✅ | ✅ | ❌ |
| Enterprise Use | ⚠️ | ✅ | ⚠️ |
Integration Patterns
SaaS Authentication Flow
User → OAuth Provider → Frappe → ERPNext
Enterprise SSO Flow
Employee → IdP → Frappe → Internal Systems
Advanced: Custom Social Provider Integration
Register Custom Provider
Administrators can configure any OAuth2 provider manually by defining endpoints in Social Login Key.
Custom Login Pipeline (Optional)
# hooks.py
social_login_pipeline = [
"frappe.integrations.oauth2.custom_pipeline"
]
Use only for advanced identity mapping.
Technical Categories & Tags
- Frappe Framework v15
- Social Login
- OAuth2 Authentication
- ERPNext SSO
- Identity Management
Summary
Social Login Key in Frappe Framework v15 provides a secure, extensible, and standards-compliant authentication framework for ERPNext platforms.
By configuring trusted providers, organizations can deliver seamless login experiences while maintaining enterprise-grade security.
