Generic OAuth Client in Frappe Framework v15

Introduction & Context

The Generic OAuth Client in Frappe Framework v15 allows applications built on Frappe and ERPNext to authenticate users using external OAuth 2.0 providers. Instead of building custom authentication flows, developers can rely on standardized OAuth mechanisms to enable secure, scalable, and user-friendly login experiences.

This guide explains how the Generic OAuth Client works in Frappe v15, when to use it, and how it fits into modern ERP and web application architectures.

What Is a Generic OAuth Client?

A Generic OAuth Client is a configurable OAuth 2.0 integration that allows Frappe to act as a client to any OAuth-compliant identity provider. Unlike provider-specific integrations, this client is provider-agnostic, making it suitable for custom or enterprise identity systems.
In simple terms:
It lets users log in to Frappe using an external authentication server that supports OAuth 2.0.

Why Use Generic OAuth in Frappe?

Generic OAuth is useful when:

• Your organization uses a custom identity provider
• You integrate with enterprise SSO systems
• No prebuilt OAuth connector exists
• You want centralized authentication control

Key Benefits

• Standards-based OAuth 2.0 flow
• No custom authentication code required
• Secure token-based login
• Scalable for enterprise deployments

How Generic OAuth Works in Frappe v15

At a high level, the flow is:

• User clicks Login with OAuth Provider
• Frappe redirects the user to the OAuth authorization URL
• User authenticates on the provider’s site
• Provider redirects back with an authorization code
• Frappe exchanges the code for an access token
• User identity is fetched and mapped to a Frappe user

This flow strictly follows OAuth 2.0 standards.

Configuration & Setup

Where Is Generic OAuth Configured?

Generic OAuth is configured using OAuth Client records within Frappe. These records define how Frappe communicates with the external provider.

Common Configuration Parameters

• Authorization URL
• Access Token URL
• User Info URL
• Client ID
• Client Secret
• Redirect URI

All parameters must align with the OAuth provider’s configuration.

Implementation Details

OAuth Client Record Behavior

• Stored as a standard DocType record
• Used by Frappe’s authentication middleware
• Automatically handles redirects and token exchange

No custom backend code is required for basic usage.

User Guidance: How Users Experience OAuth Login

From a user’s perspective:

• They see an additional login option
• Clicking it redirects them to the external provider
• After authentication, they are logged in automatically

This reduces password fatigue and improves security.

Best Practices & Security Tips

• Always use HTTPS for OAuth endpoints
• Protect client secrets using role-based access
• Restrict scopes to minimum required
• Validate user identity fields carefully
• Map OAuth users to existing Frappe users when possible

Advanced Topics

Mapping External Users to Internal Roles

After OAuth authentication, Frappe can:

• Match users by email
• Create new users automatically
• Assign default roles programmatically

This allows seamless onboarding from external systems.

Integration Patterns

Generic OAuth is commonly used with:

• Corporate SSO systems
• External identity servers
• ERPNext customer portals
• Mobile or third-party applications

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

Troubleshooting Common Issues

Login Redirect Loop

• Verify redirect URI matches provider configuration
• Ensure correct authorization URL

Invalid Token Errors

• Check client secret
• Confirm token endpoint supports OAuth 2.0 authorization code flow

User Not Created

• Verify user info endpoint response
• Ensure email or unique identifier is returned

Industry Relevance & Use Case Mapping

Generic OAuth is widely adopted in:

• Enterprise ERP deployments – Centralized identity
• SaaS platforms – External customer login
• Government systems – Secure federated access
• Large organizations – Compliance-driven authentication

Target Audience

• ERPNext Developers
• Frappe Framework Developers
• System Architects
• Enterprise IT Teams

Summary: Why Generic OAuth Matters in Frappe v15

The Generic OAuth Client in Frappe Framework v15 provides a flexible, secure, and standards-compliant way to integrate external authentication systems. It eliminates custom login logic, improves security posture, and enables enterprise-grade identity management—making it a critical feature for modern ERPNext and Frappe applications.