Adding a Social Login Provider in Frappe Framework v15

Introduction & Context

Modern users expect fast, secure, and password-free authentication. Social login providers solve this by allowing users to sign in using trusted third-party platforms such as Google, GitHub, or other OAuth-based services.
In Frappe Framework v15, social login is implemented using a provider-based OAuth configuration. This guide explains how social login works internally, how to configure it correctly, and how it integrates seamlessly with ERPNext authentication—strictly aligned with Frappe v15.

What Is a Social Login Provider in Frappe?

A Social Login Provider is an OAuth 2.0 configuration that allows users to authenticate into Frappe using an external identity provider instead of a local username and password.
In Frappe v15, social login is:

• Provider-driven (Google, GitHub, etc.)
• OAuth 2.0 compliant
• Fully configurable via the UI
• Securely token-based

Why Use Social Login in ERPNext & Frappe?

Social login improves both security and user experience.

Key Advantages

• Eliminates password reuse risks
• Faster onboarding and login
• Trusted third-party authentication
• Reduced account management overhead

For ERPNext portals, websites, and SaaS deployments, social login is often essential.

How Social Login Works in Frappe v15

The authentication flow follows standard OAuth 2.0 behavior:

1. User clicks Login with Social Provider
2. Frappe redirects the user to the provider’s authorization URL
3. User authenticates on the provider’s platform
4. Provider redirects back with an authorization code
5. Frappe exchanges the code for an access token
6. User details are fetched and mapped to a Frappe user

This entire flow is handled by Frappe’s authentication framework—no custom login logic required.

Configuration & Setup

Where Are Social Login Providers Configured?

Social login providers are configured using the Social Login Key DocType in Frappe.

Each record represents one OAuth provider.

Core Configuration Fields

Every social login provider requires:

• Provider Name
• Client ID
• Client Secret
• Authorization URL
• Access Token URL
• User Information URL
• Redirect URI

All values must match exactly with the OAuth provider’s application settings.

Implementation Details

Internal Handling in Frappe v15

• Frappe manages OAuth redirects automatically
• Tokens are handled securely by the framework
• User creation or mapping is configurable
• Sessions are created after successful validation

No overrides or hooks are required for basic usage.

User Guidance: What Users Experience

From an end-user perspective:

• The login page shows social login buttons
• Clicking a button redirects to the provider
• After approval, the user is logged in instantly

This works across:

• Desk login
• Website login
• Customer portals

Best Practices & Security Tips

• Always use HTTPS for redirect URIs
• Never expose client secrets
• Limit OAuth scopes to required data only
• Use verified email as the unique identifier
• Disable unused providers

Advanced Topics

Auto User Creation vs User Mapping

Frappe supports:

• Automatic user creation for first-time logins
• Mapping logins to existing users via email

This makes social login ideal for both open portals and restricted enterprise systems.

Integration Patterns

Social login is commonly used in:

• ERPNext customer portals
• Public-facing Frappe websites
• SaaS ERP deployments
• Partner and vendor access systems

It integrates seamlessly with Frappe’s Desk and Website modules.

Troubleshooting Common Issues

Redirect URI Mismatch

• Ensure redirect URI matches provider settings exactly
• Check protocol (HTTP vs HTTPS)

Invalid Client Credentials

• Verify client ID and secret
• Confirm credentials belong to the correct app

User Not Logged In After Redirect

• Check user info endpoint response
• Ensure email field is returned

Industry Relevance & Use Case Mapping

Social login is especially relevant for:

• SaaS ERP platforms
• Customer-facing ERPNext portals
• Large user-base applications
• Compliance-driven identity systems

Target Audience

• ERPNext Developers
• Frappe Framework Developers
• SaaS Architects
• System Administrators

Summary: Why Social Login Matters in Frappe v15

Adding a Social Login Provider in Frappe Framework v15 enables secure, modern authentication without custom code. It enhances usability, strengthens security, and aligns ERPNext applications with enterprise and SaaS authentication standards—making it a critical feature for scalable deployments.