Internet-Draft | OAuth 2.0 Attestation-Based Client Authe | October 2024 |
Looker, et al. | Expires 24 April 2025 | [Page] |
- Workgroup:
- Network Working Group
- Internet-Draft:
- draft-ietf-oauth-attestation-based-client-auth-04
- Published:
- Intended Status:
- Informational
- Expires:
OAuth 2.0 Attestation-Based Client Authentication
Abstract
This specification defines an extension to the OAuth 2 protocol as defined in [RFC6749] which enables a Client Instance to include a key-bound attestation in interactions with an Authorization Server or a Resource Server. This new method enables Client Instances involved in a client deployment that is traditionally viewed as a public client, to be able to utilize this key-bound attestation to authenticate.¶
About This Document
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://oauth-wg.github.io/draft-ietf-oauth-attestation-based-client-auth/draft-ietf-oauth-attestation-based-client-auth.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/.¶
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 24 April 2025.¶
Copyright Notice
Copyright (c) 2024 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.¶
1. Introduction
The following diagram depicts the overall architecture and protocol flow.¶
(3) +-------+ | | | \ / +---------------+ | | | Client | | Backend | | | +---------------+ / \ | (2) | | (4) | \ / +---------------+ +---------------+ +----->| | | | (1) | | Client | (6) | Authorization | | | Instance |<--------->| Server | +------| | | | +---------------+ +---------------+ / \ | | | +-------+ (5)¶
The following steps describe this OAuth flow:¶
(1) The Client Instance generates a key (Client Instance Key) and optional further attestations (that are out of scope) to prove its authenticity to the Client Backend.¶
(2) The Client Instance sends this data to the Client Backend in request for a Client Attestation JWT.¶
(3) The Client Backend validates the Client Instance Key and optional further data. It generates a signed Client Attestation JWT that is cryptographically bound to the Client Instance Key generated by the Client. Therefore, the attestation is bound to this particular Client Instance.¶
(4) The Client Backend responds to the Client Instance by sending the Client Attestation JWT.¶
(5) The Client Instance generates a Proof of Possession (PoP) with the Client Instance Key.¶
(6) The Client Instance sends both the Client Attestation JWT and the Client Attestation PoP JWT to the authorization server, e.g. within a token request. The authorization server validates the Client Attestation and thus authenticates the Client Instance.¶
Please note that the protocol details for steps (2) and (4), particularly how the Client Instance authenticates to the client Backend, are beyond the scope of this specification. Furthermore, this specification is designed to be flexible and can be implemented even in scenarios where the client does not have a backend server. In such cases, each Client Instance is responsible for performing the functions typically handled by the backend on its own.¶
This approach acknowledges the evolving landscape of OAuth 2 deployments, where the ability for public clients to authenticate securely and reliably has become increasingly important.¶
2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
3. Terminology
- Client Attestation JWT:
-
A JSON Web Token (JWT) generated by the client backend which is bound to a key managed by a Client Instance which can then be used by the instance for client authentication.¶
- Client Attestation Proof of Possession (PoP) JWT:
-
A Proof of Possession generated by the Client Instance using the key that the Client Attestation JWT is bound to.¶
- Client Instance:
-
A deployed instance of a piece of client software.¶
- Client Instance Key:
-
A cryptographic asymmetric key pair that is generated by the Client Instance where the public key of the key pair is provided to the client backend. This public key is then encapsulated within the Client Attestation JWT and is utilized to sign the Client Attestation Proof of Possession.¶
4. Relation to RATS
The Remote Attestation Procedures (RATS) architecture defined by [RFC9334] has some commonalities to this document. The flow specified in this specification relates to the "Passport Model" in RATS. However, while the RATS ecosystem gives explicit methods and values how the RATS Attester proves itself to the Verifier, this is deliberately out of scope for Attestation-Based Client Authentication. Additionally, the terminology between RATS and OAuth is different:¶
-
a RATS "Attester" relates to an OAuth "Client"¶
-
a RATS "Relying Party" relates to an OAuth "Authorization Server or Resource Server"¶
-
a RATS "Verifier" relates to the "Client Backend" defined in this specification¶
-
a RATS "Attestion Result" relates to the "Client Attestation JWT" defined by this specification¶
-
a RATS "Endorser", "Reference Value Provider", "Endorsement", "Evidence" and "Policies and Reference Values" are out of scope for this specification¶
5. Client Attestation Format
This draft introduces the concept of client attestations to the OAuth 2 protocol, using two JWTs: a Client Attestation and a Client Attestation Proof of Possession (PoP). The primary purpose of these JWTs is to authenticate the Client Instance. These JWTs can be transmitted via HTTP headers in an HTTP request (as described in Section 6.1) from a Client Instance to an Authorization Server or Resource Server, or via a concatenated serialization (as described in Section 7) to enable usage outside of the traditional OAuth2 ecosystem .¶
5.1. Client Attestation JWT
The Client Attestation MUST be encoded as a "JSON Web Token (JWT)" according to [RFC7519].¶
The following content applies to the JWT Header:¶
-
typ
: REQUIRED. The JWT type MUST beoauth-client-attestation+jwt
.¶
The following content applies to the JWT Claims Set:¶
-
iss
: REQUIRED. Theiss
(subject) claim MUST contains a unique identifier for the entity that issued the JWT. In the absence of an application profile specifying otherwise, compliant applications MUST compare issuer values using the Simple String Comparison method defined in Section 6.2.1 of [RFC3986].¶ -
sub
: REQUIRED. Thesub
(subject) claim MUST specify client_id value of the OAuth Client.¶ -
exp
: REQUIRED. Theexp
(expiration time) claim MUST specify the time at which the Client Attestation is considered expired by its issuer. The authorization server MUST reject any JWT with an expiration time that has passed, subject to allowable clock skew between systems.¶ -
cnf
: REQUIRED. Thecnf
(confirmation) claim MUST specify a key conforming to [RFC7800] that is used by the Client Instance to generate the Client Attestation PoP JWT for client authentication with an authorization server. The key MUST be expressed using the "jwk" representation.¶ -
iat
: OPTIONAL. Theiat
(issued at) claim MUST specify the time at which the Client Attestation was issued.¶ -
nbf
: OPTIONAL. Thenbf
(not before) claim MUST specify the time before which the Client Attestation MUST NOT be accepted for processing.¶
The following additional rules apply:¶
-
The JWT MAY contain other claims. All claims that are not understood by implementations MUST be ignored.¶
-
The JWT MUST be digitally signed using an asymmetric cryptographic algorithm. The authorization server MUST reject the JWT if it is using a Message Authentication Code (MAC) based algorithm. The authorization server MUST reject JWTs with an invalid signature.¶
-
The authorization server MUST reject a JWT that is not valid in all other respects per "JSON Web Token (JWT)" [RFC7519].¶
The following example is the decoded header and payload of a JWT meeting the processing rules as defined above.¶
{ "typ": "oauth-client-attestation+jwt" "alg": "ES256", "kid": "11" } . { "iss": "https://client.example.com", "sub": "https://client.example.com", "nbf":1300815780, "exp":1300819380, "cnf": { "jwk": { "kty": "EC", "use": "sig", "crv": "P-256", "x": "18wHLeIgW9wVN6VD1Txgpqy2LszYkMf6J8njVAibvhM", "y": "-V4dS4UaLMgP_4fY4j8ir7cl1TXlFdAgcx55o7TkcSA" } } }¶
5.2. Client Attestation PoP JWT
The Client Attestation PoP MUST be encoded as a "JSON Web Token (JWT)" according to [RFC7519].¶
The following content applies to the JWT Header:¶
-
typ
: REQUIRED. The JWT type MUST beoauth-client-attestation-pop+jwt
.¶
The following content applies to the JWT Claims Set:¶
-
iss
: REQUIRED. Theiss
(subject) claim MUST specify client_id value of the OAuth Client.¶ -
exp
: REQUIRED. Theexp
(expiration time) claim MUST specify the time at which the Client Attestation PoP is considered expired. The authorization server MUST reject any JWT with an expiration time that has passed, subject to allowable clock skew between systems. Note that the authorization server may reject JWTs with an "exp" claim value that is unreasonably far in the future.¶ -
aud
: REQUIRED. Theaud
(audience) claim MUST specify a value that identifies the authorization server as an intended audience. The [RFC8414] issuer identifier URL of the authorization server MUST be used as a value for an "aud" element to identify the authorization server as the intended audience of the JWT.¶ -
jti
: REQUIRED. Thejti
(JWT identifier) claim MUST specify a unique identifier for the Client Attestation PoP. The authorization server MAY ensure that JWTs are not replayed by maintaining the set of used "jti" values for the length of time for which the JWT would be considered valid based on the applicable "exp" instant.¶ -
nonce
: OPTIONAL. Thenonce
(nonce) claim MUST specify a String value that is provided by the authorization server to associate the Client Attestation PoP JWT with a particular transaction and prevent replay attacks.¶ -
iat
: OPTIONAL. Theiat
(issued at) claim MUST specify the time at which the Client Attestation PoP was issued. Note that the authorization server may reject JWTs with an "iat" claim value that is unreasonably far in the past.¶ -
nbf
: OPTIONAL. Thenbf
(not before) claim MUST specify the time before which the Client Attestation PoP MUST NOT be accepted for processing.¶
The following additional rules apply:¶
-
The JWT MAY contain other claims. All claims that are not understood by implementations MUST be ignored.¶
-
The JWT MUST be digitally signed using an asymmetric cryptographic algorithm. The authorization server MUST reject the JWT if it is using a Message Authentication Code (MAC) based algorithm. The authorization server MUST reject JWTs with an invalid signature.¶
-
The public key used to verify the JWT MUST be the key located in the "cnf" claim of the corresponding Client Attestation JWT.¶
-
The Authorization Server MUST reject a JWT that is not valid in all other respects per "JSON Web Token (JWT)" [RFC7519].¶
The following example is the decoded header and payload of a JWT meeting the processing rules as defined above.¶
{ "typ": "oauth-client-attestation-pop", "alg": "ES256" } . { "iss": "https://client.example.com", "aud": "https://as.example.com", "nbf":1300815780, "exp":1300819380, "jti": "d25d00ab-552b-46fc-ae19-98f440f25064", "nonce" : "5c1a9e10-29ff-4c2b-ae73-57c0957c09c4" }¶
6. Client Attestation using a Header based syntax
The following section defines how a Client Attestation can be provided in an HTTP request using HTTP headers.¶
6.1. Client Attestation HTTP Headers
A Client Attestation JWT and Client Attestation PoP JWT can be included in an HTTP request using the following request header fields.¶
- OAuth-Client-Attestation:
-
A JWT that conforms to the structure and syntax as defined in Section 5.1¶
- OAuth-Client-Attestation-PoP:
-
A JWT that adheres to the structure and syntax as defined in Section 5.2¶
The following is an example of the OAuth-Client-Attestation header.¶
OAuth-Client-Attestation: eyJhbGciOiAiRVMyNTYiLCJraWQiOiAiMTEifQ.eyJ\ pc3MiOiJodHRwczovL2NsaWVudC5leGFtcGxlLmNvbSIsInN1YiI6Imh0dHBzOi8vY2x\ pZW50LmV4YW1wbGUuY29tIiwibmJmIjoxMzAwODE1NzgwLCJleHAiOjEzMDA4MTkzODA\ sImNuZiI6eyJqd2siOnsia3R5IjoiRUMiLCJ1c2UiOiJzaWciLCJjcnYiOiJQLTI1NiI\ sIngiOiIxOHdITGVJZ1c5d1ZONlZEMVR4Z3BxeTJMc3pZa01mNko4bmpWQWlidmhNIiw\ ieSI6Ii1WNGRTNFVhTE1nUF80Zlk0ajhpcjdjbDFUWGxGZEFnY3g1NW83VGtjU0EifX1\ 9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c¶
The following is an example of the OAuth-Client-Attestation-PoP header.¶
OAuth-Client-Attestation-PoP: eyJhbGciOiJFUzI1NiJ9.ewogICJpc3MiOiAia\ HR0cHM6Ly9jbGllbnQuZXhhbXBsZS5jb20iLAogICJhdWQiOiAiaHR0cHM6Ly9hcy5le\ GFtcGxlLmNvbSIsCiAgIm5iZiI6MTMwMDgxNTc4MCwKICAiZXhwIjoxMzAwODE5MzgwL\ AogICJqdGkiOiAiZDI1ZDAwYWItNTUyYi00NmZjLWFlMTktOThmNDQwZjI1MDY0IiwKI\ CAibm9uY2UiIDogIjVjMWE5ZTEwLTI5ZmYtNGMyYi1hZTczLTU3YzA5NTdjMDljNCIKf\ Q.coB_mtdXwvi9RxSMzbIey8GVVQLv9qQrBUqmc1qj9Bs¶
Note that per [RFC9110] header field names are case-insensitive; so OAUTH-CLIENT-ATTESTATION, oauth-client-attestation, etc., are all valid and equivalent header field names. Case is significant in the header field value, however.¶
The OAuth-Client-Attestation and OAuth-Client-Attestation-PoP HTTP header field values uses the token68 syntax defined in Section 11.2 of [RFC9110] (repeated below for ease of reference).¶
OAuth-Client-Attestation = token68 OAuth-Client-Attestation-PoP = token68 token68 = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) *"="¶
It is RECOMMENDED that the authorization server validate the Client Attestation JWT prior to validating the Client Attestation PoP.¶
6.2. Validating HTTP requests feature client attestations
To validate an HTTP request which contains the client attestation headers, the receiving server MUST ensure the following with regard to a received HTTP request:¶
-
There is precisely one OAuth-Client-Attestation HTTP request header field, where its value is a single well-formed JWT conforming to the syntax outlined in []{client-attestation-jwt}.¶
-
There is precisely one OAuth-Client-Attestation-PoP HTTP request header field, where its value is a single well-formed JWT conforming to the syntax outlined in client-attestation-pop-jwt.¶
-
The signature of the Client Attestation PoP JWT obtained from the OAuth-Client-Attestation-PoP HTTP header verifies with the Client Instance Key contained in the
cnf
claim of the Client Attestation JWT obtained from the OAuth-Client-Attestation HTTP header.¶
6.3. Client Attestation at the Token Endpoint
While usage of the the client attestation mechanism defined by this draft can be used in a variety of different HTTP requests to different endpoints, usage within the token request as defined by [RFC6749] has particular additional considerations outlined below.¶
The Authorization Server MUST perform all of the checks outlined in Section 6.2 for a received access token request which is making use of the client attestation mechanism as defined by this draft.¶
The following example demonstrates usage of the client attestation mechanism in an access token request (with extra line breaks for display purposes only):¶
POST /token HTTP/1.1 Host: as.example.com Content-Type: application/x-www-form-urlencoded OAuth-Client-Attestation: eyJhbGciOiAiRVMyNTYiLCJraWQiOiAiMTEifQ.eyJ\ pc3MiOiJodHRwczovL2NsaWVudC5leGFtcGxlLmNvbSIsInN1YiI6Imh0dHBzOi8vY2x\ pZW50LmV4YW1wbGUuY29tIiwibmJmIjoxMzAwODE1NzgwLCJleHAiOjEzMDA4MTkzODA\ sImNuZiI6eyJqd2siOnsia3R5IjoiRUMiLCJ1c2UiOiJzaWciLCJjcnYiOiJQLTI1NiI\ sIngiOiIxOHdITGVJZ1c5d1ZONlZEMVR4Z3BxeTJMc3pZa01mNko4bmpWQWlidmhNIiw\ ieSI6Ii1WNGRTNFVhTE1nUF80Zlk0ajhpcjdjbDFUWGxGZEFnY3g1NW83VGtjU0EifX1\ 9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c OAuth-Client-Attestation-PoP: eyJhbGciOiJFUzI1NiJ9.ewogICJpc3MiOiAia\ HR0cHM6Ly9jbGllbnQuZXhhbXBsZS5jb20iLAogICJhdWQiOiAiaHR0cHM6Ly9hcy5le\ GFtcGxlLmNvbSIsCiAgIm5iZiI6MTMwMDgxNTc4MCwKICAiZXhwIjoxMzAwODE5MzgwL\ AogICJqdGkiOiAiZDI1ZDAwYWItNTUyYi00NmZjLWFlMTktOThmNDQwZjI1MDY0IiwKI\ CAibm9uY2UiIDogIjVjMWE5ZTEwLTI5ZmYtNGMyYi1hZTczLTU3YzA5NTdjMDljNCIKf\ Q.coB_mtdXwvi9RxSMzbIey8GVVQLv9qQrBUqmc1qj9Bs grant_type=authorization_code& code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4¶
6.4. Client Attestation at the PAR Endpoint
A Client Attestation can be used at the PAR endpoint instead of alternative client authentication mechanisms like JWT client assertion-based authentication (as defined in Section 2.2 of [RFC7523]).¶
The Authorization Server MUST perform all of the checks outlined in Section 6.2 for a received PAR request which is making use of the client attestation mechanism as defined by this draft.¶
The following example demonstrates usage of the client attestation mechanism in a PAR request (with extra line breaks for display purposes only):¶
POST /as/par HTTP/1.1 Host: as.example.com Content-Type: application/x-www-form-urlencoded OAuth-Client-Attestation: eyJhbGciOiAiRVMyNTYiLCJraWQiOiAiMTEifQ.eyJ\ pc3MiOiJodHRwczovL2NsaWVudC5leGFtcGxlLmNvbSIsInN1YiI6Imh0dHBzOi8vY2x\ pZW50LmV4YW1wbGUuY29tIiwibmJmIjoxMzAwODE1NzgwLCJleHAiOjEzMDA4MTkzODA\ sImNuZiI6eyJqd2siOnsia3R5IjoiRUMiLCJ1c2UiOiJzaWciLCJjcnYiOiJQLTI1NiI\ sIngiOiIxOHdITGVJZ1c5d1ZONlZEMVR4Z3BxeTJMc3pZa01mNko4bmpWQWlidmhNIiw\ ieSI6Ii1WNGRTNFVhTE1nUF80Zlk0ajhpcjdjbDFUWGxGZEFnY3g1NW83VGtjU0EifX1\ 9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c OAuth-Client-Attestation-PoP: eyJhbGciOiJFUzI1NiJ9.ewogICJpc3MiOiAia\ HR0cHM6Ly9jbGllbnQuZXhhbXBsZS5jb20iLAogICJhdWQiOiAiaHR0cHM6Ly9hcy5le\ GFtcGxlLmNvbSIsCiAgIm5iZiI6MTMwMDgxNTc4MCwKICAiZXhwIjoxMzAwODE5MzgwL\ AogICJqdGkiOiAiZDI1ZDAwYWItNTUyYi00NmZjLWFlMTktOThmNDQwZjI1MDY0IiwKI\ CAibm9uY2UiIDogIjVjMWE5ZTEwLTI5ZmYtNGMyYi1hZTczLTU3YzA5NTdjMDljNCIKf\ Q.coB_mtdXwvi9RxSMzbIey8GVVQLv9qQrBUqmc1qj9Bs response_type=code&state=af0ifjsldkj&client_id=s6BhdRkqt3 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U &code_challenge_method=S256&scope=account-information¶
7. Concatenated Serialization for Client Attestations
A Client Attestation according to this specification MAY be presented using an alternative representation for cases where the header-based mechanism (as introduced in introduced in Section 6.1 does not fit the underlying protocols, e.g., for direct calls to Browser APIs. In those cases, a concatenated serialization of the Client Attestation and Client Attestation PoP can can be used.¶
7.1. Concatenated Serialization Format
This representation is created by concatenating Client Attestation and Client Attestation PoP separated by a tilde ('~') character:¶
<Client Attestation>~<Client Attestation PoP>¶
This form is similar to an SD-JWT+KB according to Section 5 of [SD-JWT] but does not include Disclosures, uses different typ values and does not include the sd_hash
claim in the PoP.¶
This concatenated serialization form allows a the presentation of a Client Attestation and Client Attestation PoP for cases where a header-based approach is unavailable, e.g., to establish trust in a client when using a direct Browser API call.¶
The following is an example of such a concatenated serialization (with extra line breaks for display purposes only):¶
eyJhbGciOiAiRVMyNTYiLCJraWQiOiAiMTEifQ.eyJpc3MiOiJodHRwczovL2NsaWVud\ C5leGFtcGxlLmNvbSIsInN1YiI6Imh0dHBzOi8vY2xpZW50LmV4YW1wbGUuY29tIiwib\ mJmIjoxMzAwODE1NzgwLCJleHAiOjEzMDA4MTkzODAsImNuZiI6eyJqd2siOnsia3R5I\ joiRUMiLCJ1c2UiOiJzaWciLCJjcnYiOiJQLTI1NiIsIngiOiIxOHdITGVJZ1c5d1ZON\ lZEMVR4Z3BxeTJMc3pZa01mNko4bmpWQWlidmhNIiwieSI6Ii1WNGRTNFVhTE1nUF80Z\ lk0ajhpcjdjbDFUWGxGZEFnY3g1NW83VGtjU0EifX19.SflKxwRJSMeKKF2QT4fwpMeJ\ f36POk6yJV_adQssw5c~eyJhbGciOiJFUzI1NiJ9.ewogICJpc3MiOiAiaHR0cHM6Ly9\ jbGllbnQuZXhhbXBsZS5jb20iLAogICJhdWQiOiAiaHR0cHM6Ly9hcy5leGFtcGxlLmN\ vbSIsCiAgIm5iZiI6MTMwMDgxNTc4MCwKICAiZXhwIjoxMzAwODE5MzgwLAogICJqdGk\ iOiAiZDI1ZDAwYWItNTUyYi00NmZjLWFlMTktOThmNDQwZjI1MDY0IiwKICAibm9uY2U\ iIDogIjVjMWE5ZTEwLTI5ZmYtNGMyYi1hZTczLTU3YzA5NTdjMDljNCIKfQ.coB_mtdX\ wvi9RxSMzbIey8GVVQLv9qQrBUqmc1qj9Bs¶
7.2. Validating the Concatenated Serialization
To validate a client attestation using the concatenated serialization form, the receiving server MUST ensure the following:¶
-
Before the '~' character, there exists precisely a single well-formed JWT conforming to the syntax outlined in client-attestation-jwt.¶
-
After the '~' character, there exists precisely a single well-formed JWT conforming to the syntax outlined in client-attestation-pop-jwt.¶
-
The signature of the Client Attestation PoP JWT obtained after the '~' character verifies with the Client Instance Key contained in the
cnf
claim of the Client Attestation JWT obtained before the '~' character.¶
8. Implementation Considerations
8.1. Reuse of a Client Attestation JWT
Implementers should be aware that the design of this authentication mechanism deliberately allows for a Client Instance to re-use a single Client Attestation JWT in multiple interactions/requests with an Authorization Server, whilst producing a fresh Client Attestation PoP JWT. Client deployments should consider this when determining the validity period for issued Client Attestation JWTs as this ultimately controls how long a Client Instance can re-use a single Client Attestation JWT.¶
8.2. Refresh token binding
Authorization servers issuing a refresh token in response to a token request using the client attestation mechanism as defined by this draft MUST bind the refresh token to the Client Instance, and NOT just the client as specified in section 6 [RFC6749]. To prove this binding, the Client Instance MUST use the client attestation mechanism when refreshing an access token. The client MUST also use the same key that was present in the "cnf" claim of the client attestation that was used when the refresh token was issued.¶
8.2.1. Web Server Default Maximum HTTP Header Sizes
Because the Client Attestation and Client Attestation PoP are communicated using HTTP headers, implementers should consider that web servers may have a default maximum HTTP header size configured which could be too low to allow conveying a Client Attestation and or Client Attestation PoP in an HTTP request. It should be noted, that this limit is not given by the HTTP [RFC9112], but instead web server implementations commonly set a default maximum size for HTTP headers. As of 2024, typical limits for modern web servers configure maximum HTTP headers as 8 kB or more as a default. ## Rotation of Client Instance Key¶
This specification does not provide a mechanism to rotate the Client Instance Key in the Client Attestation JWT's "cnf" claim. If the Client Instance needs to use a new Client Instance Key for any reason, then it MUST request a new Client Attestation JWT from its Client Backend.¶
10. Security Considerations
The guidance provided by [RFC7519] and [RFC8725] applies.¶
10.1. Replay Attack Detection
The following mechanisms exist within this client authentication method in order to allow an authorization server to detect replay attacks for presented client attestation PoPs:¶
-
The client uses "jti" (JWT ID) claims for the Client Attestation PoP JWT and the authorization server maintains a list of used (seen) "jti" values for the time of which the JWT would be considered valid based on the applicable "exp" claim. If any Client Attestation PoP JWT would be replayed, the authorization server would recognize the "jti" and respond with an authentication error.¶
-
The authorization server provides a nonce for the particular transaction and the client uses it for the "nonce" claim in the Client Attestation PoP JWT. The authorization server validates that the nonce matches for the transaction. This approach may require an additional roundtrip in the protocol. The authorization server MUST ensure that the nonce provides sufficient entropy.¶
-
The authorization server may expect the usage of a nonce in the Client Attestation PoP JWT, but instead of providing the nonce explicitly, the client may implicitly reuse an existing artefact, e.g. the authorization code. The authorization server MUST ensure that the nonce provides sufficient entropy.¶
The approach using a nonce explicitly provided by the authorization server gives stronger replay attack detection guarantees, however support by the authorization server is OPTIONAL to simplify mandatory implementation requirements. The "jti" method is mandatory and hence acts as a default fallback.¶
11. Appendix A IANA Considerations
11.1. Registration of attest_jwt_client_auth Token Endpoint Authentication Method
This section registers the value "attest_jwt_client_auth" in the IANA "OAuth Token Endpoint Authentication Methods" registry established by OAuth 2.0 Dynamic Client Registration Protocol [RFC7591].¶
11.2. HTTP Field Name Registration
This section requests registration of the following scheme in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" [IANA.HTTP.Fields] described in [RFC9110]:¶
-
Field Name: OAuth-Client-Attestation¶
-
Status: permanent¶
-
Reference: Section 6.1 of this specification¶
-
Field Name: OAuth-Client-Attestation-PoP¶
-
Status: permanent¶
-
Reference: Section 6.1 of this specification¶
12. References
12.1. Normative References
- [IANA.HTTP.Fields]
- IANA, "Hypertext Transfer Protocol (HTTP) Field Name Registry", n.d., <https://www.iana.org/assignments/http-fields/http-fields.xhtml>.
- [RFC2119]
- Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
- [RFC3986]
- Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/rfc/rfc3986>.
- [RFC7519]
- Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, , <https://www.rfc-editor.org/rfc/rfc7519>.
- [RFC7591]
- Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, , <https://www.rfc-editor.org/rfc/rfc7591>.
- [RFC7800]
- Jones, M., Bradley, J., and H. Tschofenig, "Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)", RFC 7800, DOI 10.17487/RFC7800, , <https://www.rfc-editor.org/rfc/rfc7800>.
- [RFC8174]
- Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
- [RFC8414]
- Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <https://www.rfc-editor.org/rfc/rfc8414>.
- [RFC8725]
- Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, , <https://www.rfc-editor.org/rfc/rfc8725>.
- [RFC9110]
- Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, , <https://www.rfc-editor.org/rfc/rfc9110>.
- [RFC9112]
- Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, , <https://www.rfc-editor.org/rfc/rfc9112>.
12.2. Informative References
- [ARF]
- "The European Digital Identity Wallet Architecture and Reference Framework", n.d..
- [RFC6749]
- Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/rfc/rfc6749>.
- [RFC7523]
- Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, , <https://www.rfc-editor.org/rfc/rfc7523>.
- [RFC9334]
- Birkholz, H., Thaler, D., Richardson, M., Smith, N., and W. Pan, "Remote ATtestation procedureS (RATS) Architecture", RFC 9334, DOI 10.17487/RFC9334, , <https://www.rfc-editor.org/rfc/rfc9334>.
- [SD-JWT]
- Fett, D., Yasuda, K., and B. Campbell, "Selective Disclosure for JWTs (SD-JWT)", Work in Progress, Internet-Draft, draft-ietf-oauth-selective-disclosure-jwt-13, , <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-selective-disclosure-jwt-13>.
Appendix A. Document History
-04¶
-
remove key attestation example¶
-
restructured JWT Claims for better readability¶
-
added JOSE typ values for Client Attestation and Client Attestation PoP¶
-
add RATS relation¶
-
add concatenated representation without headers¶
-
add PAR endpoint example¶
-
fix PoP examples to include jti and nonce¶
-
add iana http field name registration¶
-03¶
-
remove usage of RFC7521 and the usage of client_assertion¶
-
add new header-based syntax introducing Oauth-Client-Attestation and OAuth-Client-Attestation-PoP¶
-
add Client Instance to the terminology and improve text around this concept¶
-02¶
-
add text on the inability to rotate the Client Instance Key¶
-01¶
-
Updated eIDAS example in appendix¶
-
Removed text around jti claim in client attestation, refined text for its usage in the client attestation pop¶
-
Refined text around cnf claim in client attestation¶
-
Clarified how to bind refresh tokens to a Client Instance using this client authentication method¶
-
Made it more explicit that the client authentication mechanism is general purpose making it compatible with extensions like PAR¶
-
Updated acknowledgments¶
-
Simplified the diagram in the introduction¶
-
Updated references¶
-
Added some guidance around replay attack detection¶
-00¶
-
Initial draft¶
Acknowledgments
We would like to thank Brian Campbell, Francesco Marino, Guiseppe De Marco, Kristina Yasuda, Michael B. Jones, Takahiko Kawasaki and Torsten Lodderstedt for their valuable contributions to this specification.¶