diff --git a/docs/en/pid-eaa-issuance.rst b/docs/en/pid-eaa-issuance.rst index 9dab80d4b..d75af32fa 100644 --- a/docs/en/pid-eaa-issuance.rst +++ b/docs/en/pid-eaa-issuance.rst @@ -13,7 +13,7 @@ The relevant entities and interfaces involved in the issuance flow are: - *Wallet Instance*: Instance of a Wallet Solution, installed on the User device. The Wallet Instance provides graphical interfaces for User interaction with Relying Parties, PID, (Q)EAA Providers and the Wallet Provider. - *PID Provider*: The entity that issues the eIDAS Person Identification Data (PID). It is composed of: - - OpenID4VCI Component: based on the "OpenID for Verifiable Credential Issuance" specification ` [OIDC4VCI. Draft 13] `_ to release the PID. + - OpenID4VCI Component: based on the "OpenID for Verifiable Credential Issuance" specification ` [OIDC4VCI. Draft 13] `_ to release the PID. - National eID Relying Party: The component to authenticate the User with the national Digital Identity Providers, based on OpenID Connect Core 1.0 or SAML2. - National Identity Provider: It represents preexisting identity systems based on SAML2 or OpenID Connect Core 1.0, already in production in each Member State (eg: the Italian SPID and CIE id schemes notified eIDAS with *LoA* **High**, see `SPID/CIE OpenID Connect Specifications `_). @@ -39,7 +39,7 @@ Below the description of the steps represented in the previous picture: 0. **Wallet Instance Setup**: the first time the Wallet Instance is started a preliminary setup phase is carried out. It consists of the release of the Wallet Attestation issued by Wallet Attestation Service asserting the genuineness and the compliance of the Wallet Instance with the shared trust framework. The Wallet Attestation binds the public key provided by the Wallet Instance, related to one of the private keys generated by the Wallet Instance. 1. **PID/(Q)EAA Provider Discovery**: the Wallet Instance discovers the trusted Digital Credential Issuers using the Federation API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), inspecting the Credential Issuer metadata and Trust Marks for filtering the PID Provider. 2. **PID Provider Metadata**: the Wallet Instance establishes the trust to the PID Provider according to the Trust Model and obtains the Metadata that discloses the formats of the PID, the algorithms supported, and any other parameter required for interoperability needs. - 3. **PID Request**: using the Authorization Code Flow defined in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests the PID to the PID Provider. + 3. **PID Request**: using the Authorization Code Flow defined in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests the PID to the PID Provider. 4. **User Authentication**: the PID Provider authenticates the User with LoA High, acting as an Identity and Access Management Proxy to the National eID system. 5. **PID Issuance**: the User is authenticated with LoA High and the PID Provider releases a PID bound to the key material held by the requesting Wallet Instance. @@ -64,7 +64,7 @@ Below the description of the most relevant operations involved in the (Q)EAA iss 1. **Discovery of the trusted (Q)EAA Provider**: the Wallet Instance obtains the list of the trusted (Q)EAA Provider using the Federation API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), then inspects the metadata and Trust Mark looking for the Digital Credential capabilities of each (Q)EAA Provider. 2. **(Q)EAA Provider Metadata**: the Wallet Instance establishes the trust to the (Q)EAA Provider according to the Trust Model, obtaining the Metadata that discloses the formats of the (Q)EAA, the algorithms supported, and any other parameter required for interoperability needs. - 3. **(Q)EAA Request**: using the Authorization Code Flow , defined in `[OIDC4VCI. Draft 13] `_, the Wallet Instance requests a (Q)EAA to the (Q)EAA Provider. + 3. **(Q)EAA Request**: using the Authorization Code Flow , defined in `[OIDC4VCI. Draft 13] `_, the Wallet Instance requests a (Q)EAA to the (Q)EAA Provider. 4. **User Authentication**: the (Q)EAA Provider, acting as a Verifier (Relying Party), authenticates the User evaluating the presentation of the PID. 5. **(Q)EAA Issuance**: the User is authenticated with a valid PID and the (Q)EAA Provider releases a (Q)EAA bound to the key material held by the requesting Wallet Instance. @@ -75,7 +75,7 @@ Detailed Flow The PID/(Q)EAA Issuance phase uses the **Authorization Code Flow** with the following specifications: * **Pushed Authorization Requests** (PAR) [:rfc:`9126`]; -* **PKCE** (Proof Key for Code Exchange, :rfc:`7636`) as recommended in `[OIDC4VCI. Draft 13. Section 3.4] `_. +* **PKCE** (Proof Key for Code Exchange, :rfc:`7636`) as recommended in `[OIDC4VCI. Draft 13. Section 3.4] `_. In this section a *Wallet Initiated Flow* is outlined, where the User receives the PID/(Q)EAA directly in response to the Credential Request. @@ -116,7 +116,7 @@ The PID/(Q)EAA Provider performs the following checks upon the receipt of the PA 4. It MUST check that the ``iss`` claim in the Request Object matches the ``client_id`` claim in the Request Object (:rfc:`9126`, :rfc:`9101`). 5. It MUST check that the ``aud`` claim in the Request Object is equal to the PID/(Q)EAA Provider authorization endpoint uri (:rfc:`9126`, :rfc:`9101`). 6. It MUST reject the PAR request, if it contains the ``request_uri`` parameter (:rfc:`9126`). - 7. It MUST check that the Request Object contains all the mandatory parameters which values are validated according to :ref:`Table of the HTTP parameters ` [derived from :rfc:`9126`]. + 7. It MUST check that the Request Object contains all the mandatory parameters which values are validated according to :ref:`Table of the HTTP parameters ` [derived from :rfc:`9126`]. 8. It MUST check that the Request Object is not expired, checking the ``exp`` claim (:rfc:`9126`). 9. It MUST check that the Request Object was issued in a previous time than the value exposed in the ``iat`` claim. It SHOULD reject the request if the ``iat`` claim is far from the current time (:rfc:`9126`) of more than `5` minutes. 10. It MUST check that the ``jti`` claim in the Request Object has not been used before by the Wallet Instance identified by the ``client_id``. This allows the PID/(Q)EAA Provider to mitigate replay attacks (:rfc:`7519`). @@ -439,8 +439,9 @@ The requests to the PID/(Q)EAA authorization endpoint MUST use the HTTP POST met - It MUST be set to a value containing the Wallet Attestation JWT and the Proof of Possession, separated with the ``~`` character. - `oauth-attestation-draft `_. -The JWT Request Object has the following JOSE header parameters: +The JWT *Request Object* has the following JOSE header parameters: +.. _table_request_object_claim: .. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -501,7 +502,7 @@ The JWT payload is given by the following parameters: - **type**: it MUST be set to ``openid_credential``, - **credential_configuration_id**: JSON String. String specifying a unique identifier of the Credential being described in the `credential_configurations_supported` map in the Credential Issuer Metadata. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``. - - See [RAR :rfc:`9396`] and `[OIDC4VCI. Draft 13] `_. + - See [RAR :rfc:`9396`] and `[OIDC4VCI. Draft 13] `_. * - **redirect_uri** - Redirection URI to which the response is intended to be sent. It MUST be an universal or app link registered with the local operating system, so this latter will provide the response to the Wallet Instance. - See `OpenID.Core#AuthRequest `_. @@ -582,6 +583,25 @@ If the verification is successful, the PID/(Q)EAA Issuer MUST provide the respon - A JSON number that represents the lifetime of the request URI in seconds as a positive integer. - [:rfc:`9126`]. +If any errors occur during the PAR Request, the Authorization Server MUST return an error response as defined in :rfc:`9126#section-2.3`. The response MUST use *application/json* as the content type and MUST include the following parameters: + + - *error*. The error code. + - *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered. + +Below is a non-normative example of an error response. + +.. code:: + + HTTP/1.1 400 Bad Request + Content-Type: application/json + + { + "error": "invalid_request", + "error_description": + "The redirect_uri is not valid for the given client" + } + + Authorization endpoint ---------------------- @@ -636,6 +656,10 @@ If the authentication is successful the PID/(Q)EAA Issuer redirects the User by - Unique identifier of the PID/(Q)EAA Issuer who created the Authentication Response. The Wallet Instance MUST validate this parameter. - `OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response `_, `[RFC7519, Section 4.1.1] `_. +If any errors occur during the Authorization Request, the Authorization Server MUST return an error response as defined in :rfc:`6749#section-4.1.2.1`. The response MUST use *application/json* as the content type and MUST include the following parameters: + + - *error*. The error code. + - *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered. Token endpoint -------------- @@ -728,7 +752,7 @@ The payload of a **DPoP JWT Proof** MUST contain at least the following claims: Token Response ^^^^^^^^^^^^^^^ -Token endpoint response MUST contain the following mandatory claims. +If the Token Request is successfully validated, the Authorization Server provides an HTTP Token Response with a *200 (OK)* status code. The Token Response MUST contain the following mandatory claims. .. list-table:: :widths: 20 60 20 @@ -748,13 +772,27 @@ Token endpoint response MUST contain the following mandatory claims. - :rfc:`6749`. * - **c_nonce** - JSON string containing a ``nonce`` value to be used to create a *proof of possession* of key material when requesting a Credential. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. * - **c_nonce_expires_in** - JSON integer, it represents the lifetime in seconds of the **c_nonce**. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. * - **authorization_details** - JSON object, used to identify Credentials with the same metadata but different claimset/claim values and/or simplify the Credential request even when only one Credential is being issued. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. + +If any errors occur during the validation of the Token Request, the Authorization Server MUST return an error response as defined in :rfc:`6749#section-5.2`. + +.. code:: + + HTTP/1.1 400 Bad Request + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "error":"invalid_client" + "error_description":"Client authentication failed" + } Access Token @@ -822,20 +860,20 @@ If the *DPoP proof* is invalid, the Credential endpoint returns an error respons - **Reference** * - **credential_definition** - JSON object containing the detailed description of the Credential type. It MUST have at least the **type** sub claims which is a JSON array containing the type values the Wallet SHALL request in the Credential Request. It MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the PID/(Q)EAA Issuer metadata. In the case of the PID it MUST be set to ``PersonIdentificationData``. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. * - **format** - Format of the Credential to be issued. This MUST be `vc+sd-jwt`. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. * - **proof** - JSON object containing proof of possession of the key material the issued credential shall be bound to. The proof object MUST contain the following mandatory claims: - **proof_type**: JSON string denoting the proof type. It MUST be `jwt`. - **jwt**: the JWT used as proof of possession. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. .. note:: - If the **format** value is `mso_mdoc`, the credential request MUST contain the ``doctype`` claim which is a JSON string identifying the credential type according to `EIDAS-ARF`_ . See Appendix E.2. of `[OIDC4VCI. Draft 13] `_ for more details. + If the **format** value is `mso_mdoc`, the credential request MUST contain the ``doctype`` claim which is a JSON string identifying the credential type according to `EIDAS-ARF`_ . See Appendix E.2. of `[OIDC4VCI. Draft 13] `_ for more details. The JWT proof type MUST contain the following parameters for the JOSE header and the JWT body: @@ -849,13 +887,13 @@ The JWT proof type MUST contain the following parameters for the JOSE header and - **Reference** * - **alg** - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms in Section :ref:`Cryptographic Algorithms ` and MUST NOT be set to ``none`` or to a symmetric algorithm (MAC) identifier. - - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. + - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. * - **typ** - It MUST be set to `openid4vci-proof+jwt`. - - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. + - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. * - **jwk** - Representing the public key chosen by the Wallet Instance, in JSON Web Key (JWK) [:rfc:`7517`] format that the PID/(Q)EAA shall be bound to, as defined in Section 4.1.3 of [:rfc:`7515`]. The ``jwk`` value MUST be equal to the same public key that is generated for the DPoP. - - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. + - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. .. list-table:: :widths: 20 60 20 @@ -866,22 +904,22 @@ The JWT proof type MUST contain the following parameters for the JOSE header and - **Reference** * - **iss** - The value of this claim MUST be the **client_id** of the Wallet Instance. - - `[OIDC4VCI. Draft 13] `_, `[RFC7519, Section 4.1.1] `_. + - `[OIDC4VCI. Draft 13] `_, `[RFC7519, Section 4.1.1] `_. * - **aud** - The value of this claim MUST be the identifier URL of the PID/(Q)EAA Issuer. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. * - **iat** - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. - - `[OIDC4VCI. Draft 13] `_, [:rfc:`7519`. Section 4.1.6]. + - `[OIDC4VCI. Draft 13] `_, [:rfc:`7519`. Section 4.1.6]. * - **nonce** - The value type of this claim MUST be a string, where the value is a **c_nonce** provided by the PID/(Q)EAA Issuer in the Token response. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. Credential Response ^^^^^^^^^^^^^^^^^^^^ -Credential Response to the Wallet Instance MUST be sent using `application/json` media type. The response MUST contain the following mandatory claims: +Credential Response to the Wallet Instance MUST be sent using `application/json` media type. If the Credential Request is successfully validated, the PID/(Q)EAA Provider MUST return HTTP response with a *200 (OK)* status code and MUST contain the following mandatory claims: .. _table_credential_response_claim: .. list-table:: Credential http response parameters @@ -893,20 +931,37 @@ Credential Response to the Wallet Instance MUST be sent using `application/json` - **Reference** * - **format** - Format of the Credential to be issued. This MUST be set to `vc+sd-jwt` when the credential type is SD-JWT. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. * - **credential** - Contains the issued PID/(Q)EAA. When the credential type is SD-JWT, it MUST be an SD-JWT JSON Object (see Section :ref:`PID/(Q)EAA Data Model `). - - Appendix E in `[OIDC4VCI. Draft 13] `_. + - Appendix E in `[OIDC4VCI. Draft 13] `_. * - **c_nonce** - JSON string containing a ``nonce`` value to be used to create a *proof of possession* of the key material when requesting a further Credential or for the renewal of a credential. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. * - **c_nonce_expires_in** - JSON integer corresponding to the **c_nonce** lifetime in seconds. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. .. note:: - If the **format** value is `mso_mdoc`, the **credential** value MUST be a base64url-encoded JSON string according to Appendix E of `[OIDC4VCI. Draft 13] `_. + If the **format** value is `mso_mdoc`, the **credential** value MUST be a base64url-encoded JSON string according to Appendix E of `[OIDC4VCI. Draft 13] `_. + + +If the Credential Request is invalid, the PID/(Q)EAA Provider MUST return an error response as defined in `[OIDC4VCI. Draft 13] `. The response MUST use the content type *application/json* and MUST include the following parameters: + + - *error*. The error code. + - *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered. + +.. code:: + + HTTP/1.1 400 Bad Request + Content-Type: application/json + Cache-Control: no-store + + { + "error": "invalid_proof" + "error_description":"The proof field is not present or the provided key proof is invalid or not bound to a nonce provided by the Credential Issuer." + } .. _Entity Configuration Credential Issuer: