]> SPIRL

arndts.ietf@gmail.com

SPIRL

pieter@spirl.com

AREA Web Authorization Protocol workload identity credential exchange This specification profiles the Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants and JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants to enable the use of SPIFFE Verifiable Identity Documents (SVIDs) as client credentials in OAuth 2.0. It defines how OAuth clients with SPIFFE credentials can authenticate to OAuth authorization servers using their JWT-SVIDs or X.509-SVIDs without the need for client secrets. This approach enhances security by enabling seamless integration between SPIFFE-enabled workloads and OAuth authorization servers while eliminating the need to distribute and manage shared secrets such as static client secrets. About This Document Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction Traditional OAuth client authentication typically relies on client secrets or private key JWT authentication, both require an out of band distribution of secret material to the OAuth client. In modern cloud-native architectures where identity is managed by SPIFFE (Secure Production Identity Framework for Everyone), there is a need to provision additional secret material for OAuth clients when attested identifiers and credentials such as SVIDs are already available. This specification profiles the Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants to allow SPIFFE-enabled workloads to use their SPIFFE Verifiable Identity Documents (SVIDs) — either X.509 certificates or JWT tokens — as client credentials for OAuth 2.0 client authentication. JWT tokens make use of the profiled version of - the JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants . This profile focuses specifically on client authentication rather than authorization grants. This focus is deliberate for several reasons:

1. In modern service-oriented architectures, services often need to authenticate as themselves to OAuth authorization servers.
2. Using SPIFFE as client authentication towards OAuth 2.0 authorization servers is a bridge between SPIFFE, which covers workload identity and OAuth, which covers human identity.
3. Using SPIFFE as authorization grants for authorization requests where the workload itself is the resource owner is covered by other specifications, such as .

The SPIFFE profile for client authentication enables seamless integration between SPIFFE-based and OAuth-based systems, allowing applications to leverage both ecosystems without requiring additional credential management. It also enables a more secure authentication method by leveraging cryptographically verifiable credentials rather than shared secrets.

Conventions and Definitions 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 when, and only when, they appear in all capitals, as shown here.

Terminology This specification uses the terms defined in OAuth 2.0 , the Assertion Framework for OAuth 2.0 , the JWT profile of it , and the SPIFFE specifications. In particular, the following terms are particularly relevant: Trust Domain: As defined in SPIFFE; A trust domain represents a single trust root. All SVIDs issued within a trust domain are verifiable via the trust domain's keys. SPIFFE ID: A unified resource identifier that uniquely and specifically identifies a workload using the spiffe scheme. See for details. SVID: A SPIFFE Verifiable Identity Document. This document specifies the use of two types of SVIDs:

• X.509-SVID: An X.509 certificate that contains a SPIFFE ID in the URI SAN extension. See for details.
• JWT-SVID: A JSON Web Token (JWT) that contains a SPIFFE ID in the sub claim. See for details.

SPIFFE Bundle: A collection of public keys and associated metadata that allow validation of SVIDs issued by a trust domain. SPIFFE Bundle Endpoint: A URL that serves a SPIFFE bundle for a trust domain.

OAuth Client Authentication Using SPIFFE This section describes how SPIFFE identity documents can be used for OAuth 2.0 client authentication, following the patterns established in and, in case of JWT-SVID . OAuth 2.0 client authentication is used to authenticate the client to the authorization server when making requests to the token endpoint. When using SPIFFE for client authentication, the client presents its SVID (either JWT-SVID or X.509-SVID) to prove its identity.

Client Authentication with JWT-SVIDs JWT-SVID based authentication naturally follows the JWT Profile for OAuth 2.0 Client Authentication , with specific adaptations for SPIFFE JWT-SVIDs. remains valid. To identify the assertion content as a JWT-SVID this specification establishes the following client assertion type as an OAuth URI according to : Based on the following request parameters MUST be present to perform client authentication in the context of this specification:

• client_assertion_type: MUST be set to urn:ietf:params:oauth:client-assertion-type:jwt-spiffe.
• client_assertion: MUST be a single SPIFFE JWT-SVID.

To validate JWT-SVID client authentication requests the authorization server MUST:

1. Verify that the JWT is well-formed and contains all required claims (SPIFFE ID in sub, aud, and exp).
2. Verify that the JWT has not expired (check the exp claim).
3. Verify that the aud claim equals the endpoint of the request without fragment and query parameters.
4. Verify the JWT signature using the signing keys of the trust domains according to .
5. Verify that the SPIFFE ID in the sub claim matches a registered client identifier or is associated with a registered client identifier.

JWT-SVID example The following examples illustrates an authorization_code request to the token endpoint of an OAuth 2.0 authorization server leveraging a SPIFFE JWT-SVID to authenticate the client. For clarify, the SPIFFE-JWT header and body decoded:

Client Authentication using X509-SVID X.509-SVID based authentication uses mutual TLS as defined in OAuth 2.0 Mutual-TLS Client Authentication , with specific adaptations for SPIFFE X.509-SVIDs. To authenticate using an X.509-SVID, the client establishes a mutual TLS connection with the authorization server using its X.509-SVID as the client certificate. The authorization server validates the client certificate as an X.509-SVID and extracts the SPIFFE ID from the URI SAN. The server certificate MUST be validated by the client using its system trust store, and NOT the SPIFFE trust bundle. The request MUST include the client_id parameter containing the SPIFFE-ID of the client. It MUST match the URI SAN of the presented X509-SVID client credential. The server validates the client certificates according the following rules

1. Perform standard X.509 path validation against the trust anchors according to .
2. Verify that the certificate contains exactly one URI SAN with a valid SPIFFE ID.
3. Verify that the certificate is a leaf certificate (Basic Constraints extension has CA=FALSE).
4. Verify that the certificate has the digitalSignature key usage bit set.
5. Verify that the SPIFFE ID in the URI SAN matches a registered client identifier or is associated with a registered client identifier.

X509-SVID Example The following request uses a refresh token to obtain a new access token. The client is spiffe://example.org/my-oauth-client and is authenticted by performing this request over a mutual TLS connection. For clarity, the presented X509-SVID client certificate to the server decoded via openssl x509 -text is:

SPIFFE Trust Establishment and Client Registration This specification requires previously established trust between the OAuth 2.0 Authorization Server and the SPIFFE Trust Domain. This needs to happen out of band and is not in scope of this specification. However, the mechanisms of key distribution is in scope and described in . Similar to the trust establishment, corresponding OAuth clients need to be established prior of using SPIFFE as client authentication. This is also out of scope, implementors may for example choose to levarage OAuth 2.0 dynamic client registration according to or configure them out of band.

SPIFFE Key Distribution and Validation This section describes how an authorization server verifies the signature of an X509 or JWT-SVID. It recommends two SPIFFE-native approaches. Trust bundles in general MUST be keyed by the trust domain identifier to prevent mix up between trust domain and their corresponding bundles. The 2 approaches can be used in conjunction, for instance:

SPIFFE Bundle Endpoint The SPIFFE Bundle Endpoint exposes the signing keys for X509-SVIDs and JWT-SVIDs over HTTP via a JSON Web Key Set according to . Server authentication on this endpoint is available in two flavors. For the sake of interoperability, in the context of this specification the WebPKI flavor MUST be used. This effectively means that the server certificate of the bundle endpoint is trusted by the authorization server accessing it. See Sec 5.2.1 of for details. The authorization server SHOULD periodically poll the bundle endpoint to retrieve updated trust bundles, following the refresh hint and period provided in the bundle. See for details. The SPIFFE bundle endpoint cannot be derived from the JWT-SVID and X509-SVID and MUST be configured manually out of band. Bundle endpoints MUST be keyed by the trust domain identifier.

Example The following examples showcase how the Authorization Server can perform key discovery for the trust domain example.org. Important to note is the difference between example.org trust domain and example.com location for the SPIFFE Bundle Endpoint. This highlights the importance of explicit configuration and undermines the fact that the SPIFFE Bundle Endpoint cannot be derived or discovered from the X509-SVID without explicit configuration. Example configuration at the OAuth Authorization Server in the JSON format

• Note difference between example.org and example.com

Example SPIFFE Bundle Endpoint request, response:

• The use parameter in the JSON Web Key indicates the credential format the key is indended for. Multiple keys of the same use can be present.

The X509-SVID signing certificate (.keys[0].x5c[0] from response above) in text form:

• Arndt: Bundle doesn't match X509-SVID. This needs to be fixed.

Alternative methods to avoid The following key distribution mechanisms are alternatives and SHOULD be avoided for interopability reasons.

SPIFFE Workload API The SPIFFE Workload API allows workloads to retrieve a trust bundle. It requires the authorization server to be part of a SPIFFE trust domain and be considered a workload within it. The SPIFFE Workload API is build in a way that the workload proactively retrieves trust bundles updates and does not need to poll them, which reduces the time to distribute them. In addition to the trust bundle of the trust domain the workload resides in, the SPIFFE Workload API also allows to retrieve trust bundles from federated trust domains. This approach is NOT RECOMMENDED for OAuth SPIFFE Client Authentication for several reasons:

• OAuth Authorization Server needs to be a workload within a SPIFFE trust domain, which is a significant limitation for deployment scenarios.
• Federated trust domain bundles create ambiguity about how they are handled. When distributed via the SPIFFE Workload API the trust relationship and points where they are established become ambiguous.

Manual configuration In small, static environments the authorization server MAY be configured with the SPIFFE bundles manually. This approach requires human interaction to set up, rotate and manage keying material and is thus generally NOT RECOMMENDED.

Using the system trust store X509-SVIDs MUST NOT be validated using the system trust store. The SPIFFE ID carried in the URI SAN is rarely a verifiable attribute in the broader X.509 ecosystem. Using the system trust store as trust anchor would allow ANY certificate authority in it to issue a trusted X509-SVID for ANY SPIFFE ID. In comparison: using SPIFFE-native validation methods restricts the signing of SPIFFE-IDs to the corresponding trust domain signing keys.

Using the JWT-SVID iss claim JWT-SVIDs carrying iss claims could technically be validated by retrieving the signing keys via OpenID Connect Discovery or OAuth 2.0 Authorization Server Metadata. This approach only applies for JWT-SVIDs and only works when the iss claim is present, which is not guaranteed and not part of the JWT-SVID specification. The narrow scope of applicability does not make it a viable alternative to the SPIFFE Bundle Endpoint. In combination with interoperability concerns, this approach is NOT RECOMMENDED.

Security Considerations TODO Security

IANA Considerations This document has no IANA actions.

Normative References The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] This document establishes an IETF URN Sub-namespace for use with OAuth-related specifications. This document is not an Internet Standards Track specification; it is published for informational purposes. A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification. This specification provides a framework for the use of assertions with OAuth 2.0 in the form of a new client authentication mechanism and a new authorization grant type. Mechanisms are specified for transporting assertions during interactions with a token endpoint; general processing rules are also specified. The intent of this specification is to provide a common framework for OAuth 2.0 to interwork with other identity systems using assertions and to provide alternative client authentication mechanisms. Note that this specification only defines abstract message flows and processing rules. In order to be implementable, companion specifications are necessary to provide the corresponding concrete instantiations. This specification defines the use of a JSON Web Token (JWT) Bearer Token as a means for requesting an OAuth 2.0 access token as well as for client authentication. This specification defines mechanisms for dynamically registering OAuth 2.0 clients with authorization servers. Registration requests send a set of desired client metadata values to the authorization server. The resulting registration responses return a client identifier to use at the authorization server and the client metadata values registered for the client. The client can then use this registration information to communicate with the authorization server using the OAuth 2.0 protocol. This specification also defines a set of common client metadata fields and values for clients to use during registration. This document describes OAuth client authentication and certificate-bound access and refresh tokens using mutual Transport Layer Security (TLS) authentication with X.509 certificates. OAuth clients are provided a mechanism for authentication to the authorization server using mutual TLS, based on either self-signed certificates or public key infrastructure (PKI). OAuth authorization servers are provided a mechanism for binding access tokens to a client's mutual-TLS certificate, and OAuth protected resources are provided a method for ensuring that such an access token presented to it was issued to the client presenting the token. n.d. n.d. n.d. n.d. n.d. n.d. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.

Acknowledgments TODO acknowledge.