diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 87feddf..6108686 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -2,14 +2,11 @@ This document lists current maintainers of the Model Context Protocol ext-auth project. -**Last updated:** October 14, 2025 +**Last updated:** October 23, 2026 -## Lead Maintainers +## Extension Maintainers - [Paul Carleton](https://github.com/pcarleton) - -## Core Maintainers - - [Aaron Parecki](https://github.com/aaronpk) - [Darin McAdams](https://github.com/D-McAdams) - [Den Delimarsky](https://github.com/localden) diff --git a/README.md b/README.md index 22f1f0d..b985e20 100644 --- a/README.md +++ b/README.md @@ -7,21 +7,20 @@ These extensions are: - **Optional** - Implementations can choose to adopt these extensions - **Additive** - Extensions do not modify or break core protocol functionality; they add new capabilities while preserving core protocol behavior - **Composable** - Extensions are modular and designed to work together without conflicts, allowing implementations to adopt multiple extensions simultaneously -- **Versioned independently** - Extensions follow the core MCP versioning cycle but may adopt independent versioning as needed +- **Versioned with the core protocol** - A Stable extension is published as revisions keyed to core protocol revisions, and proposed changes collect in its `draft/` directory ## Extensions -### Stable - -- [Enterprise-Managed Authorization](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/stable/enterprise-managed-authorization.mdx) +The directory that holds an extension's specification shows its stage: `specification/experimental/`, `specification/beta/` or `specification/stable/`. [SEP-3392](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3392) defines the stages. -### Draft +### Stable -- [Client Credentials](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/oauth-client-credentials.mdx) +- [Enterprise-Managed Authorization](./specification/stable/enterprise-managed-authorization/2026-07-28/enterprise-managed-authorization.mdx) ([draft](./specification/stable/enterprise-managed-authorization/draft/enterprise-managed-authorization.mdx)) +- [OAuth Client Credentials](./specification/stable/oauth-client-credentials/2026-07-28/oauth-client-credentials.mdx) ([draft](./specification/stable/oauth-client-credentials/draft/oauth-client-credentials.mdx)) ## Governance -This repository follows the [Model Context Protocol Governance](https://modelcontextprotocol.io/community/governance) process, with a dedicated set of maintainers for authorization extensions. See [MAINTAINERS.md](./MAINTAINERS.md) for the list of maintainers specific to this repository. +This repository follows the [Model Context Protocol Governance](https://modelcontextprotocol.io/community/governance) process, with a dedicated set of Extension Maintainers for authorization extensions, listed in [MAINTAINERS.md](./MAINTAINERS.md). The extensions are associated with the [Authorization Interest Group](https://modelcontextprotocol.io/community/interest-groups/auth). All decisions regarding authorization extensions follow the same governance model as the core specification, including: diff --git a/specification/stable/enterprise-managed-authorization/2026-07-28/enterprise-managed-authorization.mdx b/specification/stable/enterprise-managed-authorization/2026-07-28/enterprise-managed-authorization.mdx new file mode 100644 index 0000000..5f5f4e5 --- /dev/null +++ b/specification/stable/enterprise-managed-authorization/2026-07-28/enterprise-managed-authorization.mdx @@ -0,0 +1,270 @@ +--- +title: Enterprise-Managed Authorization +--- + +**Protocol Revision**: 2026-07-28 + +## 1. Introduction + +### 1.1 Purpose and Scope + +This document defines an application of the "[Identity Assertion JWT Authorization Grant](https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-assertion-authz-grant/)" for use within enterprise deployments of the Model Context Protocol (MCP). + +When an MCP Client and MCP Server are both enabled for single sign-on through an enterprise Identity Provider, this three-way relationship can be leveraged to streamline the authorization process. + +This document specifies how an MCP Client can obtain an access token from an MCP Server's authorization server by presenting an identity assertion it previously obtained from an enterprise Identity Provider during single sign-on, and how that authorization server validates the request before issuing an access token. + +This profile is designed to facilitate secure and interoperable authorization within enterprise environments, leveraging the organization's existing identity infrastructure. Enterprise-managed authorization for MCP Clients and Servers has some key benefits: + +- For end users, this removes the need to manually connect and authorize the MCP Client to each MCP Server for use within the organization. +- For enterprise admins, this enables visibility and control over which MCP Servers are able to be used within the organization. +- For MCP clients, this enables the client to automatically obtain access tokens for any connected MCP servers without user interaction, and removes the need for user interaction when obtaining new access tokens. + +### 1.2 Roles and Terminology + +This document uses the roles and terms defined in [Section 2 of draft-ietf-oauth-identity-assertion-authz-grant](https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-04.html#section-2). In the context of this profile: + +- The **Client** is the MCP Client. +- The **Resource Server** is the MCP Server. +- The **Resource Authorization Server** is the authorization server that issues access tokens for the MCP Server, as advertised in the MCP Server's Protected Resource Metadata ([RFC9728](https://datatracker.ietf.org/doc/html/rfc9728)). +- The **IdP Authorization Server (IdP)** is the enterprise Identity Provider used for single sign-on. + +## 2. Identity Assertion Authorization Grant Overview + +This profile is an application of the "Identity Assertion JWT Authorization Grant" [draft-ietf-oauth-identity-assertion-authz-grant](https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-assertion-authz-grant/), which itself is a profile of "Identity Chaining Across Trust Domains" [draft-ietf-oauth-identity-chaining](https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-chaining/). + +The Identity Assertion JWT Authorization Grant follows three steps: + +1. Single Sign-On to the MCP Client via OpenID Connect or SAML + 1a. optionally exchange the SAML assertion for a Refresh Token +2. Token Exchange ([RFC8693](https://datatracker.ietf.org/doc/html/rfc8693)) +3. JWT Authorization Grant ([RFC7523](https://datatracker.ietf.org/doc/html/rfc7523)) + +The core flow is as follows: + +- A user logs in to an MCP Client through their enterprise Identity Provider, resulting in an Identity Assertion (ID Token or SAML assertion) being issued to the MCP Client. +- For SAML: + - The MCP Client sends a Token Exchange request to the Identity Provider with the SAML assertion, and obtains a Refresh Token. +- The MCP Client sends a Token Exchange [[RFC8693](https://datatracker.ietf.org/doc/html/rfc8693)] request to the Identity Provider including the ID Token or Refresh Token, and the identifier of the MCP Server it is attempting to access, and obtains a Identity Assertion JWT Authorization Grant (ID-JAG). +- The MCP Client uses the Identity Assertion JWT Authorization Grant as a JWT Authorization Grant [[RFC7523](https://datatracker.ietf.org/doc/html/rfc7523)] to request an access token from the Resource Authorization Server. +- The Resource Authorization Server validates the Identity Assertion JWT Authorization Grant and, if valid, issues an access token. +- The MCP Client uses the access token to make requests to the MCP Server. + +### 2.1 Sequence Diagram + +The following diagram outlines an example flow: + +```mermaid +sequenceDiagram + participant UA as Browser + participant C as MCP Client + participant IdP as Identity Provider + participant MAS as MCP Authorization Server + participant MRS as MCP Resource Server + + C-->>UA: Redirect to IdP + UA->>IdP: Redirect to IdP + Note over IdP: User Logs In + IdP-->>UA: IdP Authorization Code + UA->>C: IdP Authorization Code + C->>IdP: Token Request with IdP Authorization Code + IdP-->>C: ID Token + + note over C: User is logged
in to MCP Client.
Client stores ID Token. + + C->>IdP: Exchange ID Token for ID-JAG + note over IdP: Evaluate Policy + IdP-->>C: Responds with ID-JAG + C->>MAS: Token Request with ID-JAG + note over MAS: Validate ID-JAG + MAS-->>C: MCP Access Token + + loop + C->>MRS: Call MCP API with Access Token + MRS-->>C: MCP Response with Data + end +``` + +## 3. User Authentication + +To authenticate a user, the MCP Client initiates the process through a request with the IdP using OpenID Connect or SAML. + +For example, a web-based MCP client might initiate the user authentication process by redirecting the browser using OpenID Connect: + +``` +302 Redirect +Location: https://acme.idp.example/authorize?response_type=code&scope=openid&client_id=... +``` + +The user authenticates with the IdP, and is redirected back to the Client with an authorization code, which it can then exchange for an ID Token. + +The enterprise IdP may enforce additional security controls such as multi-factor authentication before granting the user access to the MCP Client. +For example, in an OpenID Connect flow, after receiving a redirect from the IdP with an authorization code, the MCP Client makes a request to the IdP's token endpoint and, if valid, receives the tokens in the response: + +``` +POST /token HTTP/1.1 +Host: acme.idp.example +Content-Type: application/x-www-form-urlencoded + +grant_type=authorization_code +&code=..... + +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "id_token": "eyJraWQiOiJzMTZ0cVNtODhwREo4VGZCXzdrSEtQ...", + "token_type": "Bearer", + "access_token": "7SliwCQP1brGdjBtsaMnXo", + "scope": "openid" +} +``` + +## 4. Token Exchange + +To request an ID-JAG, the MCP Client makes a Token Exchange request to the IdP's token endpoint as defined in [Section 4.3 of draft-ietf-oauth-identity-assertion-authz-grant](https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-04.html#section-4.3). + +In this profile: + +- `audience` **MUST** be the issuer identifier of the Resource Authorization Server. +- `resource` is **OPTIONAL** and if set, **MUST** be the Resource Identifier of the MCP Server as defined in [RFC9728](https://datatracker.ietf.org/doc/html/rfc9728). + +If the IdP requires client authentication when the MCP Client performs OpenID Connect for single sign-on, then client authentication of the Token Exchange request is also required. + +The example below illustrates the Token Exchange request, using an OpenID Connect ID Token as the Identity Assertion and a client secret as the client authentication method. The ID token is passed as a Subject Token. + +``` +POST /oauth2/token HTTP/1.1 +Host: acme.idp.example +Content-Type: application/x-www-form-urlencoded + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange +&requested_token_type=urn:ietf:params:oauth:token-type:id-jag +&audience=https://auth.chat.example/ +&resource=https://mcp.chat.example/ +&scope=chat.read+chat.history +&subject_token=eyJraWQiOiJzMTZ0cVNtODhwREo4VGZCXzdrSEtQ... +&subject_token_type=urn:ietf:params:oauth:token-type:id_token +&client_id=2ec954a1d60620116d36d9ceb7 +&client_secret=a26d84873504215a34a86d52ef5cd64f4b76 +``` + +If the client uses SAML for single sign-on to the IdP, see [Section 4.5](https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-04.html#section-4.5) for details on how the client can exchange the SAML assertion for a refresh token, then use the refresh token to request an ID-JAG. + +### 4.1 Processing Rules + +The IdP processes the request according to [Section 4.3.3 of draft-ietf-oauth-identity-assertion-authz-grant](https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-04.html#section-4.3.3). The IdP evaluates administrator-defined policies for the token exchange request and determines if the MCP Client should be granted access to act on behalf of the user for the target MCP Server and scopes. + +### 4.2 Token Exchange Response + +If access is granted, the IdP returns the ID-JAG in a token exchange response as defined in [Section 4.3.4 of draft-ietf-oauth-identity-assertion-authz-grant](https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-04.html#section-4.3.4): + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store +Pragma: no-cache + +{ + "issued_token_type": "urn:ietf:params:oauth:token-type:id-jag", + "access_token": "eyJhbGciOiJIUzI1NiIsI...", + "token_type": "N_A", + "scope": "chat.read chat.history", + "expires_in": 300 +} +``` + +Error responses are returned as OAuth 2.0 Token Error responses per [Section 5.2 of RFC6749](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2). + +### 4.3 Identity Assertion JWT Authorization Grant + +The ID-JAG is a JWT issued and signed by the IdP with the claims defined in [Section 3.1 of draft-ietf-oauth-identity-assertion-authz-grant](https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-04.html#section-3.1). + +In this profile, the `resource` claim **MUST** contain the Resource Identifier of the MCP Server if present. + +An example JWT shown with expanded header and payload claims may look like this: + +``` +{ + "typ": "oauth-id-jag+jwt" +} +. +{ + "jti": "9e43f81b64a33f20116179", + "iss": "https://acme.idp.example", + "sub": "U019488227", + "email": "user@example.com", + "aud": "https://auth.chat.example/", + "resource": "https://mcp.chat.example/", + "client_id": "f53f191f9311af35", + "exp": 1311281970, + "iat": 1311280970, + "scope": "chat.read chat.history" +} +. +signature +``` + +See [Section 6 of draft-ietf-oauth-identity-assertion-authz-grant](https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-04.html#section-6) for handling of multi-tenant issuers and subject identifier uniqueness. + +## 5. Access Token Request + +The MCP Client presents the ID-JAG to the Resource Authorization Server's token endpoint as defined in [Section 4.4 of draft-ietf-oauth-identity-assertion-authz-grant](https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-04.html#section-4.4), using `grant_type` `urn:ietf:params:oauth:grant-type:jwt-bearer` and the ID-JAG as the `assertion`. + +The MCP Client authenticates with its credentials as registered with the Resource Authorization Server. + +If the MCP Client is not pre-registered with the Resource Authorization Server, then it can use its [Client ID Metadata Document](/specification/2025-11-25/basic/authorization#client-id-metadata-documents) as its client ID, and optionally authenticate using [private_key_jwt](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-01.html#section-6.2). + +An example request may look like this: + +``` +POST /oauth2/token HTTP/1.1 +Host: auth.chat.example + +grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer +&assertion=eyJhbGciOiJIUzI1NiIsI... +&client_id=https://client.example.com/client.json +``` + +### 5.1 Processing Rules + +The Resource Authorization Server processes the request according to [Section 4.4.1 of draft-ietf-oauth-identity-assertion-authz-grant](https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-04.html#section-4.4.1). + +In this profile, the issued access token **MUST** be audience-restricted to the MCP Server identified by the `resource` claim in the ID-JAG. + +### 5.2 Access Token Response + +The Resource Authorization Server responds with an OAuth 2.0 Token Response, like this: + +``` +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store + +{ + "token_type": "Bearer", + "access_token": "2YotnFZFEjr1zCsicMWpAA", + "expires_in": 86400, + "scope": "chat.read chat.history" +} +``` + +## 6. Discovery + +An MCP Client can determine that a Resource Authorization Server supports this profile by checking for `urn:ietf:params:oauth:grant-profile:id-jag` in the `authorization_grant_profiles_supported` field of the server's authorization server metadata, as defined in [Section 7.2 of draft-ietf-oauth-identity-assertion-authz-grant](https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-04.html#section-7.2). + +## 7. Security Considerations + +### 7.1 Client Registration + +In most enterprise deployments, the IdP policy will only allow users to sign in to pre-registered clients. The MCP client will likely need to be pre-registered with the enterprise IdP for single sign-on. + +See [Section 5 of draft-ietf-oauth-identity-assertion-authz-grant](https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-04.html#section-5) for how the IdP determines the `client_id` value to include in the ID-JAG. + +### 7.2 Scope of Enterprise Visibility and Policy Enforcement + +This specification enables the enterprise IdP to be part of the issuance of the access token at the MCP Server. The visibility the IdP has between the MCP Client and MCP Server is limited to the process of issuing the access token, but does not extend to the actual MCP traffic between the MCP Client and Server. + +This enables the enterprise IdP to enforce policies such as which users in the organization can use certain MCP clients with certain MCP servers. Depending on the granularity of the OAuth scopes defined at the MCP server, this can also extend to govern which scopes a given user can request. + +For example, the enterprise policy of granting an access token through this extension may allow users in the "engineering" group to get read-only access from an AI code editor to the source control MCP server, whereas users in the "marketing" group may be able to get read and write access to the internal documentation application. diff --git a/specification/stable/enterprise-managed-authorization.mdx b/specification/stable/enterprise-managed-authorization/draft/enterprise-managed-authorization.mdx similarity index 99% rename from specification/stable/enterprise-managed-authorization.mdx rename to specification/stable/enterprise-managed-authorization/draft/enterprise-managed-authorization.mdx index 586ce27..f4bf861 100644 --- a/specification/stable/enterprise-managed-authorization.mdx +++ b/specification/stable/enterprise-managed-authorization/draft/enterprise-managed-authorization.mdx @@ -2,7 +2,7 @@ title: Enterprise-Managed Authorization --- -**Status**: Stable +**Protocol Revision**: draft ## 1. Introduction diff --git a/specification/stable/oauth-client-credentials/2026-07-28/oauth-client-credentials.mdx b/specification/stable/oauth-client-credentials/2026-07-28/oauth-client-credentials.mdx new file mode 100644 index 0000000..656c5c8 --- /dev/null +++ b/specification/stable/oauth-client-credentials/2026-07-28/oauth-client-credentials.mdx @@ -0,0 +1,163 @@ +--- +title: OAuth Client Credentials Extension +--- + +
+ +**Protocol Revision**: 2026-07-28 + +## Introduction + +### Purpose and Scope + +This extension defines OAuth 2.1 Client Credentials flow support for the Model +Context Protocol, enabling machine-to-machine authentication without user +interaction. This extension builds upon the baseline authorization requirements +defined in the main [Authorization specification](../basic/authorization.mdx). + +### Extension Requirements + +This extension is **OPTIONAL** for MCP implementations. When adopted: + +- Implementations **MUST** conform to all requirements specified in this + extension +- Implementations **MUST** also conform to the baseline authorization + requirements +- This extension is specifically designed for HTTP-based transports + +### Standards Compliance + +This extension is based on the following established specifications: + +- OAuth 2.1 IETF DRAFT + ([draft-ietf-oauth-v2-1-13](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13)) +- OAuth 2.0 Authorization Server Metadata + ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)) +- OAuth 2.0 Protected Resource Metadata + ([RFC9728](https://datatracker.ietf.org/doc/html/rfc9728)) +- JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and + Authorization Grants + ([RFC7523](https://datatracker.ietf.org/doc/html/rfc7523)) + +## Client Credentials Flow + +### Overview + +The Client Credentials flow enables machine-to-machine authentication without +user interaction. This flow requires pre-registered client credentials, which +are typically established out-of-band through administrative channels. Dynamic +Client Registration is not used in this flow. + +### Client Authentication Methods + +Clients **MUST** authenticate using one of these methods: + +- JWT Authentication (RECOMMENDED) + - Clients use JWT Authentication as defined in + [RFC 7523 Section 2.2](https://datatracker.ietf.org/doc/html/rfc7523#section-2.2). +- Client Secret + - Clients use a Client Secret transmitted in the request content as defined + in + [OAuth 2.1 Section 2.4.1](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#name-client-secret) + +### Server Metadata Requirements + +When supporting the client credentials flow, Authorization Server metadata +**MUST** include the following fields: + +- `token_endpoint_auth_methods_supported`: **MUST** include at least one of: + - `"private_key_jwt"` + - `"client_secret_basic"` +- `token_endpoint_auth_signing_alg_values_supported`: Required when supporting + JWT authentication + +### Flow Steps + +The complete Client Credentials flow proceeds as follows: + +```mermaid +sequenceDiagram + participant C as Client + participant M as MCP Server (Resource Server) + participant A as Authorization Server + + C->>M: MCP request without token + M->>C: HTTP 401 Unauthorized with WWW-Authenticate header + Note over C: Extract resource_metadata URL from WWW-Authenticate + + C->>M: Request Protected Resource Metadata + M->>C: Return metadata + + Note over C: Parse metadata and extract authorization server(s)
Client determines AS to use + + C->>A: GET Authorization server metadata endpoint + Note over C,A: Try OAuth 2.0 and OpenID Connect
discovery endpoints in priority order + A-->>C: Authorization server metadata + + Note over C: Prepare client authentication + alt JWT Authentication (RECOMMENDED) + Note over C: Generate signed JWT assertion + C->>A: POST /token with client_assertion + else Client Secret Authentication + Note over C: Use client_id and client_secret + C->>A: POST /token with client credentials + end + A->>C: Access token + C->>M: MCP request with access token + M-->>C: MCP response + Note over C,M: MCP communication continues with valid token +``` + +### Examples + +The following examples illustrate both client authentication methods: + +#### JWT Authentication Example + +``` +POST /token HTTP/1.1 +Host: auth.example.com +Content-Type: application/x-www-form-urlencoded + +grant_type=client_credentials +&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer +&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0. + eyJpc3Mi[...omitted for brevity...]. + cC4hiUPo[...omitted for brevity...] +&resource=https%3A%2F%2Fmcp.example.com +&scope=mcp%3Aread +``` + +> **Note:** The `client_id` parameter is omitted from the request body as +> [RFC 7523 Section 3](https://datatracker.ietf.org/doc/html/rfc7523#section-3) +> specifies that client identification is conveyed through the `sub` claim +> within the JWT assertion. + +#### Client Secret Authentication Example + +``` +POST /token HTTP/1.1 +Host: auth.example.com +Content-Type: application/x-www-form-urlencoded + +grant_type=client_credentials +&client_id=s6BhdRkqt3 +&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw +&resource=https%3A%2F%2Fmcp.example.com +&scope=mcp%3Aread +``` + +## Security Considerations + +Implementations adopting this extension **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), +with particular attention to: + +- Client authentication security +- Token storage and handling +- Communication security requirements +- Client credential protection + +For detailed security guidance specific to client credentials flows, refer to +[RFC 7523 Section 5 "Security Considerations"](https://datatracker.ietf.org/doc/html/rfc7523#section-5). diff --git a/specification/draft/oauth-client-credentials.mdx b/specification/stable/oauth-client-credentials/draft/oauth-client-credentials.mdx similarity index 100% rename from specification/draft/oauth-client-credentials.mdx rename to specification/stable/oauth-client-credentials/draft/oauth-client-credentials.mdx