Skip to main content

Sign-in with OpenID Connect

EUDIPLO can act as an OpenID Provider, so an application that already speaks OpenID Connect can verify a credential from the user's wallet. The application redirects the user to EUDIPLO, the user presents a credential, and the application receives an ID token with the verified claims. Any OpenID Connect client library works; the application needs no wallet-specific code.

For a complete setup with Keycloak as identity broker, see the cookbook Sign in with a wallet. This is the opposite direction of Other OIDC providers, where EUDIPLO trusts an external provider for its own management API.

Before you start​

  • A presentation configuration that requests what the user presents. It must not define transaction data: an authorization request cannot supply it.
  • A token with the presentation:manage role.
  • The application's redirect URIs. HTTPS is required; HTTP only for localhost, 127.0.0.1 and [::1].

1. Register the client​

In the Web Client, open Credential Verification β†’ OIDC Clients and choose Create OIDC client. After Create, the page shows the client ID, issuer and secret once; copy them. The client's page also adds, expires and deletes secrets. Or use the API:

curl -X POST "$EUDIPLO/api/verifier/oidc-clients" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"name": "Customer Portal",
"redirectUris": ["https://portal.example.com/auth/callback"],
"scopes": [{ "scope": "pid", "presentationConfigId": "pid" }]
}'

The response holds the id (your client_id), the clientSecret and the issuer. The secret is returned only now and stored as a hash; it cannot be read back.

FieldRequiredType / allowed valuesDescription
nameyesstringDisplay name of the client.
redirectUrisyesarray of stringRedirect URIs, matched exactly. HTTPS is required; HTTP only for localhost.
profileyesstring: secure | basicsecure requires a pushed authorization request (PAR); basic also accepts the parameters at the authorization endpoint directly.
scopesyesarray of objectScopes the client may request, each with one presentation config.
scopes[].scopeyesstringScope the client requests next to openid. Letters, digits and _.:-, at most 64 characters; openid is reserved.
scopes[].presentationConfigIdyesstringPresentation config that verifies a sign-in with this scope. It must not define transaction data.
subjectnoobject or nullClaim that identifies a user across sign-ins. sub becomes a hash of it, the same for each sign-in of that user with this client; a sign-in whose presentation lacks it fails. Without it, sub is new for every sign-in.
subject.credentialIdyesstringID of the credential query (DCQL) that holds the claim.
subject.claimyesstringDot-separated path to the claim, e.g. personal_administrative_number. A string or number.
claimsFromnostring or nullID of a credential query (DCQL) whose claims are also put at the top level of the ID token, next to credentials, so a relying party can map given_name directly. The token's own claims (iss, sub, aud and so on) are never replaced. A query that was not presented adds nothing.
  • Scopes: each scope selects one presentation configuration. A client can assign a configuration once; several clients can use the same configuration. openid is reserved.
  • Profile: secure (the default) requires a pushed authorization request (RFC 9126); the authorization endpoint then reads only client_id and request_uri. basic also accepts the parameters at the authorization endpoint directly, for libraries that cannot push a request, such as Auth.js. Without the push, anyone who knows the client ID can start sign-ins for it, so use secure where your library allows it.
  • Change a client with PATCH /api/verifier/oidc-clients/{id}; scopes are replaced as a whole. DELETE removes it.

2. Configure your application​

Point the OpenID Connect library at the issuer; it reads <issuer>/.well-known/openid-configuration:

https://eudiplo.example.com/verifiers/<tenantId>/oidc

The discovery document exists once the tenant has a client. Configure the library with:

SettingValue
Client authenticationclient_secret_basic or client_secret_post
Scopeopenid and exactly one scope of the client, for example openid pid
PKCES256, always required
Response typecode
ID token algorithmThe one in id_token_signing_alg_values_supported, ES256 unless the key chain uses another curve. RS256 is not offered: set id_token_signed_response_alg in libraries that default to it, such as openid-client

Every request must ask for openid and exactly one other scope. Many libraries request openid profile email by default, which EUDIPLO refuses with invalid_scope; set the scope explicitly. prompt=none fails with login_required, since every sign-in is a new presentation.

3. Read the ID token​

The ID token is signed by the tenant's authorization server key chain with its algorithm (ES256, ES384 or ES512); verify it with the keys from jwks_uri. The verified claims arrive under credentials, in the same shape as the presentation webhook:

{
"iss": "https://eudiplo.example.com/verifiers/root/oidc",
"sub": "3f0c1d9e-4c1b-4f63-9a59-2f4f0b6a2c11",
"aud": "<client_id>",
"auth_time": 1760000000,
"nonce": "<your nonce>",
"acr": "urn:eudiplo:acr:oidc:same-device",
"credentials": [{ "id": "pid", "values": [{ "given_name": "Ada", "birthdate": "1815-12-10" }] }]
}
  • sub is the ID of the presentation session and new for every sign-in: EUDIPLO keeps no account of the user. Never use it as a key; identify the user by a claim in credentials, or set subject on the client (below).
  • There is no userinfo endpoint, refresh token or logout. The access token is opaque and accepted nowhere.
  • The sign-in is an ordinary presentation session of the tenant: it appears in the session list, triggers the configuration's webhook and follows the tenant's retention. A webhook that answers with a redirectUri replaces the sign-in's callback, so a same-device sign-in can no longer finish; leave it out for configurations used here.

Stable subject and top-level claims​

Identity brokers such as Keycloak recognize a returning user by sub and map claims from the top level of the ID token. Two client fields support this:

  • subject: { "credentialId": "pid", "claim": "personal_administrative_number" } makes sub a hash of that claim, the same for every sign-in of the user with this client and different for each client. claim is a dot-separated path to a string or number; if the claim is missing, empty or of another type, the sign-in fails with access_denied. Choose a claim that does not change for the person. The query must have a trusted_authorities entry with at least one value in every scope's presentation configuration, so nobody can present a self-issued credential with another person's value.

    sub is an HMAC of tenant, client, issuer and value, keyed with a secret derived from MASTER_SECRET: without it, nobody can compute a user's sub at another client or guess the value, and two issuers that hand out the same value never share a sub. The issuer is the thumbprint of the trust list certificate the credential matched (for a listed CA, all issuers under it count as one issuer), or under OpenID Federation the issuer's entity ID; a presentation whose issuer is not known fails with access_denied. When an issuer's certificate in the trust list is replaced, its users' sub values change, and a broker such as Keycloak sees them as new users. subject therefore needs MASTER_SECRET, and changing MASTER_SECRET changes every such sub, so relying parties would see all users as new.

  • claimsFrom: "pid" also copies the claims of the first presented credential of that query to the top level, so given_name sits next to iss. Nested claims such as address keep their structure; a query that was not presented adds nothing. The token's own claims (iss, sub, aud, exp, iat, nonce, acr and so on) and technical claims such as vct and cnf are never replaced.

{
"sub": "Xq3m…pairwise hash…",
"given_name": "Ada",
"family_name": "Lovelace",
"credentials": [{ "id": "pid", "values": [{ "given_name": "Ada", "family_name": "Lovelace" }] }]
}

Set them when you create the client or with PATCH /api/verifier/oidc-clients/{id}; null removes them.

Same device and cross device​

The sign-in page shows a QR code for a wallet on another device and a button for a wallet on the same device. Only the browser that started the sign-in can finish it. acr says which flow happened:

acrMeaning
urn:eudiplo:acr:oidc:same-deviceThe wallet returned the holder to the browser that started the sign-in.
urn:eudiplo:acr:oidc:cross-deviceThe wallet presented on another device, or returned the holder to a different browser. Only the starting browser proved itself.

A cross-device sign-in can be phished: an attacker starts a sign-in, shows its QR code to someone else, and that person's credential lands in the attacker's session. Where the sign-in grants anything that matters, check acr in the ID token, or send acr_values=urn:eudiplo:acr:oidc:same-device in the pushed request, and EUDIPLO refuses a cross-device presentation with access_denied. With the basic profile the browser carries the parameters and can drop acr_values, so check acr there.

A same-device sign-in waits for the wallet's redirect. A wallet that does not redirect back cannot finish it; scan the QR code instead.

Errors​

If the presentation fails, the sign-in expires (15 minutes), the subject claim is missing, the instance has no MASTER_SECRET for a client with subject, or the client was deleted meanwhile, the browser returns to your redirect_uri with error=access_denied, a short error_description for your logs, and your state.

An invalid request (unknown scope, missing PKCE or a code_challenge that is not a 43-character S256 hash, prompt=none, a state over 1024 characters) is answered where it was sent: with the secure profile in the pushed request's response (HTTP 400 with error and error_description); with basic at your redirect_uri with the matching OAuth error, except an over-long state, which cannot be returned and shows an error page. A scope whose presentation configuration no longer has the subject's credential query, or no trusted_authorities entry with a value for it, is refused the same way with invalid_scope.

The user sees an error page instead of a redirect for an unknown client, an unregistered redirect_uri, and an expired (after 5 minutes) or already used request_uri. If EUDIPLO cannot create the presentation request, the browser returns with error=server_error.

Rotate the client secret​

A client holds up to two secrets and accepts either. In the Web Client, use Add secret on the client's page, then delete the old secret there; with the API:

  1. POST /api/verifier/oidc-clients/{id}/secrets returns a new clientSecret.
  2. Switch your application to it.
  3. DELETE /api/verifier/oidc-clients/{id}/secrets/{secretId} removes the old one. lastUsedAt on each secret, accurate to five minutes, shows when it was last used. To stop accepting a secret at a set time instead, PATCH it with expiresAt.

The last secret of a client cannot be deleted; add the new one first.