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:managerole. - The application's redirect URIs. HTTPS is required; HTTP only for
localhost,127.0.0.1and[::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.
| Field | Required | Type / allowed values | Description |
|---|---|---|---|
name | yes | string | Display name of the client. |
redirectUris | yes | array of string | Redirect URIs, matched exactly. HTTPS is required; HTTP only for localhost. |
profile | yes | string: secure | basic | secure requires a pushed authorization request (PAR); basic also accepts the parameters at the authorization endpoint directly. |
scopes | yes | array of object | Scopes the client may request, each with one presentation config. |
scopes[].scope | yes | string | Scope the client requests next to openid. Letters, digits and _.:-, at most 64 characters; openid is reserved. |
scopes[].presentationConfigId | yes | string | Presentation config that verifies a sign-in with this scope. It must not define transaction data. |
subject | no | object or null | Claim 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.credentialId | yes | string | ID of the credential query (DCQL) that holds the claim. |
subject.claim | yes | string | Dot-separated path to the claim, e.g. personal_administrative_number. A string or number. |
claimsFrom | no | string or null | ID 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.
openidis reserved. - Profile:
secure(the default) requires a pushed authorization request (RFC 9126); the authorization endpoint then reads onlyclient_idandrequest_uri.basicalso 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 usesecurewhere your library allows it. - Change a client with
PATCH /api/verifier/oidc-clients/{id};scopesare replaced as a whole.DELETEremoves 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:
| Setting | Value |
|---|---|
| Client authentication | client_secret_basic or client_secret_post |
| Scope | openid and exactly one scope of the client, for example openid pid |
| PKCE | S256, always required |
| Response type | code |
| ID token algorithm | The 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" }] }]
}
subis 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 incredentials, or setsubjecton 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
redirectUrireplaces 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" }makessuba hash of that claim, the same for every sign-in of the user with this client and different for each client.claimis a dot-separated path to a string or number; if the claim is missing, empty or of another type, the sign-in fails withaccess_denied. Choose a claim that does not change for the person. The query must have atrusted_authoritiesentry with at least one value in every scope's presentation configuration, so nobody can present a self-issued credential with another person's value.subis an HMAC of tenant, client, issuer and value, keyed with a secret derived fromMASTER_SECRET: without it, nobody can compute a user'ssubat another client or guess the value, and two issuers that hand out the same value never share asub. 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 withaccess_denied. When an issuer's certificate in the trust list is replaced, its users'subvalues change, and a broker such as Keycloak sees them as new users.subjecttherefore needsMASTER_SECRET, and changingMASTER_SECRETchanges every suchsub, 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, sogiven_namesits next toiss. Nested claims such asaddresskeep their structure; a query that was not presented adds nothing. The token's own claims (iss,sub,aud,exp,iat,nonce,acrand so on) and technical claims such asvctandcnfare 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:
acr | Meaning |
|---|---|
urn:eudiplo:acr:oidc:same-device | The wallet returned the holder to the browser that started the sign-in. |
urn:eudiplo:acr:oidc:cross-device | The 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:
POST /api/verifier/oidc-clients/{id}/secretsreturns a newclientSecret.- Switch your application to it.
DELETE /api/verifier/oidc-clients/{id}/secrets/{secretId}removes the old one.lastUsedAton each secret, accurate to five minutes, shows when it was last used. To stop accepting a secret at a set time instead,PATCHit withexpiresAt.
The last secret of a client cannot be deleted; add the new one first.