Skip to content

SEP-2350: Clarify client-side scope accumulation in step-up authorization #2350

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mcp-commander merged 5 commits into from
Mar 28, 2026
+60 −9
Merged

SEP-2350: Clarify client-side scope accumulation in step-up authorization #2350

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
48164f3
docs: clarify client-side scope accumulation in step-up authorization
dend Mar 4, 2026
db9367d
docs: add hierarchical scope note to step-up authorization flow
localden Mar 7, 2026
d5213f4
Merge branch 'main' into den/scopes
localden Mar 7, 2026
4325a78
Add guidance against incremental scope challenging within a single op…
localden Mar 23, 2026
029482b
Merge branch 'main' into den/scopes
localden Mar 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 60 additions & 9 deletions docs/specification/draft/basic/authorization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,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`.

Expand Down Expand Up @@ -512,30 +515,57 @@ 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.

@DavidParks8 DavidParks8 Mar 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why are they not required? This seems like a great way to enable constant AS thrashing.

@localden localden Mar 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The thrashing mitigation lives on the client side. Step 2 of the step-up flow requires clients to compute the union of previously requested scopes and the newly challenged scopes before re-authorizing, and clients SHOULD implement retry limits. So a well-behaved client hits the AS once per new scope requirement, not once per operation.

We can't make server-side union a MUST because servers often can't provide it reliably:

  • The server only sees the current token. If a user declined a scope at a prior consent screen, or the client accumulated scopes across multiple re-auth cycles, the server has no visibility into that history.
  • With opaque tokens and no introspection endpoint, the server can't enumerate the token's current scopes at all.
  • In proxy-to-upstream setups, the upstream 403 tells you what's missing for this call but nothing about what the client already holds.

In RFC 6750 Section 3.1, the doc defines the scope attribute as "the scope necessary to access the requested resource," which is a per-request statement. The client is the only party with ground truth on what's already requested, so that's where accumulation belongs.

Servers that can compute the union are free to do so (the "extended approach" a few lines down covers this). We're just not mandating statefulness that a large class of servers can't deliver.


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.

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
response, as misconfigured scopes may require frequent user interaction.

<Note>
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.
</Note>

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
Expand All @@ -548,13 +578,34 @@ 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

Clients **SHOULD** implement retry limits and **SHOULD** track scope upgrade attempts to avoid
repeated failures for the same resource and operation combination.

<Note>
**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
Comment thread
localden marked this conversation as resolved.
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.
</Note>

## 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).
Expand Down
Loading