Skip to content

(Q)EAA Issuance with OpenID4VC

Basic Idea

The Q(EAA) Provider issues signed credentials to the Wallet which are stored for a longer period. The Wallet can then present the credentials (including a proof of possession by signing over a wallet-held key) to the Relying Party.

The flows include examples for the credential formats SD-JWT VC and mdoc, but other formats are not precluded.

Exemplary Flows

The flows described in this document are examples demonstrating one possible implementation approach. QEAAs can be issued by any QTSP, not limited to the EUDIW context shown here. Applicable industry standards for their implementation are ETSI TS 119 461, TS 119 471, TS 119 472-1.

Qualified Signature/Seal Requirement for QEAA

For QEAA, the (Q)EAA Provider must sign credentials with a Qualified Electronic Signature (QES) or Qualified Electronic Seal (QSeal) as required by Annex V of the eIDAS Regulation. The QTSP issuing the QEAA must be listed in the EU Trusted List.

Cryptographic Formats

Long-Term keys:

  • (Q)EAA Provider has long-term key pair \((ep\_pub, ep\_priv)\) which is used to sign the Credential

Transaction-specific keys:

  • EUDIW generates device key \((device\_pub, device\_priv)\) which is used to generate proof of possession of a Credential
  • EUDIW optionally generates key pair \((cre\_eph\_pub, cre\_eph\_priv)\) which is used to encrypt the credential response

Artifacts:

  • EUDIW fetches Wallet Attestation from Wallet Provider: \(wallet\_attestation\)
  • (Q)EAA Provider issues
    • SD-JWT VC (plus Disclosures): \(sd\_jwt := \text{sign}(\mathit{hashed\_attestation\_data}, device\_pub)_{ep\_priv}\)
    • ISO mdoc: \(mdoc := \text{sign}(\mathit{hashed\_attestation\_data}, device\_pub)_{ep\_priv}\)

Dependencies

TODO: May want to expand to include metadata.

G cluster_eaa_provider (Q)EAA Provider cluster_wallet Wallet ep 🗝 (ep_priv, ep_pub) user_data attestation data ep->user_data sign (SD-JWT VC/ mdoc issuerAuth) device_key 🗝 (device_priv, device_pub) ep->device_key sign (SD-JWT VC/ mdoc issuerAuth) nonce_audience nonce, audience device_key->nonce_audience sign (KB-JWT/ mdoc deviceAuth)

Note: Wallet attestation not shown in this chart.

Remote Issuance with Authorization Code Flow

Sequence Diagram

User Journey: (Q)EAA Issuance - Authorization Code

(Q)EAA Issuance over OpenID4VCI with Authorization Code Flow(Q)EAA Issuance over OpenID4VCI with Authorization Code FlowUserUser.s EUDI Wallet InstanceBrowser App.Q.EAA ProviderUserOpenID HolderUserOpenID HolderUser's EUDI Wallet InstanceUser's EUDI Wallet InstanceBrowser App(same device)Browser App(same device)(Q)EAA ProviderLong-term Key: (ep_pub,ep_priv)(Q)EAA ProviderLong-term Key: (ep_pub,ep_priv)alt[Wallet initiated](001)open wallet, unlock walletScreen: launch_walletScreen: unlock_wallet(002)Select issuance ofpre-configured (Q)EAAPre-configured (Q)EAAs containscredential_issuer URLs and scopesScreen: credential_catalogScreen: next_steps[Issuer initiated](003)Open Issuer's Website(004)Query website: HTTP GET<credential_issuer_url>/(005)HTTP 200HTML with static CredentialOffer<Grant-Type: AuthorizationCode>Screen: same_device_issuer_website(006)open wallet, unlock walletScreen: launch_walletScreen: unlock_walletScreen: next_steps(007)[TLS] HTTP GET ./well-knownCredential Issuer Metadata(008)[TLS] HTTP 200 <SignedCredential Issuer Metadata>(009)Verify Signed CredentialIssuer Metadata(010)provide consent for (Q)EAAProvider and offeredattestationScreen: consent_provider_and_attestationalt[optional Wallet Attestation](011)[TLS] HTTP POST</session_endpoint> walletattestation nonce(012)generate and store nonce(013)[TLS] HTTP 200 <walletattestation nonce>(014)get wallet attestation fromWallet Provider backend(wallet attestation nonce)(015)generate PoP for walletattestation(016)[TLS] PAR (code_challenge,wallet attestation + PoP,redirect_uri, either scope orauthorization_details)alt[optional Wallet Attestation](017)verify wallet attestationcheck wallet solution statuson trust list(018)[TLS] request_uri(019)[TLS] HTTP GET <OpenID4VCIAuthorizationRequest(request_uri)>(020)[TLS] HTTP GET <OpenID4VCIAuthorizationRequest(request_uri)>User Authentication(021)<user authentication>the (Q)EAA Provider may perform any form ofuser authentication in the browser, this maybe:- username/password- OpenID4VP credential presentation- taking a foto- any other mechanism enabled through thebrowserScreen: same_device_issuer_authentication(022)[TLS] HTTP 302 redirect-uri<OpenID4VCI AuthorizationResponse(authorizationcode)>(023)[TLS] HTTP 302 redirect-uri<OpenID4VCI AuthorizationResponse(authorizationcode)>(024)user consent for receiving the(Q)EAAScreen: consent_add_credential(025)[TLS] HTTP POST <TokenRequest(authorization code,PKCE code_verifier, walletattestation + PoP, DPoPHeader)>(026)lookup authorization codegenerate TokenResponse withDPoP access tokenverify PKCE challengealt[optional Wallet Attestation](027)verify wallet attestation(028)[TLS] HTTP 200 <TokenResponse(DPoP-boundaccesss_token, c_nonce,optionalauthorization_details)>(029)generate cryptographicbinding key pair (device_pub,device_priv) and proof ofpossession with c_nonceDevice key should be protected by platformsecurity mechanismsScreen: device_authenticatoralt[optional credential response encryption](030)generate credential responseencryption key pair(cre_eph_pub, cre_eph_priv)(031)createcredential_response_encryptionobject with jwk containingcre_eph_pub(032)[TLS] HTTP POST <CredentialRequest(DPoP-bound accesstoken, device_pub, optionallycredential_response_encryption)>(033)lookup access token validate key proofalt[SD-JWT VC (Q)EAA](034)generate SD-JWT VC (Q)EAAand Disclosures withattestation data anddevice_pub as cnf key, signwith ep_priv[mdoc (Q)EAA](035)generate mdoc (Q)EAA withattestation data anddevice_pub as deviceKey, signwith ep_privalt[credential_response_encryption present](036)generate encrypted credentialresponse JWT using the valuesreceived in thecredential_response_encryptionobject(037)[TLS] HTTP 200<JWT(CredentialResponse((Q)EAA))>(038)decrypt credential responseJWT and retrieve credential[not present](039)[TLS] HTTP 200 <CredentialResponse((Q)EAA)>(040)store (Q)EAAScreen: successScreen: homeit might be useful to have a redirect in thebrowser

Step-by-Step Description

No Description
001 (Wallet initiated) The user opens and unlocks their wallet.
002 (Wallet initiated) The user navigates to a credential catalog of pre-configured (Q)EAA Providers and is offered credentials in the Wallet. They selects a (Q)EAA and the Wallet continues the flow with the pre-configured Credential Issuer URL and credential identifier.
003 (Issuer initiated) User browses to the (Q)EAA Provider's website.
004 (Issuer initiated) Browser app on the user's device opens the (Q)EAA Provider's website
005 (Issuer initiated) (Q)EAA Provider returns an HTML page to the browser containing a Credential Offer; containing
- the Credential Issuer URL
an identifier to the offered credential
- an optional issuer_state parameter to bind this issuance to a pre-existing session
006 (Issuer initiated) The user clicks on the link, the Wallet launches, and they unlock the wallet
007 The Wallet fetches the Credential Issuer's metadata from the ./well-known files of the Credential Issuer URL
008 The (Q)EAA Provider (from here on named Issuer in his OpenID4VCI role) returns the Credential Issuer Metadata; containing:
- technical information about the Issuer
- translations and display data for the offered credentials
009 The Wallet verifies the signed metadata provided by the Credential Issuer by checking the signature (should be signed with valid access certificate) & existence and validity of the of the embedded Relying Party Registration Certificate as defined in ETSI TS 119 472-3
010 The Wallet displays information about the (Q)EAA Provider and the offered (Q)EAA to the user and asks for consent
011 The Wallet requests a fresh nonce for the wallet attestation
012 The Issuer generates a fresh nonce linked to the issuance session
013 The Issuer returns the wallet attestation nonce to the Wallet
014 The Wallet fetches a fresh wallet attestation from the Wallet Provider backend (could also happen in advance)
015 The Wallet generates a proof of possession (PoP) using the nonce fetched in the previous step
016 The Wallet sends a Pushed Authorization Request (PAR) to the Issuer; containing:
- the Wallet Provider's client_id
- a PKCE code_challenge
- the wallet attestation and associated proof of possession
- a redirect_uri containing an app-link
- either scope or an authorization_details parameter requesting the (Q)EAA
017 The Issuer verifies the wallet attestation and validates the status of the Wallet solution through a trust list
018 The Issuer stores the Authorization Request, generates a request_uri and sends it back to the Wallet
019 The Wallet uses the request_uri to create an Authorization Request and send this to the Authorization endpoint of the Issuer by issuing a HTTP GET request over the system's default browser.
020 The Browser sends the Authorization Request to the Issuer
021 In this authentication phase, the Issuer may exchange any information over the browser to the user, as he got the "screen control". This may be, but is not limited to:
- username / password
- OpenID4VP credential presentation of PID, other (Q)EAA, etc..
- taking a photo
022 The Issuer finalizes the authentication phase by responding with an Authorization Response; containing
- the auth code
- the redirect provided by the wallet in the PAR
023 The browser follows the redirect, re-launching the wallet
024 The wallet provides information about the offered (Q)EAA and asks the user for consent
025 The Wallet sends a Token Request to the (Q)EAA Provider; containing:
- the auth code from Authorization Response
- the PKCE code_verifier matching the code_challenge from Authorization Request
- the wallet attestation and Proof of possession
- a DPoP key
026 The Issuer matches the code, verifies the PKCE code_verifier to the previously received code_challenge and verifies the wallet attestation. It then generates an access token bound to the DPoP key.
027 The Issuer verifies the wallet attestation and proof of possession
028 The Issuer sends a Token Response; containing
- DPoP-bound access token
- a c_nonce
- an authorization_details object, if the authorization_details parameter was used in the Authorization Request instead of a scope
029 The Wallet generates a key pair for the cryptographic binding of the (Q)EAA (kb_eph_pub, kb_eph_priv) and signs the c_nonce
030 The Wallet may request an encrypted credential response. In order to do so, it generates a new ephemeral keypair (cre_eph_pub, cre_eph_priv).
031 The Wallet creates the credential_response_encryption JSON object containing the following information:
- a jwk containing the cre_eph_pub
- the JWE alg parameter
- the JWE enc parameter
032 The Wallet sends the Credential Request to the Issuer; containing
- the DPoP-bound access token
- the proof of cryptographic binding key kb_eph_pub signed c_nonce
- and optionally the credential_response_encryption object
033 The Issuer validates the access_token and the proof (signed over the c_nonce)
034 (SD-JWT VC (Q)EAA) The Issuer creates the Disclosures from attestation data and signs the SD-JWT VC with ep_priv containing
- attestation data and hashed Disclosures as the user claims
- kb_eph_pub as cnf claim He then appends the Disclosures.
035 (mdoc (Q)EAA) The Issuer creates the hashed Releases from attestation data and signs the mdoc with ep_priv containing
- attestation data and hashed Releases as issuerAuth
- kb_eph_pub as deviceKeyInfo
036 In case credential_response_encryption information is present, the Issuer creates an encrypted JWT (JWE) using the values received in the credential_response_encryption object and adds (among others) the (Q)EAA credential to the payload.
037 The Issuer sends the Credential Response JWT; containing:
- The (Q)EAA as credential
038 The Wallet decrypts the Credential Response JWT using the cre_eph_priv and retrieves the credential.
039 In case credential_response_encryption information are not present, the Issuer sends the plain Credential Response; containing:
- The (Q)EAA as credential.
040 The Wallet stores the (Q)EAA and the associated keys.

Remote Issuance Pre-Authorized Code Flow

Sequence Diagram

User Journey: (Q)EAA Issuance - Pre-Authorized Code

(Q)EAA Issuance over OpenID4VCI with Pre-Authorized Code Flow(Q)EAA Issuance over OpenID4VCI with Pre-Authorized Code FlowUserUser.s EUDI Wallet InstanceBrowser App.Q.EAA ProviderUserOpenID HolderUserOpenID HolderUser's EUDI Wallet InstanceUser's EUDI Wallet InstanceBrowser AppBrowser App(Q)EAA ProviderLong-term Key: (ep_pub,ep_priv)(Q)EAA ProviderLong-term Key: (ep_pub,ep_priv)(001)Open Issuer's WebsiteUser Authenticationthe (Q)EAA Provider may perform any form ofuser authentication prior to creating thecredential offer(002)Query website: HTTP GET<credential_issuer_url>/(003)HTTP 200HTML with dynamic CredentialOffer<pre-authorized code,tx_code>alt[Issuer initiated - Same Device]Screen: same_device_issuer_website(004)open wallet, unlock walletScreen: launch_walletScreen: unlock_wallet[Issuer initiated - Cross Device]Screen: cross_device_issuer_website(005)scan QR-CodeScreen: launch_walletScreen: unlock_walletScreen: device_camera(006)[TLS] HTTP GET ./well-knownCredential Issuer Metadata(007)[TLS] HTTP 200 <SignedCredential Issuer Metadata>(008)Verify Signed CredentialIssuer Metadata(009)provide consent for (Q)EAAProvider and offeredattestationScreen: consent_provider_and_attestationalt[optional Wallet Attestation](010)[TLS] HTTP POST</session_endpoint> walletattestation nonce(011)generate and store nonce(012)[TLS] HTTP 200 <walletattestation nonce>nonce may be provided in credential offer orreuse pre-auth code(013)perform and get walletattestation from WalletProvider backend (walletattestation nonce)(014)generate PoP for walletattestation(015)[TLS] HTTP POST <TokenRequest(pre-authorizationcode, DPoP Header, optionalwallet attestation, optionaltxCode)>alt[optional Wallet Attestation](016)verify wallet attestationcheck wallet solution statuson trust list(017)lookup authorization codegenerate TokenResponse withDPoP access token(018)[TLS] HTTP 200 <TokenResponse(DPoP-boundaccesss_token, c_nonce)>(019)generate cryptographicbinding key pair (device_pub,device_priv) and proof ofpossession with c_nonceDevice key should be protected by platformsecurity mechanismsScreen: device_authenticatoralt[optional credential response encryption](020)generate credential responseencryption key pair(cre_eph_pub, cre_eph_priv)(021)createcredential_response_encryptionobject with jwk containingcre_eph_pub(022)[TLS] HTTP POST <CredentialRequest(DPoP-bound accesstoken, device_pub, optionallycredential_response_encryption)>(023)lookup access token validate key proofalt[SD-JWT VC (Q)EAA](024)generate SD-JWT VC (Q)EAAand Disclosures withattestation data anddevice_pub as cnf key, signwith ep_priv[mdoc (Q)EAA](025)generate mdoc (Q)EAA withattestation data anddevice_pub as deviceKey, signwith ep_privalt[credential_response_encryption present](026)generate encrypted credentialresponse JWT using the valuesreceived in thecredential_response_encryptionobject(027)[TLS] HTTP 200<JWT(CredentialResponse((Q)EAA))>(028)decrypt credential responseJWT and retrieve credential[not present](029)[TLS] HTTP 200 <CredentialResponse((Q)EAA)>(030)store (Q)EAAScreen: successScreen: homeit might be useful to have a redirect in thebrowser for same-device flow

Step-by-Step Description

No Description
001 The user browses to (Q)EAA Provider's website. At this point it is assumed that the user authentication already took place before the OpenID4VCI protocols starts. This may happen through any mechanism, e.g. username/password, providing OTPs, etc..
002 Browser app on the user's device opens the (Q)EAA Provider's website
003 (Q)EAA Provider returns a HTML page to the browser containing a Credential Offer; containing
- the Credential Issuer URL
- an identifier to the offered credential
- a pre-Authorized Code for authorization, linked to the identified user
- the flag tx_code indicating whether the Wallet is expected to provide a Transaction Code in the Token Request. The Transaction Code is sent by the Issuer over a second channel, e.g., via e-mail or SMS, and helps to strengthen security by additional session binding.
004 (Same-Device) The user clicks on the link, the Wallet launches and he unlocks the wallet
005 (Cross-Device) The user opens and unlocks his wallet and scans the QR-Code
006 The Wallet fetches the Credential Issuer's metadata from the ./well-known files of the Credential Issuer URL
007 The (Q)EAA Provider (from here on named Issuer in his OpenID4VCI role) returns the Credential Issuer Metadata; containing:
- technical information about the Issuer
- translations and display data for the offered credentials
008 The Wallet verifies the signed metadata provided by the Credential Issuer by checking the signature (should be signed with valid access certificate) & existence and validity of the of the embedded Relying Party Registration Certificate as defined in ETSI TS 119 472-3
009 The Wallet shows information about the (Q)EAA Provider and the offered (Q)EAA to the user and asks for consent
010 The Wallet requests a fresh nonce for the wallet attestation nonce (wallet attestation)
011 The Issuer generates a fresh nonce linked to the issuance session
012 The Issuer returns the wallet attestation nonce to the Wallet
013 The Wallet fetches fresh wallet attestation from the Wallet Provider backend
014 The Wallet generates proof of possession (PoP) using the nonce fetched in the previous step
015 The Wallet sends a Token Request to the (Q)EAA Provider; containing:
- the pre-authorized code from Authorization Response
- the wallet attestation and Proof of possession
- a DPoP key
- the Transaction Code that the user received over a second communication channel from the Issuer, if tx_code was present in the Credential Offer
016 The Issuer verifies the wallet attestation and validates the status of the Wallet solution through a trust list
017 The Issuer matches the pre-authorized code and generates an access token bound to the DPoP key.
018 The Issuer sends a Token Response; containing
- DPoP-bound access token
- a c_nonce
019 The Wallet generates a key pair for the cryptographic binding of the (Q)EAA (kb_eph_pub, kb_eph_priv) and signs the c_nonce
020 The Wallet may request an encrypted credential response. In order to do so, it generates a new ephemeral keypair (cre_eph_pub, cre_eph_priv).
021 The Wallet creates the credential_response_encryption JSON object containing the following information:
- a jwk containing the cre_eph_pub
- the JWE alg parameter
- the JWE enc parameter
022 The Wallet sends the Credential Request to the Issuer; containing
- the DPoP-bound access token
- the proof of cryptographic binding key kb_eph_pub signed c_nonce
- and optionally the credential_response_encryption object
023 The Issuer validates the access_token and the proof
024 (SD-JWT VC (Q)EAA) The Issuer creates the Disclosures from attestation data and signs the SD-JWT VC with ep_priv containing
- attestation data and hashed Disclosures as the user claims
- kb_eph_pub as cnf claim He then appends the Disclosures.
025 (mdoc (Q)EAA) The Issuer creates the hashed Releases from attestation data and signs the mdoc with ep_priv containing
- attestation data and hashed Releases as issuerAuth
- kb_eph_pub as deviceKeyInfo
026 In case credential_response_encryption information is present, the Issuer creates an encrypted JWT (JWE) with the information and adds (among others) the (Q)EAA credential to the payload.
027 The Issuer sends the Credential Response JWT; containing:
- The (Q)EAA as credential
028 The Wallet decrypts the Credential Response JWT using the cre_eph_priv and retrieves the credential.
029 In case credential_response_encryption information are not present, the Issuer sends the plain Credential Response; containing:
- The (Q)EAA as credential.
030 The Wallet stores the (Q)EAA and the associated keys.

Usability Considerations

Common Considerations

  • (Q)EAA Provider / Credential catalog should inform users in advance of what is required for the successful issuance of the (Q)EAA and what steps follow
  • For reasons of transparency and to increase trust, (Q)EAA Providers should provide sufficient information (metadata) for the consent screen. This allows users to learn everything relevant e.g. about the provider itself.
  • User must confirm the process with the Device Authenticator
  • User can have a (Q)EAA credential on several end devices at the same time

Authorization Code Flow Considerations

  • User needs to authenticate successfully on (Q)EAA Provider website
  • If the user has to go through more than 2 context switches (issuer initiated flow), it can be confusing, might create unnecessary complexity and additional potential points of failure, and ultimately leads to friction.

Pre-Authorized Code Flow Considerations

  • User is already authenticated on (Q)EAA Provider website or no authentication is required
  • To obtain/copy the transaction code, an additional context switch may be necessary

Privacy Considerations

  • Unlinkability has to be achieved with batch issuance

Security Considerations

  • (Q)EAA Providers may choose to require a wallet attestation
  • the security guarantees of the Pre-Authorized Code Flow, especially in the Cross-Device Flow, are not intended for higher security levels

Implementation Consideration

TBD

Attestation Data and Signature Scope

The term attestation data refers to the attributes and claims contained in the credential that are covered by the issuer's signature. For QEAA, the following clarifications apply:

Credential Format Signed Content Signature Format
SD-JWT VC All claims (hashed disclosures) + holder binding key (cnf) JWS (JSON Web Signature) with QES/QSeal
mdoc All attributes in issuerAuth + device key binding (deviceKeyInfo) COSE_Sign1 with QES/QSeal
W3C VCDM All claims in credentialSubject + holder binding JWS or Data Integrity Proof with QES/QSeal

Unsigned Attributes

Per ETSI TS 119 182, some attribute containers may support unsigned attributes. In the German EUDIW architecture, all qualified attestation attributes MUST be covered by the qualified signature/seal. Unsigned attributes are not permitted for QEAA to ensure legal equivalence with paper documents.

For detailed signature format requirements per credential type, refer to:

  • ETSI TS 119 472-1: General requirements for electronic attestations of attributes
  • ETSI TS 119 472-3: Issuance requirements and signature formats

Requirements for QEAA Issuance

The issuance of (Q)EAA credentials has to fulfill the following requirements:

  • the identification of the holder based on Article 24(1) eIDAS and ETSI TS 119 461
  • the authentication according to ETSI TS 119 471 and ETSI TS 119 472-1
  • respect the requirements of Annex V of the eIDAS Regulation
  • signing with a Qualified Electronic Signature (QES) or Qualified Electronic Seal (QSeal)
  • using the credential formats defined in the Implementing Acts (SD-JWT VC, mdoc, W3C VCDM)
  • using the signature formats for the credential formats as defined in ETSI TS 119 472-3