Skip to content

Revise Workload Identity Federation documentation #10

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Open
PieterKas wants to merge 13 commits into
base: dmcadams-wif-extenstion
Choose a base branch
from
+76 −102
Open

Revise Workload Identity Federation documentation #10

Changes from 1 commit
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
f757bcf
Revise Workload Identity Federation documentation
PieterKas Nov 27, 2025
89dda73
Update specification/draft/workload-identity-federation.mdx
PieterKas Dec 3, 2025
2e6ec5a
Update workload-identity-federation.mdx
PieterKas Dec 3, 2025
13b5523
Update specification/draft/workload-identity-federation.mdx
PieterKas Dec 4, 2025
bfbd978
Update specification/draft/workload-identity-federation.mdx
PieterKas Dec 4, 2025
4ae8bf5
Update specification/draft/workload-identity-federation.mdx
PieterKas Dec 4, 2025
5ad9bce
Define usage of OIDC Discovery Mechanism
PieterKas Dec 4, 2025
5d806f5
Removed duplicative text
PieterKas Dec 4, 2025
955bf0a
Added back example
PieterKas Dec 4, 2025
740b0be
Reverted "iss" examples
PieterKas Dec 4, 2025
8ccede8
Refined flow description
PieterKas Dec 4, 2025
972fab4
Editorial Pass
PieterKas Dec 4, 2025
a1b94cc
Typo corrected
PieterKas Dec 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
165 changes: 59 additions & 106 deletions specification/draft/workload-identity-federation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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=<JWT> │
│ 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 <access_token> │
│ 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:
Expand All @@ -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).
Expand All @@ -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
Expand Down Expand Up @@ -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",
Expand All @@ -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.
Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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:
Expand Down