From 48164f3cac816ddb6072ed129efa5ffb80140fb6 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <1389609+dend@users.noreply.github.com> Date: Wed, 4 Mar 2026 13:06:50 -0800 Subject: [PATCH 1/3] docs: clarify client-side scope accumulation in step-up authorization Align server scope management with RFC 6750 Section 3.1 so servers report scopes needed for the current operation rather than including previously granted client scopes. Add explicit client-side scope accumulation guidance to the step-up authorization flow and clarify the meaning of "authoritative" in protected resource metadata discovery requirements. Fixes #2349 --- .../draft/basic/authorization.mdx | 47 +++++++++++++++---- 1 file changed, 38 insertions(+), 9 deletions(-) diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx index 15b9e2220..4cc892bd5 100644 --- a/docs/specification/draft/basic/authorization.mdx +++ b/docs/specification/draft/basic/authorization.mdx @@ -112,7 +112,10 @@ The scopes included in the `WWW-Authenticate` challenge **MAY** match `scopes_su or superset of it, or an alternative collection that is neither a strict subset nor superset. Clients **MUST NOT** assume any particular set relationship between the challenged scope set and `scopes_supported`. Clients **MUST** treat the scopes provided in the -challenge as authoritative for satisfying the current request. Servers **SHOULD** strive for +challenge as authoritative for the current operation — that is, these scopes are required to +satisfy the current request. When re-authorizing, clients **SHOULD** include these scopes +alongside any previously granted scopes to avoid losing permissions needed for other operations +(see [Step-Up Authorization Flow](#step-up-authorization-flow)). Servers **SHOULD** strive for consistency in how they construct scope sets but they are not required to surface every dynamically issued scope through `scopes_supported`. @@ -514,14 +517,23 @@ scope during runtime operations, the server **SHOULD** respond with: - `error_description` (optional) - human-readable description of the error **Server Scope Management**: When responding with insufficient scope errors, servers -**SHOULD** include the scopes needed to satisfy the current request in the `scope` -parameter. +**SHOULD** include the scopes needed to satisfy the current operation in the `scope` +parameter, consistent with +[RFC 6750 Section 3.1](https://datatracker.ietf.org/doc/html/rfc6750#section-3.1). +The `scope` attribute describes the scopes necessary to access +the requested resource — servers are not required to include +the client's previously granted scopes. Servers have flexibility in determining which scopes to include: -- **Minimum approach**: Include the newly-required scopes for the specific operation. Include any existing granted scopes as well, if they are required, to prevent clients from losing previously granted permissions. -- **Recommended approach**: Include both existing relevant scopes and newly required scopes to prevent clients from losing previously granted permissions -- **Extended approach**: Include existing scopes, newly required scopes, and related scopes that commonly work together +- **Minimum approach**: Include only the scopes required for the + specific operation that triggered the error. +- **Recommended approach**: Include the scopes required for the + current operation along with related scopes that commonly work + together, to reduce the number of step-up authorization rounds. +- **Extended approach**: Include the scopes required for the + current operation, related scopes, and any other scopes the + server anticipates the client may need in the near future. The choice depends on the server's assessment of user experience impact and authorization friction. @@ -530,14 +542,23 @@ Servers **SHOULD** be consistent in their scope inclusion strategy to provide pr Servers **SHOULD** consider the user experience impact when determining which scopes to include in the response, as misconfigured scopes may require frequent user interaction. + + Scope accumulation across operations is a client-side responsibility. Clients + **SHOULD** compute the union of previously requested scopes and newly + challenged scopes when initiating re-authorization, as described in [Step-Up + Authorization Flow](#step-up-authorization-flow). This allows servers to + remain stateless with respect to client scope sets while ensuring clients do + not lose previously granted permissions. + + Example insufficient scope response: ```http HTTP/1.1 403 Forbidden WWW-Authenticate: Bearer error="insufficient_scope", - scope="files:read files:write user:profile", + scope="files:write", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource", - error_description="Additional file write permission required" + error_description="File write permission required for this operation" ``` #### Step-Up Authorization Flow @@ -550,7 +571,15 @@ Clients acting on behalf of a user **SHOULD** attempt the step-up authorization The flow is as follows: 1. **Parse error information** from the authorization server response or `WWW-Authenticate` header -2. **Determine required scopes** as outlined in [Scope Selection Strategy](#scope-selection-strategy). +2. **Determine required scopes** by computing the union of the + client's previously requested scope set and the scopes from + the current challenge. This ensures previously granted + permissions are preserved when servers emit per-operation + scope challenges per + [RFC 6750 Section 3.1](https://datatracker.ietf.org/doc/html/rfc6750#section-3.1). + Clients **MAY** also consult the + [Scope Selection Strategy](#scope-selection-strategy) for + initial scope selection guidance. 3. **Initiate (re-)authorization** with the determined scope set 4. **Retry the original request** with the new authorization no more than a few times and treat this as a permanent authorization failure From db9367d0b9a4ffee00833ebac6665c8969c91c23 Mon Sep 17 00:00:00 2001 From: Den Delimarsky Date: Sat, 7 Mar 2026 19:33:27 +0000 Subject: [PATCH 2/3] docs: add hierarchical scope note to step-up authorization flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarifies that when authorization servers use hierarchical scopes (where a broad scope implies narrower ones), clients computing scope unions may produce semantically redundant sets. Clients don't need to deduplicate these — the authorization server normalizes during token issuance. Also notes that hierarchy awareness IS needed server-side for the 403 gating decision (is this token sufficient?), but not for determining what scopes to emit in the challenge — the server still emits the minimal required scope per RFC 6750 3.1. Addresses feedback from @SamMorrowDrums re: GitHub's rolled-up scope model, where a tool requiring repo:read must accept a token carrying only repo:admin. :house: Remote-Dev: homespace --- docs/specification/draft/basic/authorization.mdx | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx index 4cc892bd5..2c17cc284 100644 --- a/docs/specification/draft/basic/authorization.mdx +++ b/docs/specification/draft/basic/authorization.mdx @@ -586,6 +586,19 @@ The flow is as follows: Clients **SHOULD** implement retry limits and **SHOULD** track scope upgrade attempts to avoid repeated failures for the same resource and operation combination. + + **Hierarchical scopes**: Some authorization servers define scope hierarchies + where a broader scope implies narrower ones (for example, an `admin` scope + that subsumes `read`). When accumulating scopes, the client's union may + contain semantically redundant entries — for example, a token previously + granted a broad scope may be challenged with a narrower one it already + implies. Clients need not deduplicate hierarchically; authorization servers + typically normalize such redundancy during token issuance. Servers, for their + part, must account for hierarchy when deciding whether a token is sufficient + for an operation, but this does not affect the scopes they emit in a + challenge. + + ## Security Considerations Implementations **MUST** follow OAuth 2.1 security best practices as laid out in [OAuth 2.1 Section 7. "Security Considerations"](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#name-security-considerations). From 4325a78f0df5cc9174133408f06fe79d25ee7321 Mon Sep 17 00:00:00 2001 From: Den Delimarsky Date: Mon, 23 Mar 2026 04:34:42 +0000 Subject: [PATCH 3/3] Add guidance against incremental scope challenging within a single operation :house: Remote-Dev: homespace --- docs/specification/draft/basic/authorization.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx index 2c17cc284..abda6ceb7 100644 --- a/docs/specification/draft/basic/authorization.mdx +++ b/docs/specification/draft/basic/authorization.mdx @@ -537,6 +537,15 @@ Servers have flexibility in determining which scopes to include: The choice depends on the server's assessment of user experience impact and authorization friction. +Regardless of the approach chosen, servers **SHOULD** include all +scopes required for the current operation in a single challenge. +Challenging incrementally (returning one missing scope, then another +on the subsequent retry) forces multiple authorization round-trips +for a single operation and degrades user experience. The required +scopes may be determined dynamically based on the specific request +arguments and context, but once determined, they should be emitted +together. + Servers **SHOULD** be consistent in their scope inclusion strategy to provide predictable behavior for clients. Servers **SHOULD** consider the user experience impact when determining which scopes to include in the