Authors:
Reviewers:
Status: Approved
Table of Contents
This specification implements the OID4VCI workflow for issuing Person Identification Data (PID) credentials by government-approved identity providers within the European Wallet Ecosystem. It defines a standard process to minimize risks and ensure interoperability in issuing high-assurance PIDs across the EUDI wallet ecosystem, adhering to the requirements set forth in the ARF [2] and in the implementing act 2024/2977-2979 for PID and EAA issuance [6].
The EWC LSP must align with the standard protocol for issuing PID from trusted and accredited sources. This uniform approach serves as the foundation for enabling interoperability between identity providers and wallet holders throughout the EWC ecosystem. This RFC assumes that users are familiar with the chosen EWC protocols and standards, and can reference the original specifications when required.
The PID credential issuance process incorporates comprehensive steps to ensure the security, reliability, and compliance. This includes both an authorization flow and a pre-authorized flow, with additional preliminary and post-issuance steps to align with regulatory standards and security best practices. The process is illustrated below, incorporating the critical steps of Wallet Conformity, Trust Anchor Verification, Reliable Data Acquisition, PID Generation, Secure Issuance and Storage; Renewal and Revocation Policies Management it’s not in scope of this rfc.
Wallet Conformity: Before initiating the PID issuance, the wallet unit must be confirmed to comply with established standards. This includes possessing an internal certificate from Certification Assessment Bodies (CAB) that validates its conformity, ensuring the wallet’s capability to securely manage the PID and associated qualified electronic attestations.
Data Acquisition from Reliable Sources: Personal data used for PID generation must be sourced from authentic and current databases, such as civil registries, ensuring the PID credentials are based on accurate and up-to-date information.
The PID issuance follows detailed steps starting from the discovery of issuer capabilities, through authentication and authorization, leading to the actual credential issuance. The process is adapted to include the preliminary steps, ensuring a secure and compliant issuance path.
sequenceDiagram
participant I as Individual using EUDI Wallet
participant TA as Trust Anchor
participant O as PID Provider
participant AS as Authentic Source
Note over I,O: Discovery of Issuer Capabilities
I->>O: GET: Credential Offer URI
I->> O: GET: /.well-known/openid-credential-issuer
O-->> I: OpenID credential issuer configuration
I->> O: GET: /.well-known/oauth-authorization-server
O-->>I: OAuth authorization server metadata
Note over I,TA: Issuer Authorization Verification
I->> I: validate signed metadata
I->>TA: Request Issuer Authorization Status
TA-->>I: Confirm PID provider is trusted
Note over I,O: Authenticate, Authorize, Check Wallet's Conformity
opt authorization flow
I->>O: Authorization request
Note over O,AS: User Authentication
opt user data verified vs authentic source
O->>AS: Request Personal Identifier Data
AS-->>O: Provide Personal Identifier Data
end
O-->>I: Authorization response
end
I->> O: Token request
Note right of I: WTA and WIA should be sent as parameters on token request
O-->>O: Wallet Unit attestation validation
O-->>TA: Wallet Provider verification against Trust Framework
opt wallet attestations not valid
O-->>I: Error message response
end
O->>O: authorization/pre-authorized code validation
O-->>I: Token response
Note over I,O: PID Generation and Secure Issuance
I->>O: POST: Credential request with access token
Note over O,AS: Data Acquisition from Authentic Source <BR> or temporary storage (userInfo)
O->>AS: Request Personal Identifier Data
AS-->>O: Provide Personal Identifier Data
O-->>I: Credential response with PID, stored securely in wallet
I->> I: Validation of the signature vs pid provider signature certificate
Figure 1: PID Issuance Process Incorporating Preliminary Checks
The process highlights the integration of the new preliminary steps with the traditional authorization code flow and pre-authorized code flow, adhering to the OID4VCI specification. It ensures a robust framework for digital identity issuance, from initial compliance verification to the secure generation and storage of PID credentials, followed by ongoing management.
Following the issuance of the PID, initial and periodic verification procedures are crucial to maintain the validity and integrity of the PID and its related electronic attestations. This includes checking for revocation status and ongoing compliance of both the wallet and issuer within the Trust Anchor framework. Additionally, policies for the renewal and revocation of PIDs and electronic attestations must be established to address changes in the individual’s status, data breaches, or compliance issues.
For PID credential issuance, this RFC allows both authorization and preauthorized code flows.
Credential offer can be provided by reference and by value.
In the first case the credential_offer_uri query parameter contains the URL where the credential offer from the government-approved identity provider can be resolved.
This approach ensures a streamlined user experience while maintaining the necessary information exchange for the PID issuance process. The wallet user obtains the above by scanning a QR code for cross-device workflows or via a deeplink for same-device workflows.
Here there’s an example:
openid-credential-offer://?credential_offer_uri=https://identity-provider.gov/pid-credential-offer
Options regarding credential offer are well described at https://issuer.eudiw.dev/
On resolving the credential_offer_uri query parameter, the issuer responds with details of the PID credential offer. The response format is adapted to the specific requirements of PID issuance and may include information such as the credential type related to personal identification and the applicable trust framework. The response can be in one of the following formats:
{
"credential_issuer": "https://identity-provider.gov",
"credential_configuration_ids": ["urn:eu.europa.ec.eudi:pid:1"],
"grants": {
"authorization_code": {
"issuer_state": "eyJhbGciOiJSU0Et...FYUaBy"
}
}
}
The wallet instance retrieves this JSON response and processes it accordingly. The format of the credential (e.g., jwt_vc, dc+sd-jwt) is specified, focusing on the PID. This process ensures that the credential issuance aligns with the stringent requirements for PID within the EWC ecosystem.
For the pre-authorized flow, the credential response format is adapted to include the necessary grants for PID issuance:
{
"credential_issuer": "https://identity-provider.gov",
"credential_configuration_ids": ["urn:eu.europa.ec.eudi:pid:1"],
"grants": {
"urn:ietf:params:oauth:grant-type:pre-authorized_code": {
"pre-authorized_code": "asfdasfdsadfsa",
"tx_code": {
"length": 4,
"input_mode": "numeric",
"description":
"Please provide onetimecode....",
}
}
}
}
The wallet instance initiates a request to discover the government identity provider’s authorization server configurations, essential for PID credential issuance. To obtain the issuer’s configurations, the wallet resolves the /.well-known/openid-credential-issuer endpoint using the credential_issuer URI found in the PID credential offer response (as per EWC RFC001):
GET https://identity-provider.gov/.well-known/openid-credential-issuer
Subsequently, the wallet requests the authorization server metadata endpoint to retrieve metadata (openid and oauth standard samples):
GET https://identity-provider.gov/.well-known/openid-configuration
GET https://identity-provider.gov/.well-known/oauth-authorization-server
Upon resolving the well-known endpoints, the identity provider responds with its configuration, tailored to support PID credential issuance. The response includes details about supported credentials, endpoints for issuing and managing credentials. It also specifies the cryptographic methods and trust frameworks applicable for PID credentials, as defined by [1]: https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0-ID1.html#name-credential-issuer-metadata-p
Once the well-known endpoint for authorization servers configuration is resolved, the response will follow the oauth standard or openid specification
According to IA 2977 draft [6] the PID provider must be authenticated to the wallet (art 3 comma 8,9) using a relying party access certificate (The same requirement is expressed in ETSI TS 119 471 [8] (REQ-EAASP-4.2.2.1-21)). The authentication of the PID provider is a critical step in this process because it ensures that data of the user would not be shared with unauthorized subjects, so it’s mandatory that it will take place at the beginning of the process itself. This authentication is based on the RP access certificate validation performed by the wallet instance.
PID Issuer must sign the metadata hash and must add the signed payload to a signed_metadata attribute together with the certificate. Taking as example the RFC001 par 3.4 Discover response, the final result could be like the following:
{
"metadata1":"xyz",
"metadata2":"wwe",
......
"signed_metadata": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
The wallet has
In any case the signature of the credential, issued at the end of the process and delivered to the wallet, must be validated against the pid provider signature certificate.
Note: Pid Provider authentication and the definition of rp access certificates is still under development so it won’t be mandatory in EWC integration test bed.
At this stage, not all PID issuer will support this authentication method: signed_metadata won’t be present and the wallet should raise an alert to the user in order to inform that the PID provider authentication will not take place. On the other side the wallet could not support this function, so signed_metadata will be ignored if present.
The authorization request seeks permission to access the PID credential endpoint. Here is an adapted example of this request, specifically aimed at PID issuance by a government identity provider:
GET https://identity-provider.gov/auth/authorize?
&response_type=code
&scope=openid
&issuer_state=uniqueStateIdentifier
&state=client-state
&client_id=did%3Akey%3Az2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r
&authorization_details%3D%5B%7B%22format%22%3A%22jwt_vc%22%2C%22locations%22%3A%5B%22https%3A%2F%2Fissuer.example.com%22%5D%2C%22type%22%3A%22openid_credential%22%2C%22types%22%3A%5B%22urn%3Aeu.europa.ec.eudi%3Apid%3A1%22%5D%7D%5D
&redirect_uri=openid%3A
&nonce=glkFFoisdfEui43
&code_challenge=YjI0ZTQ4NTBhMzJmMmZhNjZkZDFkYzVhNzlhNGMyZDdjZDlkMTM4YTY4NjcyMTA5M2Q2OWQ3YjNjOGJlZDBlMSAgLQo%3D
&code_challenge_method=S256
&client_metadata=%7B%22vp_formats_supported%22%3A%7B%22jwt_vp%22%3A%7B%22alg%22%3A%5B%22ES256%22%5D%7D%2C%22jwt_vc%22%3A%7B%22alg%22%3A%5B%22ES256%22%5D%7D%7D%2C%22response_types_supported%22%3A%5B%22vp_token%22%2C%22id_token%22%5D%2C%22authorization_endpoint%22%3A%22openid%3A%2F%2F%22%7D
Host: https://identity-provider.gov
Query params for the authorisation request are given below:
response_type
|
The value must be ‘code’ |
scope
|
The value must be ‘openid’ |
state
|
The client uses an opaque value to maintain the state between the request and callback. |
client_id
|
Decentralised identifier |
authorization_details
|
As specified in OAuth 2.0 Rich Authorization Requests specification to specify fine-grained access [4]. An example is as given below: ```json { "type": "openid_credential", "locations": [ "https://credential-issuer.example.com" ], "format": "jwt_vc_json", "credential_definition": { "type": [ "urn:eu.europa.ec.eudi:pid:1" ] } } ``` |
redirect_uri
|
For redirection of the response |
code_challenge
|
As specified in PKCE for OAuth Public Client specification [5] |
code_challenge_method
|
As specified in PKCE for OAuth Public Client specification |
client_metadata
|
Holder wallets are non-reachable and can utilise this field in the Authorisation Request to deliver configuration |
issuer_state
|
If present in the credential offer |
Note 1: the wallet trust attestation and the wallet instance attestation shall be verified during token request step.
Note 2: In the authorization flow, we assume that the user will be asked to authenticate in order to provide his identity and optionally personal data will be collected and stored by identity provider.
Is is not expected that PID provider requires additional data from the Holder to issue PID as PID is expected to be first credential in the wallet upon initialization. After user authentication (usually by existing notified eID mean), PID provider issues an authorization response containing a code parameter with a short-lived authorization code. This streamlined response facilitates a quick and secure exchange, vital for the sensitive nature of PID credential issuance:
HTTP/1.1 302 Found
Location: https://Wallet.example.org/cb?code=SplxlOBeZQQYbYS6WxSbIA
[!NOTE] The above can be deeplinked to the EUDI wallet as well.
In this step wallet trustwothiness in verified. The validation mechanism is delegated to RFC004. Wallet unit attestations received within token request will be verified; Wallet provider could be validated against trust framework and the wallet instance could be verified against a trustlist for valid and not revoked wallet versions published by the wallet provider, if available. The binding ow wallet instance and WUA must be verified too, in a similar manner of which the PID is bound to the wallet key in step 3.10 Credential Request/Response. In order to simplify the PID issuance pilot, the validation of Wallet attestations is not mandatory.
Note: The validation of wallet is based on wallet unit attestation (rif RFC004 (WIP) [https://github.com/EWC-consortium/eudi-wallet-rfcs/blob/main/ewc-rfc004-individual-wallet-attestation.md]) based on IETF attestation based client identification [11].
For PID credential issuance, the token request using the authorization code flow is structured as follows:
POST /token HTTP/1.1
Host: identity-provider.gov
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
&grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
&redirect_uri=https%3A%2F%2FWallet.example.org%2Fcb
Whether the wallet attestation could be performed, two headers must be included
OAuth-Client-Attestation: <wallet-unit-attestation-jwt>
OAuth-Client-Attestation-PoP: <wallet-unit-attestation-pop-jwt>
This request is made with the following query params:
grant_type
|
Grant type for authorisation. E.g. authorization_code
|
client_id
|
Decentralised identifier |
code
|
Authorisation code |
code_verifier
|
Wallet-generated secure random token used to validate the original code_challenge provided in the initial Authorization Request
|
In scenarios where a pre-authorized code is used, the token request is structured as follows:
POST /token HTTP/1.1
Host: identity-provider.gov
Content-Type: application/x-www-form-urlencoded
&grant_type=urn:ietf:params:oauth:grant-type:pre-authorized_code
&pre-authorized_code=SplxlOBeZQQYbYS6WxSbIA
&tx_code=493536
Whether the wallet attestation could be performed, two headers must be included
OAuth-Client-Attestation: <wallet-unit-attestation-jwt>
OAuth-Client-Attestation-PoP: <wallet-unit-attestation-pop-jwt>
This request is made with the following query params:
grant_type
|
Grant type for authorisation. E.g. urn:ietf:params:oauth:grant-type:pre-authorized_code
|
pre-authorized_code
|
Code representing the Credential Issuer's authorisation for the Wallet to obtain Credentials of a certain type. This code must be short-lived and single-use. |
tx_code
|
The end user pin is decided by the issuer and sent to the holder through an out-of-band process. E.g. Email, SMS |
The token response for PID credential issuance includes:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp..sHQ",
"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI4a5k..zEF",
"token_type": "bearer",
"expires_in": 86400,
}
This response grants the wallet an access token and a refresh token to be used for the request of PID credential.
To request the PID credential, the wallet instance sends a request to the PID Endpoint as follows:
POST /credential
Content-Type: application/json
Authorization: Bearer eyJ0eXAi...KTjcrDMg
{
"credential_identifier": "urn:eu.europa.ec.eudi:pid:1",
"proofs": {
"jwt": [
"eyJ0eXAiOiJvcGVuaWQ0dmNpLXByb29mK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiblVXQW9BdjNYWml0aDhFN2kxOU9kYXhPTFlGT3dNLVoyRXVNMDJUaXJUNCIsInkiOiJIc2tIVThCalVpMVU5WHFpN1N3bWo4Z3dBS18weGtjRGpFV183MVNvc0VZIn19",
"eyJraWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEva2V5cy8xIiwiYWxnIjoiRVMyNTYiLCJ0eXAiOiJKV1QifQ"
]
}
}
This request specifies the format and type of credential being requested, along with a JWT proof of the wallet key. PID issuer extracts from the jwt of the proof , the public key and the nonce in order to verify it correctness and integrity.
[!NOTE] The nonce of the proof is handle differently in oidc4vci versions (the one used in EWC is the 13rd). In version 13 before credential request, pid issuer should send a nonce to the wallet that should be signed and set in the proof. In the latest published version a nonce endpoint should be provided to the wallet to get a nonce to be signed.
The issuance of PID credentials may proceed directly or be deferred, contingent on the issuer’s readiness to issue the credential immediately or to require additional processing time.
This step will follow RFC001 Chapter 3.9 - 3.10 using an in-time response and the credential_identifier parameter. The credential identifier values are obtained from the token response in 3.9.
There are legal requirements (CIR 2024/2977 Article 3.5) for PID issuers to implement key binding - PID issued must be bound to the key from the wallet:
Providers of person identification data shall ensure that person identification data that they issue is cryptographically bound to the wallet unit to which it is issued.
In OpenID4VCI protocol this is realized via proofs: https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-proof-types. This proof is strongly tied with nonce generated by issuer.
For PID issuers there are several requirements based on this:
For PID example ref to Appendix C.
[!NOTE] It would be inline with HAIP to set we accept only JWT proofs that contains public key specified in JWK that should be included in cnf attribute of SD-JWT credential. There are several types of proofs and to ensure interoperability we should probably agree on one type that we will implement.
In cases where the PID credential is immediately available, the response is structured as follows:
{
"credentials": [
{
"credential": "LUpixVCWJk0eOt4CXQe1NXK....WZwmhmn9OQp6YxX0a2L"
},
{
"credential": "YXNkZnNhZGZkamZqZGFza23....29tZTIzMjMyMzIzMjMy"
}
]
}
This response provides the PID credential in an encoded format, ensuring that the recipient can use it straightaway. The c_nonce ensures the response’s freshness, enhancing security.
[!NOTE] A complete example of PID with sd jwt is provided in Appendix B
3.11.2 Deferred
Should the credential not be ready for immediate issuance, the response includes an acceptance token, signaling that the PID credential’s issuance is deferred:
{
"transaction_id": "8xLOxBtZp8"
}
If the response contains transaction_id field, then it indicates the credential is not yet available and will be accessible through a deferred PID credential retrieval process:
POST /deferred-credential
Host: server.example.com
Content-Type: application/json
Authorization: BEARER eyJ0eXAiOiJKV1QiLCJhbGci..zaEhOOXcifQ
{
"transaction_id": "8xLOxBtZp8"
}
During this process, the wallet queries the Trust Anchor to ascertain the issuer’s trust status, thereby affirming that the issuer has been vetted and is compliant with established standards and regulations governing PID. It ensures that only entities with verified trustworthiness can issue PID. Further details will be added as soon as additional requirements are derived from ongoing discussions.
This verification process involves assessing whether the wallet possesses an internal certificate, issued by Certification Assessment Bodies (CAB), which confirms its compliance with the requisite standards for securely handling PID digital identities and associated qualified electronic attestations. It guarantees the secure storage and management of the PID. Further details will be added as soon as additional requirements are derived from ongoing discussions.
Standard HTTP response codes shall be supported. Any additional ones can be formulated in the following format.
{
"error": "invalid_request",
"error_description": "The PID credential request is invalid or expired"
}
The table below summarises the success/error responses that can be used:
| Response format | Description | ||
| invalid_request | The request was invalid or improperly formatted. E.g. The PID credential is expired | ||
| invalid_grant |
invalid_client
|
The Client tried to send a Token Request with a Pre-Authorized Code without Client ID, but the Authorization Server does not support anonymous access
|
|