Merge pull request #59 from openid/request_uri2

request_uri extension

diagrams/request_uri_mode_post.md

@@ -0,0 +1,44 @@
+```plantuml
+@startuml
+
+autonumber
+
+participant "Wallet" as w
+
+participant "User Agent" as u
+
+participant "Verifier" as r
+
+u --> r : use
+activate r
+
+r --> u: authorization request\n(client_id, request_uri, request_uri_method=post, [client_id_scheme])
+deactivate r
+u --> w: authorization request\n(client_id, request_uri, request_uri_method=post, [client_id_scheme])
+activate w
+w --> w: [optional. Check client_id with trust framework]
+note over r,w
+    Note that the client_id is self asserted by the verifier. If the client_id is not trusted, then the user should be informed that an untrusted 
+    verifier is requesting information and asked if he/she wants to proceed. If the client_id identifies a trusted verifier, then the request_uri 
+    that is responded to should be the one that actually belongs to the trusted client_id, as verified by the trust framework.
+end note
+w --> r: POST **request_uri** ([wallet_metadata][, wallet_nonce])
+r -> r: create and sign (and optionally encrypt) request object 
+r --> w: **signed (optionally encrypted) request object** (client_id, client_id_scheme, wallet_nonce, nonce, \nresponse_uri, presentation_definition, state)
+w -> w: authenticate and\n authorize Verifier
+
+note over u, w: User authentication and Credential selection/confirmation
+
+w -> w: create credential presentation(s) associated with nonce
+w --> r: POST response \n(vp_token(credential presentation(s)), presentation_submission, state)
+r -> r: check state, store vp_token\n & create redirect_uri with response_code
+r --> w: redirect_uri
+w --> u: redirect (redirect_uri)
+u --> r: redirect (redirect_uri)
+activate r
+r --> r: presentation response
+r -> r: validate response \n(incl. response_code)
+r -> r: validate presentation \n(incl. nonce binding)
+r -> r: use presented credential 
+@enduml
+```

openid-4-verifiable-presentations-1_0.md

@@ -232,7 +232,14 @@ Presentation of Verifiable Credentials using OpenID for Verifiable Presentations
 
 The Authorization Request follows the definition given in [@!RFC6749] taking into account the recommendations given in [@!I-D.ietf-oauth-security-topics].
 
-The Verifier may send an Authorization Request as Request Object by value or by reference as defined in JWT-Secured Authorization Request (JAR) [@RFC9101].
+The Verifier MAY send an Authorization Request as a Request Object either by value or by reference, as defined in the JWT-Secured Authorization Request (JAR) [@RFC9101].
+
+This specification defines a new mechanism for the cases when the Wallet wants to provide to the Verifier details about its technical capabilities to
+allow the Verifier to generate a request that matches the technical capabilities of that Wallet.
+To enable this, the Authorization Request can contain a `request_uri_method` parameter with the value `post`
+that signals to the Wallet that it can make an HTTP POST request to the Verifier's `request_uri`
+endpoint with information about its capabilities as defined in {#request_uri_method_post}. The Wallet MAY continue with JAR
+when it receives `request_uri_method` parameter with the value `post` but does not support this feature.
 
 The Verifier articulates requirements of the Credential(s) that are requested using `presentation_definition` and `presentation_definition_uri` parameters that contain a Presentation Definition JSON object as defined in Section 5 of [@!DIF.PresentationExchange]. Wallet implementations MUST process Presentation Definition JSON object and select candidate Verifiable Credential(s) using the evaluation process described in Section 8 of [@!DIF.PresentationExchange] unless implementing only a credential profile that provides rules on how to evaluate and process [@!DIF.PresentationExchange].
 
@@ -261,6 +268,12 @@ This specification defines the following new parameters:
 
 A public key to be used by the Wallet as an input to the key agreement to encrypt Authorization Response (see (#jarm)). It MAY be passed by the Verifier using the `jwks` or the `jwks_uri` claim within the `client_metadata` or `client_metadata_uri` request parameter.
 
+`request_uri_method`: 
+: OPTIONAL. A string determining the HTTP method to be used when the `request_uri` parameter is included in the same request. Two case-sensitive valid values are defined in this specification: `get` and `post`. If `request_uri_method` value is `get`, the Wallet MUST send the request to retrieve the Request Object using the HTTP GET method, i.e., as defined in [@RFC9101]. If `request_uri_method` value is `post`, a supporting Wallet MUST send the request using the HTTP POST method as detailed in (#request_uri_method_post). If the `request_uri_method` parameter is not present, the Wallet MUST process the `request_uri` parameter as defined in [@RFC9101]. Wallets not supporting the `post` method will send a GET request to the request URI (default behavior as defined in [@RFC9101]). `request_uri_method` parameter MUST NOT be present if a `request_uri` parameter is not present.
+
+If the Verifier set the `request_uri_method` parameter value to `post` and there is no other means to convey its capabilities to the Wallet, it SHOULD add the `client_metadata` parameter to the Authorization Request. 
+This enables the Wallet to assess the Verifier's capabilities, allowing it to transmit only the relevant capabilities through the `wallet_metadata` parameter in the Request URI POST request. If the Verifier uses the `client_id_scheme` parameter in the Request Object, it MUST also add the same `client_id_scheme` value in the Authorization Request.   
+
 The following additional considerations are given for pre-existing Authorization Request parameters:
 
 `nonce`:
@@ -283,6 +296,17 @@ The following is a non-normative example of an Authorization Request:
     &nonce=n-0S6_WzA2Mj HTTP/1.1
 ```
 
+The following is a non-normative example of an Authorization Request with a `request_uri_method` parameter (including the additional `client_id_scheme` and `client_metadata` parameters): 
+
+```
+  GET /authorize?
+    client_id=client.example.org
+    &client_id_scheme=x509_san_dns
+    &client_metadata=...
+    &request_uri=https%3A%2F%2Fclient.example.org%2Frequest%2Fvapof4ql2i7m41m68uep
+    &request_uri_method=post HTTP/1.1
+```
+
 ## `presentation_definition` Parameter {#request_presentation_definition}
 
 This parameter contains a Presentation Definition JSON object conforming to the syntax defined in Section 5 of [@!DIF.PresentationExchange].
@@ -460,6 +484,67 @@ To use `client_id_scheme` values `entity_id`, `did`, `verifier_attestation`, `x5
 
 Other specifications can define further values for the `client_id_scheme` parameter. It is RECOMMENDED to use collision-resistant names for such values.
 
+## Request URI Method `post` {#request_uri_method_post}
+
+This request is handled by the Request URI endpoint of the Verifier.  
+
+The request MUST use the HTTP POST method with the `https` scheme, and the content type `application/x-www-form-urlencoded` and the accept header set to `application/oauth-authz-req+jwt`.
+
+The following parameters are defined: 
+
+`wallet_metadata`:
+: OPTIONAL. A String containing a JSON object containing metadata parameters as defined in (#as_metadata_parameters). 
+
+`wallet_nonce`:
+: OPTIONAL. A String value used to mitigate replay attacks of the Authorization Request. When received, the Verifier MUST use it as the `wallet_nonce` value in the signed authorization request object. Value can be a base64url encoded, fresh, cryptographically random number with sufficient entropy.  
+
+If the Wallet requires the Verifier to encrypt the Request Object, it SHOULD use the `jwks` or `jwks_uri` parameter within the `wallet_metadata` parameter to pass the public key for the input to the key agreement. Other mechanisms to pass the encryption key can be used as well. If the Wallet requires an encrypted Authorization Response, it SHOULD specify supported encryption algorithms using the `authorization_encryption_alg_values_supported` and `authorization_encryption_enc_values_supported` parameters. 
+
+Additionally, if the `client_id_scheme` value permits signed Request Objects, the Wallet SHOULD list supported cryptographic algorithms for securing the Request Object through the `request_object_signing_alg_values_supported` parameter. Conversely, the Wallet MUST NOT include this parameter if the `client_id_scheme` precludes signed Request Objects.
+
+The following is a non-normative example of a request:
+
+```
+  POST /request HTTP/1.1
+  Host: client.example.org
+  Content-Type: application/x-www-form-urlencoded
+
+    wallet_metadata=%7B%22vp_formats_supported%22%3A%7B%22jwt_vc_json%22%3A%7B%22alg_values_supported
+    %22%3A%5B%22ES256K%22%2C%22ES384%22%5D%7D%2C%22jwt_vp_json%22%3A%7B%22alg_values_supported%22%3A%
+    5B%22ES256K%22%2C%22EdDSA%22%5D%7D%7D%7D&
+    wallet_nonce=qPmxiNFCR3QTm19POc8u
+```
+
+### Request URI Response
+
+The Request URI response MUST be an HTTP response with the content type "application/oauth-authz-req+jwt" and the body being a signed, optionally encrypted, request object as defined in [@RFC9101]. The request object MUST fulfill the requirements as defined in (#vp_token_request).
+
+The following is a non-normative example of a request object:
+
+```json
+{
+   "client_id": "client.example.org",
+   "client_id_scheme": "x509_san_dns",
+   "response_uri": "https://client.example.org/post",
+   "response_type": "vp_token",
+   "response_mode": "direct_post",
+   "presentation_definition": {...},
+   "nonce": "n-0S6_WzA2Mj",
+   "wallet_nonce": "qPmxiNFCR3QTm19POc8u",
+   "state" : "eyJhb...6-sVA"
+}
+```
+
+The Wallet MUST process the request as defined in [@RFC9101]. Additionally, if the Wallet passed a `wallet_nonce` in the POST request, the Wallet MUST validate whether the request object contains the respective nonce value in a `wallet_nonce` claim. If it does not, the Wallet MUST terminate request processing. 
+
+The Wallet MUST extract the set of Authorization Request parameters from the Request Object. The Wallet MUST only use the parameters in this Request Object, even if the same parameter was provided in an Authorization Request query parameter. The Client Identifier value in the `client_id` Authorization Request parameter and the Request Object `client_id` claim value MUST be identical. If the Authorization Request contains a `client_id_scheme` parameter, the `client_id_scheme` Authorization Request parameter and the Request Object `client_id_scheme` claim value MUST be identical. If any of these conditions are not met, the Wallet MUST terminate request processing.
+
+The Wallet then validates the request as specified in OAuth 2.0 [@RFC6749].
+
+### Request URI Error Response
+
+If the Verifier responds with any HTTP error response, the Wallet MUST terminate the process.
+
 # Response {#response}
 
 A VP Token is only returned if the corresponding Authorization Request contained a `presentation_definition` parameter, a `presentation_definition_uri` parameter, or a `scope` parameter representing a Presentation Definition (#vp_token_request).
@@ -704,6 +789,11 @@ This document also defines the following additional error codes and error descri
 
 - The Presentation Definition URL can be reached, but the specified `presentation_definition` cannot be found at the URL.
 
+`invalid_request_uri_method`:
+
+- The value of the `request_uri_method` request parameter is neither `get` nor `post` (case-sensitive).
+
+
 ## VP Token Validation
 
 Verifiers MUST validate the VP Token in the following manner:
@@ -1105,6 +1195,18 @@ Implementations MUST follow [@!BCP195].
 
 Whenever TLS is used, a TLS server certificate check MUST be performed, per [@!RFC6125].
 
+# Privacy Considerations
+
+## Authorization Requests with Request URI
+
+If the Wallet is acting within a trust framework that allows the Wallet to determine whether a 'request_uri' belongs to a certain 'client_id', the Wallet is RECOMMENDED to validate the Verifier's authenticity and authorization given by 'client_id' and that the 'request_uri' corresponds to this Verifier. If the link cannot be established in those cases, the Wallet SHOULD refuse the request or ask the End-User for advise.
+
+If no user interaction is required before sending the request, it is easy to request on a large scale and in an automated fashion the wallet capabilities from all visitors of a website. Even without personally identifiable information (PII) this can reveal some information about users, like their nationality (e.g., a Wallet with special capabilities only used in one EU member state).
+
+Mandatory user interaction before sending the request, like clicking a button, unlocking the wallet or even just showing a screen of the app, can make this less attractive/likely to being exploited.
+
+Requests from the Wallet to the Verifier SHOULD be sent with the minimal amount of information possible, and in particular, without any HTTP headers identifying the software used for the request (e.g., HTTP libraries or their versions). The Wallet MUST NOT send PII or any other data that could be used for fingerprinting to the Request URI in order to prevent user tracking. 
+
 {backmatter}
 
 <reference anchor="VC_DATA" target="https://www.w3.org/TR/2022/REC-vc-data-model-20220303/">
@@ -1695,6 +1797,10 @@ The technology described in this specification was made available from contribut
 
    [[ To be removed from the final specification ]]
 
+   -21
+
+   * added `post` request method for Request URI
+
    -20
 
    * added "verifier_attestation" client id scheme value