From befca37299a58f00ef852c17f98d876e5b88681a Mon Sep 17 00:00:00 2001 From: 18alantom <2.alan.tom@gmail.com> Date: Thu, 3 Jul 2025 14:36:04 +0530 Subject: [PATCH] chore: README for integrations with OAuth2 docs - Update descriptionsi in OAuth Settings --- frappe/integrations/README.md | 52 ++++++++++++++++--- .../oauth_settings/oauth_settings.json | 8 +-- 2 files changed, 48 insertions(+), 12 deletions(-) diff --git a/frappe/integrations/README.md b/frappe/integrations/README.md index 1d9cc30d44..b0ddb0564b 100644 --- a/frappe/integrations/README.md +++ b/frappe/integrations/README.md @@ -8,19 +8,55 @@ Frappe Framwork uses [`oauthlib`](https://github.com/oauthlib/oauthlib) to manag 2. **Authorization Server**: server that issues tokens to access some resource. 3. **Client**: app that requires access to some resource on a resource server. -Different DocTypes and features pertain to each of roles: +DocTypes pertaining to the above roles: -0. **Common**: - - **OAuth Settings**: allows configuring certain OAuth features. -1. **Authorization Server** +1. **Common** + - **OAuth Settings**: allows configuring certain OAuth features pertaining to the three roles. +2. **Authorization Server** - **OAuth Client**: keeps records of _clients_ registered with the frappe instance. - **OAuth Bearer Token**: tokens given out to registered _clients_ are maintained here. - **OAuth Authorization Code**: keeps track of OAuth codes a client responds with in exchange for a token. - - **OAuth Provider Settings**: allows skipping authorization -2. **Client** + - **OAuth Provider Settings**: allows skipping authorization. `[DEPRECATED]` use **OAuth Settings** instead. +3. **Client** - **Connected App**: keeps records of _authorization servers_ against whom this frappe instance is registered as a _client_ so some resource can be accessed. Eg. a users Google Drive account. - **Social Key Login**: similar to **Connected App**, but for the purpose of logging into the frappe instance. Eg. a users Google account to enable "Login with Google". - **Token Cache**: tokens received by the Frappe instance when accessing a **Connected App**. -3. -## OAuth Settings +### Features + +Additional features over `oauthlib` that have implemented in the Framework: + +- **Dynamic Client Registration**: allows a client to register itself without manual configuration by the resource owner. [RFC7591](https://datatracker.ietf.org/doc/html/rfc7591) +- **Authorization Server Metadata Discovery**: allows a client to view the instance's auth server (itself) metadata such as auth end points. [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414) +- **Resource Server Metadata Discovery**: allows a client to view the instance's resource server metadata such as documentation, auth servers, etc. [RFC9278](https://datatracker.ietf.org/doc/html/rfc9728) + +### Additional Docs + +Documentation of various OAuth2 features: + +1. [How to setup OAuth 2?](https://docs.frappe.io/framework/user/en/guides/integration/how_to_set_up_oauth) +2. [OAuth 2](https://docs.frappe.io/framework/user/en/guides/integration/rest_api/oauth-2) +3. [Token Based Authentication](https://docs.frappe.io/framework/user/en/guides/integration/rest_api/token_based_authentication) +4. [Using Frappe as OAuth Service](https://docs.frappe.io/framework/user/en/using_frappe_as_oauth_service) +5. [Social Login Key](https://docs.frappe.io/framework/user/en/guides/integration/social_login_key) +6. [Connected App](https://docs.frappe.io/framework/user/en/guides/app-development/connected-app) + +> [!WARNING] +> +> Some of these might be outdated, it is always recommended to check the code +> when in doubt. + +### OAuth Settings + +A Single doctype that allows configuring OAuth2 related features. It is +recommended to open the DocType page itself as each field and section has a +sufficiently descriptive help text. + +The settings allow toggling the following features: + +- Authorization check when active token is present using the _Skip Authorization_ field. _**Note**: Keep this unchecked in production._ +- **Authorization Server Metadata Discovery**: by toggling the _Show Auth Server Metadata_ field. +- **Dynamic Client Registration**: by toggling the _Enable Dynamic Client Registration_ field. +- **Resource Server Metadata Discovery**: by toggling the _Show Protected Resource Metadata_. + +The remaining fields (in the **Resource Server** section) are used only when responding to requests on `/.well-known/oauth-protected-resource` diff --git a/frappe/integrations/doctype/oauth_settings/oauth_settings.json b/frappe/integrations/doctype/oauth_settings/oauth_settings.json index add8b2eb70..696accde2b 100644 --- a/frappe/integrations/doctype/oauth_settings/oauth_settings.json +++ b/frappe/integrations/doctype/oauth_settings/oauth_settings.json @@ -21,7 +21,7 @@ ], "fields": [ { - "description": "These settings are used when this Frappe instance functions as a resource server.", + "description": "These fields are used to provide resource server metadata to clients querying the \"/.well-known/oauth-protected-resource\" end point. For additional reference view: https://datatracker.ietf.org/doc/html/rfc9728", "fieldname": "resource_server_section", "fieldtype": "Section Break", "label": "Resource Server" @@ -63,7 +63,7 @@ }, { "default": "1", - "description": "Allows clients to fetch metadata from the /.well-known/oauth-authorization-server endpoint.", + "description": "Allows clients to fetch metadata from the /.well-known/oauth-authorization-server endpoint. Reference: RFC8414", "fieldname": "show_auth_server_metadata", "fieldtype": "Check", "label": "Show Auth Server Metadata" @@ -83,7 +83,7 @@ }, { "default": "1", - "description": "Allows clients to register themselves without manual intervention. Registration creates a OAuth Client entry.", + "description": "Allows clients to register themselves without manual intervention. Registration creates a OAuth Client entry. Reference: RFC7591", "fieldname": "enable_dynamic_client_registration", "fieldtype": "Check", "label": "Enable Dynamic Client Registration" @@ -100,7 +100,7 @@ "index_web_pages_for_search": 1, "issingle": 1, "links": [], - "modified": "2025-07-03 14:07:31.542741", + "modified": "2025-07-03 14:29:35.314601", "modified_by": "Administrator", "module": "Integrations", "name": "OAuth Settings",