OAuth
Frappe Framework uses oauthlib to implement OAuth 2.0. A Frappe instance can function as an OAuth Resource Server, Authorization Server, and Client, allowing it to both provide and consume protected resources.
Frappe includes complete OAuth support for authentication, authorization, token management, client registration, and metadata discovery through dedicated DocTypes and centralized OAuth Settings.
OAuth Roles
A Frappe instance can perform one or more of the following OAuth roles:
- Resource Server — Stores and serves protected resources such as DocType data.
- Authorization Server — Issues OAuth access tokens to authorized clients.
- Client — Connects to external OAuth providers to access protected resources.
OAuth DocTypes
Common
- OAuth Settings — Configures OAuth functionality shared across Resource Server, Authorization Server, and Client features.
Authorization Server
- OAuth Client — Stores registered OAuth clients.
- OAuth Bearer Token — Stores issued access tokens.
- OAuth Authorization Code — Stores authorization codes used during the OAuth flow.
- OAuth Provider Settings — Legacy configuration for authorization settings. This DocType is deprecated in favor of OAuth Settings.
Client
- Connected App — Stores connections to external OAuth providers such as Google Drive.
- Social Key Login — Enables users to sign in using third-party identity providers.
- Token Cache — Stores OAuth access and refresh tokens received from connected applications.
Supported OAuth Features
Frappe extends the capabilities of oauthlib by supporting the following OAuth features:
- Dynamic Client Registration — Allows OAuth clients to register automatically.
- Authorization Server Metadata Discovery — Publishes metadata describing the authorization server.
- Resource Server Metadata Discovery — Publishes metadata describing protected resources and authentication requirements.
These features follow standard OAuth specifications, making Frappe compatible with modern OAuth clients and services.
Additional Documentation
The following guides provide more information about OAuth in Frappe:
- How to Set Up OAuth 2
- OAuth 2
- Token-Based Authentication
- Using Frappe as an OAuth Service
- Social Login Key
- Connected App
Some older documentation may not reflect the latest implementation. When in doubt, always refer to the source code.
OAuth Settings
The OAuth Settings DocType provides centralized configuration for OAuth functionality. Each setting includes descriptive help text to explain its purpose.
Available Settings
- Skip Authorization — Skips the authorization confirmation when a valid token already exists.
- Show Auth Server Metadata — Enables Authorization Server Metadata Discovery.
- Enable Dynamic Client Registration — Allows OAuth clients to register automatically.
- Show Protected Resource Metadata — Enables Resource Server Metadata Discovery.
Keep Skip Authorization disabled in production environments unless you fully understand its security implications.
The remaining fields in the Resource section are used when responding to requests made to the following endpoint:
/.well-known/oauth-protected-resourcePublic Clients
Public clients, such as Single Page Applications (SPAs), are restricted by default using CORS policies.
To allow trusted public clients to communicate with your OAuth endpoints, add their hostnames to the Allowed Public Client Origins field in OAuth Settings.
Only add trusted origins to the Allowed Public Client Origins list to minimize security risks.
