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",