SEP-2207: OIDC-Flavored Refresh Token Guidance

​

Abstract

​

Motivation

• In pure OAuth 2.1, there is no standard mechanism for a client to explicitly request a refresh token. The Authorization Server determines whether to issue one based on the client’s capabilities (e.g., the refresh_token grant type in client metadata) and its own policies.
• In OIDC (and Authorization Servers that adopt this convention), the offline_access scope exists to allow clients to explicitly request refresh tokens, in addition to the OAuth logic.

1. Clients aren’t requesting refresh tokens: Major MCP clients (Cursor, Claude, VS Code, etc.) aren’t explicitly asking for refresh tokens via the offline_access scope because they don’t know whether the Authorization Server supports, expects, or requires it.
2. Resource servers shouldn’t specify offline_access: The offline_access scope is not a resource-specific scope—it’s a concern between the client and Authorization Server. Including it in the WWW-Authenticate header’s scope parameter or in the Protected Resource Metadata’s scopes_supported would be semantically incorrect since it implies the resource requires refresh tokens, which it never would.
3. Authorization Servers can be inconsistent: When processing an authorization code grant, different Authorization Servers may have different behavior when issuing refresh tokens to different clients, especially when the client doesn’t specify refresh_token as a grant type or request the offline_access scope.
4. Interoperability gap: Without this guidance, implementations may behave inconsistently, leading to poor user experience (frequent re-authentication) or security issues (issuing refresh tokens to clients that can’t securely store them).

​

Specification

​

MCP Client Requirements

1. Advertise capability: Clients SHOULD include refresh_token in their grant_types client metadata to indicate they support refresh tokens.
2. Scope augmentation: When the client desires a refresh token and the Authorization Server metadata contains offline_access in its scopes_supported field, the client MAY add the offline_access scope to the list of scopes from the resource server before making authorization requests to the Authorization Server.
3. No guarantee: Clients MUST NOT assume that advertising support or requesting offline_access guarantees they will receive a refresh token. The Authorization Server retains discretion based on its policies.

​

MCP Server (Resource Server) Requirements

1. SHOULD NOT include offline_access in the scope parameter of WWW-Authenticate headers, as refresh tokens are not a resource requirement.
2. SHOULD NOT include offline_access in scopes_supported in Protected Resource Metadata, as it is not a resource-specific scope.

​

Rationale

​

Why not require offline_access in the 401 response?

​

Why check client metadata for grant types? Why not always issue refresh tokens?

• Cannot securely store refresh tokens
• Has no mechanism to use them

​

Why allow offline_access as an alternative signal?

​

Alternative approaches considered

1. Mandate offline_access in resource responses: Rejected because it misrepresents the resource’s requirements and creates an anti-pattern.
2. Always issue refresh tokens: Rejected because it ignores client capabilities and Authorization Server security policies.
3. Separate OIDC-specific specification: Rejected in favor of a unified approach that works for both pure OAuth and OIDC deployments.
4. Provide guidance for Authorization Servers: Rejected in favor of relying on OAuth and OIDC specs for this guidance as it can vary.

​

Backward Compatibility

• Clients that already request offline_access continue to work
• Authorization Servers that already check client capabilities continue to work
• MCP Servers are not required to make any changes
• The guidance is additive and does not change existing required behavior

​

Security Implications

​

Positive security implications

1. Reduced token leakage risk: By not issuing refresh tokens to clients that don’t advertise support, we reduce the risk of long-lived tokens being stored insecurely.
2. Defense in depth: The risk-based assessment step gives Authorization Servers flexibility to implement additional security controls.

​

Considerations

1. Client metadata may not be sufficient: Since client metadata is self-reported, a malicious actor could register a client claiming refresh_token grant support to obtain long-lived tokens. Authorization Servers MAY use the risk-based assessment step (see Specification) to apply additional restrictions—such as domain allowlists, reputation checks, or verification requirements—rather than solely relying on client metadata claims when deciding whether to issue refresh tokens.
2. Scope injection: Clients adding offline_access should ensure this doesn’t interfere with other scope-related logic or create unexpected authorization prompts.

​

Reference Implementation

• TypeScript SDK: Client-side offline_access scope handling
• Python SDK: Client-side offline_access scope handling
• Authorization Server example: Demonstration of client capability checking
• Client conformance test: Allowing for easy validation of SDK implementations

​

Acknowledgments

• Aaron Parecki (OAuth/OIDC expertise)
• Paul Carleton (MCP authorization guidance)
• Simon Russell (OIDC deployment experience)