WIMSE Headless JWT Authentication and Authorization

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 26 December 2025.¶

Copyright Notice

Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

In workload-to-service communication, a common pattern is for a workloads to use a JSON Web Token (JWT) to identify and authenticate itself as part of a process to obtain an access token for a service. This is done by having the workload present an asynchronously-provisioned bearer token in the form of a signed JWT to an Authorization Server. The Authorization Server verifies the JWT and then provides an OAuth access token as described in [RFC7523]. The "bootstrap" problem of discovering the original JWT issuer is solved by requesting a JSON configuration document using the process described in OpenID Connect Discovery [OIDC.Discovery] or OAuth 2.0 Authorization Server Metadata [RFC8414].¶

Since this pattern is not described in a specification, it leads to variability in interoperability. The purpose of this document is to capture this common workload identity practice as an RFC in order to obtain consistency and promote interoperability in industry.¶

2. Conventions and Definitions

All terminology in this document follows [I-D.ietf-wimse-arch].¶

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

3. Architecture and Message Flow

Figure 1 illustrates the OIDC-based message flow described in Section 4:¶

4. JWT used for Authentication

The overall message flow is seen in Figure 1, and this section explains it in more detail. It assumes the workload has previously acquired a JWT adhering to the profile specified in [RFC7523]. JWT provisioning assumptions are described in more detail in Section 6.3.¶

1. The workload calls an Authorization Server's token endpoint and presents a JWT Bearer Token as specified in Section 4 of [RFC7523].¶

2. The Authorization Server takes the value from the iss claim and appends /.well-known/openid-configuration to retrieve the JWT Issuer's configuration via HTTP, as specified in [OIDC.Discovery]. Alternatively, the OAuth 2.0 Authorization Server Metadata endpoint [RFC8414] may be used.¶

3. The Authorization Server then retrieves the JWKs via HTTP from the jwks_uri declared in the JWT Issuer's configuration response.¶

4. Using the appropiate issuer key, the Authorization Server verifies the signature of the JWT Bearer Token, and validates that the workload is authorized to receive an Access Token.¶

5. Assuming successful verification, the Authorization Server then responds to the workload with an Access Token suitable for use with the Resource Server.¶

6. The Workload then authenticates with the Resource Server using the Access Token.¶

The headless JWT authorization grant flow combines [RFC7523] and OIDC key discovery to simplify workload authentication and authorization..¶

This document limits discussion to HTTP, as this is the protocol predominantly used. Although other protocols are out of scope, this should not be read as a limit on their future use.¶

5. Key Discovery

Issuer key discovery follows the steps outlined in Section 4 of [OIDC.Discovery]. The Resource Server makes a request to a location that is well-known according to [RFC5785]:¶

GET /.well-known/openid-configuration HTTP/1.1
Host: example.com

For OAuth 2.0, the equivalent location is /.well-known/oauth-authorization-server. In both cases, the requester expects a JSON document containing configuration information. An example is provided here:¶

{
  "issuer": "https://example.com",
  "jwks_uri": "https://example.com/.well-known/jwks.json",
  "authorization_endpoint": "https://example.com/auth",
  "token_endpoint": "https://example.com/token"
}

For the sake of the pattern described in this document, only the issuer and jwks_uri fields are relevant.¶

Note that this key discovery mechanism does not address the question of whether the key itself should be trusted. This is a registration problem, and is discussed further in Section 8.¶

6. JWT Format and Processing Requirements

{
  "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
}

7. Trust Relationships

For functional headless JWT authentication, trust must be established at multiple levels for the authentication flow to function. For an authorization server to issue an access token to a workload, two distinct trust relationships must exist:¶

1. The authorization server MUST trust the JWT issuer.¶

2. The authorization server MUST trust the specific workload based on claims within the JWT bearer token.¶

These two trust relationships serve different purposes and SHOULD be managed independently as outlined below.¶

An example of the differences between issuer and workload trust relationships are three workload instances (A, B and C) that are all presenting JWT Bearer Tokens issued from the same JWT Issuer. This means that they build upon the trust relationship between the JWT issuer and authorization server. One workload instance has a specific workload trust relationship with the authorization server based on its subject identifier (the sub claim). It requires a very specific identifier which needs to match exactly. Another one makes use of a hierarchy within the subject identifier and the last one uses a combination of subject, audience and a custom claim as a basis for the trust relationship.¶

           ┌──────────────────────┐
           │                      │
           │ Authorization Server │◄─────────────────┐
           │                      │                  │
           └──────────────────────┘        Issuer trust relationship
                ▲     ▲     ▲                        │
                │     │     │                        │
                │     │     │                        ▼
             Individual workload              ┌─────────────┐
             trust relationships              │             │
                │     │     │                 │ JWT Issuer  │
       ┌────────┘     │     └─────────┐       │             │
       │              │               │       └──────┬──────┘
       │              │               │              │
       │              │               │              │
       ▼              ▼               ▼              │
┌────────────┐  ┌────────────┐  ┌────────────┐   Issue JWT
│            │  │            │  │            │  Bearer Tokens
│ Workload A │  │ Workload B │  │ Workload C │       │
│            │  │            │  │            │       │
└────────────┘  └────────────┘  └────────────┘       │
       ▲              ▲                ▲             │
       └──────────────┴────────────────┴─────────────┘

8. Interoperability Considerations

In order for the workload to access the resource,¶

1. The JWT Issuer must be recognized by the Authorization Server,¶

2. Claims in the JWT are inspected and used to determine the subject, or principal, of the access token issued for the Resource Server,¶

3. And the resulting Resource Server principal must be authorized to access the Resource.¶

Step #1 requires the prior configuration of an explicit trust relationship between the Authorization Server and the JWT Issuer, and depends on vendor-specific configuration. Dynamic client registration standards ([RFC7591] and [OIDC.Dynamic]) explicitly place it out of scope.¶

Step #2 is a processing rule that is also previously-configured in an implementation-dependent manner. As an example of current practice for configuration of Steps #2 and #3, see [GitHub].¶

9. Security Considerations

This document illustrates a common pattern in trust domain federation. However, the "identity exchange" Step #2 in Section 8 is not standardized. In practice, the Workload Platform and the Resource Server platform define principals differently, and the translation mechanism between the two identities is implemented differently by each Resource Server platform. This lack of standardization is not merely inconvenient; it is a rich source of privilege escalation attacks. This is particularly true when both the Workload Platform and the Resource Server platform are multi-tenanted.¶

The following recommendations apply to configurations that control the "identity exchange" step that controls the translation of the workload JWT to a Resource Server identity:¶

1. When a Workload Platform contains multiple Tenants, the configuration SHOULD rely on a JWT issuing key bound to a single Tenant of the workload platform, rather than a single JWT issuing key for the Workload Platform.¶

2. The configuration SHOULD use specific JWT claims to prevent any JWT signed by the JWT Issuer from being used to impersonate any Resource Server principal.¶

3. When a Workload Platform contains multiple Tenants, the configuration SHOULD NOT solely rely on JWT claims that can be controlled by any Tenant. The configuration MAY rely on a "tenant" claim, if the claim value is issuer-controlled and corresponds to a single Tenant.¶

4. The configuration SHOULD NOT permit the transcription of JWT claims to the Resource Server principal without performing additional validation.¶

The security considerations in section 8 of [RFC7521] generally apply. As bearer tokens, stolen JWTs are particularly valuable to attackers:¶

1. A secure channel (e.g. TLS) MUST be used when providing a JWT for authentication.¶

2. JWTs SHOULD be protected from unauthorized access using operating system or platform access controls.¶

3. JWT validity SHOULD be set to the shortest possible duration allowable by overall system availability constraints.¶

10. IANA Considerations

This document has no IANA actions.¶

11. References

Acknowledgments

The authors would like to thank the following people for their feedback and reviews of the document: Evan Gilman, Pieter Kasselman, Darin McAdams, and Arndt Schwenkschuster.¶

Authors' Addresses