Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
2 contributors

Users who have contributed to this file

@evan2645 @yinonavraham
127 lines (94 sloc) 10 KB

The JWT SPIFFE Verifiable Identity Document

Status of this Memo

This document specifies an experimental identity document standard for the internet community, and requests discussion and suggestions for improvements. It is a work in progress. Distribution of this document is unlimited.

Table of Contents

1. Introduction
2. JOSE Header
2.1. Algorithm
2.2. Key ID
2.3. Type
3. JWT Claims
3.1. Subject
3.2. Audience
3.3. Expiration Time
4. Token Signing and Validation
5. Token Transmission
5.1. Serialization
5.2. HTTP
5.3. gRPC
6. Security Considerations
6.1. Replay Protection
6.2. Audience
6.3. Transport Security
Appendix A. Validation Reference

1. Introduction

JWT-SVID is the first token-based SVID in the SPIFFE specification set. Aimed at providing immediate value in solving difficulties associated with asserting identity across Layer 7 boundaries, compatibility with existing applications and libraries is a core requirement.

JWT-SVIDs are standard JOSE-protected JWT tokens with a handful of restrictions applied. JOSE has historically proven difficult to implement securely, gaining a reputation in the security community as a technology which is likely to introduce vulnerabilities in its deployments and implementations. JWT-SVID takes steps to mitigate these problems as much as is reasonably possible without breaking compatibility with existing applications and libraries.

2. JOSE Header

Historically, complexity introduced by the cryptographic agility of the JOSE header has led to a series of vulnerabilities in popular JWT implementations. To avoid such pitfalls, this specification restricts some of the allowances originally afforded. This section describes the permitted registered headers, as well as their values. Any header not described here, registered or private, MUST NOT be included in the JWT-SVID JOSE Header.

Only JWS is supported, and all header values MUST reside in a JWS Protected Header.

2.1. Algorithm

The alg header MUST be set to one of the values defined in RFC 7518 sections 3.3, 3.4, or 3.5. Validators receiving a token with the alg parameter set to a different value MUST reject the token.

The supported alg values are:

alg Param Value Digital Signature Algorithm
RS256 RSASSA-PKCS1-v1_5 using SHA-256
RS384 RSASSA-PKCS1-v1_5 using SHA-384
RS512 RSASSA-PKCS1-v1_5 using SHA-512
ES256 ECDSA using P-256 and SHA-256
ES384 ECDSA using P-384 and SHA-384
ES512 ECDSA using P-521 and SHA-512
PS256 RSASSA-PSS using SHA-256 and MGF1 with SHA-256
PS384 RSASSA-PSS using SHA-384 and MGF1 with SHA-384
PS512 RSASSA-PSS using SHA-512 and MGF1 with SHA-512

2.2. Key ID

The kid header is optional.

2.3. Type

The typ header is optional. If set, its value MUST be either JWT or JOSE.

3. JWT Claims

The JWT-SVID specification does not introduce any new claims, though it does set some restrictions on the registered claims defined by RFC 7519. Registered claims not described in this document, in addition to private claims, MAY be used as implementers see fit. It should be noted, however, that reliance on claims which are not defined here may impact interoperability, as the producing and consuming applications must independently agree. Implementers should exercise caution when introducing additional claims and carefully consider the impact on SVID interoperability, particularly in environments where the implementer does not control both the producer and the consumer.

This section outlines the requirements and restrictions placed upon existing registered claims by the JWT-SVID specification.

3.1. Subject

The sub claim MUST be set to the SPIFFE ID of the workload to which it is issued. This is the primary claim against which workload identity is asserted.

3.2. Audience

The aud claim MUST be present, containing one or more values. Validators MUST reject tokens without an aud claim set, or if the value that the validator identifies with is not present as an aud element. It is strongly recommended that the number of values be limited to one in normal cases. Please see the Security Considerations section for more information.

The values chosen are site-specific, and SHOULD be scoped to the service which it is intended to be presented to. For example, reports or spiffe://example.org/reports are suitable values for tokens which are presented to the reports service. Values such as production or spiffe://example.org/ are discouraged due to their wide scope, opening the possibility for impersonation if just a single service in production is compromised.

3.3. Expiration Time

The exp claim MUST be set, and validators MUST reject tokens without this claim. Implementers are encouraged to keep the validity period as small as is reasonably possible, however this specification does not set any hard upper limits on its value.

4. Token Signing and Validation

JWT-SVID signing and validation semantics are the same as regular JWTs/JWSs. Validators MUST ensure that the alg header is set to a supported value before processing.

JWT-SVID signatures are computed and validated following the steps outlined in RFC 7515 section 7. The aud and exp claims MUST be present and processed according to RFC 7519 sections 4.1.3 and 4.1.4. Validators receiving tokens without the aud and exp claims set MUST reject the token.

5. Token Transmission

This section describes the manner in which a JWT-SVID may be transmitted from one workload to another.

5.1. Serialization

JWT-SVIDs MUST be serialized using the JWS Compact Serialization method described in RFC 7515 Section 3.1. Note that this precludes the use of a JWS Unprotected Header, as mandated in the JOSE Header section.

5.2. HTTP

JWT-SVIDs transmitted via HTTP SHOULD be transmitted in the “Authorization” header (“authorization” for HTTP/2) using the “Bearer” authentication scheme defined in RFC 6750 section 2.1. For example, Authorization: Bearer <serialized_token> in HTTP/1.1 and authorization: Bearer <serialized_token> in HTTP/2.

5.3. gRPC

The gRPC protocol uses HTTP/2. As a result, the HTTP transmission guidelines in the HTTP section equally apply. Concretely, gRPC implementations SHOULD set a metadata key authorization with a value of Bearer <serialized_token>.

6. Security Considerations

This section outlines the security considerations that implementers and users should take into account when using JWT-SVID.

6.1. Replay Protection

Being a bearer token, JWT-SVIDs are susceptible to replay attacks. By requiring that the aud and exp claims be set, this specification has taken steps to improve the situation, but is unable to solve it completely while retaining validation compatibility with RFC 7515. It is very important to understand this risk. Use of an aggressive value for the exp claim is recommended. Some users may wish to leverage the jti claim despite the added overhead. While use of the jti claim is permitted by this specification, it should be noted that JWT-SVID validators are not required to track jti uniqueness.

6.2. Audience

There is an implicit trust granted to recipients of JWT-SVIDs. Tokens sent to one audience can be replayed to another audience should more than one be present. For example, if Alice has a token with audiences Bob and Chuck, and transmits that token to Chuck, then Chuck can impersonate Alice by sending the same token to Bob. As such, care should be taken when minting a JWT-SVID with more than one audience. Single audience JWT-SVID tokens are strongly recommended to limit the scope of replayability.

6.3. Transport Security

JWT-SVIDs share the same risks as other bearer token schemes, namely interception of the bearer token grants an attacker the full privileges afforded by the JWT-SVID due to their inherent replay-ability. There are mitigations to limit the impact, such as mandated expiration via the exp claim but there will always be a window of vulnerability. For this reason, all hops/links along the communication channels over which JWT-SVIDs are transmitted should provide confidentiality (e.g. from workload to load balancer, from the load balancer to another workload). Notable exceptions are non-network links with reasonable security assumptions regarding exposure, for example a Unix domain socket between two processes within the same host.

Appendix A. Validation Reference

The following table provides a quick reference for anyone implementing a JWT-SVID validator. If using an off-the-shelf library, it is the responsibility of the implementer to ensure that the following validation steps are being taken.

Additionally, please see the JWT-SVID Schema for a more formal reference.

Field Type Requirement
alg Header Set to one of the values in the table in section 2.1. Reject otherwise.
aud Claim At least one value present. Users should configure at least one acceptable value in advance. Reject otherwise.
exp Claim Must be set. Must not be in the past (a small amount of leeway is acceptable). Reject otherwise.
You can’t perform that action at this time.