Merge pull request #112 from oauth-wg/nonce_endpoint

new proposal for challenge endpoint

Author: paulbastian

draft-ietf-oauth-attestation-based-client-auth.md

@@ -36,6 +36,7 @@ author:
 
 normative:
   RFC3986: RFC3986
+  RFC6750: RFC6750
   RFC7591: RFC7591
   RFC7519: RFC7519
   RFC7800: RFC7800
@@ -125,7 +126,7 @@ Please note that the protocol details for steps (2) and (4), particularly how th
 
 {::boilerplate bcp14-tagged}
 
-# Terminology
+# Terminology {#terminology}
 
 Client Attestation JWT:
 :  A JSON Web Token (JWT) generated by the Client Attester which is bound to a key managed by a Client Instance which can then be used by the instance for client authentication.
@@ -142,6 +143,9 @@ Client Instance Key:
 Client Attester:
 : An entity that authenticates a Client Instance and attests it by issuing a Client Attestation JWT.
 
+Challenge:
+: A String that is the input to a cryptographic challenge-response pattern. This is traditionally called a nonce within OAuth.
+
 # 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:
@@ -221,7 +225,7 @@ The following content applies to the JWT Claims Set:
 * `exp`: REQUIRED. The `exp` (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. The `aud` (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. The `jti` (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. The `nonce` (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.
+* `challenge`: OPTIONAL. The `challenge` (challenge) claim MUST specify a String value that is provided by the authorization server for the client to include in the Client Attestation PoP JWT.
 * `iat`: OPTIONAL. The `iat` (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. The `nbf` (not before) claim MUST specify the time before which the Client Attestation PoP MUST NOT be accepted for processing.
 
@@ -249,7 +253,7 @@ The following example is the decoded header and payload of a JWT meeting the pro
   "nbf": 1300815780,
   "exp": 1300819380,
   "jti": "d25d00ab-552b-46fc-ae19-98f440f25064",
-  "nonce" : "5c1a9e10-29ff-4c2b-ae73-57c0957c09c4"
+  "challenge": "5c1a9e10-29ff-4c2b-ae73-57c0957c09c4"
 }
 ~~~
 
@@ -314,6 +318,8 @@ To validate an HTTP request which contains the client attestation headers, the r
 2. 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).
 3. 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.
 
+An error parameter according to Section 3 of {{RFC6750}} SHOULD be included to indicate why a request was declined. If the Client Attestation is absent or not using an expected server-provided challenge, the value `use_attestation_challenge` can be used to indicate that an attestation with a server-provided challenge was expected. If the attestation and proof of possession was present but could not be successfully verified, the value `invalid_client_attestation` is used.
+
 ## Client Attestation at the Token Endpoint {#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.
@@ -424,32 +430,59 @@ To validate a client attestation using the concatenated serialization form, the
 2. After the '~' character, there exists precisely a single well-formed JWT conforming to the syntax outlined in [](client-attestation-pop-jwt).
 3. 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.
 
-# Nonce Retrieval {#nonce-retrieval}
-
-This specification defines header fields that allow a Client to request a fresh nonce value to be used in the OAuth-Client-Attestation-PoP. The nonce is opaque to the client.
+# Challenge Retrieval {#challenge-retrieval}
 
-An Authorization Server compliant with this specification SHOULD signal via the metadata entry `client_attestation_pop_nonce_required` which endpoints support and expect a server-provided nonce. The client MUST retrieve a nonce before other calls to this endpoint and MUST use this nonce for the Client Attestation PoP.
+This section defines an optional mechanism that allows a Client to request a fresh Challenge from the Authorization Server to be included in the Client Attestation PoP JWT. This construct may be similar or equivalent to a nonce, see [](terminology). The value of the challenge is opaque to the client.
 
-A Request to an endpoint supporting the server-provided nonce MUST include the `attestation-nonce-request` field name with the value `true` and use the HTTP method of type OPTIONS (without payload) to actively request a nonce. The server answers with an HTTP Response with status code 200 without body, but sets the header field `attestation-nonce` to the nonce.
+An Authorization Server MAY offer a challenge endpoint for Clients to fetch Challenges in the context of this specification. If the Authorization Server supports metadata as defined in {{RFC8414}}, it MUST signal support for the challenge endpoint by including the metadata entry `challenge_endpoint` containing the URL of the endpoint as its value. If the Authorization Server offers a challenge endpoint, the Client MUST retrieve a challenge and MUST use this challenge in the OAuth-Attestation-PoP as defined in (#client-attestation-pop-jwt).
 
-The client MUST use this nonce in the OAuth-Attestation-PoP as defined in (#client-attestation-pop-jwt).
+A request for a Challenge is made by sending an HTTP POST request to the URL provided in the challenge_endpoint parameter of the Authorization Server metadata.
 
 The following is a non-normative example of a request:
 
 ~~~
-OPTIONS /as/par HTTP/1.1
+POST /as/challenge HTTP/1.1
 Host: as.example.com
-attestation-nonce-request: true
+Accept: application/json
 ~~~
 
-the following is a non-normative example of a response:
+The Authorization Server provides a Challenge in the HTTP response with a 200 status code and the following parameters included in the message body of the HTTP response using the application/json media type:
+* attestation_challenge: REQUIRED if the authorization server supports Client Attestations and server provided challenges as described in this document. String containing a Challenge to be used in the OAuth-Attestation-PoP as defined in (#client-attestation-pop-jwt). The intention of this element not being required in other circumstances is to preserve the ability for the challenge endpoint to be used in other applications unrelated to client attestations.
+
+The Authorization Server MUST make the response uncacheable by adding a `Cache-Control` header field including the value `no-store`. The Authorization Server MAY add additional challenges or data.
+
+The following is a non-normative example of a response:
 
 ~~~
 HTTP/1.1 200 OK
 Host: as.example.com
-attestation-nonce: AYjcyMzY3ZDhiNmJkNTZ
+Content-Type: application/json
+
+{
+  "attestation_challenge": "AYjcyMzY3ZDhiNmJkNTZ"
+}
 ~~~
 
+## Providing Challenges on Previous Responses
+
+The Authorization Server MAY provide a fresh Challenge with any HTTP response using a HTTP header-based syntax. The HTTP header field parameter MUST be named "OAuth-Client-Attestation-Challenge" and contain the value of the Challenge. The Client MUST use this new Challenge for the next OAuth-Client-Attestation-PoP.
+
+The following is a non-normative example of an Authorization Response containing a fresh Challenge:
+
+~~~
+HTTP/1.1 200 OK
+Content-Type: application/json
+Cache-Control: no-store
+OAuth-Client-Attestation-Challenge: AYjcyMzY3ZDhiNmJkNTZ
+
+{
+  "access_token": "2YotnFZFEjr1zCsicMWpAA",
+  "token_type": "Bearer",
+  "expires_in": 3600
+}
+~~~
+
+
 # Implementation Considerations
 
 ## Reuse of a Client Attestation JWT
@@ -468,6 +501,16 @@ Because the Client Attestation and Client Attestation PoP are communicated using
 
 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 Attester.
 
+## Replay Attack Detection {#implementation-consideration-replay}
+
+Authorization Servers implementing measures to detect replay attacks as described in [](#security-consideration-replay) require efficient data structures to manage large amounts of challenges for use cases with high volumes of transactions. To limit the size of the data structure, the Authorization Server should use a sliding window, allowing Client Attestation PoPs within a certain time window, in which the seen `challenge` or `jti` values are stored, but discarded afterwards. To ensure security, Client Attestation PoPs outside this time window MUST be rejected by the Authorization Server. The allowed window is determined by the `iat` of the Client Attestation PoP and the sliding window time duration chosen by the Authorization Server. These data structures need to:
+
+- search the data structure to validate whether a challenge form a Client Attestation PoP has been previously seen
+- insert the new challenges from the Client Attestation PoP if the search returned no result
+- delete the challenges after the Client Attestation PoP has passed the sliding time window
+
+A trie (also called prefix tree), or a patricia trie (also called radix tree) is a RECOMMENDED data structures to implement such a mechanism.
+
 # Privacy Considerations
 
 ## Client Instance Tracking Across Authorization Servers
@@ -478,26 +521,50 @@ Implementers should be aware that using the same client attestation across multi
 
 The guidance provided by {{RFC7519}} and {{RFC8725}} applies.
 
-## Replay Attack Detection
+## Replay Attacks {#security-consideration-replay}
+
+An Authorization Server SHOULD implement measures to detect replay attacks by the Client Instance. In the context of this specification, this means to detect that an attacker is resending the same Client Attestation PoP JWT in multiple requests. The following options are RECOMMENDED for this client authentication method:
 
-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 Authorization Server manages a list of witnessed `jti` values of the Client Attestation PoP JWT for the time window of which the JWT would be considered valid. This sliding time window is based on the `iat` of the Client Attestation PoP and and the duration chosen by the Authorization Server. If any Client Attestation PoP JWT would be replayed, the Authorization Server would recognize the `jti` value in the list and respond with an authentication error. Details how to implement such a data structure to maintain `jti` values is given in [](#implementation-consideration-replay).
+- The Authorization Server provides a challenge as an `OAuth-Client-Attestation-Challenge` in the challenge endpoint to the Client Instance and the Client uses it as a `challenge` value in the Client Attestation PoP JWT. The Authorization Server may chose to:
+  - manage a list of witnessed `challenge` values, similar to the previously described `jti` approach. Details how to implement such a data structure to maintain `challenge` values is given in [](#implementation-consideration-replay). This guarantees stronger replay protection with a challenge chosen by the Authorization Server itself, at the potential cost of an additional round-trip.
+  - use self-contained challenges while not storing the seen challenges. This approach scales well, while only guaranteeing freshness, but no replay protection within the limited time-window chosen by the Authorization Server.
+- The Authorization Server generates a challenge that is bound to the Client Instance's session, such that a specific `challenge` in the Client Attestation PoP JWT is expected and validated. The Authorization Server may either:
+  - send the challenge as part of another previous response to the Client Instance of providing the challenge explicitly
+  - reuse an existing artefact of the Client Instance's session, e.g. the authorization code. This MUST be communicated out-of-band between Authorization Server and Client.
 
-- 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.
+Because clock skews between servers and clients may be large, Authorization Servers MAY limit Client Attestation PoP lifetimes by using server-provided challenge values containing the time at the server rather than comparing the client-supplied iat time to the time at the server. Challenges created in this way yield the same result even in the face of arbitrarily large clock skews.
 
-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.
+In any case the Authorization Server SHOULD ensure the freshness of the Client Attestation PoP by checking either the iat claim or if present the server provided challenge, is within an acceptable time window.
+
+The approach using a challenge 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` value is mandatory and hence acts as a default fallback.
 
 # Appendix A IANA Considerations
 
 ## OAuth Parameters Registration
 
 This specification requests registration of the following values in the IANA "OAuth Authorization Server Metadata" registry {{IANA.OAuth.Params}} established by {{RFC8414}}.
 
-* Metadata Name: client_attestation_pop_nonce_required
-* Metadata Description: An array of URLs that specify the endpoints supporting the nonce retrieval and expecting a Client Attestation bound to a server-provided nonce.
+* Metadata Name: challenge_endpoint
+* Metadata Description: URL of the authorization servers challenge endpoint which is used to obtain a fresh challenge for usage in client authentication methods such as client attestation.
+* Change Controller: IETF
+* Reference: [](#challenge-retrieval) of this specification
+
+## OAuth Extensions Error Registration
+
+This specification requests registration of the following values in the IANA "OAuth Extensions Error Registry" registry of {{IANA.OAuth.Params}} established by {{RFC6749}}.
+
+* Name: use_attestation_challenge
+* Usage Location: token error response, resource access error response
+* Protocol Extension: OAuth 2.0 Attestation-Based Client Authentication
+* Change Controller: IETF
+* Reference: this specification
+
+* Name: invalid_client_attestation
+* Usage Location: token error response, resource access error response
+* Protocol Extension: OAuth 2.0 Attestation-Based Client Authentication
 * Change Controller: IETF
-* Reference: [](#nonce-retrieval) of this specification
+* Reference: this specification
 
 ## Registration of attest_jwt_client_auth Token Endpoint Authentication Method
 
@@ -522,19 +589,21 @@ This section requests registration of the following scheme in the "Hypertext Tra
 
 <br/>
 
-* Field Name: attestation-nonce-request
+* Field Name: OAuth-Client-Attestation-Challenge
 * Status: permanent
-* Reference: [](#nonce-retrieval) of this specification
-
-<br/>
-
-* Field Name: attestation-nonce
-* Status: permanent
-* Reference: [](#nonce-retrieval) of this specification
+* Reference: [](#challenge-retrieval) of this specification
 --- back
 
 # Document History
 
+-06
+
+* add oauth error response values `invalid_client_attestation` and `use_attestation_challenge`
+* revert the HTTP OPTIONS mechanism to fetch nonces and add a dedicated challenge endpoint
+* rename nonce to challenge
+* rewrite security consideration on replay attacks
+* add implementation consideration on replay attacks
+
 -05
 
 * add nonce endpoint