From f495d9eef5abddfca615eec4c0ab04725232ccf4 Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Fri, 5 Dec 2025 17:31:17 +0000 Subject: [PATCH 1/3] Create workload-identity-federation.mdx Initial Draft --- .../draft/workload-identity-federation.mdx | 522 ++++++++++++++++++ 1 file changed, 522 insertions(+) create mode 100644 specification/draft/workload-identity-federation.mdx diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx new file mode 100644 index 0000000..e102321 --- /dev/null +++ b/specification/draft/workload-identity-federation.mdx @@ -0,0 +1,522 @@ +# Workload Identity Federation + +## Introduction + +### Purpose and Scope + +This extension defines Workload Identity Federation for the Model Context +Protocol, enabling autonomous MCP clients to access MCP servers using existing +workload identity credentials without requiring separate client registration or +long-lived credentials. This extension builds upon the baseline authorization +requirements defined in the main Authorization specification. + +Workload Identity Federation is designed for scenarios where an MCP client +operates as an autonomous workload - that is, the client authenticates and +authorizes as itself rather than through an interactive OAuth authorization +flow on behalf of an end-user. In these deployments, the MCP client effectively +functions as a workload within a workload platform (such as Kubernetes or cloud +provider environments). Like the Client Credentials extension, this pattern +addresses machine-to-machine authentication use cases. + +This extension allows an MCP client that already possesses a JWT credential +(issued by its workload platform, SPIFFE infrastructure, or other trusted +identity provider) to present that credential directly to an authorization +server protecting an MCP server. The authorization server validates the JWT and +issues a temporary access token suitable for accessing the MCP server. + +This approach eliminates the need for: +- Client credentials (client secrets or private keys) +- Client identifiers (client_id) +- Client registration (including Dynamic Client Registration) +- Managing separate credentials for each service the client needs to access + +Instead, MCP clients leverage their existing platform-provided workload identity +and "federate" to other services through trust relationships configured in the +authorization server. This significantly simplifies workload-to-service +access patterns while maintaining security through proper issuer trust +and claim-based authorization. + +### 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 +- This extension is designed for autonomous MCP clients operating as workloads + +### Standards Compliance + +This extension is based on the following established specifications: + +- JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and + Authorization Grants ([RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523)) +- OpenID Connect Discovery 1.0 + ([OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)) +- JSON Web Key (JWK)([RFC7517](https://datatracker.ietf.org/doc/html/rfc7517)) + +## Workload Identity Federation Flow + +### Overview + +Workload Identity Federation enables autonomous MCP clients to obtain access +tokens for MCP servers by presenting existing JWT credentials issued to them as +workloads. The flow involves three primary entities: + +- **MCP Client**: An autonomous client seeking access to an MCP server, + possessing a JWT credential from a trusted issuer. The MCP client functions + as a workload within its deployment environment. +- **Authorization Server**: The OAuth 2.0 authorization server protecting the + MCP server, responsible for validating workload JWTs and issuing access + tokens +- **MCP Server**: The resource server that accepts access tokens issued by the + authorization server + +The authorization server MUST be pre-configured with trust relationships to +specific JWT issuers and rules determining which workload identities are +authorized to receive access tokens. + +### Message Flow +The message flow combines using a JWT as an authorization grant as defined in +[RFC7523](https://datatracker.ietf.org/doc/html/rfc7523) with automated issuer +discovery as described in [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) +to obtain the [RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) JWK +Key set which is used to validate the JWT authorization grant. + +The complete Workload Identity Federation flow proceeds as follows: + +```mermaid +sequenceDiagram + participant Client as MCP Client + participant Auth as Authorization
Server + participant OIDC as OIDC
Discovery
Endpoint + participant JWKS_URI as JWK Set
Location + participant Server as MCP Server + + Client->>Auth: 1. Request Access Token + Note over Auth: 2. Construct OpenID Provider Discovery Endpoint URL + Auth->>OIDC: 3. Request OpenID Provider Configuration Document + OIDC->>Auth: 4. Return OpenID Provider Configuration Document + Note over Auth: 5. Extract `jwks_uri` + Auth->>JWKS_URI: 6. Request JWK Set + JWKS_URI->>Auth: 7. Return JWK Set + Note over Auth: 8. Validate JWT
Authorization Grant + Auth->>Client: 9. Return Access Token + Client->>Server: 10. MCP Server Access + Note over Server: 11. Validate Access Token + Server->>Client: 12. MCP Server Response +``` + +### Flow Steps + +1. **Request Access Token**: The MCP client requests an access token through a + POST request to the authorization server's token endpoint using the JWT Bearer + grant type as specified in + [RFC 7523 Section 2.1](https://datatracker.ietf.org/doc/html/rfc7523#section-2.1). + The request includes: + - `grant_type`: `urn:ietf:params:oauth:grant-type:jwt-bearer` + - `assertion`: The client's workload JWT credential + - `resource`: The canonical URI of the target MCP server (as defined in the + baseline MCP Authorization specification) + +2. **Construct OpenID Provider Discovery Endpoint URL**: The authorization server extracts the `iss` (issuer) + claim from the JWT and determines if it is a trusted issuer. If the issuer is + trusted, the authorization server constructs the OpenID Provider Discovery Endpoint URL from the issuer + claim as described in Section 4 of [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig). + +3. **Request OpenID Provider Configuration Document**: The authorization server requests the OpenID Provider Configuration Document + as described in Section 4.1 of [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest). + +4. **Return OpenID Provider Configuration Document** The OpenID Provider Configuration Document is returned as described in Section 4.2 of [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse). + +5. **Extract `jwks_uri`**: The authorization server validates the OpenID Provider Configuration Document as + described in Section 4.3 of [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationValidation) and extracts the `jwks_uri` configuration information. + +6. **Request JWK Set**: The authorization server retrieves the + [RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) JWK set + containing the issuer's public keys from the TLS protected location specified by + `jwks_uri` configuration information. + +7. **Return JWK Set**: The JWK set is returned from the TLS protected location. + +8. **Validate JWT Authorization Grant**: The authorization server validates the + JWT authorization grant according to + [RFC 7523 Section 3](https://datatracker.ietf.org/doc/html/rfc7523#section-3), + with considerations specified in this document. This includes verifying the + signature using the retrieved public keys and validating that the JWT claims + meet the authorization server's configured trust and authorization + requirements. + +9. **Return Access Token**: If JWT validation succeeds, the authorization server + issues an access token suitable for accessing the specified MCP server and + returns it to the MCP client per + [RFC 7523 Section 2.1](https://datatracker.ietf.org/doc/html/rfc7523#section-2.1). + +10. **MCP Server Access**: The MCP client makes a JSON-RPC request to the MCP + server, including the access token in the `Authorization` header using the + `Bearer` authentication scheme as specified in the baseline MCP Authorization + specification. + +7. **Validate Access Token**: The MCP server validates the access token according to + the baseline MCP Authorization specification requirements, including + verifying the token was issued for the MCP server as the intended audience. + +8. **MCP Server Response**: If the token is valid and the MCP client is authorized, the + MCP server processes the request and returns the JSON-RPC response. + +## JWT Requirements + +### JWT Format + +The workload JWT presented by the MCP client MUST be a signed JWT conforming to +[RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523). The JWT MUST contain +at least the following claims: + +- `iss` (Issuer): Identifies the issuer of the JWT. This value is used for + issuer discovery and trust validation. +- `sub` (Subject): Identifies the workload. This may be any identifier that + uniquely identifies the workload within the issuer's domain. Examples include + SPIFFE IDs, platform-specific workload identifiers, or service account names. +- `aud` (Audience): Identifies the intended audience for the JWT. This MUST be + the authorization server's token endpoint URL. +- `exp` (Expiration Time): The time after which the JWT MUST NOT be accepted. +- `iat` (Issued At): The time at which the JWT was issued. +- `jti` (JWT ID): A unique identifier for the JWT to prevent replay attacks. + +Additional claims MAY be present and MAY be used by the authorization server in +making authorization decisions. + +Example JWT payload: + +```json +{ + "iss": "https://issuer.example.org", + "sub": "spiffe://example.org/ns/default/sa/customer-router-agent", + "aud": "https://auth.example.com/token", + "jti": "jwt-grant-id-x1y2z3a4", + "exp": 1744845092, + "iat": 1744841036 +} +``` + +### JWT Validation + +Authorization servers MUST validate the JWT according to +[RFC 7523 Section 3](https://datatracker.ietf.org/doc/html/rfc7523#section-3), +with the following considerations: + +- The `sub` (subject) claim identifies the workload but does not identify a + resource owner or correspond to an OAuth `client_id`. +- The authorization server MUST verify that the issuer is trusted according to + its configured trust relationships. +- The authorization server MUST verify the JWT signature using keys retrieved + from a TLS protected URI as described in this specification. +- The authorization server MUST apply configured authorization rules to + determine whether the specific workload identified in the JWT claims should + receive an access token. + +### JWT Provisioning + +How MCP clients obtain their workload JWT credentials is outside the scope of +this specification. Workload JWTs are typically provisioned by: + +- Workload platforms (e.g. Kubernetes) +- SPIFFE implementations +- Identity providers integrated with workload deployment systems + +The JWT provisioning mechanism relies on a separate registration or attestation +process that establishes trust between the workload and the JWT issuer. + +## Authorization Server Requirements +### Issuer Key Discovery +Authorization servers MUST support OpenID Connect Discovery +[OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) +for discovering issuer configuration and retrieving issuer public keys +as described in in this specification. + +Example issuer configuration request: + +```http +GET /.well-known/openid-configuration HTTP/1.1 +Host: issuer.example.org +``` + +Example issuer configuration response: + +```json +{ + "issuer": "https://issuer.example.org", + "jwks_uri": "https://issuer.example.org/.well-known/jwks.json", + "token_endpoint": "https://issuer.example.org/token" +} +``` + +### Issuer Key Retrieval +The issuer keys MUST be published as a [RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) JWK Key set and it MUST be +retrieved from a TLS protected URI. + +### Trust Configuration + +Authorization servers MUST implement mechanisms to configure: + +1. **Issuer Trust**: Which JWT issuers are trusted to authenticate workloads +2. **Claim-Based Authorization**: Rules determining which workloads (based on + JWT claims) are authorized to receive access tokens for specific MCP servers + +The specific implementation of these configuration mechanisms is outside the +scope of this specification. However, authorization servers SHOULD provide +administrative interfaces or APIs for managing these trust relationships and +authorization rules. + +### Token Endpoint + +Authorization servers supporting this extension MUST support the JWT Bearer +grant type at their token endpoint as specified in +[RFC 7523 Section 2.1](https://datatracker.ietf.org/doc/html/rfc7523#section-2.1). + +The token endpoint MUST accept requests with: +- `grant_type`: `urn:ietf:params:oauth:grant-type:jwt-bearer` +- `assertion`: The workload JWT +- `resource`: The target MCP server URI (as specified in the baseline MCP + Authorization specification) + +Additional parameters MAY be supported but are not required by this +specification. + +### Authorization Server Metadata + +Authorization servers supporting this extension MUST include the +`grant_types_supported` field in their Authorization Server Metadata as defined +in [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). + +The `grant_types_supported` array MUST include the value +`urn:ietf:params:oauth:grant-type:jwt-bearer`. + +Example Authorization Server Metadata: + +```json +{ + "issuer": "https://auth.example.com", + "token_endpoint": "https://auth.example.com/token", + "grant_types_supported": [ + "authorization_code", + "refresh_token", + "urn:ietf:params:oauth:grant-type:jwt-bearer" + ] +} +``` + +## MCP Server Requirements + +MCP servers accepting access tokens issued through Workload Identity Federation +MUST validate tokens according to the baseline MCP Authorization specification +requirements. + +No additional requirements are imposed on MCP servers by this extension. + +## Examples + +### Complete Token Exchange Example + +**Token Request:** + +```http +POST /token HTTP/1.1 +Host: auth.example.com +Content-Type: application/x-www-form-urlencoded + +grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer +&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InNpZ25pbmcta2V5 +LTEifQ.eyJpc3MiOiJodHRwczovL2lzc3Vlci5leGFtcGxlLm9yZyIsInN1YiI6InNwaWZmZ +TovL2V4YW1wbGUub3JnL25zL2RlZmF1bHQvc2EvY3VzdG9tZXItcm91dGVyLWFnZW50IiwiY +XVkIjoiaHR0cHM6Ly9hdXRoLmV4YW1wbGUuY29tL3Rva2VuIiwianRpIjoiand0LWdyYW50L +WlkLXgxeTJ6M2E0IiwiZXhwIjoxNzQ0ODQ1MDkyLCJpYXQiOjE3NDQ4NDEwMzZ9.EXAMPLE +_SIGNATURE +&resource=https%3A%2F%2Fmcp.example.com +``` + +**Decoded JWT Assertion:** + +Header: +```json +{ + "alg": "RS256", + "typ": "JWT", + "kid": "signing-key-1" +} +``` + +Payload: +```json +{ + "iss": "https://issuer.example.org", + "sub": "spiffe://example.org/ns/default/sa/customer-router-agent", + "aud": "https://auth.example.com/token", + "jti": "jwt-grant-id-x1y2z3a4", + "exp": 1744845092, + "iat": 1744841036 +} +``` + +**Token Response:** + +```http +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store + +{ + "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImF1dGgtc +2VydmVyLWtleS0xIn0.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiO +iJzcGlmZmU6Ly9leGFtcGxlLm9yZy9ucy9kZWZhdWx0L3NhL2N1c3RvbWVyLXJvdXRlci1hZ +2VudCIsImF1ZCI6Imh0dHBzOi8vbWNwLmV4YW1wbGUuY29tIiwiZXhwIjoxNzQ0ODQ0NjM2L +CJpYXQiOjE3NDQ4NDEwMzYsInNjb3BlIjoibWNwOnJlYWQgbWNwOndyaXRlIn0.EXAMPLE_S +IGNATURE", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "mcp:read mcp:write" +} +``` + +**MCP Server Request:** + +```http +POST /mcp HTTP/1.1 +Host: mcp.example.com +Content-Type: application/json +Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImF1dGg +tc2VydmVyLWtleS0xIn0... + +{ + "jsonrpc": "2.0", + "method": "tools/list", + "id": 1 +} +``` + +### Error Response Example + +When the JWT is invalid or the workload is not authorized: + +```http +HTTP/1.1 400 Bad Request +Content-Type: application/json +Cache-Control: no-store + +{ + "error": "invalid_grant", + "error_description": "The provided JWT assertion is invalid or the +workload is not authorized to access the requested resource" +} +``` + +## Trust Relationships + +For functional Workload Identity Federation, trust must be established at +multiple levels: + +1. **Issuer Trust**: The authorization server MUST trust the JWT issuer +2. **Workload Trust**: The authorization server MUST trust the specific workload + based on claims within the JWT + +These two trust relationships serve different purposes and SHOULD be managed +independently. + +### Issuer Trust Relationship + +Issuer trust represents the foundational level of trust and determines whether +JWT bearer tokens from a particular issuer are accepted. This trust relationship +is between the authorization server and the JWT issuer only. + +Issuer trust is typically established at a global or tenant-wide level and is +subject to organizational policy and governance controls. Changes to issuer +trust affect all workloads associated with that issuer simultaneously. + +The mechanism for establishing issuer trust is implementation-specific and +outside the scope of this specification. Common approaches include: +- Maintaining an allowlist of trusted issuer URLs +- Configuring issuer metadata endpoints for automatic key discovery +- Associating issuers with specific tenants or organizational units + +### Workload Trust Relationship + +Workload trust builds upon issuer trust and focuses on the relationship between +the authorization server and individual workloads. Once the JWT bearer token is +validated (signature verified and issuer trusted), the authorization server +must determine whether the specific workload identified in the JWT claims should +receive an access token. + +Workload trust is typically established individually based on: +- The `sub` (subject) claim identifying the workload +- Additional claims such as namespace, tenant identifier, or service account +- Combinations of multiple claims forming a compound identity + +This trust is subject to different policy and governance controls than issuer +trust, often allowing more granular per-workload authorization decisions. + +### Multi-Tenancy Considerations + +When workload platforms or authorization servers support multiple tenants, +additional care must be taken to prevent privilege escalation across tenant +boundaries. + +Authorization servers SHOULD: +- Rely on JWT issuing keys bound to a single tenant of the workload platform, + rather than a single issuing key for all tenants in a platform. +- Use specific JWT claims to prevent any JWT signed by the issuer from being + used to impersonate any principal. +- NOT solely rely on JWT claims that can be controlled by any tenant. +- MAY rely on a "tenant" claim if the claim value is issuer-controlled and + corresponds to a single tenant. + +See the Security Considerations section for additional details on privilege +escalation prevention. + +## Security Considerations + +Implementations adopting this extension MUST follow the security considerations +outlined in: + +- [RFC 7523 Section 4 "Security Considerations"](https://datatracker.ietf.org/doc/html/rfc7523#section-4) +- [RFC 7517 Section 9 "Security Considerations"](https://datatracker.ietf.org/doc/html/rfc7517#section-9) +- [OpenID Connect Discovery 1.0, Section 7 "Security Considerations"](https://openid.net/specs/openid-connect-discovery-1_0.html#Security) +- The baseline MCP Authorization specification security requirements + +### JWT Validity and Lifetime + +JWT validity SHOULD be set to the shortest possible duration allowable by +overall system availability constraints. Short-lived JWTs (on the order of +seconds to minutes) reduce the window of opportunity for stolen JWTs to be +misused. + +A secure channel (e.g., TLS) MUST be used when providing a JWT for +Workload Identity Federation. JWTs SHOULD be protected from unauthorized +access using operating system or platform access controls. + +### Identity Translation and Privilege Escalation + +The translation of workload JWT claims to MCP server access tokens represents a +critical trust boundary. Improper configuration of this translation can lead to +privilege escalation attacks, particularly in multi-tenant environments. See +the "Multi-Tenancy Considerations" section for specific guidance on multi-tenant +deployments. + +The following recommendations apply to all deployments: +- Configuration SHOULD NOT permit the transcription of JWT claims to access + token claims without additional validation +- Authorization servers SHOULD implement explicit allowlists or policies + defining which workload identities can access which MCP servers +- Authorization servers SHOULD log and audit all token issuance decisions for + security monitoring + +### Issuer Key Retrieval Security + +Authorization servers MUST validate issuer URLs and ensure they use HTTPS. +Authorization servers SHOULD implement the following protections: + +- Maintain an allowlist of permitted issuer domains to prevent malicious issuer + discovery +- Validate TLS certificates when retrieving issuer configuration and JWKs +- Implement reasonable timeouts and rate limits on issuer discovery requests +- Cache issuer configurations and JWKs appropriately to reduce attack surface +- Monitor for issuer configuration changes that might indicate compromise From a23b33ee41727c82eeb43560580df6fb395b6c3c Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Mon, 12 Jan 2026 12:12:37 +0000 Subject: [PATCH 2/3] Refine Workload Identity Federation documentation Clarified the prerequisites for the authorization server and improved the description of the message flow. Updated terminology for issuer trust and added details on token validation. --- .../draft/workload-identity-federation.mdx | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index e102321..af99d33 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -11,7 +11,7 @@ long-lived credentials. This extension builds upon the baseline authorization requirements defined in the main Authorization specification. Workload Identity Federation is designed for scenarios where an MCP client -operates as an autonomous workload - that is, the client authenticates and +operates as an autonomous workload, that is, the client authenticates and authorizes as itself rather than through an interactive OAuth authorization flow on behalf of an end-user. In these deployments, the MCP client effectively functions as a workload within a workload platform (such as Kubernetes or cloud @@ -72,16 +72,15 @@ workloads. The flow involves three primary entities: - **MCP Server**: The resource server that accepts access tokens issued by the authorization server -The authorization server MUST be pre-configured with trust relationships to -specific JWT issuers and rules determining which workload identities are -authorized to receive access tokens. +As a prerequisite for this flow, the authorization server MUST be configured with a set of JWT issuers (defined by a URL), which are considered 'trusted issuers'. The nature of the trusted relationship and the mechanism by which the set is populated or maintained is out of scope of this document and left up to the implementer. JWTs not issued by these trusted issuers can be safely rejected by the authorization server. ### Message Flow The message flow combines using a JWT as an authorization grant as defined in [RFC7523](https://datatracker.ietf.org/doc/html/rfc7523) with automated issuer discovery as described in [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) to obtain the [RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) JWK -Key set which is used to validate the JWT authorization grant. +Key set which is used to validate the JWT authorization grant before the +authorization server issues an access token. The complete Workload Identity Federation flow proceeds as follows: @@ -154,12 +153,15 @@ sequenceDiagram 10. **MCP Server Access**: The MCP client makes a JSON-RPC request to the MCP server, including the access token in the `Authorization` header using the - `Bearer` authentication scheme as specified in the baseline MCP Authorization + `Bearer` authentication scheme as specified in the baseline + [MCP Authorization](https://modelcontextprotocol.io/specification/draft/basic/authorization) specification. 7. **Validate Access Token**: The MCP server validates the access token according to - the baseline MCP Authorization specification requirements, including - verifying the token was issued for the MCP server as the intended audience. + the baseline + [MCP Authorization](https://modelcontextprotocol.io/specification/draft/basic/authorization) + specification, including verifying the token was issued for the MCP + server as the intended audience. 8. **MCP Server Response**: If the token is valid and the MCP client is authorized, the MCP server processes the request and returns the JSON-RPC response. @@ -259,7 +261,7 @@ retrieved from a TLS protected URI. Authorization servers MUST implement mechanisms to configure: -1. **Issuer Trust**: Which JWT issuers are trusted to authenticate workloads +1. **Trust Issuers**: Which JWT issuers are trusted to authenticate workloads 2. **Claim-Based Authorization**: Rules determining which workloads (based on JWT claims) are authorized to receive access tokens for specific MCP servers From 5c2a22fe12a332037521b23f9101b839d858f42d Mon Sep 17 00:00:00 2001 From: Paul Carleton Date: Fri, 23 Oct 2026 15:34:30 +0000 Subject: [PATCH 3/3] Add Workload Identity Federation as an experimental extension Move Pieter Kasselman's Workload Identity Federation text from specification/draft/ to specification/experimental/workload-identity-federation.mdx and list it in README.md. The only changes to the text are the ones Prettier makes, so the format check passes. --- README.md | 6 +++ .../workload-identity-federation.mdx | 46 ++++++++++++------- 2 files changed, 35 insertions(+), 17 deletions(-) rename specification/{draft => experimental}/workload-identity-federation.mdx (96%) diff --git a/README.md b/README.md index b985e20..fac6e70 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,12 @@ The directory that holds an extension's specification shows its stage: `specific - [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)) +### Experimental + +Experimental extensions may change or be withdrawn at any time, without notice. + +- [Workload Identity Federation](./specification/experimental/workload-identity-federation.mdx) + ## Governance 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). diff --git a/specification/draft/workload-identity-federation.mdx b/specification/experimental/workload-identity-federation.mdx similarity index 96% rename from specification/draft/workload-identity-federation.mdx rename to specification/experimental/workload-identity-federation.mdx index af99d33..43e942c 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/experimental/workload-identity-federation.mdx @@ -15,7 +15,7 @@ operates as an autonomous workload, that is, the client authenticates and authorizes as itself rather than through an interactive OAuth authorization flow on behalf of an end-user. In these deployments, the MCP client effectively functions as a workload within a workload platform (such as Kubernetes or cloud -provider environments). Like the Client Credentials extension, this pattern +provider environments). Like the Client Credentials extension, this pattern addresses machine-to-machine authentication use cases. This extension allows an MCP client that already possesses a JWT credential @@ -25,6 +25,7 @@ server protecting an MCP server. The authorization server validates the JWT and issues a temporary access token suitable for accessing the MCP server. This approach eliminates the need for: + - Client credentials (client secrets or private keys) - Client identifiers (client_id) - Client registration (including Dynamic Client Registration) @@ -75,6 +76,7 @@ workloads. The flow involves three primary entities: As a prerequisite for this flow, the authorization server MUST be configured with a set of JWT issuers (defined by a URL), which are considered 'trusted issuers'. The nature of the trusted relationship and the mechanism by which the set is populated or maintained is out of scope of this document and left up to the implementer. JWTs not issued by these trusted issuers can be safely rejected by the authorization server. ### Message Flow + The message flow combines using a JWT as an authorization grant as defined in [RFC7523](https://datatracker.ietf.org/doc/html/rfc7523) with automated issuer discovery as described in [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) @@ -91,7 +93,7 @@ sequenceDiagram participant OIDC as OIDC
Discovery
Endpoint participant JWKS_URI as JWK Set
Location participant Server as MCP Server - + Client->>Auth: 1. Request Access Token Note over Auth: 2. Construct OpenID Provider Discovery Endpoint URL Auth->>OIDC: 3. Request OpenID Provider Configuration Document @@ -126,13 +128,13 @@ sequenceDiagram 3. **Request OpenID Provider Configuration Document**: The authorization server requests the OpenID Provider Configuration Document as described in Section 4.1 of [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest). -4. **Return OpenID Provider Configuration Document** The OpenID Provider Configuration Document is returned as described in Section 4.2 of [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse). +4. **Return OpenID Provider Configuration Document** The OpenID Provider Configuration Document is returned as described in Section 4.2 of [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse). 5. **Extract `jwks_uri`**: The authorization server validates the OpenID Provider Configuration Document as described in Section 4.3 of [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationValidation) and extracts the `jwks_uri` configuration information. 6. **Request JWK Set**: The authorization server retrieves the - [RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) JWK set + [RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) JWK set containing the issuer's public keys from the TLS protected location specified by `jwks_uri` configuration information. @@ -152,19 +154,19 @@ sequenceDiagram [RFC 7523 Section 2.1](https://datatracker.ietf.org/doc/html/rfc7523#section-2.1). 10. **MCP Server Access**: The MCP client makes a JSON-RPC request to the MCP - server, including the access token in the `Authorization` header using the - `Bearer` authentication scheme as specified in the baseline - [MCP Authorization](https://modelcontextprotocol.io/specification/draft/basic/authorization) - specification. + server, including the access token in the `Authorization` header using the + `Bearer` authentication scheme as specified in the baseline + [MCP Authorization](https://modelcontextprotocol.io/specification/draft/basic/authorization) + specification. -7. **Validate Access Token**: The MCP server validates the access token according to - the baseline - [MCP Authorization](https://modelcontextprotocol.io/specification/draft/basic/authorization) - specification, including verifying the token was issued for the MCP - server as the intended audience. +11. **Validate Access Token**: The MCP server validates the access token according to + the baseline + [MCP Authorization](https://modelcontextprotocol.io/specification/draft/basic/authorization) + specification, including verifying the token was issued for the MCP + server as the intended audience. -8. **MCP Server Response**: If the token is valid and the MCP client is authorized, the - MCP server processes the request and returns the JSON-RPC response. +12. **MCP Server Response**: If the token is valid and the MCP client is authorized, the + MCP server processes the request and returns the JSON-RPC response. ## JWT Requirements @@ -230,7 +232,9 @@ The JWT provisioning mechanism relies on a separate registration or attestation process that establishes trust between the workload and the JWT issuer. ## Authorization Server Requirements + ### Issuer Key Discovery + Authorization servers MUST support OpenID Connect Discovery [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) for discovering issuer configuration and retrieving issuer public keys @@ -254,7 +258,8 @@ Example issuer configuration response: ``` ### Issuer Key Retrieval -The issuer keys MUST be published as a [RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) JWK Key set and it MUST be + +The issuer keys MUST be published as a [RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) JWK Key set and it MUST be retrieved from a TLS protected URI. ### Trust Configuration @@ -277,6 +282,7 @@ grant type at their token endpoint as specified in [RFC 7523 Section 2.1](https://datatracker.ietf.org/doc/html/rfc7523#section-2.1). The token endpoint MUST accept requests with: + - `grant_type`: `urn:ietf:params:oauth:grant-type:jwt-bearer` - `assertion`: The workload JWT - `resource`: The target MCP server URI (as specified in the baseline MCP @@ -340,6 +346,7 @@ _SIGNATURE **Decoded JWT Assertion:** Header: + ```json { "alg": "RS256", @@ -349,6 +356,7 @@ Header: ``` Payload: + ```json { "iss": "https://issuer.example.org", @@ -436,6 +444,7 @@ trust affect all workloads associated with that issuer simultaneously. The mechanism for establishing issuer trust is implementation-specific and outside the scope of this specification. Common approaches include: + - Maintaining an allowlist of trusted issuer URLs - Configuring issuer metadata endpoints for automatic key discovery - Associating issuers with specific tenants or organizational units @@ -449,6 +458,7 @@ must determine whether the specific workload identified in the JWT claims should receive an access token. Workload trust is typically established individually based on: + - The `sub` (subject) claim identifying the workload - Additional claims such as namespace, tenant identifier, or service account - Combinations of multiple claims forming a compound identity @@ -460,9 +470,10 @@ trust, often allowing more granular per-workload authorization decisions. When workload platforms or authorization servers support multiple tenants, additional care must be taken to prevent privilege escalation across tenant -boundaries. +boundaries. Authorization servers SHOULD: + - Rely on JWT issuing keys bound to a single tenant of the workload platform, rather than a single issuing key for all tenants in a platform. - Use specific JWT claims to prevent any JWT signed by the issuer from being @@ -504,6 +515,7 @@ the "Multi-Tenancy Considerations" section for specific guidance on multi-tenant deployments. The following recommendations apply to all deployments: + - Configuration SHOULD NOT permit the transcription of JWT claims to access token claims without additional validation - Authorization servers SHOULD implement explicit allowlists or policies