initial draft for challenge endpoint

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 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,53 @@ 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}
+# Challenge Retrieval {#challenge-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.
+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.
 
-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.
+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).
 
-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.
-
-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. String containing a Challenge to be used in the OAuth-Attestation-PoP as defined in (#client-attestation-pop-jwt).
+
+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 on any previous successful 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. Note that this also includes error responses.
+
+The following is a non-normative example of an Authorization Response containing a fresh Challenge:
+
+~~~
+HTTP/1.1 302 Found
+OAuth-Client-Attestation-Challenge: AYjcyMzY3ZDhiNmJkNTZ
+Location: https://Wallet.example.org/cb?
+  code=SplxlOBeZQQYbYS6WxSbIA
 ~~~
 
+
 # Implementation Considerations
 
 ## Reuse of a Client Attestation JWT
@@ -482,21 +509,37 @@ The guidance provided by {{RFC7519}} and {{RFC8725}} applies.
 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 authorization server provides a challenge for the particular transaction and the client uses it for the "challenge" claim in the Client Attestation PoP JWT. The authorization server validates that the challenge matches for the transaction. This approach may require an additional roundtrip in the protocol. The authorization server MUST ensure that the challenge provides sufficient entropy.
+- The authorization server may expect the usage of a challenge in the Client Attestation PoP JWT, but instead of providing the challenge explicitly, the client may implicitly reuse an existing artefact, e.g. the authorization code. The authorization server MUST ensure that the challenge 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.
+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" method 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
 
@@ -521,19 +564,19 @@ 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
+
 -05
 
 * add nonce endpoint