PID Issuance¶

The relevant entities and interfaces involved in the issuance flow are:

Wallet Provider: It represents an organization (public or private) that is responsible for the release of an eIDAS-compliant EUDI Wallet Solution. It also issues thes Wallet Instance Attestation to its Wallet Instances by means of an Attestation Service. The Wallet Attestation certifies the genuinity and authenticity of the Wallet Instance and its compliance with a Trust Framework in compliance to the security and privacy requirements.

Wallet Solution: It represents the entire product and service owned by a Wallet Provider, offered to all Users of that solution. A Wallet Solution must be certified as being EUDI-compliant by a Conformity Assessment Body (CAB).

Wallet Instance: instance of a Wallet Solution, installed on User's device. It provides interfaces for User interaction with the Wallet Provider, Relying Parties, PID and (Q)EAA Providers.

PID Provider: It represents the issuer of 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 PID credentials.

National eID Relying Party (OpenID Connect or SAML2): It represents the component to authenticate the End-User with the national Digital Identity Providers.

National IdP: It represents preexisting identity systems based on SAML2 or OpenID Connect, already in production in each Member State (for Italy SPID and CIE id authentication schemed notified eIDAS with LoA High, see SPID/CIE OpenID Connect Specifications).

_images/High-Level-Flow-EUDIW-PID-Issuing.svg — Fig. 2 PID Issuance - General architecture and high level flow¶

The Fig. 2 shows a general architecture and highlights the main operations involved in the issuance of a PID, in particular:

Wallet Instance Setup: the first time the Wallet Instance is started a preliminary setup phase MUST be carried out. It consists of the release of a verifiable proof issued by the Attestation Service provided by the Wallet Provider that asserts the genuineness, the authenticity and the compliance with a trust framework of the Wallet Instance. The verifiable proof binds a public key corresponding to a local private key generated by the Wallet Instance.

Obtaining the trusted PID Provider: the Wallet Instance queries the Trust Anchor to fetch the trusted PID Provider.

Obtaining of PID Provider metadata: the Wallet Instance establishes the trust to the PID Provider according to the Trust Model, obtaining the Metadata that discloses the formats of the PID, the algorithms supported, and any other parameter required for interoperability needs.

PID request: following the Authorization Code Flow in [OIDC4VCI. Draft 13] the Wallet Instance requests a PID to the PID Provider. A fresh key pairs is generated by the Wallet Instance, the public key is used by PID Provider for the key binding of the PID.

End-user authentication: the PID Provider authenticates the End-User with LoA High, acting as an IAM Proxy to the National eID system.

PID issuance: once the User authentication with LoA High happens, the User gives their consent, the PID Provider checks the Wallet Instance by means of the Wallet Attestation and the Trust Chain related to the Wallet Provider. Finally, the PID Provider releases a PID bound to the key material held by the requesting Wallet instance.

The Wallet Instance Setup phase is described in Section [...]. In the following Section the steps from 1 to 5 are further expanded into more technical detailed steps.

Detailed Flow¶

The PID Issuance phase is based on the Authorization Code Flow with Pushed Authorization Requests (PAR) [RFC 9126] and PKCE (Proof Key for Code Exchange, RFC 7636) as recommended in [OIDC4VCI. Draft 13. Section 3.4]. A Wallet Initiated Flow is considered and the User receives the PID directly in response to the Credential Request (Immediate Flow).

_images/Low-Level-Flow-EUDIW-PID-Issuing.svg — Fig. 3 PID Issuance - Detailed flow¶

Steps 1-4: The User has selected a PID Provider, and the Wallet Instance obtains the metadata for the selected PID Provider.

Note

Federation Check: The Wallet Instance needs to check if the PID Provider is part of Federation and then it can consume its Metadata. A non-normative example of a response from the endpoint .well-known/openid-federation with the Entity Configuration and the Metadata of the PID Provider is represented within the section Entity Configuration Credential Issuer.

Steps 5-6: The Wallet Instance creates a PKCE code verifier that sends in a pushed authorization request, using the request parameter (see RFC 9126 Section 3) to the PID Provider authorization endpoint. The Wallet Instance signs the request using its private key. A OAuth2 client authentication method must be involved, since in this flow the pushed authorization endpoint is a protected endpoint. The client authentication should be based on the model defined in [RFC 7521] using the Wallet Instance Attestation JWS inside the client_assertion parameter. The authorization_details [RAR RFC 9396] parameter is extended to allow Wallet Instance to specify the types of the credentials when requesting authorization for the PID issuance.

Below a non-normative example of the PAR.

POST /as/par HTTP/1.1
Host: pid-provider.example.org
Content-Type: application/x-www-form-urlencoded

response_type=code
&client_id=$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
&request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KIC Jpc3MiOiAiczZCaGRSa3F0MyIsDQogImF1ZCI6ICJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsDQo gInJlc3BvbnNlX3R5cGUiOiAiY29kZSBpZF90b2tlbiIsDQogImNsaWVudF9pZCI6ICJzNkJoZFJrcXQz IiwNCiAicmVkaXJlY3RfdXJpIjogImh0dHBzOi8vY2xpZW50LmV4YW1...
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-key-attestation
&client_assertion=$WalletInstanceAttestation$

The JWS header of request object is represented below:

{
  "alg": "ES256",
  "kid": "FifYx03bnosD8m6gYQIfNHNP9cM_Sam9Tc5nLloIIrc",
}

The JWS payload of the request object is represented below:

{
"response_type":"code",
"client_id":"$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$",
"state":"fyZiOL9Lf2CeKuNT2JzxiLRDink0uPcd",
"code_challenge":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
"code_challenge_method":"S256",
"authorization_details":[
{
    "type":"openid_credential",
    "format": "vc+sd-jwt",
    "credential_definition": {
        "type": ["eu.eudiw.pid.it"]
    }
}
],
"redirect_uri":"eudiw://start.wallet.example.org",
"client_assertion_type":"urn:ietf:params:oauth:client-assertion-type:jwt-key-attestation",

Step 7: The PID Provider creates a new request URI representing this new authorization request to be returned to the Wallet Instance.: }

Note

Federation Check: PID Provider MUST check that the Wallet Provider is part of the federation and in addition it MUST verify the Wallet Instance Attestation validity by checking its signature and data.

Step 7: The PID Provider creates a new request URI representing a new authorization request and returns it to the Wallet Instance. A non-normative example of the authorization request is represented below:

HTTP/1.1 201 Created
Cache-Control: no-cache, no-store
Content-Type: application/json

{
    "request_uri":"urn:ietf:params:oauth:request_uri:bwc4JK-ESC0w8acc191e-Y1LTC2",
    "expires_in": 60
}

Steps 8-9: The Wallet Instance sends an authorization request to the PID Provider authorization endpoint.

GET /authorize?client_id=$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$&request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1
Host: pid-provider.example.org

Note

User Authentication and Consent: The PID Provider performs the User authentication based on the requirements of eIDAS LoA High and asks the User consent for the PID issuance.

Steps 10-11: The PID Provider sends an authorization code to the Wallet Instance.

Note

The Wallet Instance redirect URI is a universal or app link registered with the local operating system, so this latter will resolve it and pass the response to the Wallet Instance.

HTTP/1.1 302 Found
Location: eudiw://start.wallet.example.org?code=SplxlOBeZQQYbYS6WxSbIA&state=fyZiOL9Lf2CeKuNT2JzxiLRDink0uPcd&iss=https%3A%2F%2Fpid-provider.example.org

Step 14: The Wallet Instance sends a token request to the PID Provider token endpoint using the authorization code, code_verifier, DPoP proof and private_key_jwt.

POST /token HTTP/1.1
Host: pid-provider.example.org
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik
    VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR
    nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE
    QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj
    oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia
    WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg
    4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

client_id=$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$
&grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=eudiw://start.wallet.example.org
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJIUzI1NiI

Step 15: The PID Provider validates the request and if it is successful, it issues an access token (bound to the DPoP key) and a fresh c_nonce.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
"access_token": "Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU",
"token_type": "DPoP",
"expires_in": 2677,
"c_nonce": "tZign[...]snFbp",
"c_nonce_expires_in": 86400
}

Steps 16-18: The Wallet Instance creates a new key pair to which the new credential shall be bound. Then, it creates a proof of possession with the new key and the c_nonce obtained in Step 15 and it creates a DPoP proof for the request to the PID credential issuance endpoint.

Step 19: The Wallet Instance sends a PID issuance request to the PID Provider credential endpoint. It contains the access token, the DPoP proof, the credential type, the proof (proof of possession of the key) and the format.

Note

PID Credential Schema and Status registration: The PID Provider MUST register all the issued PIDs for their later revocation, if needed.

POST /credential HTTP/1.1
Host: pid-provider.example.org
Content-Type: application/x-www-form-urlencoded
Authorization: DPoP Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik
    VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR
    nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R
    1JEQSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiJlMWozVl9iS2ljOC1MQUVCIiwiaHRtIj
    oiR0VUIiwiaHR1IjoiaHR0cHM6Ly9yZXNvdXJjZS5leGFtcGxlLm9yZy9wcm90ZWN0Z
    WRyZXNvdXJjZSIsImlhdCI6MTU2MjI2MjYxOCwiYXRoIjoiZlVIeU8ycjJaM0RaNTNF
    c05yV0JiMHhXWG9hTnk1OUlpS0NBcWtzbVFFbyJ9.2oW9RP35yRqzhrtNP86L-Ey71E
    OptxRimPPToA1plemAgR6pxHF8y6-yqyVnmcw6Fy1dqd-jfxSYoMxhAJpLjA

credential_definition=%7B%22type%22:%5B%22eu.eudiw.pid.it%22%5D%7D
&format=vc+sd-jwt
&proof=%7B%22proof_type%22:%22...-ace0-9c5210e16c32%22%7D

A non-normative example of proof parameter is given below:

{
"proof_type": "jwt",
"jwt": "eyJraWQiOiJkaWQ6ZXhhbXBsZTplYm …"
}

Where the decoded content of the JWT is represented below:

{
  "alg": "ES256",
  "typ": "openid4vci-proof+jwt",
  "kid": "dB67gL7ck3TFiIAf7N6_7SHvqk0MDYMEQcoGGlkUAAw"
}

{
"iss": "0b434530-e151-4c40-98b7-74c75a5ef760",
"aud": "https://pid-provider.example.org",
"iat": 1504699136,
"nonce": "tZign...snFbp"
}

Steps 20-22: The PID Provider checks the DPoP proof and whether the access token is valid and suitable for the requested PID. It also checks the proof of possession for the key material the new credential shall be bound to. If all checks succeed, the PID Provider creates a new credential bound to the key material and sends it to the Wallet Instance. The Wallet Instance MUST perform the PID integrity and authenticity checks and if it is successful can proceed with secure storage of the PID credential.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
"format": "vc+sd-jwt"
"credential" : "LUpixVCWJk0eOt4CXQe1NXK[...]WZwmhmn9OQp6YxX0a2L",
"c_nonce": "fGFF7[...]UkhLa",
"c_nonce_expires_in": 86400
}

Pushed Authorization Request Endpoint¶

Pushed Authorization Request (PAR) Request¶

The requests to the PID Provider authorization endpoint MUST be HTTP with method POST, with the following mandatory parameters in the HTTP request message body, encoded in application/x-www-form-urlencoded format.

Table 1 PAR http request parameters¶
Claim	Description	Reference
response_type	MUST be set to `code`.	RFC 6749
client_id	MUST be set to the thumbprint of the `jwk` value in the `cnf` parameter inside the Wallet Instance Attestation.	RFC 6749
code_challenge	A challenge derived from the code verifier that is sent in the authorization request	RFC 7636#section-4.2.
code_challenge_method	A method that was used to derive code challenge. It MUST be set to `S256`.	RFC 7636#section-4.3.
request	It MUST be a signed JWT. The private key corresponding to the public one in the `cnf` parameter inside the Wallet Instance Attestation MUST be used for signing the request object.	OpenID Connect Core. Section 6
client_assertion_type	It MUST be set to `urn:ietf:params:oauth:client-assertion-type:jwt-key-attestation`.	Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants
client_assertion	It MUST be the Wallet Instance Attestation signed JWT.	Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants

The JWT Request Object has the following JOSE header parameters:

JOSE header	Description	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 Cryptographic Algorithms and MUST NOT be none or an identifier for a symmetric algorithm (MAC).	RFC 7516#section-4.1.1.
kid	Unique identifier of the JWK as base64url-encoded JWK Thumbprint value.	RFC 7638#section_3.

Note

The parameter typ, if omitted, assumes the implicit value JWT.

The JWT payload is given by the following parameters:

Claim	Description	Reference
response_type	It MUST be set as in the Table of the HTTP parameters.	See Table of the HTTP parameters.
client_id	It MUST be set as in the Table of the HTTP parameters.	See Table of the HTTP parameters.
state	Unique session identifier at the client side. This value will be returned to the client in the response, at the end of the authentication. It MUST be a random string with at least 32 alphanumeric characters.	See OpenID.Core#AuthRequest.
code_challenge	It MUST be set as in the Table of the HTTP parameters.	See Table of the HTTP parameters.
code_challenge_method	It MUST be set as in the Table of the HTTP parameters.	See Table of the HTTP parameters.
authorization_details	JSON Object. It MUST include the following claims: type: it MUST be set to `openid_credential`, format: it MUST be set to `vc+sd-jwt`, credential_definition: JSON Object. It MUST have the type claim which MUST be set to `eu.eudiw.pid.it`	See [RAR RFC 9396] and [OIDC4VCI. Draft 13].
redirect_uri	Redirection URI to which the response will be sent. It MUST be an universal or app link registered with the local operating system, so this latter will resolve it and pass the response to the Wallet Instance.	See OpenID.Core#AuthRequest.
client_assertion_type	It MUST be set as in the Table of the HTTP parameters.	See Table of the HTTP parameters.
client_assertion	It MUST be set as in the Table of the HTTP parameters.	See Table of the HTTP parameters.

Pushed Authorization Request (PAR) Response¶

If the verification is successful, the PID Provider MUST provide the response with a 201 HTTP status code. The following parameters are included as top-level members in the HTTP response message body, using the application/json media type as defined in [RFC 8259].

Claim	Description	Reference
request_uri	The request URI corresponding to the authorization request posted. This URI MUST be a single-use reference to the respective authorization request. It MUST contain some part generated using a cryptographically strong pseudorandom algorithm. The value format MUST be `urn:ietf:params:oauth:request_uri:<reference-value>` with `<reference-value>` as the random part of the URI that references the respective authorization request data.	[RFC 9126].
expires_in	A JSON number that represents the lifetime of the request URI in seconds as a positive integer.	[RFC 9126].

Authorization endpoint¶

The authorization endpoint is used to interact with the Credential Issuer and obtain an authorization grant. The authorization server MUST first verify the identity of the resource owner (the User that own it's credentials) as defined in the RFC 6749.

Authorization Request¶

The Authorization request is issued by the Wallet Instance Browser, HTTP POST or GET methods MAY be used. When the method POST is used, the parameters MUST be sent using the Form Serialization. When the method GET is used, the parameters MUST be sent using the Query String Serialization. For more details see OpenID.Core#Serializations.

The mandatory parameters in the HTTP authentication request are specified in the following table.

Claim	Description	Reference
client_id	It MUST be set as in the Table of the HTTP parameters.	See Table of the HTTP parameters.
request_uri	It MUST be set to the same value as obtained by PAR Response. See Table of the HTTP PAR Response parameters.	[RFC 9126].

Authorization Response¶

The authentication response is returned by the PID Provider authorization endpoint at the end of the authentication flow.

If the authentication is successful the PID Provider redirects the User by adding the following query parameters as required to the redirect_uri. The redirect URI MUST be an universal or app link registered with the local operating system, so this latter is able to resolve its value and delegates the Wallet Instance for the processing.

Claim	Description	Reference
code	Unique Authorization Code that the client submits to the Token Endpoint.	[RFC 6749#section-4.1.2], Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants
state	The client MUST check the correspondence with the state value in the request object. It is defined as in the Table of the JWT Request parameters.	[RFC 6749#section-4.1.2].
iss	Unique identifier of the PID PRovider 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].

Token endpoint¶

The token endpoint is used by the Wallet Instance to obtain an access token by presenting its authorization grant, as defined in RFC 6749.

Token Request¶

The request to the PID Provider Token endpoint MUST be an HTTP request with method POST, where its body message is encoded in application/x-www-form-urlencoded format. The Wallet Instance sends the Token endpoint request with private_key_jwt authentication and a DPoP proof containing the mandatory parameters, defined in the table below.

The Token endpoint MUST accept and validate the DPoP proof sent in the DPoP HTTP header. The Token endpoint MUST validate the DPoP proof based on the steps defined in Section 4.3 of the DPoP specifications [DPoP-draft16]. Thus, this mitigates the misuse of leaked or stolen access tokens at the credential endpoint. If the DPoP proof is invalid, the Token endpoint returns an error response, according to Section 5.2 of [RFC 6749] with invalid_dpop_proof as the value of the error parameter.

Claim	Description	Reference
client_id	It MUST be set as in the Table of the HTTP parameters.	See Table of the HTTP parameters.
grant_type	It MUST be set to `authorization_code`.	Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants.
code	Authorization code returned in the Authentication Response.	Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants.
redirect_uri	It MUST be set as in the request object Table of the JWT Request parameters.	Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants.
code_verifier	Verification code of the code_challenge.	Proof Key for Code Exchange by OAuth Public Clients.
client_assertion_type	It MUST be set to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.	Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants.
client_assertion	JWT signed with the Wallet Instance private key containing the following parameters: iss: This MUST contain the client_id. sub: This MUST contain the iss. aud: URL of the PID Provider Token Endpoint. iat: UNIX Timestamp with the time of the JWT issuance, coded as NumericDate as indicated in RFC 7519. exp: UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated in RFC 7519. jti: Unique Identifier for this authentication request, generated by the client. E.g., uuid4 format.	Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants.

A DPoP proof is included in an HTTP request using the DPoP header parameter containing a DPoP JWS.

The JOSE header of a DPoP JWT MUST contain at least the following parameters:

JOSE header	Description	Reference
typ	It MUST be equal to `dpop+jwt`.	[RFC 7515] and [RFC 8725. Section 3.11].
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 Cryptographic Algorithms and MUST NOT be none or an identifier for a symmetric algorithm (MAC).	[RFC 7515].
jwk	representing the public key chosen by the client, in JSON Web Key (JWK) [RFC7517] format, as defined in Section 4.1.3 of [RFC7515]. It MUST NOT contain a private key.	[RFC 7517] and [RFC 7515].

The payload of a DPoP proof MUST contain at least the following claims:

Claim	Description	Reference
jti	Unique identifier for the DPoP proof JWT. The value MUST be assigned in a UUID v4 string format according to [RFC 4122].	[RFC 7519. Section 4.1.7].
htm	The value of the HTTP method of the request to which the JWT is attached.	[RFC 9110. Section 9.1].
htu	The HTTP target URI, without query and fragment parts, of the request to which the JWT is attached.	[RFC 9110. Section 7.1].
iat	UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in RFC 7519.	[RFC 7519. Section 4.1.6].

Token Response¶

Token endpoint response MUST contain the following mandatory claims.

Claim	Description	Reference
access_token	The DPoP-bound Access Token, in signed JWT format, allows accessing the Credential Endpoint for obtaining the PID.	RFC 6749.
token_type	Type of Access Token returned. It MUST be equal to `DPoP`.	RFC 6749.
expires_in	Expiry time of the Access Token in seconds.	RFC 6749.
c_nonce	JSON string containing a nonce to be used to create a proof of possession of key material when requesting a Credential.	[OIDC4VCI. Draft 13].
c_nonce_expires_in	JSON integer, it represents the lifetime in seconds of the c_nonce.	[OIDC4VCI. Draft 13].

Access Token¶

A DPoP-bound Access Token is provided by the PID Provider Token endpoint as a result of a successful token request. The Access Token is encoded in JWT format, according to [RFC 7519]. The Access Token MUST have at least the following mandatory claims and it MUST be bound to the public key that is provided by the DPoP proof. This binding can be accomplished based on the methodology defined in Section 6 of [DPoP-draft16].

Claim	Description	Reference
iss	It MUST be an HTTPS URL that uniquely identifies the PID Provider. The client MUST verify that this value matches the PID Provider where it has requested the credential.	[RFC 9068], [RFC7519, Section 4.1.1].
sub	It identifies the subject of the JWT. It MUST be of type pairwise.	[RFC 9068], [RFC 7519] and [OpenID.Core#SubjectIDTypes].
client_id	It MUST contain a HTTPS URL that uniquely identifies the RP.	[RFC 9068].
aud	It MUST match the value client_id. The RP MUST verify that this value matches its client ID.	[RFC 9068].
iat	UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in RFC 7519.	[RFC 9068], [RFC 7519. Section 4.1.6].
exp	UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated in RFC 7519.	[RFC 9068], [RFC 7519].
jti	It MUST be a String in uuid4 format. Unique Token ID identifier that the RP MAY use to prevent reuse by rejecting the Token ID if already processed.	[RFC 9068], [RFC 7519].
nonce	It MUST be a random string of at least 32 alphanumeric characters. The value type of this claim MUST be a string, where the value is a c_nonce provided by the PID Provider.	[OpenID.Core#AuthRequest].
jkt	JWK SHA-256 Thumbprint Confirmation Method. The value of the jkt member MUST be the base64url encoding (as defined in [RFC7515]) of the JWK SHA-256 Thumbprint of the DPoP public key (in JWK format) to which the access token is bound.	[DPoP-draft16. Section 6.1] and [RFC 7638].

Credential endpoint¶

The Credential Endpoint issues a Credential as approved by the End-User upon presentation of a valid Access Token representing this approval, as defined in OPENID4VCI.

Credential Request¶

The Wallet Instance may request a PID to the PID Provider Credential endpoint with a HTTP POST request encoded in application/json format, where the following parameters in the message body MUST be present.

The Credential endpoint MUST accept and validate the DPoP proof sent in the DPoP HTTP header based on the steps defined in Section 4.3 of [DPoP-draft16]. If the DPoP proof is invalid, the Credential endpoint returns an error response per Section 5.2 of [RFC 6749] with invalid_dpop_proof as the value of the error parameter.

Warning

The Wallet Instance MUST create a new DPoP proof for the Credential request and MUST NOT use the previously created proof for the Token Endpoint.

Claim

Description

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 subsequent Credential Request. It MUST be eu.eudiw.pid.it.

[OIDC4VCI. Draft 13].

format

Format of the Credential to be issued. This MUST be vc+sd-jwt.

[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].

Note

If the format value is mso_mdoc, the credential request MUST contain the doctype claim which is a JSON string identifying the PID 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:

JOSE Header	Description	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 Cryptographic Algorithms and MUST NOT be `none` or an identifier for a symmetric algorithm (MAC).	[OIDC4VCI. Draft 13], [RFC 7515], [RFC 7517].
typ	MUST be openid4vci-proof+jwt.	[OIDC4VCI. Draft 13], [RFC 7515], [RFC 7517].
kid	It MUST contain the identifier of the key material the PID shall be bound to.	[OIDC4VCI. Draft 13], [RFC 7515], [RFC 7517].

Claim	Description	Reference
iss	The value of this claim MUST be the client_id of the Wallet Instance.	[OIDC4VCI. Draft 13], [RFC7519, Section 4.1.1].
aud	The value of this claim MUST be the identifier URL of the PID Provider.	[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].
nonce	The value type of this claim MUST be a string, where the value is a c_nonce provided by the PID Provider in the Token response.	[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:

Claim	Description	Reference
format	Format of the Credential to be issued. This MUST be vc+sd-jwt.	[OIDC4VCI. Draft 13].
credential	Contains the issued PID. It MUST be an SD-JWT JSON Object (see Section PID Data Model).	Appendix E in [OIDC4VCI. Draft 13].
c_nonce	JSON string containing a nonce to be used to create a proof of possession of key material when requesting a further credential or for renewal credential.	[OIDC4VCI. Draft 13].
c_nonce_expires_in	JSON integer corresponding to the c_nonce lifetime in seconds.	[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].

Entity Configuration Credential Issuer¶

Below a non-normative example of an Entity Configuration containing an openid_credential_issuer metadata.

HTTP/1.1 200 OK
Content-Type: application/entity-statement+jwt

{

  "alg": "RS256",
  "kid": "FANFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs",
  "typ": "entity-statement+jwt"

}
.
{
  "exp": "1649610249",
  "iat": "1649437449",
  "iss": "https://pid-provider.example.org",
  "sub": "https://pid-provider.example.org",
  "jwks": {
    "keys": [{
      "kty": "RSA",
      "use": "sig",
      "n": "1Ta-sE …",
      "e": "AQAB",
      "kid": "FANFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs"
    }]
  },
  "metadata": {
    "openid_credential_issuer": {
      "credential_issuer": "https://pid-provider.example.org",
      "authorization_endpoint": "https://pid-provider.example.org/connect/authorize",
      "token_endpoint": "https://pid-provider.example.org/connect/token",
      "pushed_authorization_request_endpoint": "https://pid-provider.example.org/connect/par",
      "dpop_signing_alg_values_supported": ["RS256", "RS512", "ES256", "ES512"],
      "credential_endpoint": "https://pid-provider.example.org/credential",
      "credentials_supported": {
        "eu.eudiw.pid.it": {
          "format": "vc+sd-jwt",
          "cryptographic_binding_methods_supported": ["jwk"],
          "cryptographic_suites_supported": ["RS256", "RS512", "ES256", "ES512"],
          "display": [{
              "name": "PID Provider Italiano di esempio",
              "locale": "it-IT",
              "logo": {
                "url": "https://pid-provider example.org/public/logo.svg",
                "alt_text": "logo di questo PID Provider"
              },
              "background_color": "#12107c",
              "text_color": "#FFFFFF"
            },
            {
              "name": "Example Italian PID Provider",
              "locale": "en-US",
              "logo": {
                "url": "https://pid-provider.example.org/public/logo.svg",
                "alt_text": "The logo of this PID Provider"
              },
              "background_color": "#12107c",
              "text_color": "#FFFFFF"
            }
          ],
          "credential_definition": {
            "type": ["PIDCredential"],
            "credentialSubject": {
              "given_name": {
                "mandatory": true,
                "display": [{
                    "name": "Current First Name",
                    "locale": "en-US"
                  },
                  {
                    "name": "Nome",
                    "locale": "it-IT"
                  }
                ]
              },
              "family_name": {
                "mandatory": true,
                "display": [{
                    "name": "Current Family Name",
                    "locale": "en-US"
                  },
                  {
                    "name": "Cognome",
                    "locale": "it-IT"
                  }
                ]
              },
              "birthdate": {
                "mandatory": true,
                "display": [{
                    "name": "Date of Birth",
                    "locale": "en-US"
                  },
                  {
                    "name": "Data di Nascita",
                    "locale": "it-IT"
                  }
                ]
              },
              "place_of_birth": {
                "mandatory": true,
                "display": [{
                    "name": "Place of Birth",
                    "locale": "en-US"
                  },
                  {
                    "name": "Luogo di Nascita",
                    "locale": "it-IT"
                  }
                ]
              },
              "unique_id": {
                "mandatory": true,
                "display": [{
                    "name": "Unique Identifier",
                    "locale": "en-US"
                  },
                  {
                    "name": "Identificativo univoco",
                    "locale": "it-IT"
                  }
                ]
              },
              "tax_id_number": {
                "mandatory": true,
                "display": [{
                    "name": "Tax Id Number",
                    "locale": "en-US"
                  },
                  {
                    "name": "Codice Fiscale",
                    "locale": "it-IT"
                  }
                ]
              }
            }
          }
        }
      }
    },

    "federation_entity": {
      "organization_name": "Pid Provider Organization Example",
      "homepage_uri": "https://pid-provider.example.org",
      "policy_uri": "https://pid-provider.example.org/privacy_policy",
      "tos_uri": "https://pid-provider.example.org/info_policy",
      "logo_uri": "https://pid-provider.example.org/logo.svg"
    },

    "openid_relying_party": {
      <This is the metadata of the PID Provider acting as a Relying Party in the national digital identity framework (CIE/SPID). See spid-cie-oidc-docs for details.>
    }
  }
}

Docs Italia beta

Public documents, made digital.

PID Issuance¶

Detailed Flow¶

Pushed Authorization Request Endpoint¶

Pushed Authorization Request (PAR) Request¶

Pushed Authorization Request (PAR) Response¶

Authorization endpoint¶

Authorization Request¶

Authorization Response¶

Token endpoint¶

Token Request¶

Token Response¶

Access Token¶

Credential endpoint¶

Credential Request¶

Credential Response¶

Entity Configuration Credential Issuer¶