OpenID for Verifiable Presentations (EUDI wallet, eIDAS 2.0) (v6.6)

pac4j allows you to authenticate users with a digital wallet, using the OpenID for Verifiable Presentations protocol (OpenID4VP). Your application acts as a verifier: it asks the wallet to present credentials, such as the person identification data of the European Digital Identity wallet (EUDI wallet).

The module implements the final version 1.0 of OpenID4VP, not its earlier drafts, which differ on the wire: the drafts had a separate client_id_scheme parameter where 1.0 prefixes the client_id itself, and a presentation_definition query language which 1.0 replaced with DCQL. A wallet built on a draft will not understand these requests. The EUDI profile it follows is the OpenID4VC High Assurance Interoperability Profile 1.0.

1) Dependency

You need to use the following module: pac4j-openid4vp.

Example (Maven dependency):

<dependency>
    <groupId>org.pac4j</groupId>
    <artifactId>pac4j-openid4vp</artifactId>
    <version>${pac4j.version}</version>
</dependency>

It only depends on pac4j-core, on nimbus-jose-jwt and on spring-core (for the resources holding the keys), plus BouncyCastle to read a key and its certificate chain from a keystore.

The module does not depend on pac4j-oidc: OpenID4VP shares the OAuth vocabulary (client_id, nonce, a signed request object) but none of the OpenID Connect mechanisms. There is no identity provider, no token endpoint and no user info: the wallet presents the credentials directly and the whole validation happens in the application.

2) The protocol, briefly

A presentation runs in three steps:

1. the application, as the verifier, hands the wallet a request: which credentials it wants, expressed in the Digital Credentials Query Language (DCQL), a nonce to bind the answer to, and the key to encrypt that answer to. The request is a JWT signed by the verifier, the request object
2. the wallet authenticates the verifier, shows the End-User what is asked, and, on consent, builds a presentation from its credentials: for a SD-JWT VC, the issuer-signed credential with only the disclosed claims, and a key binding JWT proving the holder holds the key and answers this very nonce
3. the wallet returns the presentation, encrypted to the verifier, which validates the issuer signature, the trust in that issuer, the revocation status and the key binding, and finally reads the claims.

How the request reaches the wallet depends on where the wallet is: invoked by a URL, on the same device or through a QR code, or through the Digital Credentials API of the browser. pac4j provides one client for each way (see below).

See the OpenID for Verifiable Presentations 1.0 specification, and in particular its client identifier prefixes, response encryption and Digital Credentials API sections.

3) The EUDI wallet: ARF and HAIP

The European Digital Identity wallet is established by the eIDAS 2.0 regulation (Regulation (EU) 2024/1183), which has every member state provide one to its citizens and has the relying parties register to use it: the access certificate of a verifier comes from that registration. Its technical architecture is the Architecture and Reference Framework (ARF) of the European Commission. For remote presentations, the ARF relies on OpenID4VP, and since that specification leaves many options open, it mandates a profile which closes them: the OpenID4VC High Assurance Interoperability Profile (HAIP). In the words of the ARF (section 5.7.4): “the use of the profile for ‘OpenID for Verifiable Presentations for IETF SD-JWT VC’ specified in [HAIP] is necessary to ensure interoperability between Wallet Units and Relying Parties”, and its annex 2 turns it into requirements: relying parties and wallet units shall comply with HAIP.

HAIP decides, among other things, that:

• the request object is signed, and the verifier authenticates with the x509_hash client identifier prefix: its identifier is the hash of its relying party access certificate, obtained through the registration process of a member state
• the answer is encrypted (direct_post.jwt or dc_api.jwt), to a key generated for each request, with ECDH-ES on P-256 and A128GCM or A256GCM
• the credentials are SD-JWT VCs or ISO mobile documents (mdoc), the person identification data being issued in both formats.

The EudiWalletClient pins those choices, so that a configuration only has to provide the access certificate, its key and the query, and maps the person identification data onto an EudiPidProfile with a typed accessor for each attribute (getGivenName(), isAgeOver18()…). Beware that the attribute identifiers of the PID have changed across versions of the ARF: check them against the version you target.

An EUDI wallet only talks to a registered relying party: the EudiWalletClient needs that access certificate, with its private key and its chain, loaded through the keystore property of the configuration, or through its jwks property when the key carries the chain in a x5c member. It cannot be tried against a real wallet without it.

4) Clients and configuration

The clients

• OpenId4VpClient: the generic verifier, for a wallet invoked by a URL. The redirection is a openid4vp:// URL: on the same device the browser follows it and the wallet opens; on another device, the application must display it as a QR code: it calls the protected URL via AJAX, and the wallet URL is returned in the Location header. The wallet then fetches the request object by HTTP (request_uri), or first posts what it supports and gets a request object built for it (request_uri_method=post), and posts its answer (direct_post or direct_post.jwt): all of it on the regular pac4j callback URL, without any session. The page waits for the answer and calls back when it has arrived, which turns the received presentation into a VerifiableCredentialProfile
• OpenId4VpDcApiClient: the same verifier over the Digital Credentials API of the browser, with a OpenId4VpDcApiConfiguration. The page never leaves: the client answers the page a JSON {"request": "<signed request object>"} which the page passes to navigator.credentials.get(), the browser hands it to the wallet with the authenticated origin of the page, and the page posts the answer back (dc_api or dc_api.jwt). Unlike the URL binding, the wallet never calls the application by itself: every request reaches the application from the browser, with its web session, as any other page request. In return, the request must be signed, and the origins the page runs from must be declared
• EudiWalletClient: the OpenId4VpClient with the HAIP choices pinned and not configurable: the x509_hash prefix, so the certificate loaded from the keystore is the identity of the verifier, the direct_post.jwt response mode, and the EudiPidProfile. Use it to read the person identification data of an EUDI wallet, the generic client to talk to any other wallet or to another credential.

Example (EUDI wallet, with the relying party access certificate in a keystore):

OpenId4VpConfiguration config = new OpenId4VpConfiguration()
    .setKeystore(new KeystoreProperties()
        .setKeystorePath("/path/to/access-certificate.p12")
        .setKeystorePassword("...")
        .setKeyStoreAlias("rp"))
    .setDcqlQuery(EudiPidQuery.sdJwtVc(GIVEN_NAME, AGE_OVER_18));
EudiWalletClient client = new EudiWalletClient(config);

Example (any wallet, over the Digital Credentials API, with a DID):

OpenId4VpDcApiConfiguration config = new OpenId4VpDcApiConfiguration();
config.setExpectedOrigins(List.of("https://verifier.example.org"))
    .setClientId("did:web:verifier.example.org")
    .setClientIdPrefix(ClientIdPrefix.DECENTRALIZED_IDENTIFIER)
    .setJwks(new JwksProperties().setJwksPath("/path/to/verifier.jwks").setKid("verifier-key"))
    .setDcqlQuery(new DcqlQuery()
        .addCredential(new CredentialQuery("pid", CredentialFormat.SD_JWT_VC)
            .setVctValues("urn:eudi:pid:1")
            .addClaim("family_name")
            .addClaim(new ClaimsQuery("age_over_18").withValues(true))));
OpenId4VpDcApiClient client = new OpenId4VpDcApiClient(config);

The query

The credentials are asked for with a DCQL query, which the dcql package models: a DcqlQuery holds CredentialQuery objects, one per credential, each with its format, its format-specific meta (setVctValues for a SD-JWT VC, setDoctypeValue for a mobile document), the ClaimsQuery objects naming the claims by their path, and optional TrustedAuthority constraints on the issuers; CredentialSetQuery objects say which combinations of credentials satisfy the verifier. The query is checked at initialization, serialized into the request, and read back from JSON with DcqlQuery.parse. For the person identification data of the EUDI wallet, EudiPidQuery.sdJwtVc(...) and EudiPidQuery.mdoc(...) build the query from the attribute names of EudiPidProfileDefinition. Matching the query against the credentials is the wallet’s job: the model writes, checks and reads, nothing more.

The query can also be given as plain JSON text, which setDcqlQuery(String) parses into the same model, checked the same way at initialization:

config.setDcqlQuery("{\"credentials\":[{\"id\":\"pid\",\"format\":\"dc+sd-jwt\",\"meta\":{\"vct_values\":[\"urn:eudi:pid:1\"]},\"claims\":[{\"path\":[\"given_name\"]},{\"path\":[\"age_over_18\"]}]}]}");

The configuration

The OpenId4VpConfiguration has the following properties, with the HAIP choices as defaults:

The OpenId4VpDcApiConfiguration adds one property and closes two: its default response mode is DC_API_JWT, only DC_API and DC_API_JWT are accepted, and the REDIRECT_URI prefix is refused since this binding hands the browser a signed request.

The clients themselves expose a requestObjectBuilder (OpenId4VpRequestObjectBuilder, or DcApiRequestObjectBuilder over the Digital Credentials API), to be overridden to add parameters to the request object, and the usual redirectionActionBuilder, credentialsExtractor, authenticator and profileCreator of an indirect client.