From f757bcfdd3b3944b8ae923efbcf315d951d387b2 Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Thu, 27 Nov 2025 21:06:48 +0000 Subject: [PATCH 01/13] Revise Workload Identity Federation documentation Refactor message flow and update flow steps for clarity. Adjust issuer discovery and key retrieval sections to improve understanding. --- .../draft/workload-identity-federation.mdx | 165 +++++++----------- 1 file changed, 59 insertions(+), 106 deletions(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index fe79e26..c588995 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -80,66 +80,40 @@ specific JWT issuers and rules determining which workload identities are authorized to receive access tokens. ### Message Flow +The message flow combines RFC7523 with retrieving a RFC7517 JWK Key set from a TLS secured URI The complete Workload Identity Federation flow proceeds as follows: ``` -┌──────────┐ ┌──────────────────┐ -│ │ │ │ -│ MCP │ │ Authorization │ -│ Client │ │ Server │ -│ │ │ │ -└────┬─────┘ └────────┬─────────┘ - │ │ - │ 1. POST /token │ - │ grant_type=urn:ietf:params:oauth:grant- │ - │ type:jwt-bearer │ - │ assertion= │ - │ resource=https://mcp.example.com │ - ├──────────────────────────────────────────────────►│ - │ │ - │ 2. Discover issuer - │ configuration - │ GET /.well-known/ - │ openid-configuration - │ │ - │ 3. Retrieve JWKs - │ from jwks_uri - │ │ - │ 4. Verify JWT signature - │ and validate claims - │ │ - │ 5. Access Token Response │ - │ { │ - │ "access_token": "...", │ - │ "token_type": "Bearer", │ - │ "expires_in": 3600 │ - │ } │ - │◄──────────────────────────────────────────────────┤ - │ │ - │ │ -┌────▼─────┐ ┌───────▼──────────┐ -│ │ │ │ -│ MCP │ │ MCP Server │ -│ Client │ │ │ -└────┬─────┘ └────────┬─────────┘ - │ │ - │ 6. JSON-RPC Request │ - │ Authorization: Bearer │ - │ POST /mcp │ - ├──────────────────────────────────────────────────►│ - │ │ - │ 7. Validate token - │ and process request - │ │ - │ 8. JSON-RPC Response │ - │◄──────────────────────────────────────────────────┤ - │ │ -``` +┌──────────┐ ┌──────────────────┐ ┌──────────┐ +│ │ │ │ │ │ +│ MCP │ │ Authorization │ │ MCP │ +│ Client │ │ Server │ │ Server │ +│ │ │ │ │ │ +└──────────┘ └──────────────────┘ └──────────┘ + │ │ │ + │ 1. Request Access Token │ │ + │--------------------------->│ │ + │ │ │ + │ 2. Determine Issuer Key Location │ + │ │ │ + │ 3. Obtain Issuer Keys │ + │ │ │ + │ 4. Validate JWT │ + │ │ │ + │ 5. Return Access Token │ │ + │<---------------------------│ │ + │ 6. MCP Server Access │ + │--------------------------------------------------------->│ + │ │ + │ 7. Validate Access Token + │ 8. MCP Server Response │ + │--------------------------------------------------------->│ +``` ### Flow Steps -1. **Token Request**: The MCP client makes a POST request to the authorization +1. **Request Access Token**: The MCP client makes 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: @@ -148,25 +122,28 @@ The complete Workload Identity Federation flow proceeds as follows: - `resource`: The canonical URI of the target MCP server (as defined in the baseline MCP Authorization specification) -2. **Issuer Discovery**: The authorization server extracts the `iss` (issuer) - claim from the JWT and performs issuer discovery by retrieving the OpenID - Connect configuration from `{issuer}/.well-known/openid-configuration` as - specified in - [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html). - Alternatively, the OAuth 2.0 Authorization Server Metadata endpoint may be - used per [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). - -3. **Key Retrieval**: The authorization server retrieves the issuer's public - keys from the `jwks_uri` specified in the issuer's configuration document. - -4. **JWT Validation**: The authorization server validates the JWT according to +2. **Determine Issuer Key Location**: The authorization server extracts the `iss` (issuer) + claim from the JWT and determine if it is a trusted issuer. If it trusts the + issuer, it MUST determine the location from which to retrieve the RFC7517 JWK key + set based on the `iss` claim. The JWK key set location MUST be a TLS protected + URI. The authorization server MAY maintain a mapping between an issuer and the + location of its JWK key set. Alternatively it MAY use a dynamic JWK issuer key + discovery mechanism as defined by OpenID Connect Discovery 1.0 or obtain the + location from the OAuth 2.0 Authorization Server Metadata endpoint may be used per + [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). + +3. **Obtain Issuer Keys**: The authorization server retrieves the JWK key set + containing the issuer's public keys from the TLS protected location specified in + the issuer's configuration document. + +4. **Validate JWT**: The authorization server validates the JWT 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. -5. **Access Token Issuance**: If validation succeeds, the authorization server +5. **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). @@ -176,11 +153,11 @@ The complete Workload Identity Federation flow proceeds as follows: `Bearer` authentication scheme as specified in the baseline MCP Authorization specification. -7. **Token Validation**: The MCP server validates the access token according to +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. **Response**: If the token is valid and the MCP client is authorized, the +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 @@ -209,7 +186,7 @@ Example JWT payload: ```json { - "iss": "https://issuer.example.org", + "iss": "spiffe://example.org", "sub": "spiffe://example.org/ns/default/sa/customer-router-agent", "aud": "https://auth.example.com/token", "jti": "jwt-grant-id-x1y2z3a4", @@ -226,10 +203,10 @@ 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 the JWT signature using keys retrieved - through issuer discovery as described in this specification. - 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. @@ -239,7 +216,7 @@ with the following considerations: How MCP clients obtain their workload JWT credentials is outside the scope of this specification. Workload JWTs are typically provisioned by: -- Workload platforms +- Workload platforms (e.g. Kubernetes) - SPIFFE implementations - Identity providers integrated with workload deployment systems @@ -248,39 +225,15 @@ process that establishes trust between the workload and the JWT issuer. ## Authorization Server Requirements -### Issuer Discovery - -Authorization servers MUST support OpenID Connect Discovery -[OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) -or OAuth 2.0 Authorization Server Metadata -[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) for discovering -issuer configuration and retrieving issuer public keys. - -The issuer discovery process follows these steps: - -1. Extract the `iss` claim from the workload JWT -2. Construct the well-known configuration URL: - `{iss}/.well-known/openid-configuration` (or the OAuth 2.0 equivalent) -3. Retrieve the configuration document via HTTPS -4. Extract the `jwks_uri` from the configuration -5. Retrieve the issuer's public keys from the `jwks_uri` via HTTPS +### Issuer Key Retrieval +The issuer keys MUST be published as a [RFC7517] JWK Key set and it MUST be +retrieved from a TLS protected URI. -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" -} -``` +The authorization server MAY maintain a mapping between an issuer and the +location of its JWK key set. Alternatively it MAY use a dynamic JWK issuer key +discovery mechanism as defined by OpenID Connect Discovery 1.0 or obtain the +location from the OAuth 2.0 Authorization Server Metadata endpoint may be used per +[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). ### Trust Configuration @@ -376,7 +329,7 @@ Header: Payload: ```json { - "iss": "https://issuer.example.org", + "iss": "spiffe://example.org", "sub": "spiffe://example.org/ns/default/sa/customer-router-agent", "aud": "https://auth.example.com/token", "jti": "jwt-grant-id-x1y2z3a4", @@ -535,7 +488,7 @@ The following recommendations apply to all deployments: - Authorization servers SHOULD log and audit all token issuance decisions for security monitoring -### Issuer Discovery Security +### Issuer Key Retrieval Security Authorization servers MUST validate issuer URLs and ensure they use HTTPS. Authorization servers SHOULD implement the following protections: From 89dda73c55b73ecab2d70f6efb261f8ded327334 Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Wed, 3 Dec 2025 11:46:46 +0000 Subject: [PATCH 02/13] Update specification/draft/workload-identity-federation.mdx --- specification/draft/workload-identity-federation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index c588995..32305da 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -108,7 +108,7 @@ The complete Workload Identity Federation flow proceeds as follows: │ │ │ 7. Validate Access Token │ 8. MCP Server Response │ - │--------------------------------------------------------->│ + │<-------------------------------------------------------->│ ``` ### Flow Steps From 2e6ec5a66d04c0ab471c42e8108bb03f0134ddbd Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Wed, 3 Dec 2025 11:47:50 +0000 Subject: [PATCH 03/13] Update workload-identity-federation.mdx --- specification/draft/workload-identity-federation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index 32305da..6a56f7c 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -108,7 +108,7 @@ The complete Workload Identity Federation flow proceeds as follows: │ │ │ 7. Validate Access Token │ 8. MCP Server Response │ - │<-------------------------------------------------------->│ + │<---------------------------------------------------------│ ``` ### Flow Steps From 13b55238f0b1ad540db248f230f3229606d30657 Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Thu, 4 Dec 2025 12:00:59 +0000 Subject: [PATCH 04/13] Update specification/draft/workload-identity-federation.mdx --- specification/draft/workload-identity-federation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index 6a56f7c..9cd167e 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -80,7 +80,7 @@ specific JWT issuers and rules determining which workload identities are authorized to receive access tokens. ### Message Flow -The message flow combines RFC7523 with retrieving a RFC7517 JWK Key set from a TLS secured URI +The message flow combines using a JWT as an authorization grant as define in [RFC7523](https://datatracker.ietf.org/doc/html/rfc7523) with retrieving a [RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) JWK Key set from a TLS secured URI The complete Workload Identity Federation flow proceeds as follows: From bfbd9781cf274cff16971a1e7069dd7dca78cc1e Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Thu, 4 Dec 2025 12:21:18 +0000 Subject: [PATCH 05/13] Update specification/draft/workload-identity-federation.mdx --- .../draft/workload-identity-federation.mdx | 40 +++++++------------ 1 file changed, 14 insertions(+), 26 deletions(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index 9cd167e..a045c11 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -85,32 +85,20 @@ The message flow combines using a JWT as an authorization grant as define in [RF The complete Workload Identity Federation flow proceeds as follows: ``` -┌──────────┐ ┌──────────────────┐ ┌──────────┐ -│ │ │ │ │ │ -│ MCP │ │ Authorization │ │ MCP │ -│ Client │ │ Server │ │ Server │ -│ │ │ │ │ │ -└──────────┘ └──────────────────┘ └──────────┘ - │ │ │ - │ 1. Request Access Token │ │ - │--------------------------->│ │ - │ │ │ - │ 2. Determine Issuer Key Location │ - │ │ │ - │ 3. Obtain Issuer Keys │ - │ │ │ - │ 4. Validate JWT │ - │ │ │ - │ 5. Return Access Token │ │ - │<---------------------------│ │ - │ 6. MCP Server Access │ - │--------------------------------------------------------->│ - │ │ - │ 7. Validate Access Token - │ 8. MCP Server Response │ - │<---------------------------------------------------------│ - -``` +```mermaid +sequenceDiagram + participant Client as MCP Client + participant Auth as Authorization Server + participant Server as MCP Server + + Client->>Auth: 1. Request Access Token + Note over Auth: 2. Determine Issuer Key Location + Note over Auth: 3. Obtain Issuer Keys + Note over Auth: 4. Validate JWT + Auth->>Client: 5. Return Access Token + Client->>Server: 6. MCP Server Access + Note over Server: 7. Validate Access Token + Server->>Client: 8. MCP Server Response ### Flow Steps 1. **Request Access Token**: The MCP client makes a POST request to the authorization From 4ae8bf59bfa64d00ab20a1b058ecaac1847964ac Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Thu, 4 Dec 2025 12:21:31 +0000 Subject: [PATCH 06/13] Update specification/draft/workload-identity-federation.mdx --- specification/draft/workload-identity-federation.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index a045c11..9141daa 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -114,11 +114,7 @@ sequenceDiagram claim from the JWT and determine if it is a trusted issuer. If it trusts the issuer, it MUST determine the location from which to retrieve the RFC7517 JWK key set based on the `iss` claim. The JWK key set location MUST be a TLS protected - URI. The authorization server MAY maintain a mapping between an issuer and the - location of its JWK key set. Alternatively it MAY use a dynamic JWK issuer key - discovery mechanism as defined by OpenID Connect Discovery 1.0 or obtain the - location from the OAuth 2.0 Authorization Server Metadata endpoint may be used per - [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). + URI. The authorization server MUST maintain a mapping between an issuer and the location of its JWK key set through manual configuration. 3. **Obtain Issuer Keys**: The authorization server retrieves the JWK key set containing the issuer's public keys from the TLS protected location specified in From 5ad9bcef1b21cd7225a6736f639c49a6abaa7636 Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:16:48 +0000 Subject: [PATCH 07/13] Define usage of OIDC Discovery Mechanism Update diagram and message flow to support usage of the OIDC discovery mechanism --- .../draft/workload-identity-federation.mdx | 59 ++++++++++++------- 1 file changed, 38 insertions(+), 21 deletions(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index 9141daa..7a5eeb0 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -80,25 +80,32 @@ 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 define in [RFC7523](https://datatracker.ietf.org/doc/html/rfc7523) with retrieving a [RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) JWK Key set from a TLS secured URI +The message flow combines using a JWT as an authorization grant as defined in [RFC7523](https://datatracker.ietf.org/doc/html/rfc7523) with retrieving a [RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) JWK Key set from a TLS secured URI The complete Workload Identity Federation flow proceeds as follows: -``` ```mermaid sequenceDiagram participant Client as MCP Client - participant Auth as Authorization Server + 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. Determine Issuer Key Location - Note over Auth: 3. Obtain Issuer Keys - Note over Auth: 4. Validate JWT - Auth->>Client: 5. Return Access Token - Client->>Server: 6. MCP Server Access - Note over Server: 7. Validate Access Token - Server->>Client: 8. MCP Server Response + 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 + 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 makes a POST request to the authorization @@ -110,29 +117,39 @@ sequenceDiagram - `resource`: The canonical URI of the target MCP server (as defined in the baseline MCP Authorization specification) -2. **Determine Issuer Key Location**: The authorization server extracts the `iss` (issuer) - claim from the JWT and determine if it is a trusted issuer. If it trusts the - issuer, it MUST determine the location from which to retrieve the RFC7517 JWK key - set based on the `iss` claim. The JWK key set location MUST be a TLS protected - URI. The authorization server MUST maintain a mapping between an issuer and the location of its JWK key set through manual configuration. +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 defined 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 + using the URL constructed in Step 2 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. **Extrack 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. -3. **Obtain Issuer Keys**: The authorization server retrieves the JWK key set - containing the issuer's public keys from the TLS protected location specified in - the issuer's configuration document. +7. **Return JWK Set**: The JWK set is returned from the TLS protected location. -4. **Validate JWT**: The authorization server validates the JWT according to +8. **Validate JWT**: The authorization server validates the JWT 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. -5. **Return Access Token**: If JWT validation succeeds, the authorization server +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). -6. **MCP Server Access**: The MCP client makes a JSON-RPC request to the MCP +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. From 5d806f515f877c5daa21d0cc9557373af4d8db39 Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:46:53 +0000 Subject: [PATCH 08/13] Removed duplicative text --- .../draft/workload-identity-federation.mdx | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index 7a5eeb0..c67b94b 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -75,7 +75,7 @@ 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 +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. @@ -96,7 +96,7 @@ sequenceDiagram 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 + 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 @@ -127,13 +127,13 @@ sequenceDiagram 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. **Extrack 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. +5. **Extrack `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. + `jwks_uri` configuration information. 7. **Return JWK Set**: The JWK set is returned from the TLS protected location. @@ -187,7 +187,7 @@ Example JWT payload: ```json { - "iss": "spiffe://example.org", + "iss": "https://example.org", "sub": "spiffe://example.org/ns/default/sa/customer-router-agent", "aud": "https://auth.example.com/token", "jti": "jwt-grant-id-x1y2z3a4", @@ -225,6 +225,11 @@ 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. ### Issuer Key Retrieval The issuer keys MUST be published as a [RFC7517] JWK Key set and it MUST be From 955bf0a3d999baf81d801c3e7184aaf2c959dfe4 Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:50:28 +0000 Subject: [PATCH 09/13] Added back example --- .../draft/workload-identity-federation.mdx | 25 +++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index c67b94b..4ba2071 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -231,16 +231,27 @@ Authorization servers MUST support OpenID Connect Discovery 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] 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. -The authorization server MAY maintain a mapping between an issuer and the -location of its JWK key set. Alternatively it MAY use a dynamic JWK issuer key -discovery mechanism as defined by OpenID Connect Discovery 1.0 or obtain the -location from the OAuth 2.0 Authorization Server Metadata endpoint may be used per -[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). - ### Trust Configuration Authorization servers MUST implement mechanisms to configure: From 740b0be2455fe34f03049ef6b03ae599ff6d9feb Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:52:43 +0000 Subject: [PATCH 10/13] Reverted "iss" examples --- specification/draft/workload-identity-federation.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index 4ba2071..0303ae2 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -187,7 +187,7 @@ Example JWT payload: ```json { - "iss": "https://example.org", + "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", @@ -346,7 +346,7 @@ Header: Payload: ```json { - "iss": "spiffe://example.org", + "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", From 8ccede816c21afdf1119c69b3dc453da41e19bfd Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Thu, 4 Dec 2025 14:02:50 +0000 Subject: [PATCH 11/13] Refined flow description --- specification/draft/workload-identity-federation.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index 0303ae2..eae0d02 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -80,7 +80,11 @@ 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 retrieving a [RFC7517](https://datatracker.ietf.org/doc/html/rfc7517) JWK Key set from a TLS secured URI +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: From 972fab4c01ceff9c2b7d36680431a6b28aaefbf2 Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Thu, 4 Dec 2025 15:34:26 +0000 Subject: [PATCH 12/13] Editorial Pass Minor tweaks and editorial updates --- .../draft/workload-identity-federation.mdx | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index eae0d02..da4958e 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -19,7 +19,7 @@ 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 implementation, or other trusted +(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. @@ -33,7 +33,7 @@ This approach eliminates the need for: 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 -authentication patterns while maintaining security through proper issuer trust +access patterns while maintaining security through proper issuer trust and claim-based authorization. ### Extension Requirements @@ -53,10 +53,7 @@ This extension is based on the following established specifications: 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)) -- OAuth 2.0 Authorization Server Metadata - ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) -- OAuth 2.0 Protected Resource Metadata - ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)) +- JSON Web Key (JWK)([RFC7517](https://datatracker.ietf.org/doc/html/rfc7517)) ## Workload Identity Federation Flow @@ -103,7 +100,7 @@ sequenceDiagram 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 + 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 @@ -112,8 +109,9 @@ sequenceDiagram ### Flow Steps -1. **Request Access Token**: The MCP client makes a POST request to the authorization - server's token endpoint using the JWT Bearer grant type as specified in +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` @@ -124,14 +122,14 @@ sequenceDiagram 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 defined in Section 4 of [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig). + 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 - using the URL constructed in Step 2 as described in Section 4.1 of [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest). + 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. **Extrack `jwks_uri`**: The authorization server validates the OpenID Provider Configuration Document as +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 @@ -141,7 +139,8 @@ sequenceDiagram 7. **Return JWK Set**: The JWK set is returned from the TLS protected location. -8. **Validate JWT**: The authorization server validates the JWT according to +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 @@ -443,7 +442,7 @@ outside the scope of this specification. Common approaches include: Workload trust builds upon issuer trust and focuses on the relationship between the authorization server and individual workloads. Once the JWT bearer token is -authenticated (signature verified and issuer trusted), the authorization server +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. @@ -463,12 +462,12 @@ 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 the entire 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 + 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 + corresponds to a single tenant. See the Security Considerations section for additional details on privilege escalation prevention. @@ -479,7 +478,8 @@ 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 7521 Section 8 "Security Considerations"](https://datatracker.ietf.org/doc/html/rfc7521#section-8) +- [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 @@ -490,8 +490,8 @@ 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 -authentication. JWTs SHOULD be protected from unauthorized access using -operating system or platform access controls. +Workload IDentity Federation. JWTs SHOULD be protected from unauthorized +access using operating system or platform access controls. ### Identity Translation and Privilege Escalation From a1b94ccf3b61f3963b51a4d4c1c6b353218e90d9 Mon Sep 17 00:00:00 2001 From: PieterKas <90690777+PieterKas@users.noreply.github.com> Date: Thu, 4 Dec 2025 15:35:57 +0000 Subject: [PATCH 13/13] Typo corrected --- specification/draft/workload-identity-federation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/draft/workload-identity-federation.mdx b/specification/draft/workload-identity-federation.mdx index da4958e..323b42e 100644 --- a/specification/draft/workload-identity-federation.mdx +++ b/specification/draft/workload-identity-federation.mdx @@ -490,7 +490,7 @@ 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 +Workload Identity Federation. JWTs SHOULD be protected from unauthorized access using operating system or platform access controls. ### Identity Translation and Privilege Escalation