OpenID4VP / Clients and configuration (v6.6)

Choose how your Java application opens the wallet: a URL or QR code with OpenId4VpClient, or the browser’s Digital Credentials API with OpenId4VpDcApiClient. EudiWalletClient fixes the settings for the EUDI PID profile; the configuration below explains what each choice requires.

See also:

  ▸ OpenID4VP overview

  ▸ Response validation and verifiers

  ▸ DCQL queries, user profiles and logging

1) 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: to know when, it polls an endpoint of the application returning client.getPresentationStatus(ctx), which is PENDING, RECEIVED or EXPIRED for the transaction of the browser session
• 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, whose identifier claim must be chosen by the application. 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.

The following examples configure the presentation request, including the claim identifying the user: a client whose DCQL query cannot return that claim refuses to initialize. See The profile identifier.

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(PERSONAL_ADMINISTRATIVE_NUMBER, GIVEN_NAME, AGE_OVER_18))
    // the PID defines no sub: name the claim identifying the user, here one that the targeted PID provider issues
    .setProfileIdResolver(ProfileIdResolver.issuerAndClaim(PERSONAL_ADMINISTRATIVE_NUMBER));
EudiWalletClient client = new EudiWalletClient(config);

personal_administrative_number is optional in the PID and not issued by every provider: check it against the target ecosystem, or set a ProfileIdResolver (see The profile identifier).

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("badge", CredentialFormat.SD_JWT_VC)
            .setVctValues("https://credentials.example.org/employee-badge")
            // sub: the claim the default profile definition identifies the user with
            .addClaim("sub")
            .addClaim("family_name")
            .addClaim(new ClaimsQuery("role").withValues("manager"))));
OpenId4VpDcApiClient client = new OpenId4VpDcApiClient(config);

2) 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. The OpenId4VpAuthenticator builds the user profile, with its profileDefinition (OpenId4VpProfileDefinition, or EudiPidProfileDefinition for the EudiWalletClient); the default profile creator returns it, and a custom one may enrich it.