fix: RP discovery_uri -> request_uri_method according to Torsten's ad…

…avnced flow

docs/en/relying-party-solution.rst

@@ -8,7 +8,7 @@
 Relying Party Solution
 +++++++++++++++++++++++
 
-This section describes how a Relying Party may request to a Wallet Instance the presentation of the PID and the (Q)EAAs, 
+This section describes how a Relying Party requests to a Wallet Instance the presentation of the PID/EAAs 
 according to `OpenID for Verifiable Presentations - draft 20 <https://openid.net/specs/openid-4-verifiable-presentations-1_0.html>`_.
 
 In this section the following flows are described:
@@ -23,20 +23,15 @@ High Level Design
 
 From the User's perspective:
 
-1. the Wallet Instance scans the QR Code and obtains the URL (Cross Device flow) or obtain directly the URL (Same Device flow);
-2. the Wallet Instance extracts from the payload the ``client_id`` parameter;
+1. the Wallet Instance scans the QR Code and obtains the URL (Cross Device flow) or obtain directly an URL (Same Device flow);
+2. the Wallet Instance extracts from the payload the ``client_id`` and the `request_uri` parameters;
 3. the Wallet Instance establishes the Trust to the Relying Party by building the Federation Trust Chain. Implementations may evaluate the trust after having obtained the signed Request Object (see point 5);
-4. the Wallet Instance extracts ``discovery_uri`` if any.
-  - If ``discovery_uri`` is present, then: 
-    - The Wallet Instance sends the Wallet Instance Metadata to the Relying Party's ``discovery_uri``;
-    - the Wallet Instance obtains the signed Request Object.
-  - Otherwise:
-    - the Wallet Instance extracts from the payload the ``request_uri`` parameter;
-    - the Wallet Instance invokes the retrieved URI;
-    - the Wallet Instance obtains the signed Request Object from the Relying Party.
-5. The Wallet Instance assesses the trustworthiness of the Relying Party by examining its associated Trust Chain and verifying the signature to ensure interaction with a reliable entity;
+4. the Wallet fetches the signed Request Object using an HTTP request with method GET to the endpoint provided in the ``request_uri`` parameter;
+5. the Wallet verifies the signature of the signed Request Object and that its issuer matches the ``client_id`` obtained at the step number 2.
+6. the Wallet checks the presence in the signed Request Object of the parameter `request_uri_method`, if this parameter is present and set with the ``post`` valueThe Wallet transmits its metadata to the request_uri endpoint of the Relying Party using an HTTP POST method and obtains an updated signed Request Object;
+5. The Wallet Instance evaluates the requested PID/EAAs and checks the elegibility of the Relying Party in asking these by applying the policies related to that specific Relying Party;
 6. the Wallet Instance asks User disclosure and consent;
-7. the Wallet Instance presents the requested disclosure of credentials to the Relying Party;
+7. the Wallet Instance presents the requested disclosure of P to the Relying Party;
 8. the Wallet Instance informs the User about the successfull authentication with the Relying Party and give a good user experience to let the User continuing its navigation.
 
 
@@ -56,7 +51,7 @@ Below a sequence diagram that summarizes the interactions between all the involv
 
 .. image:: ../../images/cross_device_auth_seq_diagram.svg
   :align: center
-  :target: https://www.plantuml.com/plantuml/uml/VLLDRnit4BtpLmpKGsqZTftq9i157DUDdRJrrbBYYm63ueuarXIvvSVAQj7_tXcCLbgfSYu2bfpt-DvyZDwdh6Ck2wTqoS6NnGIZKkhIv11Xy2LX781EK9IQX1Sv-3x1pzXQWsa0t_rgP_FymHLK3V5OOnljCmmUj7EOuTOJlJV87B3S3Ib4TQfdwBEye1Nw6kYLtR1xT2lhPr3HuOeZeKMb2fp-H90XFE04HXXP3dZTsfdEDdXLD0UqE8Hx_AjWob35aD5ahEaaXH8DiLnS01k2ovBdwEbDpM0ugY8c-fQlQguJ7iF5XT8csrPdP0KjTWzSHUGp3ISdYI1uSWAjTWKV_IGKSfG3RAs22U7P7e17aVbKeeKe0YLARFvnVnLgXBjxk1cFAx9GsqXkuEZ7ytV7iBHv3iPPzFd9rczso3H9g6qoeSMuuXDLOz-8sjfQAZMBeJIaAQIko12yMwtpMOOmceSbKBOwHGtPuchGxN88TmrwleMz-eDkcZVWWj4Ez4worH84EZBQ4oamw-Rm-YL7alVeD-OUVS_Sezzn9qVJ61QYKCYuhPGmShwhkz6uapT6C_UMHLtfHa-iizbYWXmOlyiBnD84wxDwfGsGYqwdYR7VVe1Gah1jTzvD_aIJzqkpoSDbpXorCmimZYNbJSXNZ7QwsWlv3REkTTRRAEripVIV7iOmiZElSudul-jE5zRmjJfAnn9Gjdgd8O89dgTacu-oROIhuASsBh3kMofxLU2n2z7-BND6Ozam8pnwQUYsUShX6Vqh2RzU9vppBUwjdZY4dU4LWYseCtYeIINB0ZmZ5VBPZwnYQ6sDaHJQ1Boc84o10tv1EjQCf3ljwuFyXF4XGyIMLDLdFLdo5E-2caT3ExXDgM2K6WlbQxNRif0yWqaQq6oeb8e-48fRcS9ePTz-l1b_lB--_bqTHWmLNCtHFCDDS6GBFkCAFbXVSr-n44A5AJklGae49zS4EOMIE8AvcZ9nri0p0MK9MiuBtVGjva1ok6cbWfKKwqmf6C_HTxE_6KKN4jQWSuvsKZAc8H2bwBHJe5HJfEnH6ocGsnvqHD2jjeuxWnS1fm9LBsTVcguTvAzWxGUEP553uNkiZw4tjBo2VtXxzXRUdP_3tMUIySyWhZSoxuh14EOvDmbATDBASTtRJuPtvh_zeLZk3xsiu95UuCu6bWdKf3Y9tFwBREsRorlSTalxqsWecTjRnf0ogpXYWzsVY1YGR1nB4aJ7vI7epBRe1S8am7xJ6oWKvnpWIyErWH0X5SETDorEiVRtz5CMxZy0
+  :target: https://www.plantuml.com/plantuml/svg/XLLTRo8t5xxthpZYlNWXIjBizWufrMRJT9FTjao1tTmW8UCvW1jZJ_qnX5RzxpssPuQX8ceK8OrzFfxdEH_-u3otFkmKuy4R7NOhj8onE-6DXS5NXtO0t45WR6LUyy7_7Vo8jHJe1l2_d-Lcwp-gWAoYE5B8YciFWsUk57fuqXHU2qmnzgScWK9TyGrgdpDmXhe4od9gDaLra7e31HqUacMDZ0Mu-e5Snl2CAvYXZN10yrfkk9T6iy2ZGOrZcE8V0Ps7mXgFmcD99yu4AoZAxIr4Gd0N_1OrvKpEC2miElhENyMMEnp1xItZmikQUum8QcmJt5kCPnmkBXovuCK5r9m4MUYL2SJ86pXI1M7CYppZRZFCPR0IR0kmnfRcRzDxKo9Cfl0udnT4ePIMsC3m-vlt8zXBlmMX92LOolAo7-mI4YXMOXyzEtBPCxQn9bG4nBYsic2qEZGYXZ7CjcOF954Beo8kiGHqkn_3f4ATRlzLTE1LTGdA2Aw0doZCzf1TPu9h2WenQdVuyEejmLleZj52znWjDDTbPhNGQsjsCNSNX7g8TP4m5eBi77WRdCywHUikCfasTMWok7Jlv4PZsPw1MVqUnUwIzOj52IiZjK_5ocdFUfFaoeDSzvsNE_HRKu9quB21LqncSyQ0_ZfebJMrBD6r0fCNBxdduCtRS6A4hikEIlGBvL5e6QiZUCLNKaalqNMEcKkeA1EMRt1wI-wJeOLVMhonS9LHKb2UpkiRMha-f0JS1ujWrhqQTFCxoHaxBwvaHDRUa-MtOkX6sI0SvtvjB0YZupmVcpuSk_VUwBMqEopx8nAEVH7haHQ4iVBFrBqKsbKn8YnqhbbTBRrvGVt6XdXeT8cqCbt9LmhXPCta09rJH_3iPDrvKZaxNXEA_DctB7BBM48e7SI5sihw4z9nygGxAiZP-EIZZGUBDQ4ghtkmcbIqjSeuprp1atC1BSpZXEMGH-oVd-SmQmlRYqBm13gNPx4BnPYbh0YcHajczBWyVNgSVve-FFpApdkC6TnlKRp0er542xxW0JvANLBl9I3aHRJflp3EaJkn9fSh28uiKgmghAWVuOKSyxgMKHUwwLFq1khSfQc2HIxMDMCmtw9k5rQwBAKJoZWiWNjlvIgGN6CgKOEJvf-axgPMKWx8es4HUCsbYfqHnof9mNgQVQtQTiYFLiC7Xlb9QITr1BrD51-BxzvTluFtDpSm-K8m_XhO_7QaTJ4OmzRxoa6mAhUoRNfxAUAY_xi_5FlJHwHzDsPyX_rdevb0JeXTXjlF6AdzrujJO_VWVPwD6-LENv2y_s4O2RPBAHF8Qeoo21d7tJdNZQon6TyK9F9rbn38ZWg4hrMgZR7WWeYTjmugOVz0Fs6d_W40
 
 The details of each step shown in the previous picture are described in the table below.
 
@@ -70,65 +65,64 @@ The details of each step shown in the previous picture are described in the tabl
   * - **1**, **2**
     - The User requests to access to a protected resource, the Relying Party redirects the User to a discovery page in which the User selects the *Login with the Wallet* button. The Authorization flow starts.
   * - **3**, **4**,
-    - The Relying Party provides the Wallet Instance with a URL where a generic signed Authorization Request Object can be downloaded and the ''discovery_uri'' where the Wallet Instance can provide technical capabilities to the Relying Party. 
+    - The Relying Party provides the Wallet Instance with a URL where a generic signed Request Object can be downloaded.
   * - **5**, **6**, **7**, **8**, **9**
-    - In the **Cross Device Flow**: the Request URI is provided in the form of a QR Code that is shown to the User. The User frames the QRCode with the Wallet Instance and extracts  ``client_id``, ``request_uri`` and ``discovery_uri``. In the **Same Device Flow** the Relying Party provides the same information of the Cross-Device flow but in the form of HTTP Redirect Location (302). 
-  * - **10**
-    - The Wallet Instance provides its metadata to the Relying Party, informing it about any features and limitations of its implementation.
-  * - **11**
-    - The Relying Party evaluates the Wallet Instance capabilities and produces a signed Request Object compliant to the Wallet technical capabilities.
-  * - **12**
-    - The Relying Party responds with a signed Request Object. The ``exp`` value of the signed Request Object MUST NOT be greater than 240 seconds.
-  * - **13**, **14**, **15**, **16**
-    - The Request Object JWS is verified by the Wallet Instance. Following that, it validates the related Trust Chain to demonstrate trust to the Relying Party. It attests to its capabilities and eligible scopes by verifying the request's signature and processing the Relying Party metadata. This method additionally verifies whose Verifiable Credentials and personal attributes the Relying Party is granted to request.
-  * - **17**, **18**
+    - In the **Cross Device Flow**: the Request URI is provided in the form of a QR Code that is shown to the User. The User frames the QRCode with the Wallet Instance and extracts  ``client_id``, ``request_uri`` and ``state``. In the **Same Device Flow** the Relying Party provides the same information of the Cross-Device flow but in the form of HTTP Redirect Location (302). 
+  * - **10**, **11**, **12**
+    - The Wallet Instance obtains the signed Request Object.
+  * - **13**, **14** and **15**
+    - The Wallet Instance checks if the Relying Party has provided the ``request_uri_method`` within its signed Request Object. If true, the Wallet provides its metadata in the to the Relying Party. The Relying PArty produces a new signed Request Object compliant to the Wallet technical capabilities.
+  * - **13**, **14**, **15**, **16**, **17**, **18**
+    - The Request Object JWS is verified by the Wallet Instance. The Wallet processes the Relying Party metadata and applies the policies related to the Relying Party, attesting whose Digital Credentials and User data the Relying Party is granted to request.
+  * - **19**, **20**
     - The Wallet Instance requests the User's consent for the release of the Credentials. The User authorizes and consents the presentation of the Credentials by selecting/deselecting the personal data to release.
-  * - **19**
+  * - **21**
     - The Wallet Instance provides the Authorization Response to the Relying Party using an HTTP request with the method POST (response mode "direct_post").
-  * - **20**, **21**, **22**, **23** and **24**
+  * - **22**, **23**, **24**, **25** and **26**
     - The Relying Party verifies the Authorization Response, extracts the Wallet Attestation to establish the trust with the Wallet Solution. The Relying Party extracts the Digital Credentials and attests the trust to the Credentials Issuer and the proof of possession of the Wallet Instance about the presented Digital Credentials. Finally, the Relying Party verifies the revocation status of the presented Digital Credentials.
-  * - **25**, **26**, **27** and **28**
+  * - **27** and **28**
     - The Relying Party provides to the Wallet a redirect URI with a response code to be used by the Wallet to finalize the authentication.
   * - **29**
     - The User is informed by the Wallet Instance that the Autentication succeded, then the protected resource is made available to the User.
 
 
-Discovery endpoint
-------------------
+Request URI with HTTP POST
+--------------------------
 
-The Relying Party SHOULD provide a discovery endpoint where the Wallet Instance 
-can inform the Relying Party about its technical capabilities.
+The Relying Party SHOULD provide the POST method with its ``request_uri`` endpoint
+allowing the Wallet Instance to inform the Relying Party about its technical capabilities.
 
 This feature can be useful when, for example, the Wallet Instance supports 
-a restricted set of features, supported algorithms or custom url-schemes for 
-its ``authorization_endpoint``, and other information that it deems necessary to 
-share with the Relying Party before it issues the signed Authorization Request Object.
+a restricted set of features, supported algorithms or a specific url for 
+its ``authorization_endpoint``, and any other information that it deems necessary to 
+provide to the Relying Party the parameters necessary for better interoperability.
 
 .. warning::
     The Wallet Instance, when providing its technical capabilities to the 
     Relying Party, MUST NOT include any User information or other explicit 
     information regarding the hardware used or usage preferences of its User.
 
-If both the Relying Party and the Wallet Instance supports the discovery of the 
-Wallet Instance technical capabilities, the Wallet Instance capabilities MUST 
-be provided using an HTTP request to the `discover_uri` of the Relying Party, 
+If both the Relying Party and the Wallet Instance
+supports the ``request_uri_method`` with HTTP POST,
+the Wallet Instance capabilities MUST 
+be provided using an HTTP request to the `request_uri` endpoint of the Relying Party, 
 with the method POST and content type set to `application/json`.
 
 A non-normative example of the HTTP request is represented below:
 
 .. code:: http
 
-POST /discovery-uri HTTP/1.1
+POST /request-uri HTTP/1.1
 HOST: relying-party.example.org
 Content-Type: application/json
 
 {
-    "authorization_endpoint": "haip:",
+    "authorization_endpoint": "https://wallet-solution.digital-strategy.europa.eu/authorization",
     "response_types_supported": [
-    "vp_token"
+      "vp_token"
     ],
     "response_modes_supported": [
-    "form_post.jwt"
+      "form_post.jwt"
     ],
     "vp_formats_supported": {
       "vc+sd-jwt": {
@@ -139,17 +133,19 @@ Content-Type: application/json
       }
     },
     "request_object_signing_alg_values_supported": [
-        "ES256"
+      "ES256"
     ],
     "presentation_definition_uri_supported": false,
 }
 
+The response of the Relying Party is defined in the section below.
+
 
 Authorization Request Details
 -----------------------------
 
-The Relying Party MUST create a Request Object in the form of a signed JWT, 
-then it MUST provide it to the Wallet Instance through an HTTP URL (request URI). 
+The Relying Party MUST create a Request Object in the form of a signed JWT and
+it MUST provide it to the Wallet Instance through an HTTP URL (request URI). 
 The HTTP URL points to the web resource where the signed request object is 
 available for download. The URL parameters contained in the Relying Party 
 response, containing the request URI, are described in the Table below.
@@ -172,21 +168,19 @@ Below a non-normative example of the response containing the required parameters
 
 .. code-block:: javascript
 
-  haip://authorize?client_id=...&request_uri=...&discovery_uri=...
-
-The value corresponding to the `request_uri` endpoint MUST be randomized, according to `RFC 9101, The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR) <https://www.rfc-editor.org/rfc/rfc9101.html#section-5.2.1>`_ Section 5.2.1.
+  https://wallet-solution.digital-strategy.europa.eu/authorization?client_id=...&request_uri=...
 
+The value corresponding to the `request_uri` endpoint SHOULD be randomized, according to `RFC 9101, The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR) <https://www.rfc-editor.org/rfc/rfc9101.html#section-5.2.1>`_ Section 5.2.1.
 
 
-In the **Same Device Flow** the Relying Party uses a HTTP response redirect (status code 302) as represented in the following non-normative example:
+In the **Same Device Flow** the Relying Party uses an HTTP response redirect (with status code set to 302) as represented in the following non-normative example:
 
 .. code:: text
 
-    HTTP/1.1 /pre-authz-endpoint Found
-    Location: https://wallet-providers.eudi.wallet.gov.it?
+    HTTP/1.1 /authorization Found
+    Location: https://wallet-solution.digital-strategy.europa.eu?
     client_id=https%3A%2F%2Frelying-party.example.org%2Fcb
     &request_uri=https%3A%2F%2Frelying-party.example.org%2Frequest_uri
-    &discovery_uri=https%3A%2F%2Frelying-party.example.org%2Fdiscovery_uri
 
 
 In the **Cross Device Flow**, a QR Code is shown by the Relying Party to the User in order to provide the Authorization Request. The User frames the QR Code using their Wallet Instance.
@@ -201,7 +195,7 @@ Below is represented a non-normative example of the QR Code raw payload:
 
 .. code-block:: text
 
-  haip://authorize?client_id=https%3A%2F%2Frelying-party.example.org&request_uri=https%3A%2F%2Frelying-party.example.org%2Frequest_uri&https%3A%2F%2Frelying-party.example.org%2Fdiscovery_uri
+  https://wallet-solution.digital-strategy.europa.eu/authorization?client_id=https%3A%2F%2Frelying-party.example.org&request_uri=https%3A%2F%2Frelying-party.example.org
 
 .. note::
     The *error correction level* chosen for the QR Code MUST be Q (Quartily - up to 25%), since it offers a good balance between error correction capability and data density/space. This level of quality and error correction allows the QR Code to remain readable even if it is damaged or partially obscured.
@@ -233,13 +227,14 @@ Below a non-normative example of the HTTP Request to this specialized endpoint,
 Request Object Details
 ----------------------
 
-Below a non-normative example of HTTP request made by the Wallet Instance to the Relying Party to provide the Wallet Instance Attestion and retrieve the signed Request Object:
+Below a non-normative example of HTTP request made by the Wallet Instance to the Relying Party.
 
 .. code-block:: javascript
 
   GET /request_uri HTTP/1.1
   HOST: relying-party.example.org
 
+
 Request URI response
 --------------------
 
@@ -269,7 +264,8 @@ The Relying Party issues the signed Request Object, where a non-normative exampl
     "state": "3be39b69-6ac1-41aa-921b-3e6c07ddcb03",
     "iss": "https://relying-party.example.org",
     "iat": 1672418465,
-    "exp": 1672422065
+    "exp": 1672422065,
+    "request_uri_method": "post"
   }
 
 The JWS header parameters are described below:
@@ -320,7 +316,8 @@ The JWS payload parameters are described herein:
     - Unix Timestamp, representing the time at which the JWT was issued.
   * - **exp**
     - Unix Timestamp, representing the expiration time on or after which the JWT MUST NOT be valid anymore.
-
+  * - **request_uri_method**
+    - String determining the HTTP method to be used with the `request_uri` endpoint to provide the Wallet metadata to the Relying Party. The value is case-insensitive and can be set to: `get` or `post`. The GET method, as defined in [@RFC9101], involves the Wallet sending a GET request to retrieve a Request Object. The POST method involves the Wallet requesting the creation of a new Request Object by sending an HTTP POST request, with its metadata, to the request URI of the Relying Party.
 
 .. warning::
 
@@ -438,13 +435,13 @@ Below is a non-normative example of the ``vp_token`` decoded content, represente
    }
    .
    {
-    "iss": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c",
-    "jti": "3978344f-8596-4c3a-a978-8fcaba3903c5",
-    "aud": "https://relying-party.example.org/response_uri",
-    "iat": 1541493724,
-    "exp": 1573029723,
-    "nonce": "2c128e4d-fc91-4cd3-86b8-18bdea0988cb"
-    "vp": "<Issuer-Signed-JWT>~<Disclosure 1>~<Disclosure 2>~...~<Disclosure N>"
+     "iss": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c",
+     "jti": "3978344f-8596-4c3a-a978-8fcaba3903c5",
+     "aud": "https://relying-party.example.org/response_uri",
+     "iat": 1541493724,
+     "exp": 1573029723,
+     "nonce": "2c128e4d-fc91-4cd3-86b8-18bdea0988cb"
+     "vp": "<Issuer-Signed-JWT>~<Disclosure 1>~<Disclosure 2>~...~<Disclosure N>"
    }
 
 Where the following parameters are used: