# EUDIPLO
> Middleware for the European Digital Identity Wallet ecosystem
This file contains all documentation content in a single document following the llmstxt.org standard.
## What is EUDIPLO?
EUDIPLO is open-source middleware that connects your backend to EUDI Wallets. Your application calls a JSON management API to issue a credential or to request one. EUDIPLO handles the wallet-facing protocols (OID4VCI, OID4VP, SD-JWT VC, mDOC) and reports the result back through a webhook, server-sent events or polling.
You run EUDIPLO yourself, as one backend container with optional PostgreSQL, S3-compatible storage and an external key store. One instance serves many tenants, and each tenant has its own keys, credential types and verification requests. A Web Client and a CLI help you configure and operate the instance; everything the Web Client does is also available through the API.
EUDIPLO only implements the protocols of the EUDI Wallet ecosystem. See the [standards support matrix](reference/protocols.md) for the exact scope.
### Where does it fit?
```mermaid
flowchart LR
A["Your Application"] -->|"HTTP / JSON"| B["EUDIPLO"]
B -->|"OID4VCI / OID4VP"| C["EUDI Wallet"]
```
### Get started
**[Start the cookbook →](cookbooks/foundation.md)** It installs EUDIPLO, issues a membership credential to a wallet on your phone, and verifies it.
For a quick look at the Web Client with sample data, run `eudiplo demo`. Open `http://localhost:4200`, check that **EUDIPLO Instance** is `http://localhost:3000`, and sign in with client ID and secret `root`. The demo uses the same ports as the cookbook, so stop it with `eudiplo down --instance local` before you begin.
### Find your way
#### Cookbooks
Recipes that end in a working result, with a checkpoint after every step.
[Browse the recipes](cookbooks/index.md)
#### Guides
One task per page: [Issuance](issuance/index.md), [Presentation](presentation/index.md), [Trust](trust/index.md) and [Operate](operate/index.md).
#### Reference
Exact facts: the [management API](reference/api.md), [environment variables](reference/environment-variables.md), the [CLI](reference/cli.md) and [webhooks](reference/webhooks.md).
### Use the docs with a coding assistant
Point your assistant at [`llms.txt`](pathname:///llms.txt), an index of all pages, or at [`llms-full.txt`](pathname:///llms-full.txt), every page in one file. Both follow [llmstxt.org](https://llmstxt.org). `llms-full.txt` contains the Markdown source of each page, so generated content (environment variables, configuration fields, roles and the CLI command reference) is only on the published pages.
---
## Cookbook: Certificates from the EUDI Hub
Wallets of the German ecosystem accept a verifier only with an access certificate from the German registrar, the EUDI Hub, and show what it may request from its registration certificate. In this recipe you replace the self-signed access certificate of `membership-check` with one from the EUDI Hub sandbox, and add registration certificates for the verifier and the issuer. The [EUDI Hub](../trust/eudi-hub.md) guide describes every field and error.
### What you will build
The access key chain `Membership verifier access` keeps its key and gets a certificate from the EUDI Hub. `membership-check` attaches a registration certificate for its DCQL query to every request, and the credential issuer metadata of `membership-demo` publishes one for the `membership` credential.
```mermaid
flowchart LR
P[EUDI Hub portal] -->|access token| E[EUDIPLO]
E -->|CSR of Membership verifier access| H[EUDI Hub sandbox]
E -->|DCQL query of membership-check| H
E -->|credential types of membership-demo| H
H -->|access certificate, registration certificates| E
```
### Before you start
- **Starts from:** [Issue and verify](index.md): tenant `membership-demo` with the access key chain `Membership verifier access`, the credential configuration `membership` and the presentation configuration `membership-check`.
- The client `membership-demo-admin` holds `registrar:manage`, which chapter 2, step 1 adds only if your wallet needs registrar certificates. If it is missing, add it to the client under **Administration → API Clients** and sign in again. Without `tenant:admin`, a client cannot add a role to itself: a client or user that may grant it must add it ([granting roles](../reference/roles.md#granting-roles)).
- An account in the [EUDI Hub portal](https://portal.eudi-hub.gov.de/) assigned to an organization that may request certificates in the sandbox. Create and verify the organization in the portal; EUDIPLO does not do that.
- Your organization's official identifier (for example its EUID or Handelsregisternummer), a privacy policy URL, a support URL and a general web address.
- If `OUTBOUND_URL_ALLOWED_HOSTS` is set, it lists `api.eudi-hub.gov.de` and the host of the EUDI Hub's issuing CA ([prerequisites](../trust/eudi-hub.md#prerequisites)).
- `curl` and `jq` for the checkpoints, with a token of `membership-demo-admin`:
```bash
export EUDIPLO=http://localhost:3000
read -rs ADMIN_SECRET
ADMIN_TOKEN=$(curl -s -X POST "$EUDIPLO/api/oauth2/token" \
-d grant_type=client_credentials -d client_id=membership-demo-admin \
--data-urlencode client_secret="$ADMIN_SECRET" | jq -r .access_token)
```
### Step 1: Copy an access token from the portal
EUDIPLO acts at the EUDI Hub with the access token of your portal session. It is valid for a few minutes and is never stored, so copy a fresh one right before each of the next steps:
1. Sign in to the [EUDI Hub portal](https://portal.eudi-hub.gov.de/) and open the developer tools of your browser on the **Network** tab.
2. Open **Access certificates** in the portal and select a request to `api.eudi-hub.gov.de`.
3. Copy the value of its `Authorization` request header.
Treat the token like a password: until it expires, it acts as your portal user.
**Checkpoint:** the copied value starts with `Bearer eyJ` or `eyJ`.
### Step 2: Get the access certificate
1. Open **Cryptographic Assets → Keys**, select `Membership verifier access` and choose **Request from EUDI Hub** on its **Active Certificate** card.
2. Paste the token into **Access token**, choose **Load Organizations** and select your organization.
3. Keep **Environment** **Sandbox**, enter your **Support URI**, and leave **Certificate name** empty, so the portal shows the key chain's description.
4. Choose **Request Certificate**.
EUDIPLO sends a certificate signing request for the existing key, so the private key never leaves EUDIPLO, and stores the issued certificate together with the CA that issued it.
**Checkpoint:** the **Active Certificate** card shows an **Issuer** of the EUDI Hub that differs from the **Subject**. The portal lists the certificate under **Access certificates**.
### Step 3: Register the verifier
Request the registration certificate after the access certificate. EUDIPLO attaches it to every request of `membership-check`, whichever access key chain signs it, so request a new one whenever you change that key chain or its certificate.
1. Copy a fresh access token (step 1).
2. Open **Credential Verification → Verification Configs**, select `membership-check`, go to the **Security** tab and choose **Request from EUDI Hub** on the **Registration Certificate** card.
3. Paste the token and select the organization. EUDIPLO fills empty fields with what the EUDI Hub knows about the organization.
4. Complete the fields the EUDI Hub needs:
- **Identifier type** and **Identifier**, as in the official record.
- **Service description (German)** `Prüfung von Vereinsmitgliedschaften` and **Service description (English)** `Club membership checks`.
- **Purpose (German)** `Prüfung Ihrer Vereinsmitgliedschaft` and **Purpose (English)** `Check your club membership`.
- **Privacy policy**, **Support URI** and **Info URI**.
5. Keep **Sandbox** and choose **Request Certificate**.
EUDIPLO registers a credential request for `urn:example:membership:1` with the claims `name` and `member_id` at the EUDI Hub, or reuses one with the same content, and stores the certificate in `registration_cert`.
**Checkpoint:** the certificate authorizes exactly the DCQL query, and its expiry date is in the future:
```bash
curl -s "$EUDIPLO/api/verifier/config/membership-check" -H "Authorization: Bearer $ADMIN_TOKEN" \
| jq -r .registration_cert.jwt \
| jq -R 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson
| {exp: (.exp | todate), credentials}'
```
### Step 4: Register the issuer
1. Copy a fresh access token (step 1).
2. Open **Credential Issuance → Issuer Settings**, go to the **Registration Certificate** tab and choose **Request from EUDI Hub**.
3. Paste the token, select the organization, and complete **Identifier**, **Service description**, **Support URI** and **Info URI** as in step 3.
4. Keep **Sandbox** and choose **Request Certificate**.
EUDIPLO registers the VCT of every credential configuration of the tenant as a credential issuance, here `urn:example:membership:1` (also for `membership-untrusted` if you followed [Accept only trusted issuers](trusted-issuers.md)), and turns the registration certificate on.
**Checkpoint:** the credential issuer metadata publishes the certificate:
```bash
curl -s "$EUDIPLO/.well-known/openid-credential-issuer/issuers/membership-demo" \
| jq '.issuer_info[0].format'
```
The answer is `"registration_cert"`.
### Step 5: Present the credential again
Generate a new request for `membership-check` and scan it with your wallet, as in [chapter 3, step 5](first-presentation.md#step-5-generate-and-approve-a-request). The request object is now signed with the EUDI Hub access certificate and carries the registration certificate as `verifier_info`.
**Checkpoint:** the presentation session is `completed`. A wallet that reads registration certificates shows your organization and the purpose from step 3.
### Troubleshooting
| Symptom | Cause | Fix |
| --- | --- | --- |
| `400` naming HTTP 401 of the EUDI Hub | The portal token has expired or was not copied completely | Copy a fresh token (step 1) and request again. |
| `400` naming HTTP 403 of the EUDI Hub | Your portal user may not request certificates for this organization | Ask the organization's administrator in the portal for the permission. |
| **Request from EUDI Hub** is missing or locked | `membership-demo-admin` lacks `registrar:manage`, or the configuration is provisioned from a configuration file | Use a client with the role; change provisioned configurations in their files. |
| Saving a changed DCQL query of `membership-check` fails with `400` | The registration certificate does not cover the new query ([Overasking check](../trust/registration-certificates.md#overasking-check)) | Clear the registration certificate in the same save, then request a new one for the saved query (step 3). |
| Requests to `membership-check` fail with `400` | The registration certificate has expired | Request a new registration certificate (step 3). |
Status codes and retries after an EUDI Hub failure are listed under [Errors](../trust/eudi-hub.md#errors). General problems are covered in [Troubleshooting](../troubleshooting.md).
### Next steps
- [EUDI Hub](../trust/eudi-hub.md): every field, the API calls and the Live environment.
- [Registration certificates](../trust/registration-certificates.md): how wallets and EUDIPLO check them.
- [Wallet and registrar requirements](../trust/wallet-registrars.md): which wallets need which certificates.
---
## Cookbook: Issue a Membership Credential
This is chapter 2 of the **Issue and verify** cookbook. You create a tenant with its own keys and issuer identity, define a membership credential, and send it to the wallet on your phone.
### What you will build
A tenant `membership-demo` that issues an SD-JWT VC of type `urn:example:membership:1` with the claims `name: Max` and `member_id: M-001`, using a pre-authorized offer that the wallet scans as a QR code.
### Before you start
- **Starts from:** [chapter 1, Install and connect](foundation.md). You are signed in to the Web Client as root, the tunnel is running, and the phone reaches `https://YOUR-HTTPS-HOST/health`.
- You know which certificates your wallet needs ([Wallet and registrar requirements](../trust/wallet-registrars.md)).
### Step 1: Create a tenant for the recipe
1. Open **Administration → Tenants** and choose **Create tenant**.
2. Enter **Tenant ID** `membership-demo` and **Name** `Membership Demo`.
3. Under **Initial Admin Client → Client Roles**, keep the preselected `clients:manage` and `tenant:admin` and add exactly these roles:
| Role | Allows |
| ---------------------- | ---------------------------------------------------------------- |
| `issuance:manage` | Keys, issuer settings and credential types |
| `issuance:offer` | Creating credential offers and viewing issuance sessions |
| `presentation:manage` | Verification configurations |
| `presentation:request` | Creating presentation requests and viewing presentation sessions |
Add `registrar:manage` only if your wallet needs registrar certificates. Never give a tenant client `tenants:manage`: it controls **all** tenants of the instance.
4. Choose **Create tenant**. The dialog **Client Secret Generated** shows the client ID `membership-demo-admin` and its secret. Copy both and store them; the secret is not shown again.
5. Choose **Login as this Client**.
**Checkpoint:** the account menu (⋮) at the top right shows **Client ID: membership-demo-admin**, and the navigation shows **Credential Issuance** and **Credential Verification**. Create everything that follows in this tenant. All roles are listed in the [roles reference](../reference/roles.md).
### Step 2: Create the signing and access keys
Open **Cryptographic Assets → Keys**, choose **Create Key** and run the wizard twice:
| Purpose | Wizard choices | Description |
| ---------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------- |
| Sign the issued credential | **Credential Signing (Attestation)** → **Key Chain with Root CA** | `Membership credential signing` |
| Sign presentation requests to the wallet | **Access Certificate** → the certificate source your wallet needs (see below) | `Membership verifier access` |
Keep KMS provider `db` and the other defaults, then choose **Create Key Chain**. For the access certificate, pick the source that matches your wallet:
- **Self-Signed Certificate** for wallet test setups that accept it, such as Paradym.
- **External Certificate** to import a key and certificate chain issued elsewhere, such as the EU Reference Implementation's ecosystem operator. Paste the key into **External Private Key (JWK or PKCS#8 PEM)** and the chain into **Certificate Chain (PEM)**, then choose **Import Key & Certificate**.
- For the German ecosystem, create it as **Self-Signed Certificate**, then request its certificate from the EUDI Hub on the key chain page ([EUDI Hub](../trust/eudi-hub.md#request-an-access-certificate)); this needs the `registrar:manage` role.
**Checkpoint:** both key chains appear under **Keys**, each with an active key and certificate. The wizard generates their IDs; the next steps select them by description. Other provisioning options are in [Keys and certificates](../trust/keys-and-certificates.md).
:::note[Two kinds of certificates]
The HTTPS certificate of your tunnel and the credential and access certificates are unrelated. A reachable HTTPS endpoint does not make a wallet trust a self-signed issuer or verifier.
:::
### Step 3: Set up the issuer
Open **Credential Issuance → Issuer Settings** and choose **Use guided setup**.
1. **Identity:** enter name `Membership Demo` and locale **English**. A logo is optional.
2. **Wallet access:** keep the enabled built-in authorization server and batch size `1`. Leave request and response encryption off. Under **Issuance behavior (advanced)**, check that your wallet supports the DPoP setting.
3. **Trust:** leave wallet attestation optional and federation off. Leave the registration certificate off unless your wallet requires one.
4. **Review:** choose **Save settings**.
**Checkpoint:** the issuer overview shows `Membership Demo` and an enabled built-in authorization server. Every option is explained in [Issuer settings](../issuance/issuance-configuration.md).
### Step 4: Define the membership credential
Open **Credential Issuance → Credential Configs** and choose **Create credential config**. Use exactly these values; chapter 3 requests the credential by its VCT and claim paths.
#### Basics
| Field | Value |
| ----------------- | ---------------------------------------- |
| Configuration ID | `membership` |
| Description | `Membership credential for the cookbook` |
| Credential Format | `dc+sd-jwt` |
| Host VCT Metadata | **No (Custom URI)** |
| VCT URI | `urn:example:membership:1` |
Choose **Continue**.
#### Claims
Choose **Add Field** twice and enter the values as plain text, without JSON quotes:
| Path | Type | Default Value | Mandatory | Selectively Disclosable |
| ----------- | -------- | ------------- | --------- | ----------------------- |
| `name` | `string` | `Max` | On | On |
| `member_id` | `string` | `M-001` | On | On |
Choose **Continue**.
#### Appearance
Enter **Display Name** `Membership`, **Description** `Example membership card` and **Locale** **English**. Choose **Continue**.
#### Settings
1. Under **Signing, lifetime and trust**, select the key chain described as `Membership credential signing` in **Signing Key Chain**, set **Credential Lifetime** to **1 day** and keep **SD-JWT Trust Format** `x5c`.
2. Under **Credential Features**, keep **Key Binding** on and turn **Status Management** off. Set **Supported Proof Types** to **JWT** only, so the first run does not need key attestation.
3. Leave attribute providers, webhooks, authorization actions and reuse policy empty.
Choose **Continue**, check the review, and choose **Create Configuration**.
**Checkpoint:** `membership` appears under **Credential Configs** with the description `Example membership card`, format **SD-JWT VC**, a lifetime of 1 day, **No status** and **Key binding**. Open it to check VCT `urn:example:membership:1` and the two claims. Other formats and settings are in [Credential configuration](../issuance/credential-configuration.md).
:::note[Why status management is off]
It keeps status lists out of the first run. [Revocable credentials](revocable-credentials.md) turns it on.
:::
### Step 5: Send an offer to the wallet
1. Open **Credential Issuance → New Issuance**.
2. In **Select Flow**, choose **Pre-Authorized Code** and **Next**.
3. In **Select Credentials**, check that `membership` is selected under **Credential Config IDs** and continue. As the tenant's only credential type, it is preselected and shown as a chip.
4. In **Configure Claims**, keep **Form Input** and choose **Use Pre-configured Default Values**. The form now shows `name: Max` and `member_id: M-001`.
5. Leave **Transaction Code (Optional)** empty, then choose **Generate Offer**.
6. Scan the QR code with the wallet's credential-offer scanner and accept the credential.
**Checkpoint:** the wallet shows a `Membership` credential with `Max` and `M-001`. Under **Sessions → All Sessions**, the issuance session has status `fetched` (the wallet received the credential) or `completed` (the wallet also confirmed it through the notification endpoint). A QR code alone does not mean that the wallet received the credential.
### Troubleshooting
| Symptom | Cause | Fix |
| ---------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `membership` is missing in the offer form | Created in another tenant, or saved with authorization actions | Check the client ID in the account menu (⋮) at the top right; remove interactive authorization actions for this recipe. |
| **Credential Issuance** is missing in the menu | The tenant client lacks `issuance:manage` or `issuance:offer` | Open **Administration → API Clients**, add the role to `membership-demo-admin` and sign in again. Without `tenant:admin`, a client cannot add roles to itself: sign in with the root client, delete `membership-demo` under **Administration → Tenants** and repeat step 1. |
| Wallet asks for an attestation | Proof type **Attestation** or required wallet attestation is set | Use proof type **JWT** only and keep wallet attestation optional. |
| Wallet shows other claim values | The offer overrode the defaults, or the credential is an older one | Generate a new offer with the default values; a wallet keeps the claims it was issued with. |
Wallet connection, certificate and metadata errors are covered in [Troubleshooting](../troubleshooting.md).
### Next steps
- Keep the credential in the wallet and stay in tenant `membership-demo`.
- Continue with chapter 3: [Verify the membership credential](first-presentation.md).
---
## Cookbook: Verify the Membership Credential
This is chapter 3 of the **Issue and verify** cookbook. You publish a trust list with your issuer, request the `name` and `member_id` claims of the membership credential from chapter 2, approve the request in the wallet, and inspect the verified result.
### What you will build
A managed trust list `membership-issuers` that EUDIPLO signs and publishes, listing the issuer certificate of chapter 2, and a presentation configuration `membership-check` with one DCQL credential query `membership`. It asks for the two claims of `urn:example:membership:1`, accepts them only from issuers on `membership-issuers`, and the request is signed with the access certificate from chapter 2.
```mermaid
flowchart LR
K[Membership credential signing] -->|root CA listed in| T[Trust list membership-issuers]
T -->|trusted_authorities| P[membership-check]
```
### Before you start
- **Starts from:** [chapter 2, Issue a membership credential](first-credential.md). The wallet holds the `Membership` credential with `Max` and `M-001`.
- You are signed in as `membership-demo-admin`, and the public HTTPS URL is unchanged.
- The access key chain `Membership verifier access` has a certificate that your wallet's test environment accepts.
### Step 1: Create the keys for the trust list
Every credential query of a presentation configuration names the issuers it accepts, here through a trust list. Open **Cryptographic Assets → Keys** and create two key chains with **Create Key**:
| Usage | Description | Purpose |
| ----------------------- | --------------------------------- | ----------------------------------------------------------------- |
| **Trust List Signing** | `Membership trust list signing` | Signs the trust list |
| **Status List Signing** | `Membership status list signing` | Listed as the issuer's status list certificate |
For the status list key, keep **Key Chain with Root CA**: its signing key rotates while the trust list keeps naming the same root CA. EUDIPLO does not create a trust list signing key on its own.
**Checkpoint:** both key chains appear under **Keys**.
### Step 2: Publish the trust list
Open **Cryptographic Assets → Trust Lists**, choose **+** (**Create new Trust List**) and enter:
1. **ID** `membership-issuers`, **Description** `Issuers accepted for membership checks`, **Signing Key Chain** `Membership trust list signing`.
2. Choose **Add Internal Entity**. Keep **Provider type** **Credential provider**, select **Issuer Key Chain** `Membership credential signing` and **Revocation Key Chain** `Membership status list signing`, and enter **Entity Name** `Membership Demo`, **E-mail Address** `info@membership.example` and **Website** `https://membership.example/`. A published trust list names both for every entity (ETSI TS 119 602).
3. Choose **Create Trust List**.
For an internal entity, EUDIPLO lists the root CA certificate of the issuer key chain. The root stays the same when the signing key rotates. To list an issuer of another organization, choose **Add External Entity** and paste its certificates instead.
Equivalent API call
`POST /api/trust-list` with the key chain IDs from **Keys**:
```json
{
"id": "membership-issuers",
"description": "Issuers accepted for membership checks",
"keyChainId": "",
"entities": [
{
"type": "internal",
"issuerKeyChainId": "",
"revocationKeyChainId": "",
"info": {
"name": "Membership Demo",
"contactUri": "info@membership.example",
"website": "https://membership.example/"
}
}
]
}
```
**Checkpoint:** the trust list page shows the **Trust List URL** `https://YOUR-HTTPS-HOST/issuers/membership-demo/trust-list/membership-issuers`. Wallets and verifiers fetch the list there, so the URL starts with the backend's `PUBLIC_URL`, not with the address you signed in with. It serves a signed list:
```bash
curl -s https://YOUR-HTTPS-HOST/issuers/membership-demo/trust-list/membership-issuers | cut -c1-40
```
The output starts with `eyJ`, the beginning of a signed JWT.
A managed list is valid for 30 days. EUDIPLO re-signs it automatically during the last 10 days, so it never expires while the instance runs.
### Step 3: Define what to request
Open **Credential Verification → Verification Configs** and choose **Create config**.
1. On **1. Name**, enter **ID** `membership-check` and **Description** `Verify a membership name and ID`. Choose **Continue**.
2. On **2. Credentials**, choose **Add credential** and enter:
| Field | Value |
| --------------------- | -------------------------- |
| Query ID | `membership` |
| Credential format | **SD-JWT VC** |
| Credential type (VCT) | `urn:example:membership:1` |
| Claim path | `name` |
3. Choose **Add claim** and enter `member_id` as the second **Claim path**.
4. Expand **Issuer trust**, choose **Add managed trust list** and select `membership-issuers` as **Managed trust list**.
5. Keep **Require all selected credentials** under **Accepted credential combinations**. Choose **Continue**.
**Checkpoint:** the query asks for exactly two claims of the VCT you issued and names `membership-issuers` under **Issuer trust**. The wallet matches on VCT and claim paths, not on the credential configuration ID.
Equivalent DCQL for API users
```json
{
"credentials": [
{
"id": "membership",
"format": "dc+sd-jwt",
"meta": {
"vct_values": ["urn:example:membership:1"]
},
"claims": [{ "path": ["name"] }, { "path": ["member_id"] }],
"trusted_authorities": [{ "type": "etsi_tl", "values": [{ "trustListId": "membership-issuers" }] }]
}
]
}
```
EUDIPLO uses the trust list in two places:
- **In the request to the wallet**, it replaces the reference with `{"type": "aki", "values": [...]}`, the key identifiers of the listed issuer certificates. If a list cannot be loaded or an entry has no key identifier, it also sends the list URL as `etsi_tl`. An outdated list is left out, unless every list is outdated. Wallets that support `trusted_authorities` offer only matching credentials.
- **During verification**, the issuer certificate chain of the presented credential must lead to a listed entity. This check happens no matter what the wallet does.
For other credentials, **Import from Issuer** fills in the types and claim paths from issuer metadata. When the same tenant issues the credential, **Import from Credential Config** does the same from its credential configs. Both replace the query you built by hand; see [Configure a verification](../presentation/configure-verification.md). See [DCQL](../presentation/dcql.md) for claim options and alternatives.
### Step 4: Review the verification settings
On **3. Settings**:
1. Keep **Lifetime of the request** at `300` seconds and **Status List Check Mode** at **Strict**. The cookbook credential has no status entry, so there is nothing to check yet.
2. Under **Request and verification options**, select `Membership verifier access` in **Access Key Chain (optional)**. Do not select the credential signing key.
3. Leave the registration certificate empty unless your wallet requires one.
4. Leave redirect URI, webhook and the other options empty.
5. Choose **Continue**, check that the review lists `name` and `member_id`, then choose **Create Verification Config**.
**Checkpoint:** `membership-check` appears under **Verification Configs**. Only credentials of this type from issuers on `membership-issuers` pass; [Accept only trusted issuers](trusted-issuers.md) shows what happens to one from another issuer.
### Step 5: Generate and approve a request
1. Open `membership-check` and choose the **New Verification** button, or open **Credential Verification → New Verification** and select `membership-check` as **Verification Config**.
2. Choose **Generate Request**.
3. Scan the QR code with the wallet that holds the credential.
4. Check that the wallet offers the membership credential and asks for name and member ID, then approve before the request expires.
**Checkpoint:** the wallet reports that the data was shared. That alone does not prove that verification succeeded; check the session in the next step.
### Step 6: Inspect the verified session
Open **Sessions → All Sessions** and open the new presentation session. Its status chip shows **Completed** and the result card reads **Presentation verified**. The **Presented credentials** card lists the verified claims for query `membership`:
| Claim | Expected value |
| ----------- | -------------- |
| `name` | `Max` |
| `member_id` | `M-001` |
**Checkpoint:** the session is **Completed** and shows both values. A `failed` session is never a success, even if the wallet reported that it shared the data.
You have now issued and verified a credential end to end. In an application, you receive this result by webhook instead of reading the session view; see [Integrate into your backend](integrate-backend.md).
### Troubleshooting
| Symptom | Cause | Fix |
| ------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| **Create Trust List** points at **Signing Key Chain**, which says "No trust list key chains" (the API call answers `409`) | No key chain with usage **Trust List Signing** | Create the key in step 1, choose **Reload key chains** and select it as **Signing Key Chain**. |
| Saving fails with `Credential queries without trusted_authorities` | **Issuer trust** of the query is empty | Add `membership-issuers` as managed trust list (step 3). |
| Wallet finds no matching credential | VCT or claim path differ from chapter 2, the credential expired, or the wallet cannot match the `aki` values | Compare `urn:example:membership:1`, `name` and `member_id` with the credential type; issue a fresh credential. See [Accept only trusted issuers](trusted-issuers.md#troubleshooting) for wallets that cannot match `aki` values. |
| Session `failed` with `trust_chain_not_trusted` | The trust list entity lists a different issuer key chain | Edit the list and select `Membership credential signing` as **Issuer Key Chain**. |
| Reminder about a missing access certificate | No access key chain selected, or its certificate is not active | Select `Membership verifier access` in **Access Key Chain (optional)**. |
| Request expired | Approved after the 300-second lifetime | Generate a new request and approve it right away. |
| Changed claims do not show up | A wallet credential keeps the claims it was issued with | Issue a new credential, then generate a new request. |
Verifier trust, overasking and failed-session errors are covered in [Troubleshooting](../troubleshooting.md#presentation).
### Next steps
- [Integrate into your backend](integrate-backend.md): create offers and requests from your code and receive the results by webhook.
- [Revocable credentials](revocable-credentials.md): revoke the credential and watch verification fail.
- [Accept only trusted issuers](trusted-issuers.md): watch `membership-check` reject a credential from an issuer that is not on the trust list, and use a list published by someone else.
- [All recipes](index.md)
---
## Cookbook: Install and Connect
This is chapter 1 of the **Issue and verify** cookbook. You start EUDIPLO and the Web Client on your computer, make the backend reachable from your phone over HTTPS, and sign in as the root administrator.
### What you will build
A local EUDIPLO deployment created by the CLI: the backend on port `3000` with SQLite, local file storage and database-backed keys, plus the Web Client on port `4200`. An HTTPS tunnel forwards a public address to port `3000`, so the wallet on your phone can reach the backend.
```mermaid
flowchart LR
P[Wallet on phone] -->|HTTPS| T[Tunnel]
T --> B["Backend :3000"]
W["Web Client :4200"] -->|"http://localhost:3000"| B
```
### Before you start
- **Container runtime:** Docker with Docker Compose v2, or Podman with Podman Compose. Start it before you run the commands below.
- **No other EUDIPLO stack on this machine:** the cookbook uses ports `3000` and `4200`. If you ran `eudiplo demo`, stop it with `eudiplo down --instance local`.
- **A wallet on your phone** that supports SD-JWT VC, the pre-authorized code flow and OpenID4VP. See [Choosing a wallet](index.md#choosing-a-wallet).
- **A tunnel tool** such as [ngrok](https://ngrok.com/docs/share-localhost/quickstart), Cloudflare Tunnel or localtunnel. Free plans can change the URL on restart; you need one stable URL for the whole cookbook.
- **Starts from:** nothing.
### Step 1: Install the CLI
```bash
curl -fsSL https://eudiplo.dev/install.sh | bash
eudiplo --version
```
The installer verifies the release checksum and puts the standalone binary in `~/.local/bin`. It does not need Node.js on Linux (x64, arm64) or Apple-silicon Macs. Watch for two cases:
- If `eudiplo` is not found afterwards, add the directory to your shell profile, as the installer prints: `export PATH="$HOME/.local/bin:$PATH"`.
- On Intel Macs and other platforms without a standalone build, the installer falls back to `npm install -g @eudiplo/cli`. This needs Node.js 22.12 or later and npm. On Windows, use `npx @eudiplo/cli` instead of `eudiplo` in every command.
**Checkpoint:** `eudiplo --version` prints a version number.
### Step 2: Get an HTTPS address for the backend
A phone cannot use your computer's `localhost`: it would connect to the phone itself. The wallet must fetch issuer metadata from EUDIPLO and send its responses there. Start a tunnel to local port `3000`, for example:
```bash
ngrok http 3000
```
Keep this terminal open. Below, `https://YOUR-HTTPS-HOST` stands for the forwarding URL, without a trailing slash. Use this exact address from now on: issued credentials and offers contain URLs that point back to it. If the address changes later, update the deployment as described under [Troubleshooting](#troubleshooting) and issue a fresh credential.
**Checkpoint:** the tunnel shows an HTTPS forwarding URL. Requests to it return a gateway error until EUDIPLO runs.
### Step 3: Initialize and start EUDIPLO
In a second terminal, create an empty project directory and initialize it:
```bash
mkdir eudiplo-cookbook
cd eudiplo-cookbook
eudiplo init . --instance cookbook --preset minimal --no-demo-tenant --client \
--public-url https://YOUR-HTTPS-HOST --yes --start
```
This writes `eudiplo.compose.yaml`, `.eudiplo.env` and `config/kms.json`, registers the deployment as CLI instance `cookbook`, and starts it. Instead of the predictable demo credentials, it generates a root client secret and a `MASTER_SECRET`. Keep `.eudiplo.env` private. The SQLite database is stored in `config/`.
The cookbook passes `--instance cookbook` to every CLI command, so the commands reach this deployment even if another instance is your CLI default.
**Checkpoint:** the command ends without errors, and `eudiplo ps --instance cookbook` lists the services `eudiplo` and `eudiplo-client` as running.
### Step 4: Check both network paths
```bash
eudiplo status --instance cookbook
curl http://localhost:3000/health
curl https://YOUR-HTTPS-HOST/health
```
`eudiplo status` checks the public URL you registered. Both `curl` calls return JSON with `"status":"ok"`.
Then open `https://YOUR-HTTPS-HOST/health` in the **browser on your phone**. It must show the same JSON, without a certificate warning, tunnel login or confirmation page. Some free tunnels show such a page on the first visit; the wallet cannot click through it.
**Checkpoint:** the health response appears on both the computer and the phone. Do not continue to QR codes until it does.
### Step 5: Sign in to the Web Client
1. Open [http://localhost:4200](http://localhost:4200), or run `eudiplo open --instance cookbook`.
2. Check that **EUDIPLO Instance** is `http://localhost:3000`. Projects created with an older CLI prefill `http://eudiplo:3000`, the backend's address inside the Compose network, which your browser cannot reach.
3. Read the root credentials from the project directory: `grep AUTH_CLIENT .eudiplo.env`.
4. On the **Client ID and Secret** tab, enter `AUTH_CLIENT_ID` (by default `root`) as **Client ID** and `AUTH_CLIENT_SECRET` as **Client Secret**.
5. Choose **Login with Client Credentials**.
The Web Client is for administration from your computer only. The wallet never talks to it; it uses the `PUBLIC_URL` of the backend. The Web Client reads the backend at `http://localhost:3000`, but requests its tokens from the token endpoint that `PUBLIC_URL` names, `https://YOUR-HTTPS-HOST/api/oauth2/token`. Keep the tunnel running while you are signed in.
**Checkpoint:** the dashboard opens, and the navigation shows **Administration → Tenants**.
### Which certificates does your wallet need?
:::tip[Decide before chapter 2]
The next chapter creates a signing key for credentials and an access certificate for presentation requests. Some wallet test setups (for example Paradym) accept self-signed certificates. The EU Reference Implementation and the German ecosystem need certificates from their registrar.
Check your wallet's row in [Wallet and registrar requirements](../trust/wallet-registrars.md) and have those certificates ready.
:::
### Troubleshooting
| Symptom | Cause | Fix |
| ----------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `init` fails with "port is already allocated" | The demo or another stack uses port `3000` or `4200` | Stop the other stack (`eudiplo down --instance local` for the demo), then run `eudiplo up --instance cookbook`. |
| Local health works, phone health fails | Tunnel stopped, wrong target port or an interstitial page | Restart the tunnel to port `3000`; make sure the phone gets the JSON directly. |
| Web Client login reports a connection error | The tunnel is down; the login requests its token at `https://YOUR-HTTPS-HOST` | Restart the tunnel to port `3000` and sign in again. |
| Offers or metadata contain `localhost` or an old tunnel URL | `PUBLIC_URL` in `.eudiplo.env` is wrong | Edit `PUBLIC_URL`, run `eudiplo up --instance cookbook` (Compose recreates the backend with the new environment), run `eudiplo instance update cookbook --url https://YOUR-HTTPS-HOST` (the CLI commands use it), sign in to the Web Client again (it keeps the old token endpoint until then), then create a new offer. |
For login errors, `eudiplo: command not found` and other common problems, see [Troubleshooting](../troubleshooting.md).
### Next steps
- Keep the deployment and the tunnel running. To stop it later, run `eudiplo down --instance cookbook`.
- Continue with chapter 2: [Issue a membership credential](first-credential.md).
---
## Cookbooks
Each cookbook ends in a working result and has a checkpoint after every step. Start with **Issue and verify**: the other recipes build on the instance, tenant and wallet credential it creates.
### Recipes
| Recipe | Outcome | Prerequisites | Starts from | Time |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | ---------------------------------- | ---------- |
| **Issue and verify**: [1. Install and connect](foundation.md), [2. Issue](first-credential.md), [3. Verify](first-presentation.md) | A membership credential in your phone's wallet, and a verified presentation of its claims from an issuer on your trust list | Docker or Podman, a wallet app on a phone, an HTTPS tunnel | Nothing | 70 min |
| [Integrate into your backend](integrate-backend.md) | Your backend creates offers and requests through the API and receives the results by webhook | `curl`, `jq`, Node.js 22+ | Issue and verify | 45 min |
| [Issue after login](issue-after-login.md) | The wallet user signs in at Keycloak; the credential carries claims from your attribute provider | A Keycloak realm reachable over HTTPS, Node.js 22+ | Issue and verify | 60 min |
| [Sign in with a wallet](sign-in-with-wallet.md) | Members sign in to a Keycloak realm with the membership credential; Keycloak recognizes them on every sign-in | A Keycloak 26 realm you administer, `curl` | Issue and verify | 30 min |
| [Revocable credentials](revocable-credentials.md) | You revoke or suspend one issued credential and the next presentation fails | `curl` and `jq` | Issue and verify | 30 min |
| [Accept only trusted issuers](trusted-issuers.md) | A credential from an issuer outside your trust list is rejected, and verification works with a list published by someone else | `curl` and `jq` | Issue and verify | 25 min |
| [Certificates from the EUDI Hub](eudi-hub-certificates.md) | Requests to `membership-check` are signed with an access certificate from the EUDI Hub sandbox and carry its registration certificate; the issuer metadata publishes one for the issuer | An organization in the EUDI Hub portal, `curl` and `jq` | Issue and verify | 30 min |
| [Production on one VM](production-vm.md) | EUDIPLO on a Linux server behind a TLS reverse proxy, with backups and a strict health check | A VM with a DNS name, ports 80 and 443 open | Nothing | 60 min |
| [Manage an instance with the CLI](manage-with-cli.md) | A tenant kept as files in Git, validated in CI and applied on every start; edits in the Web Client are locked | Docker or Podman, `jq`, `openssl`, Git | Install and connect, or nothing | 30 min |
For a single task outside these recipes, go to the guides: [Issuance](../issuance/index.md), [Presentation](../presentation/index.md), [Trust](../trust/index.md) and [Operate](../operate/index.md). If a step fails, see [Troubleshooting](../troubleshooting.md).
### Shared values
All recipes use these values. Keep them unchanged so each recipe can reuse what the previous one created.
| Value | Used for |
| -------------------------- | --------------------------------------------------------------------- |
| `membership-demo` | Tenant ID |
| `membership` | Credential configuration ID |
| `urn:example:membership:1` | SD-JWT credential type (VCT), used for both issuance and verification |
| `name`, `member_id` | Claim paths |
| `Max`, `M-001` | Synthetic claim values |
| `membership-issuers` | Trust list ID of the issuers that `membership-check` accepts |
| `membership-check` | Presentation configuration ID |
| `membership` | Credential query ID inside the presentation request |
| `cookbook` | CLI instance name of the local deployment |
| `membership-files` | Tenant ID of the tenant kept as files (CLI recipe) |
The credential configuration ID names what EUDIPLO issues. The VCT is the credential type the wallet must match. The presentation configuration ID names the reusable verification request.
### Choosing a wallet
Use a wallet that supports SD-JWT VC, the pre-authorized code flow and OpenID4VP. The [wallet compatibility record](../reference/wallet-compatibility.md) lists tested wallets and their limitations. Whether a wallet accepts self-signed certificates depends on the wallet and its test environment; [Wallet and registrar requirements](../trust/wallet-registrars.md) helps you choose.
:::note[Learning setup]
The recipes use one tenant as both issuer and verifier, test certificates and synthetic data. Before you handle real credentials, follow [Production on one VM](production-vm.md) and the [Operate](../operate/index.md) guides.
:::
---
## Cookbook: Integrate EUDIPLO into Your Backend
Your backend takes over from the Web Client: it gets a token, creates presentation requests and credential offers, and receives the results by webhook. You make every call once with `curl`, then with `@eudiplo/sdk-core`.
### What you will build
A least-privilege API client `membership-backend`, a small webhook receiver, and the calls that verify and issue the membership credential from the first recipe. You also handle the same-device redirect and failed sessions.
```mermaid
sequenceDiagram
participant B as Your backend
participant E as EUDIPLO
participant W as Wallet
B->>E: POST /api/oauth2/token
B->>E: POST /api/verifier/offer
E-->>B: uri, crossDeviceUri, session
B->>W: QR code or link
W->>E: Presentation
E->>B: Webhook with status and outcome
W-->>B: Same device only: redirect with response_code
```
### Before you start
- **Starts from:** [Issue and verify](index.md). You need tenant `membership-demo` with `membership` and `membership-check`, the wallet with the membership credential, and the secret of `membership-demo-admin` from [chapter 2](first-credential.md).
- `curl`, `jq` and Node.js 22 or later. To show QR codes in the terminal, install `qrencode`, or use any other QR tool that runs locally.
- A token of `membership-demo-admin` for the setup calls. `read -rs` waits for you to paste the secret without showing it:
```bash
export EUDIPLO=http://localhost:3000
read -rs ADMIN_SECRET
ADMIN_TOKEN=$(curl -s -X POST "$EUDIPLO/api/oauth2/token" \
-d grant_type=client_credentials -d client_id=membership-demo-admin \
--data-urlencode client_secret="$ADMIN_SECRET" | jq -r .access_token)
```
The token endpoint accepts the client credentials in the form body or as HTTP Basic authentication. Tokens are valid for 24 hours (`expires_in: 86400`); request a new one before then.
### Step 1: Create a least-privilege API client
The backend only creates offers and requests, so it gets only `issuance:offer` and `presentation:request`, limited to the two configurations of this recipe. A backend that also revokes or suspends credentials needs `credentials:status` as well:
```bash
curl -s -X POST "$EUDIPLO/api/client" \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{
"clientId": "membership-backend",
"description": "Backend integration from the cookbook",
"roles": ["issuance:offer", "presentation:request"],
"allowedIssuanceConfigs": ["membership"],
"allowedPresentationConfigs": ["membership-check"]
}' | jq
```
The response contains `clientSecret`, shown only this once. Store it in your secret manager and in the shell:
```bash
read -rs BACKEND_SECRET
TOKEN=$(curl -s -X POST "$EUDIPLO/api/oauth2/token" \
-d grant_type=client_credentials -d client_id=membership-backend \
--data-urlencode client_secret="$BACKEND_SECRET" | jq -r .access_token)
```
**Checkpoint:** the allow-list works. A request for another configuration is refused:
```bash
curl -s -o /dev/null -w '%{http_code}\n' -X POST "$EUDIPLO/api/verifier/offer" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "response_type": "uri", "requestId": "something-else" }'
```
It prints `403`. All roles are described in the [roles reference](../reference/roles.md).
### Step 2: Run a webhook receiver
Save as `webhook-receiver.mjs`:
```js
import { createServer } from 'node:http';
createServer((req, res) => {
if (req.headers['x-api-key'] !== process.env.WEBHOOK_API_KEY) {
res.writeHead(401).end();
return;
}
let body = '';
req.on('data', (chunk) => (body += chunk));
req.on('end', () => {
const event = JSON.parse(body);
if (event.notification) {
console.log('issuance', event.session, event.notification.event);
} else if (event.status === 'completed') {
console.log('verified', event.session, JSON.stringify(event.credentials));
} else {
console.log('failed', event.session, event.outcome?.error, event.outcome?.message);
}
res.writeHead(200, { 'content-type': 'application/json' }).end('{}');
});
}).listen(8787, '0.0.0.0');
```
Start it with `WEBHOOK_API_KEY=change-me node webhook-receiver.mjs`.
EUDIPLO only calls public HTTPS URLs by default. For this local exercise, allow HTTP and private addresses: append these lines to `.eudiplo.env` in the cookbook directory, then run `eudiplo up --instance cookbook`. Never set them in production.
```env
OUTBOUND_URL_ALLOW_HTTP=true
OUTBOUND_URL_ALLOW_PRIVATE_NETWORK=true
```
Register the receiver and attach it to `membership-check`. Inside the container, `host.docker.internal` reaches your computer with Docker Desktop; use `host.containers.internal` with Podman, or your computer's LAN IP address with Docker Engine on Linux.
```bash
curl -s -X POST "$EUDIPLO/api/issuer/webhook-endpoints" \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{
"id": "membership-backend",
"name": "Membership backend",
"url": "http://host.docker.internal:8787/eudiplo",
"auth": { "type": "apiKey", "config": { "headerName": "x-api-key", "value": "change-me" } }
}' | jq
curl -s -X PATCH "$EUDIPLO/api/verifier/config/membership-check" \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{ "webhookEndpointId": "membership-backend" }' | jq .webhookEndpointId
```
**Checkpoint:** the second call prints `"membership-backend"`. The full payloads are in [Webhooks](../reference/webhooks.md).
### Step 3: Request a presentation
```bash
curl -s -X POST "$EUDIPLO/api/verifier/offer" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "response_type": "uri", "requestId": "membership-check" }' | tee request.json | jq
qrencode -t ansiutf8 "$(jq -r .crossDeviceUri request.json)"
SESSION=$(jq -r .session request.json)
```
The response has `uri` (same device, with redirect), `crossDeviceUri` (QR code on another screen) and `session`. Scan the QR code with the wallet and approve.
**Checkpoint:** the receiver prints `verified`, the session ID and the claims `"name":"Max"` and `"member_id":"M-001"`.
Webhooks are delivered once and not retried. Read the result from the session at any time, or stream status changes with server-sent events; the stream ends after a final status:
```bash
curl -s "$EUDIPLO/api/session/$SESSION" -H "Authorization: Bearer $TOKEN" \
| jq '{status, failureCode, outcome}'
curl -N "$EUDIPLO/api/session/$SESSION/events" -H "Authorization: Bearer $TOKEN"
```
### Step 4: Issue a credential
```bash
curl -s -X POST "$EUDIPLO/api/issuer/offer" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"response_type": "uri",
"flow": "pre_authorized_code",
"credentialConfigurationIds": ["membership"],
"credentialClaims": {
"membership": { "type": "inline", "claims": { "name": "Max", "member_id": "M-001" } }
},
"webhookEndpointId": "membership-backend",
"offerLifetimeSeconds": 600
}' | tee offer.json | jq
qrencode -t ansiutf8 "$(jq -r .uri offer.json)"
```
EUDIPLO validates the claims against the credential configuration and returns `uri` and `session`. Scan the QR code with the wallet and accept the credential. Without `offerLifetimeSeconds` or a lifetime in the issuer settings, an offer does not expire.
**Checkpoint:** the session status is `fetched` once the wallet has the credential. If the wallet sends a notification, the receiver prints `issuance credential_accepted` and the status becomes `completed`.
### Step 5: Check the same-device redirect
When the wallet runs on the device that started the flow, send the user back to your application. `{sessionId}` is replaced with the session ID:
```bash
curl -s -X POST "$EUDIPLO/api/verifier/offer" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"response_type": "uri",
"requestId": "membership-check",
"redirectUri": "https://app.example.com/membership/done?session={sessionId}"
}' | tee same-device.json | jq
qrencode -t ansiutf8 "$(jq -r .uri same-device.json)"
```
Scan this `uri` (not `crossDeviceUri`) and approve. The wallet then opens `https://app.example.com/membership/done?session=&response_code=` in the phone's browser. The page does not need to exist for this test; read the parameters from the address bar.
Before your application trusts the result in that browser, it must compare `response_code` with the session's `responseCode`:
```bash
curl -s "$EUDIPLO/api/session/" -H "Authorization: Bearer $TOKEN" | jq '{status, responseCode}'
```
**Checkpoint:** `status` is `completed` and `responseCode` equals the `response_code` from the address bar. Only then does that browser session belong to the person who presented the credential. A webhook can also return `{"redirectUri": "..."}` to send the user to a different page.
### Step 6: Handle failed and expired sessions
1. Create another presentation request and **decline** it in the wallet.
2. The receiver prints `failed access_denied Wallet error: access_denied` (some wallets add a description after the code). The session has `status: failed` and `failureCode: access_denied`, and a same-device redirect carries `error=access_denied` instead of `response_code`.
3. Create one more request and let it sit for more than 300 seconds. When the wallet tries it, it gets "The session has expired".
Failure webhooks never contain credentials. A periodic cleanup job writes the `expired` status later and sends no webhook, so treat a session whose `expiresAt` has passed as expired. Failure codes are listed in [Session outcome](../reference/session-outcome.md#failure-codes).
**Checkpoint:** your backend marks both sessions as unsuccessful and never reads claims from them.
### Step 7: Do the same with the SDK
```bash
npm install @eudiplo/sdk-core
```
Save as `verify.mjs` and run it with `EUDIPLO=$EUDIPLO BACKEND_SECRET=$BACKEND_SECRET node verify.mjs`:
```js
import { EudiploClient } from '@eudiplo/sdk-core';
const client = new EudiploClient({
baseUrl: process.env.EUDIPLO,
clientId: 'membership-backend',
clientSecret: process.env.BACKEND_SECRET,
});
const request = await client.createPresentationRequest({ configId: 'membership-check' });
console.log('Show as QR code:', request.crossDeviceUri);
try {
const session = await client.waitForSession(request.sessionId);
console.log(JSON.stringify(session.credentials));
} catch {
const session = await client.getSession(request.sessionId);
console.log('not verified:', session.status, session.failureCode ?? session.errorReason);
}
const offer = await client.createIssuanceOffer({
credentialConfigurationIds: ['membership'],
claims: { membership: { name: 'Max', member_id: 'M-001' } },
});
console.log('Offer:', offer.uri, offer.sessionId);
```
The client fetches and renews its token. `waitForSession` polls the session every second for up to five minutes and throws on `failed` or `expired`. For issuance it waits for `completed`, which needs a wallet notification, so check for `fetched` with `getSession` instead. The SDK has no options for `webhookEndpointId` or `offerLifetimeSeconds`; use the REST call for those.
**Checkpoint:** the script prints the verified claims after you approve, and `not verified: failed access_denied` after you decline.
### Troubleshooting
| Symptom | Cause | Fix |
| --------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `403` "Client is not authorized to use ..." | The configuration is not in the client's allow-list | Add it to `allowedIssuanceConfigs` or `allowedPresentationConfigs`, or use the listed one. |
| `400` that names an unrecognized key | Request bodies are strict; a field name is misspelled | Compare with the examples and the [API reference](../reference/api.md). |
| Creating the webhook endpoint fails | The outbound URL policy rejects the URL, or the host does not resolve in the container | Set the two `OUTBOUND_URL_*` variables, run `eudiplo up --instance cookbook`, and check the host name. |
| The receiver logs nothing | Webhook not attached, or the receiver is not reachable from the container | Check `webhookEndpointId` of `membership-check` and the backend log. |
| No `response_code` in the redirect | The wallet declined, or you scanned `crossDeviceUri`, which has no redirect | Use `uri` for same-device flows; handle the `error` parameter. |
General problems are covered in [Troubleshooting](../troubleshooting.md).
### Next steps
- [Receive results](../presentation/receive-results.md): webhooks, server-sent events and polling in detail.
- [Webhooks](../reference/webhooks.md): every payload field.
- [Credential offers](../issuance/credential-offers.md) and [Presentation requests](../presentation/requests.md): all request options, including the Digital Credentials API.
---
## Cookbook: Issue a Credential after Login
The person receiving the credential signs in at Keycloak first. EUDIPLO then asks your attribute provider for the claims of exactly that person. Use this when the claims live in your own systems and the user must prove who they are before they get a credential.
### What you will build
EUDIPLO acts as a **chained authorization server**: the wallet talks OAuth to EUDIPLO, and EUDIPLO sends the user's browser to Keycloak to sign in. When the wallet requests the credential, EUDIPLO calls your attribute provider with the Keycloak identity, and the provider returns `name` and `member_id`.
```mermaid
---
config:
sequence:
wrap: true
width: 120
actorMargin: 30
---
sequenceDiagram
participant W as Wallet
participant E as EUDIPLO (chained AS)
participant K as Keycloak
participant A as Attribute provider
W->>E: Authorization request (PAR, PKCE S256)
E->>K: Redirect the browser to the Keycloak login
K->>E: Callback with code
E->>K: Exchange code for tokens
E->>W: Authorization code, then access token
W->>E: Credential request
E->>A: POST session, credential_configuration_id, identity
A-->>E: { "membership": { "name": ..., "member_id": ... } }
E->>W: Membership credential
```
### Before you start
- **Starts from:** [Issue and verify](index.md). You need tenant `membership-demo` with the credential configuration `membership`, the HTTPS tunnel to the backend, and a sign-in as `membership-demo-admin`.
- A wallet that supports the authorization code flow with pushed authorization requests (PAR), PKCE `S256` and DPoP.
- Keycloak 26 or later, reachable over HTTPS **under the same URL** from the phone's browser and from the EUDIPLO backend. Below, `https://YOUR-KEYCLOAK-HOST` stands for that URL. For a test, run Keycloak in a container behind a second HTTPS tunnel to port `8080`.
- Node.js 22 or later for the attribute provider, and `curl` and `jq` for the checks.
### Step 1: Start Keycloak
Skip this step if you already have a Keycloak realm you can use. Otherwise, start a development instance:
```bash
docker run --name keycloak -p 8080:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change-me \
quay.io/keycloak/keycloak:latest start-dev \
--hostname https://YOUR-KEYCLOAK-HOST --proxy-headers xforwarded
```
`--hostname` makes Keycloak put the public URL into its metadata, so the phone and EUDIPLO see the same issuer.
**Checkpoint:** `curl -s https://YOUR-KEYCLOAK-HOST/realms/master/.well-known/openid-configuration | jq .issuer` prints `"https://YOUR-KEYCLOAK-HOST/realms/master"`.
### Step 2: Create the realm, client and user
In the Keycloak admin console at `https://YOUR-KEYCLOAK-HOST/admin`:
1. Create a realm `membership`.
2. Create an OpenID Connect client with client ID `eudiplo-chained-as`. Turn **Client authentication** on, keep **Standard flow** on, and set the valid redirect URI to exactly:
```text
https://YOUR-HTTPS-HOST/issuers/membership-demo/chained-as/callback
```
3. Copy the client secret from the client's **Credentials** tab.
4. Create a user with username `max` and first name `Max`, and set a non-temporary password.
**Checkpoint:** `curl -s https://YOUR-KEYCLOAK-HOST/realms/membership/.well-known/openid-configuration | jq .issuer` prints `"https://YOUR-KEYCLOAK-HOST/realms/membership"`.
### Step 3: Add the chained authorization server
In the Web Client, open **Credential Issuance → Issuer Settings**, choose **Edit** and go to the **Wallet access** tab. Under **Authorization Servers**, choose **Add Authorization Server** and enter:
| Field | Value |
| ------------------- | ---------------------------------------------- |
| ID | `keycloak` |
| Type | **Chained** |
| Upstream Issuer URL | `https://YOUR-KEYCLOAK-HOST/realms/membership` |
| Client ID | `eudiplo-chained-as` |
| Client Secret | the secret from step 2 |
Keep the built-in server for the pre-authorized offers of the other recipes, then save the settings.
EUDIPLO requests the scopes `openid`, `profile` and `email` from Keycloak, uses PKCE `S256` towards Keycloak, and sends the client secret in the token request body. Towards the wallet it requires PAR and PKCE `S256`. If the wallet sends a DPoP proof, the key is bound to the authorization and must be used again at the token endpoint. Refresh tokens are on by default and valid for 30 days. The field reference is in [Authorization servers](../issuance/authorization-servers.md).
Equivalent API call
`POST /api/issuer/config` replaces the whole `authorizationServers` list, so include the built-in server:
```json
{
"authorizationServers": [
{ "type": "built-in", "id": "issuer-built-in" },
{
"type": "chained",
"id": "keycloak",
"upstream": {
"issuer": "https://YOUR-KEYCLOAK-HOST/realms/membership",
"clientId": "eudiplo-chained-as",
"clientSecret": "",
"scopes": ["openid", "profile", "email"]
}
}
]
}
```
Use the ID of your existing built-in entry; `GET /api/issuer/config` shows it.
**Checkpoint:** the authorization server metadata is published:
```bash
curl -s https://YOUR-HTTPS-HOST/.well-known/oauth-authorization-server/issuers/membership-demo/chained-as \
| jq '{issuer, pushed_authorization_request_endpoint, code_challenge_methods_supported}'
```
`issuer` is `https://YOUR-HTTPS-HOST/issuers/membership-demo/chained-as` and the only code challenge method is `S256`.
### Step 4: Run the attribute provider
Save as `attribute-provider.mjs`. It looks the member up by the Keycloak username:
```js
import { createServer } from 'node:http';
const members = { max: { name: 'Max', member_id: 'M-001' } };
createServer((req, res) => {
if (req.headers['x-api-key'] !== process.env.PROVIDER_API_KEY) {
res.writeHead(401).end();
return;
}
let body = '';
req.on('data', (chunk) => (body += chunk));
req.on('end', () => {
const { credential_configuration_id, identity } = JSON.parse(body);
const username = identity?.token_claims?.preferred_username;
console.log('claims requested for', username, 'sub', identity?.sub);
const member = members[username];
if (!member) {
res.writeHead(404).end();
return;
}
res.writeHead(200, { 'content-type': 'application/json' })
.end(JSON.stringify({ [credential_configuration_id]: member }));
});
}).listen(8788, '0.0.0.0');
```
Start it with `PROVIDER_API_KEY=change-me node attribute-provider.mjs`. EUDIPLO sends `session`, `credential_configuration_id` and `identity` (`iss`, `sub` and the merged Keycloak ID and access token claims in `token_claims`). It expects the claims under the credential configuration ID. The call is made once, without retries; the full contract is in [Attribute provider API](../reference/attribute-provider-api.md).
The provider runs on plain HTTP on your computer, which EUDIPLO's outbound URL policy blocks by default. For this exercise, add `OUTBOUND_URL_ALLOW_HTTP=true` and `OUTBOUND_URL_ALLOW_PRIVATE_NETWORK=true` to `.eudiplo.env`, then run `eudiplo up --instance cookbook`. Never set them in production.
Then open **Credential Issuance → Attribute Providers**, choose **Create attribute provider** and enter ID `membership-directory`, name `Membership directory`, URL `http://host.docker.internal:8788/claims`, **Auth Type** **API Key**, **Header Name** `x-api-key` and **Header Value** `change-me`. Choose **Create**. With Podman, use `host.containers.internal`; with Docker Engine on Linux, use your computer's LAN IP address.
**Checkpoint:** a test call returns the claims:
```bash
curl -s -X POST http://localhost:8788/claims -H 'x-api-key: change-me' -H 'content-type: application/json' \
-d '{"session":"test","credential_configuration_id":"membership","identity":{"iss":"test","sub":"test","token_claims":{"preferred_username":"max"}}}'
```
It prints `{"membership":{"name":"Max","member_id":"M-001"}}`.
### Step 5: Send an authorization-code offer
1. Open **Credential Issuance → New Issuance**.
2. In **Select Flow**, choose **Authorization Code (External AS)** and **Next**.
3. Select `membership` under **Credential Config IDs** and continue.
4. Select `keycloak` as **Authorization Server**. Under **Claims Attribute Providers**, select `membership-directory` for `membership`.
5. Choose **Generate Offer** and scan the QR code with the wallet.
6. The wallet opens the Keycloak login. Sign in as `max`, then accept the credential.
The same offer through the API is `POST /api/issuer/offer` with:
```json
{
"response_type": "uri",
"flow": "authorization_code",
"credentialConfigurationIds": ["membership"],
"authorization_server": "keycloak",
"credentialClaims": {
"membership": { "type": "attributeProvider", "attributeProviderId": "membership-directory" }
}
}
```
**Checkpoint:** the attribute provider prints `claims requested for max` with Max's Keycloak subject, and the wallet stores a `Membership` credential with `Max` and `M-001`. Verify it with `membership-check` as in [chapter 3](first-presentation.md).
### Troubleshooting
| Symptom | Cause | Fix |
| --------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Keycloak shows "Invalid parameter: redirect_uri" | The redirect URI in Keycloak differs from the callback | Use exactly `https://YOUR-HTTPS-HOST/issuers/membership-demo/chained-as/callback`, including `/issuers/`. |
| The wallet cannot open the Keycloak login | Keycloak's metadata contains `localhost` or another internal address | Start Keycloak with `--hostname` set to the public HTTPS URL. |
| The wallet fails at the authorization request | The wallet does not use PAR, or sends no `S256` code challenge | Use a wallet that supports PAR and PKCE `S256`. |
| `invalid_dpop_proof` at the token endpoint | The wallet signs the token request with a different DPoP key | Use a wallet with consistent DPoP support. |
| Credential request fails, attribute provider logs nothing | The outbound URL policy blocks the provider, or the host is unreachable | Set the two `OUTBOUND_URL_*` variables, run `eudiplo up --instance cookbook`, and check the provider URL. |
| Attribute provider logs a different username or none | The ID token lacks `preferred_username` | Check the client scopes in Keycloak; `profile` must be assigned to `eudiplo-chained-as`. |
General problems are covered in [Troubleshooting](../troubleshooting.md).
### Next steps
- [Attribute providers](../issuance/attribute-provider.md): authentication, deferred issuance and claim validation.
- [Authorization servers](../issuance/authorization-servers.md): external authorization servers, presentation-based login and token settings.
- [Keycloak SSO](../operate/keycloak.md): use Keycloak for EUDIPLO's own administrators.
---
## Cookbook: Manage an Instance with the CLI
You manage a running EUDIPLO instance from the command line: you keep a tenant's configuration as files next to the deployment, check them before every start, apply them with a restart and gate changes in CI. The result is a tenant whose configuration lives in Git and cannot be changed behind your back in the Web Client.
### What you will build
A tenant `membership-files`, defined by five JSON files in the `config/` folder of your Compose project: the tenant settings, an admin client, a signing key chain, the issuer settings and the `membership` credential type from the [Issue and verify](first-credential.md) recipe. The backend imports the folder on every start, so a file change and a restart update the tenant. Secrets and private keys stay out of the files.
### Before you start
- **Starts from:** [chapter 1, Install and connect](foundation.md). The CLI instance `cookbook` runs, and you work in its project directory `eudiplo-cookbook`. Keep the tunnel running: the CLI reaches the instance at its public URL. Chapters 2 and 3 are not needed; this recipe creates its own tenant.
- **Without chapter 1** (no wallet or tunnel needed), [install the CLI](../operate/cli.md#install), start Docker or Podman, and create the instance on `http://localhost:3000`:
```bash
eudiplo init eudiplo-cookbook --instance cookbook --preset minimal \
--no-demo-tenant --client --yes --start
cd eudiplo-cookbook
```
- `jq`, `openssl` and Git. A GitHub repository is optional for step 6.
### Step 1: Look at the instance
```bash
eudiplo instance show cookbook
eudiplo status --instance cookbook
eudiplo ps --instance cookbook
```
`instance show` prints what the CLI knows about the deployment: target `compose`, the API URL, the project directory and the env file `.eudiplo.env`. Instances and their targets are explained in the [CLI guide](../operate/cli.md#instances).
**Checkpoint:** `eudiplo status` prints `PASS` for the health endpoint, and `eudiplo ps` lists `eudiplo` and `eudiplo-client` as running.
### Step 2: Create the tenant folder
```bash
eudiplo config tenant create membership-files --instance cookbook --name "Membership Files"
eudiplo config editor setup
```
The first command creates `config/membership-files/` with `info.json` (the tenant settings) and an empty folder for each resource type. The backend reads `config/` as its `CONFIG_FOLDER` and treats every subfolder with an `info.json` as a tenant. `config editor setup` copies the JSON schemas of the installed CLI to `.vscode/eudiplo-schemas/` and associates them with the files under `config/`, so VS Code completes and checks them while you type.
**Checkpoint:** `eudiplo config tenant list --instance cookbook` lists `membership-files (Membership Files)`.
### Step 3: Describe the tenant in files
Create these four files in `config/membership-files/`.
`clients/membership-files-admin.json`, the client you administer the tenant with:
```json
{
"$schema": "https://eudiplo.dev/schemas/v2/ClientConfigFile.schema.json",
"metadata": { "generation": 1 },
"spec": {
"clientId": "membership-files-admin",
"description": "Administers the tenant from the CLI",
"secret": "${MEMBERSHIP_FILES_ADMIN_SECRET}",
"roles": ["tenant:admin", "issuance:manage"]
}
}
```
`tenant:admin` lets the client read the configuration operations and export the tenant. `issuance:manage` opens the issuer screens of the Web Client and lets `doctor` read the KMS provider health. The secret is a placeholder that the backend fills from its environment.
`key-chains/membership-signing.json`, the key that signs the credentials:
```json
{
"$schema": "https://eudiplo.dev/schemas/v4/KeyChainConfigFile.schema.json",
"metadata": { "generation": 1 },
"spec": {
"id": "membership-signing",
"description": "Membership credential signing",
"usageType": "attestation",
"keySource": { "type": "regenerate", "keyChainType": "internalChain" }
}
}
```
`regenerate` makes EUDIPLO create the key material on the first import, so the private key never appears in a file and every instance you apply the folder to gets a key of its own. Restarts with the unchanged file keep the key. A change to this file, even to `description`, creates a new key on the next start ([details](../reference/config-bundle-format.md#import-modes-and-plan-actions)).
`issuance/issuance.json`, the issuer settings:
```json
{
"$schema": "https://eudiplo.dev/schemas/v7/IssuanceConfigFile.schema.json",
"metadata": { "generation": 1 },
"spec": {
"authorizationServers": [{ "id": "issuer-built-in", "type": "built-in" }],
"batchSize": 1,
"display": [{ "locale": "en", "name": "Membership Files" }]
}
}
```
`issuance/credentials/membership.json`, the credential type with the VCT and claims of the other recipes:
```json
{
"$schema": "https://eudiplo.dev/schemas/v4/CredentialConfigFile.schema.json",
"metadata": { "generation": 1 },
"spec": {
"id": "membership",
"description": "Membership credential",
"config": {
"format": "dc+sd-jwt",
"display": [{ "name": "Membership", "locale": "en" }]
},
"vct": "urn:example:membership:1",
"keyBinding": true,
"keyChainId": "membership-signing",
"fields": [
{ "path": ["name"], "type": "string", "mandatory": true, "disclosable": true },
{ "path": ["member_id"], "type": "string", "mandatory": true, "disclosable": true }
]
}
}
```
Then generate the client secret, store it in the env file that the backend reads, and validate the folder:
```bash
export MEMBERSHIP_FILES_ADMIN_SECRET="$(openssl rand -hex 32)"
echo "MEMBERSHIP_FILES_ADMIN_SECRET=$MEMBERSHIP_FILES_ADMIN_SECRET" >> .eudiplo.env
eudiplo config tenant validate membership-files --instance cookbook
```
The validator checks every file against its schema and resolves `${…}` placeholders from your shell environment, as the backend does from its own. Keep this shell open: the next steps use the variable.
**Checkpoint:** the validation prints `PASS membership-files`, `Validated 1 tenant(s) and 5 configuration file(s).` and `No errors found.`
### Step 4: Import the folder on every start
`eudiplo init` sets `CONFIG_IMPORT_MODE=create`, which only creates missing resources and never applies a later change to a file. In `.eudiplo.env`, change that line to:
```env
CONFIG_IMPORT_MODE=upsert
```
Then recreate the backend, so it reads the new mode and the new secret:
```bash
eudiplo up --instance cookbook
curl -s http://localhost:3000/.well-known/openid-credential-issuer/issuers/membership-files \
| jq '.credential_configurations_supported | keys'
```
The import modes are compared in [Configuration as code](../operate/configuration-as-code.md#provision-tenants-from-a-folder). Each import is recorded as a configuration operation. Read the latest one with the new client:
```bash
export EUDIPLO_CLIENT_ID=membership-files-admin
export EUDIPLO_CLIENT_SECRET="$MEMBERSHIP_FILES_ADMIN_SECRET"
export EUDIPLO_TOKEN="$(curl -s -X POST http://localhost:3000/api/oauth2/token \
-d grant_type=client_credentials -d client_id="$EUDIPLO_CLIENT_ID" \
--data-urlencode client_secret="$EUDIPLO_CLIENT_SECRET" | jq -r .access_token)"
eudiplo config operations --instance cookbook | jq '.[0] | {mode, status}'
```
`doctor` requests its own token with `EUDIPLO_CLIENT_ID` and `EUDIPLO_CLIENT_SECRET`; `config operations`, `export`, `plan` and `import` take a ready token from `EUDIPLO_TOKEN`. When they answer `401`, request a new token.
**Checkpoint:** the metadata lists `["membership"]`, and the latest operation shows `"mode": "upsert"` and `"status": "completed"`.
### Step 5: Change the tenant through its files
Sign in to the Web Client (`eudiplo open --instance cookbook`) with **Client ID** `membership-files-admin` and the secret from `echo "$MEMBERSHIP_FILES_ADMIN_SECRET"`. Open **Credential Issuance → Credential Configs → membership**: the page shows **Managed by a configuration bundle**, and editing and deleting are disabled. The API refuses such changes with `409 Conflict`, so a manual edit cannot be overwritten silently by the next import.
Change the file instead. In `issuance/credentials/membership.json`, rename the display from `Membership` to `Membership card`, then:
```bash
eudiplo config tenant validate membership-files --instance cookbook
eudiplo restart --instance cookbook --service eudiplo
curl -s http://localhost:3000/.well-known/openid-credential-issuer/issuers/membership-files \
| jq '.credential_configurations_supported.membership.credential_metadata.display'
```
`restart` returns before the backend is ready, so repeat the `curl` if it gets no answer. It is enough when only files changed; after a change to `.eudiplo.env`, run `eudiplo up`, because a restart keeps the old environment. For an urgent fix in the Web Client, detach the resource first and reattach it later ([Configuration as code](../operate/configuration-as-code.md#configuration-model)).
**Checkpoint:** after the backend is back up, the display reads `"name": "Membership card"`.
### Step 6: Version the project and check it in CI
Put the project under Git, without its secrets and database:
```bash
printf '%s\n' .eudiplo.env 'config/service.db*' > .gitignore
git init
git add .
git commit -m "EUDIPLO cookbook instance"
```
`.eudiplo.env` holds `MASTER_SECRET`, which encrypts the keys in the database, and every client secret; keep it in a secret manager, never in Git. `config/service.db` is the SQLite database of the `minimal` preset.
To check every change before it reaches an instance, add `.github/workflows/eudiplo-config.yml`:
```yaml title=".github/workflows/eudiplo-config.yml"
name: EUDIPLO configuration
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
env:
MEMBERSHIP_FILES_ADMIN_SECRET: ci-placeholder
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npx @eudiplo/cli@10 config validate tenants ./config
- run: npx @eudiplo/cli@10 config upgrade ./config --check
```
Use the CLI major version that matches your backend. The dummy value only lets the placeholder resolve; the real secret stays on the instance ([Validate in CI](../operate/configuration-as-code.md#validate-in-ci)). The backend runs a few checks that the schemas cannot express, so an import can still fail on a folder that passed (see [Troubleshooting](#troubleshooting)). The upgrade check also fails when a newer 10.x CLI raises a format version; upgrade the files only once the instance runs that release too ([Upgrade old files](../operate/configuration-as-code.md#upgrade-old-files)).
**Checkpoint:** the job's commands pass locally without the real secret, and on GitHub the workflow passes:
```bash
MEMBERSHIP_FILES_ADMIN_SECRET=ci-placeholder eudiplo config validate tenants ./config && eudiplo config upgrade ./config --check
```
### Step 7: Check the whole deployment
```bash
eudiplo doctor --instance cookbook
```
`doctor` runs the checks listed in the [CLI guide](../operate/cli.md#check-an-instance-with-doctor). With the tenant client from step 4 it also reads the KMS provider health, which it skips for the tenant-less root client.
**Checkpoint:** no check reports `FAIL`, and `KMS providers` reports `PASS`. On `http://localhost:3000`, the public URL check warns that it does not use HTTPS; through the tunnel it passes. In production, run `eudiplo doctor --strict`, which fails on warnings too.
### Troubleshooting
| Symptom | Cause | Fix |
| --- | --- | --- |
| `Unresolved placeholder ${MEMBERSHIP_FILES_ADMIN_SECRET}` from `validate` | The variable is not set in this shell or CI job | Export it, or set a dummy value in CI. |
| The metadata does not list `membership`, and the backend log shows `Failed to import tenant` | A check of the backend refused a file, for example `Authorization server id 'built-in' is reserved`, or a file cannot be imported, which the message names as `: ` | Read the reason with `eudiplo logs --instance cookbook --service eudiplo --tail 200`. When the message names an operation report, `eudiplo config operations` shows the resource that failed; the ones before it stay applied. Fix the file and restart. |
| The import fails with an unresolved placeholder | The variable is missing from `.eudiplo.env`, or you ran `restart` after adding it | Add it, then run `eudiplo up --instance cookbook`. |
| A file change has no effect | `CONFIG_IMPORT_MODE` is still `create`, or the resource was detached or changed through the API (`RESOURCE_DETACHED`, `STALE_GENERATION` in the log) | Set `upsert` and run `eudiplo up`; reattach the resource ([Configuration as code](../operate/configuration-as-code.md#configuration-model)). |
| A config command answers `401` | The token in `EUDIPLO_TOKEN` expired | Request a new token as in step 4. |
More symptoms are listed in [Troubleshooting](../troubleshooting.md).
### Next steps
- Roll the folder out to another instance, such as the one from [Production on one VM](production-vm.md): copy `config/membership-files` into its `config/` folder, add `MEMBERSHIP_FILES_ADMIN_SECRET` with a new value to its `.eudiplo.env`, set `CONFIG_IMPORT_MODE=upsert` and run `eudiplo up --instance production`. The key chain gets a new key there. That backend must run the same EUDIPLO release as this one or a newer one, because an older backend refuses newer file format versions.
- Move a tenant you built in the Web Client to another instance with a bundle and a reviewed plan: [Plan and import](../operate/configuration-as-code.md#plan-and-import).
- Upgrade the instance and your files after a release: [Upgrade the application](../operate/cli.md#upgrade-the-application) and [Upgrade old files](../operate/configuration-as-code.md#upgrade-old-files).
---
## Cookbook: Production on One VM
You run EUDIPLO on a single Linux server with the CLI, behind a TLS reverse proxy, with restricted ports, backups and a strict health check. The result is a deployment that wallets and your applications reach at a stable HTTPS address.
### What you will build
The CLI's `standard` preset: the backend, the Web Client, PostgreSQL and RustFS object storage, all in one Compose project. Caddy terminates TLS with Let's Encrypt certificates for two host names. The backend and the Web Client listen on `127.0.0.1` only, so Caddy is the only way in.
```mermaid
flowchart LR
W[Wallets and your apps] -->|"https://eudiplo.example.com"| C[Caddy]
A[Administrators] -->|"https://console.example.com"| C
C -->|"127.0.0.1:3000"| B[Backend]
C -->|"127.0.0.1:4200"| UI[Web Client]
B --> P[(PostgreSQL)]
B --> S[(RustFS)]
```
### Before you start
- **Starts from:** nothing. If EUDIPLO is new to you, run the [Issue and verify](foundation.md) cookbook on your computer first.
- A Linux VM with a public IP address, and DNS records for `eudiplo.example.com` and `console.example.com` that point to it. Replace both names with your own throughout.
- A firewall in front of the VM (for example your cloud provider's security group) that allows inbound traffic only on ports 22, 80 and 443. Docker publishes container ports past host firewalls such as `ufw`, and projects created with an older CLI publish RustFS on ports 9000 and 9001 on all interfaces.
- Docker Engine with the Compose v2 plugin. For Podman with Podman Compose, run `export EUDIPLO_CONTAINER_RUNTIME=podman` before the CLI commands.
- [Caddy](https://caddyserver.com/docs/install) installed as a system service.
### Step 1: Install the CLI
```bash
curl -fsSL https://eudiplo.dev/install.sh | bash
eudiplo --version
```
If the shell does not find `eudiplo`, add `~/.local/bin` to your `PATH`, as the installer prints. Other installer caveats are listed in [Install and connect](foundation.md#step-1-install-the-cli).
**Checkpoint:** `eudiplo --version` prints a version number.
### Step 2: Initialize the deployment
Pin the image version you want to run, the CLI's version (`eudiplo --version`) or newer, because the CLI writes configuration files in its own format versions (image tags have no `v` prefix, for example `10.0.0`). Without `--image-tag`, the deployment uses `latest`.
```bash
eudiplo init ~/eudiplo --instance production --preset standard \
--public-url https://eudiplo.example.com --image-tag 10.0.0
```
The wizard asks the remaining questions. Answer them like this:
| Prompt | Answer |
| ------------------------------------------ | --------------------------------------------- |
| Add the bundled demo tenant? | `n` |
| Auth client ID | keep `root`, or choose your own name |
| Auth client secret (leave blank to generate) | leave blank |
| Include the web client? | `y` |
| Start the deployment now? | `n`, because step 3 changes the environment |
The wizard keeps the generated secret out of your shell history. It writes `.eudiplo.env` with mode `0600`. This file contains `MASTER_SECRET`, which encrypts keys stored in the database, as well as the database, RustFS and root client secrets.
**Checkpoint:** `eudiplo instance list` shows `production`, and `~/eudiplo` contains `.eudiplo.env`, `eudiplo.compose.yaml` and `config/kms.json`. As the first instance on this server, `production` is the CLI default, so the commands below omit `--instance`.
### Step 3: Restrict ports and browser origins
Append two lines to `~/eudiplo/.eudiplo.env`:
```env
EUDIPLO_BIND_ADDRESS=127.0.0.1
CORS_ORIGINS=https://console.example.com
```
- `EUDIPLO_BIND_ADDRESS` publishes the backend (`3000`), the Web Client (`4200`) and RustFS (`9000`, `9001`) on the loopback interface only.
- `CORS_ORIGINS` lets browsers call the management API (`/api/*`) only from the console origin. Wallet-facing and public endpoints stay open to all origins. Use `scheme://host` without a path or trailing slash; the backend refuses to start with an invalid value.
**Checkpoint:** `grep -E 'PUBLIC_URL|EUDIPLO_BIND_ADDRESS|CORS_ORIGINS' ~/eudiplo/.eudiplo.env` prints all three settings.
### Step 4: Start EUDIPLO
```bash
eudiplo up
eudiplo ps
curl http://127.0.0.1:3000/health
```
**Checkpoint:** `eudiplo ps` shows `eudiplo`, `eudiplo-client`, `postgres` and `rustfs` as running, and the health call returns JSON with `"status":"ok"`. If not, read the backend log with `eudiplo logs --service eudiplo --tail 100`; add `--follow` to keep streaming.
### Step 5: Put Caddy in front
Replace `/etc/caddy/Caddyfile` with:
```text
eudiplo.example.com {
reverse_proxy 127.0.0.1:3000
}
console.example.com {
reverse_proxy 127.0.0.1:4200
}
```
Then run `sudo systemctl reload caddy`. Caddy requests Let's Encrypt certificates for both names on the first request. For nginx, Traefik or EUDIPLO's built-in TLS, see [TLS and reverse proxies](../operate/tls.md).
**Checkpoint:** `curl https://eudiplo.example.com/health` returns `"status":"ok"` from another machine, and `https://console.example.com` shows the Web Client login.
### Step 6: Sign in and run the strict check
Sign in at `https://console.example.com`. Enter `https://eudiplo.example.com` as **EUDIPLO Instance** (replace any prefilled value), then use the **Client ID and Secret** tab with `AUTH_CLIENT_ID` and `AUTH_CLIENT_SECRET` from `.eudiplo.env`.
Then let the CLI check the whole deployment:
```bash
export EUDIPLO_CLIENT_ID=root
read -rs EUDIPLO_CLIENT_SECRET && export EUDIPLO_CLIENT_SECRET
eudiplo doctor --strict
```
`read -rs` waits for you to paste the secret without showing it. `--strict` treats every warning as a failure, for example a public URL without HTTPS, a TLS certificate close to expiry or missing client credentials. Skipped checks do not fail. With the root client the KMS provider check is skipped, because provider health is read per tenant; once you have a tenant, a [tenant client](../operate/tenants-and-access.md#api-clients-with-least-privilege) with `issuance:manage` covers it too.
**Checkpoint:** `eudiplo doctor --strict` exits with status `0`. Run it after every change and from your monitoring.
### Step 7: Back up
Back up these items regularly and keep the copies off the VM:
| Item | Why | How |
| ---------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `~/eudiplo/.eudiplo.env` | Without `MASTER_SECRET`, the keys in the database cannot be decrypted | Store it in your secret manager once, and again after each change |
| `~/eudiplo/config/` | KMS configuration and file-managed tenant configuration | Copy the folder |
| PostgreSQL | Tenants, configurations, keys, sessions and status lists | `docker exec eudiplo-postgres-1 pg_dump -U eudiplo -Fc eudiplo > eudiplo-$(date +%F).dump` |
| RustFS volume `eudiplo_rustfs-data` | Uploaded images such as logos | Archive the volume, for example with a short-lived container that runs `tar` |
`eudiplo ps` shows the actual container name if it differs from `eudiplo-postgres-1`. Test a restore on a second VM before you rely on the backups.
**Checkpoint:** `docker exec -i eudiplo-postgres-1 pg_restore --list < eudiplo-$(date +%F).dump` lists the tables of the dump.
### Step 8: Upgrade
```bash
eudiplo upgrade --image-tag 10.0.1
```
The command shows the image changes, points to the upgrade guide when a major version changes, and asks for confirmation. It then writes the new tags to `.eudiplo.env`, pulls the images and recreates the containers. Database migrations run when the backend starts, and downgrades are not supported, so back up first. Read the [upgrade guide](../upgrade/index.md) before every major upgrade.
**Checkpoint:** `eudiplo doctor --strict` passes again after the upgrade.
### Troubleshooting
| Symptom | Cause | Fix |
| ------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| Caddy gets no certificate | DNS does not point to the VM, or port 80 or 443 is blocked | Check the DNS records and the firewall; read `journalctl -u caddy`. |
| Caddy returns `502` | The backend or Web Client is not running | Run `eudiplo ps` and `eudiplo logs --service eudiplo --tail 100`. |
| Web Client login fails with a CORS error | `CORS_ORIGINS` does not match the console origin exactly | Correct the value in `.eudiplo.env`, then run `eudiplo up`. Compose recreates the backend. |
| `doctor --strict` fails on authentication | `EUDIPLO_CLIENT_ID` or `EUDIPLO_CLIENT_SECRET` is not exported | Export both in the shell that runs `doctor`. |
| RustFS answers on port 9000 from the Internet | The VM firewall does not block it | Allow only ports 22, 80 and 443 in the firewall in front of the VM. |
More symptoms are listed in [Troubleshooting](../troubleshooting.md).
### Next steps
- Work through the [production checklist](../operate/production-checklist.md) before you issue real credentials.
- Create tenants and least-privilege API clients: [Tenants and access](../operate/tenants-and-access.md).
- Keep keys outside the database: [Key management](../operate/kms.md).
- Manage tenant configuration as files: [Configuration as code](../operate/configuration-as-code.md). To iterate on such files on your computer, see [Development setup](../contributing/development-setup.md).
---
## Cookbook: Revocable Credentials
You turn on status management for the membership credential, issue a new one, revoke it, and watch the next presentation fail. A variant at the end keeps only one active credential per person.
### What you will build
Every new `membership` credential gets an entry in a Token Status List that EUDIPLO publishes. Revoking or suspending sets the entry for one issuance session. `membership-check` checks the status during verification and rejects the credential.
```mermaid
flowchart LR
I[Issue with status entry] --> V1[Verify: completed]
V1 --> R[Revoke the issuance session]
R --> V2[Verify: failed]
```
### Before you start
- **Starts from:** [Issue and verify](index.md): tenant `membership-demo`, credential configuration `membership`, presentation configuration `membership-check` (with the default **Strict** status check), the tunnel and the wallet.
- `curl` and `jq`, and the secret of `membership-demo-admin`. You change the status in the Web Client, but clearing the verifier's status-list cache and some checkpoints need the API. Get a token:
```bash
export EUDIPLO=http://localhost:3000
read -rs ADMIN_SECRET
ADMIN_TOKEN=$(curl -s -X POST "$EUDIPLO/api/oauth2/token" \
-d grant_type=client_credentials -d client_id=membership-demo-admin \
--data-urlencode client_secret="$ADMIN_SECRET" | jq -r .access_token)
```
### Step 1: Set the status list defaults
Open **Credential Issuance → Status Lists** and choose **Default settings**. Set:
| Field | Value | Why |
| ----------------- | ------------------------------------ | ----------------------------------------------------------------------- |
| Bits per status | **2 bits** (Valid/Revoked/Suspended) | The default of 1 bit can only express valid and revoked |
| TTL (seconds) | `60` | Verifiers cache a status list until it expires; the default is one hour |
| Regeneration mode | **Immediate** | EUDIPLO re-signs the list right after a status change |
Fields you leave at **Global default** follow the instance's `STATUS_*` environment variables and are not stored for the tenant. Choose **Save Configuration**. Capacity and bits only apply to lists created afterwards, so set them before the first credential with status is issued. In production, choose the TTL from how fast a revocation must take effect. The API equivalent is `PUT /api/status-list-config` with `{"bits": 2, "ttl": 60, "immediateUpdate": true}`.
**Checkpoint:** the page shows the saved values after a reload.
### Step 2: Check the status list signing key
Open **Cryptographic Assets → Keys** and check that the key chain `Membership status list signing` with usage **Status List Signing** exists; [chapter 3](first-presentation.md) created it for the trust list. EUDIPLO signs status lists with it. Without such a key, EUDIPLO signs status lists with the credential signing key.
**Checkpoint:** `Membership status list signing` appears under **Keys**.
### Step 3: Turn on status management
Open **Credential Issuance → Credential Configs → membership** and choose **Edit**. On **Settings**, under **Credential Features**, turn **Status Management** on. Choose **Save Configuration**. The API equivalent is `PATCH /api/issuer/credentials/membership` with `{"statusManagement": true}`.
**Checkpoint:** the credential type shows **Status Management** as enabled.
### Step 4: Issue a credential with a status entry
The credential from chapter 2 has no status entry and cannot be revoked. Issue a new one:
1. Open **Credential Issuance → New Issuance**, choose **Pre-Authorized Code**, check that `membership` is selected (it is preselected), choose **Use Pre-configured Default Values** and **Generate Offer**.
2. Scan the QR code with the wallet and accept the credential.
3. Delete the chapter 2 credential from the wallet, so that the wallet cannot pick it in the next steps.
4. Open **Sessions → All Sessions**, open this issuance session and copy its ID for the API calls:
```bash
export SESSION=
```
EUDIPLO creates the status list on first use and adds a `status` claim to the credential that points to it.
**Checkpoint:** `GET /api/status-lists` shows one list for the tenant, and its URL serves a signed status list:
```bash
curl -s "$EUDIPLO/api/status-lists" -H "Authorization: Bearer $ADMIN_TOKEN" | jq '.[] | {id, uri}'
curl -s -o /dev/null -w '%{content_type}\n' ""
```
The second call prints a content type that starts with `application/statuslist+jwt`. The public path is `/issuers/membership-demo/status-management/status-list/{listId}`.
### Step 5: Verify while the credential is valid
Open `membership-check`, choose **New Verification**, then **Generate Request**, and approve it in the wallet.
**Checkpoint:** the presentation session is `completed`.
### Step 6: Revoke the credential
Open **Sessions → All Sessions** and open the issuance session from step 4. The **Credential Status** card shows `membership` with **1 valid**. Choose **Revoke** and confirm with **Revoke**. `membership-demo-admin` has the roles for the session page and the card; which roles they need is listed under [Revocation](../issuance/revocation.md#2-revoke-or-suspend). The API equivalent:
```bash
curl -s -X POST "$EUDIPLO/api/session/revoke" \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d "{\"sessionId\": \"$SESSION\", \"credentialConfigurationId\": \"membership\", \"status\": 1}" \
-w '%{http_code}\n'
```
`status` is `0` for valid, `1` for revoked and `2` for suspended. Without `credentialConfigurationId`, every credential of the session changes. The call needs the role `credentials:status` or `issuance:manage` and returns `204`. Then clear the status lists your tenant's verifier cached, so you do not have to wait for the TTL. The Web Client has no button for this:
```bash
curl -s -X DELETE "$EUDIPLO/api/cache/status-list" -H "Authorization: Bearer $ADMIN_TOKEN" -w '%{http_code}\n'
```
**Checkpoint:** the **Credential Status** card shows **1 revoked**, and the cache call prints `204`.
### Step 7: Watch the verification fail
Generate another request for `membership-check` and approve it in the wallet. Some wallets check the status themselves and refuse to present a revoked credential; that also counts as success for this step.
**Checkpoint:** the presentation session is `failed`. The session API shows the reason:
```bash
curl -s "$EUDIPLO/api/session/" -H "Authorization: Bearer $ADMIN_TOKEN" \
| jq '{status, errorReason}'
```
`errorReason` is "Presentation validation failed: Status is not valid". A webhook, if configured, receives `status: failed` and no credentials.
### Step 8: Suspend and reinstate
Revocation is final: the card offers neither **Suspend** nor **Reinstate** for the credential you revoked in step 6, and the API answers `409` to `0` or `2`. To try suspension, issue another credential as in step 4, delete the revoked one from the wallet, open the new issuance session and set `SESSION` to its ID. On its **Credential Status** card, choose **Suspend** and confirm. The API equivalent:
```bash
curl -s -X POST "$EUDIPLO/api/session/revoke" \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d "{\"sessionId\": \"$SESSION\", \"credentialConfigurationId\": \"membership\", \"status\": 2}" \
-w '%{http_code}\n'
```
Clear the cache and verify: a suspended credential fails like a revoked one. Choose **Reinstate** on the card, or repeat the call with `"status": 0`, to lift the suspension, then clear the cache and verify again. Status management in detail: [Revocation](../issuance/revocation.md).
**Checkpoint:** verification fails while the credential is suspended and passes after you reinstate it.
### Variant: one active credential per person
With **Single Active Credential** (`activeCredentials: {"enabled": true}`), issuing a new credential to a person revokes their previous credentials of the same type. It requires status management; the API rejects the setting without it ("statusManagement must be enabled when activeCredentials is enabled").
EUDIPLO recognizes "the same person" by the issuer and subject that an **external** authorization server binds to the issuance session. Pre-authorized offers and logins through the chained authorization server of [Issue after login](issue-after-login.md) have no such subject; EUDIPLO then skips the policy and logs this at debug level. To try the variant:
1. Configure an external authorization server as described in [Authorization servers](../issuance/authorization-servers.md).
2. Turn on **Single Active Credential** for `membership` under **Credential Features**.
3. Issue two credentials to the same user through that server, then present the first one.
**Checkpoint:** the presentation of the first credential fails with "Status is not valid", and the second one passes.
### Troubleshooting
| Symptom | Cause | Fix |
| ----------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| The session page shows no **Credential Status** card, or revoke returns `409` "No status mapping found" | The session's credential was issued without status management | Issue a new credential after step 3 and use its session. |
| Verification still passes after revoking | The wallet presented an older credential, or a cached status list was used | Delete old credentials from the wallet; clear the status-list cache; check the TTL. |
| The card shows **valid** but offers no **Suspend**, or suspend returns `400` "requires a status list with at least 2 bits" | The list was created with 1 bit per status | Set **Bits per status** to 2 (step 1), then issue a new credential; existing lists keep their bits. |
| The card shows **revoked** and offers no **Suspend** or **Reinstate**, or suspend or reinstate returns `409` "revocation is final" | The credential is revoked | Revocation cannot be undone; issue a new credential. |
| `403` on `/api/cache/status-list` | The token lacks `issuance:manage` or `presentation:manage` | Use the `membership-demo-admin` token. |
General problems are covered in [Troubleshooting](../troubleshooting.md).
### Next steps
- [Revocation](../issuance/revocation.md): status list settings, management API and aggregation.
- [Integrate into your backend](integrate-backend.md): revoke from your own code with a least-privilege client.
- [Accept only trusted issuers](trusted-issuers.md): restrict which issuers `membership-check` accepts.
---
## Cookbook: Sign in to Keycloak with a Wallet
Keycloak can use EUDIPLO as an external identity provider: the user chooses **Membership wallet** on the Keycloak login page, presents the membership credential, and Keycloak signs them in. Every application behind Keycloak gets wallet sign-in without code of its own.
### What you will build
An OpenID Connect client `Keycloak` in the tenant `membership-demo` that verifies sign-ins with the presentation configuration `membership-check`, and an identity provider `membership-wallet` in a Keycloak realm that uses it. `member_id` identifies the user, so the same member always lands in the same Keycloak account.
```mermaid
sequenceDiagram
participant B as Browser
participant K as Keycloak
participant E as EUDIPLO
participant W as Wallet
B->>K: Login page, "Membership wallet"
K->>E: Authorization request (PKCE)
E->>B: Sign-in page with QR code
W->>E: Presentation of the membership credential
E->>K: Authorization code (browser redirect)
K->>E: Token request (client secret)
E-->>K: ID token with sub, name, member_id
K->>B: Signed in
```
### Before you start
- **Starts from:** [chapter 3, Verify the membership credential](first-presentation.md). `membership-check` verifies `name` and `member_id`, and the wallet holds the membership credential.
- A Keycloak 26 realm you administer, reachable from the user's browser, and able to reach EUDIPLO's public URL. In the examples Keycloak runs at `https://YOUR-KEYCLOAK-HOST` with the realm `demo`.
- A token of the client `membership-demo-admin` from [chapter 2](first-credential.md), which has `presentation:manage`; [Integrate into your backend](integrate-backend.md#before-you-start) shows the token request.
### Step 1: Register Keycloak as a client
Keycloak's broker endpoint receives the authorization code. Its URL is `https://YOUR-KEYCLOAK-HOST/realms/demo/broker/membership-wallet/endpoint`, where `membership-wallet` is the identity provider alias you use in step 2.
```bash
curl -X POST "https://YOUR-HTTPS-HOST/api/verifier/oidc-clients" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"name": "Keycloak",
"redirectUris": ["https://YOUR-KEYCLOAK-HOST/realms/demo/broker/membership-wallet/endpoint"],
"profile": "basic",
"scopes": [{ "scope": "membership", "presentationConfigId": "membership-check" }],
"subject": { "credentialId": "membership", "claim": "member_id" },
"claimsFrom": "membership"
}'
```
- `profile: basic`: Keycloak's identity provider sends the authorization request through the browser and does not push it first.
- `subject`: `sub` becomes a hash of `member_id` and of the issuer, so Keycloak recognizes a returning member. `membership-check` names `membership-issuers` under `trusted_authorities`, which `subject` requires.
- `claimsFrom`: `name` and `member_id` also appear at the top level of the ID token, where Keycloak's mappers read them.
**Checkpoint:** the response contains `id` (the client ID), `clientSecret` and `issuer`. Store the secret now; it is not shown again. `https://YOUR-HTTPS-HOST/verifiers/membership-demo/oidc/.well-known/openid-configuration` now returns the discovery document.
### Step 2: Add the identity provider in Keycloak
In the Keycloak admin console, open the realm `demo`, then **Identity providers → OpenID Connect v1.0**, and enter:
| Field | Value |
| --- | --- |
| Alias | `membership-wallet` |
| Display name | `Membership wallet` |
| Discovery endpoint | `https://YOUR-HTTPS-HOST/verifiers/membership-demo/oidc/.well-known/openid-configuration` |
| Client authentication | Client secret sent as basic auth |
| Client ID / Client Secret | `id` and `clientSecret` from step 1 |
Save, then on the provider's **Settings** tab set:
| Field | Value |
| --- | --- |
| Use PKCE | On, method `S256` |
| Validate signatures / Use JWKS URL | On |
| Disable user info | On: everything is in the ID token |
| Scopes | `openid membership` |
| Sync mode | Force |
Leave **Logout URL** empty: EUDIPLO keeps no session to end.
**Checkpoint:** the discovery endpoint filled in the authorization, token and JWKS URLs and the issuer `https://YOUR-HTTPS-HOST/verifiers/membership-demo/oidc`.
### Step 3: Map the claims to the Keycloak account
On the provider's **Mappers** tab, add:
| Name | Mapper type | Settings |
| --- | --- | --- |
| `username` | Username Template Importer | Template `${ALIAS}.${CLAIM.member_id}` |
| `first name` | Attribute Importer | Claim `name`, User attribute `firstName` |
| `member id` | Attribute Importer | Claim `member_id`, User attribute `member_id` |
A user attribute other than the built-in ones must exist in **Realm settings → User profile** before the mapper can write it; add `member_id` there.
The membership credential carries no email address and no last name, which Keycloak's default user profile requires. Its first login flow then asks for them once (**Review profile**). Either let members enter them there, or make **email** and **lastName** optional in **Realm settings → User profile**.
**Checkpoint:** three mappers are listed.
### Step 4: Sign in
Open the account console of the realm, `https://YOUR-KEYCLOAK-HOST/realms/demo/account`, and choose **Membership wallet** on the login page. EUDIPLO shows the sign-in page: scan the QR code with the wallet, or open the wallet on the same device, and share the credential.
**Checkpoint:** the account console shows you signed in, with the first name from the credential. In the admin console, **Users** lists `membership-wallet.m-001` (Keycloak lowercases usernames), and its **Identity provider links** tab shows `membership-wallet` with a user ID that is a hash, not `M-001`.
Sign out and sign in again with the wallet. Keycloak signs you in to the same account and does not ask for the profile again.
To skip the Keycloak login page, send users straight to the wallet with `kc_idp_hint=membership-wallet` on your application's authorization request.
### Troubleshooting
| Symptom | Cause | Fix |
| --- | --- | --- |
| EUDIPLO shows "The application must push its authorization request first" | The client has the `secure` profile | `PATCH` the client with `"profile": "basic"` |
| EUDIPLO's page says the `redirect_uri` is not registered | Alias or realm in the redirect URI differ from Keycloak's | Copy the **Redirect URI** shown on the provider's settings page into `redirectUris` |
| Keycloak returns to its login page with `invalid_scope` | Keycloak sent more scopes than `openid` and one other | Set **Scopes** to exactly `openid membership` |
| Keycloak logs "Invalid token signature" or an algorithm mismatch | The ID token is signed with ES256, ES384 or ES512, as discovery says | Keep **Validate signatures** with **Use JWKS URL**; don't set a fixed RS256 key |
| Every sign-in creates a new Keycloak user | The client has no `subject` | `PATCH` the client with `subject` as in step 1 |
| Keycloak fails after the sign-in with a userinfo error | **Disable user info** is off | Turn it on: EUDIPLO has no userinfo endpoint |
| The sign-in ends with `access_denied` naming `member_id` | The presentation lacks the subject claim | Request `member_id` in `membership-check` |
### Next steps
- [Sign-in with OpenID Connect](../presentation/openid-connect.md): every client setting, `acr` and same-device sign-in.
- [Keycloak SSO](../operate/keycloak.md): use Keycloak for EUDIPLO's own management login.
- [Accept only trusted issuers](trusted-issuers.md): what happens when a credential comes from another issuer.
An end-to-end test runs the same client and identity provider settings against Keycloak 26, with a PID instead of the membership credential (`apps/backend/test/presentation/oidc-provider.e2e-spec.ts`).
---
## Cookbook: Accept Only Trusted Issuers
In [chapter 3](first-presentation.md), `membership-check` accepts the membership credential only from issuers on the trust list `membership-issuers`. You now test it with a credential from an issuer that is not on the list, and then switch to a trust list published by someone else.
### What you will build
A second signing key acts as an untrusted issuer of the same credential type. `membership-check` rejects its credentials, either in the wallet or during verification.
```mermaid
flowchart LR
K[Membership credential signing] -->|root CA listed in| T[Trust list membership-issuers]
T -->|trusted_authorities| P[membership-check]
U[Untrusted signing] -.->|not listed| P
```
### Before you start
- **Starts from:** [Issue and verify](index.md): tenant `membership-demo` with the key chain `Membership credential signing`, the credential configuration `membership`, the trust list `membership-issuers`, the presentation configuration `membership-check` that references it, and the wallet with the membership credential.
- `curl`, `jq` and the secret of `membership-demo-admin` for the checks. Get a token:
```bash
export EUDIPLO=http://localhost:3000
read -rs ADMIN_SECRET
ADMIN_TOKEN=$(curl -s -X POST "$EUDIPLO/api/oauth2/token" \
-d grant_type=client_credentials -d client_id=membership-demo-admin \
--data-urlencode client_secret="$ADMIN_SECRET" | jq -r .access_token)
```
### Step 1: Issue a credential from an untrusted issuer
Create a second issuer key in the same tenant and a credential type of the same VCT that uses it:
1. Under **Keys**, create **Credential Signing (Attestation)** → **Key Chain with Root CA** with description `Untrusted signing`.
2. Under **Credential Configs**, create `membership-untrusted` exactly like `membership` in [chapter 2, step 4](first-credential.md#step-4-define-the-membership-credential), with two differences: **Display Name** `Untrusted membership`, and the signing key chain `Untrusted signing`.
3. Send a pre-authorized offer for `membership-untrusted` with the default values, and accept it in the wallet.
**Checkpoint:** the wallet holds two credentials of type `urn:example:membership:1`: `Membership` and `Untrusted membership`.
### Step 2: Test the untrusted issuer
Generate a new request for `membership-check` and scan it. There are two correct outcomes:
- **The wallet offers only `Membership`.** It filtered by the `aki` values. Present it; the session is `completed`.
- **The wallet offers both.** Choose `Untrusted membership`. EUDIPLO rejects it.
To see the server-side rejection with a wallet that filters, add `VP_REMOVE_TA=true` to `.eudiplo.env` and run `eudiplo up --instance cookbook`. EUDIPLO then leaves `trusted_authorities` out of the wallet request but still enforces the list. Remove the setting afterwards.
**Checkpoint:** the session of the untrusted credential is `failed`:
```bash
curl -s "$EUDIPLO/api/session/" -H "Authorization: Bearer $ADMIN_TOKEN" \
| jq '{status, failureCode, errorReason}'
```
`failureCode` is `trust_chain_not_trusted` ("The credential issuer is not in the trusted list.") or `no_trust_chain_to_root`.
### Variant: use a trust list published by someone else
To accept the issuers of an external List of Trusted Entities (LoTE), edit `membership-check` and replace the managed trust list under **Issuer trust** with **Add external trust list**. Enter the **External trust-list URL** and, under **Trust-list verification material**, the **Verification certificate (base64 DER)** of the list's signer. In the query this becomes:
```json
{ "type": "etsi_tl", "values": [{ "url": "https://trust.example.org/lists/members", "verifierX509Der": "MIIB..." }] }
```
Without verification material, EUDIPLO cannot check the list's signature, and verification fails with `trust_list_unavailable`. EUDIPLO caches fetched lists for 5 minutes; `DELETE /api/cache/trust-list` clears your tenant's cached lists after the publisher changes a list. To try the variant without a second organization, enter the **Trust List URL** of `membership-issuers` from [chapter 3](first-presentation.md). For the certificate, open `Membership trust list signing` under **Keys**, choose **Copy PEM** under **Active Certificate**, and paste it without the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.
**Checkpoint:** presenting `Membership` completes the session as in chapter 3, and `Untrusted membership` is rejected as in step 2.
### Troubleshooting
| Symptom | Cause | Fix |
| ----------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| The trusted credential is rejected too | The entity lists a different issuer key chain | Edit the list and select `Membership credential signing` as **Issuer Key Chain**. |
| The wallet offers no credential at all | The wallet cannot match the `aki` values | Test with `VP_REMOVE_TA=true`; report the wallet's behavior to its vendor. |
| `trust_list_unavailable` | The list URL is unreachable, the list has no valid `NextUpdate` or one that has passed, it is numbered lower than a list accepted before ([Older versions of a list](../trust/trust-lists.md#older-versions-of-a-list)), or the verification material is missing or wrong | Open the URL; for external lists, check `verifierX509Der` (the signer's certificate without the PEM header and footer lines) or `verifierKey`. |
General problems are covered in [Troubleshooting](../troubleshooting.md).
### Next steps
- [Trust lists](../trust/trust-lists.md): entity types, wallet provider lists and renewal.
- [DCQL](../presentation/dcql.md): `trusted_authorities` together with other query options.
- [Keys and certificates](../trust/keys-and-certificates.md): import issuer certificates from your PKI.
---
## Attribute providers
Fetch claim values from your backend at the moment the wallet requests a credential. An attribute provider is a tenant resource with your endpoint's URL and authentication; credential configurations and offers reference it by ID. The request and response format is specified in the [Attribute provider API](../reference/attribute-provider-api.md).
**Prerequisites:** a client with the `issuance:manage` role and an HTTPS endpoint in your backend. For local development against HTTP or private addresses, set `OUTBOUND_URL_ALLOW_HTTP` or `OUTBOUND_URL_ALLOW_PRIVATE_NETWORK`.
### 1. Implement the endpoint
EUDIPLO posts the session, the requested credential configuration and the identity of the authenticated user. Return the claims under the configuration ID:
```ts
app.post("/claims", (req, res) => {
const { session, credential_configuration_id, identity, credentials } = req.body;
const member = members.findBySubject(identity.iss, identity.sub);
if (!member) return res.status(404).end(); // fails the credential request
res.json({
[credential_configuration_id]: { name: member.name, member_id: member.id },
});
});
```
- `identity` describes the user behind the wallet's access token; what it contains per flow is listed in [Claims](claims.md#identity-passed-to-attribute-providers).
- After a presentation (OID4VP authorization server or interactive authorization), `credentials` holds the verified presented claims, so you can derive the new credential from a PID.
- Return every claim of the credential; the response replaces the static defaults and is validated against the configuration's `fields`.
- To issue later, for example after a manual review, answer `{ "deferred": true }` and follow [Deferred issuance](deferred-issuance.md).
- Any error status fails the credential request. EUDIPLO does not retry.
### 2. Register the provider
```bash
curl -X POST "$EUDIPLO_URL/api/issuer/attribute-providers" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "member-db",
"name": "Member database",
"url": "https://backend.example.com/claims",
"auth": {
"type": "apiKey",
"config": { "headerName": "x-api-key", "value": "change-me" }
}
}'
```
`auth` is required: use `{ "type": "none" }` or an API key that EUDIPLO sends in the named header. Check it in your endpoint. The API returns the key as `` and keeps it when you send `` back, as for [webhook endpoints](../reference/webhooks.md#webhook-endpoints). In the web client, open **Attribute Providers**.
### 3. Use it
Reference the provider in the [credential configuration](credential-configuration.md) so that every issuance of this type uses it:
```json
{
"id": "membership",
"attributeProviderId": "member-db"
}
```
To use a different source for a single offer, set `credentialClaims` in the [offer request](credential-offers.md#choose-the-claim-source):
```json
{
"credentialClaims": {
"membership": { "type": "attributeProvider", "attributeProviderId": "member-db-staging" }
}
}
```
An offer can also define a one-off `webhook` source with the same contract. Offer sources take precedence over the configuration's provider; see [Claims](claims.md#sources-and-priority).
**Check:** issue a credential through an [offer](credential-offers.md) and inspect the request your endpoint received. A failing or unreachable endpoint makes the wallet's credential request fail with `invalid_credential_request`.
Attribute providers only supply claims. To learn whether the wallet stored the credential, use [notifications](notifications.md).
### Delete an attribute provider
`DELETE /api/issuer/attribute-providers/{id}` answers `409` while a credential config of the tenant names the provider in `attributeProviderId`, because issuing that credential would fail without it. The response names the credential configs in `message` and lists them in `references`:
```json
{
"statusCode": 409,
"timestamp": "2026-11-19T12:00:00.000Z",
"path": "/api/issuer/attribute-providers/member-db",
"code": "ATTRIBUTE_PROVIDER_IN_USE",
"message": "Attribute provider \"member-db\" is still used by 1 credential config (\"membership\"). Remove these references before deleting the attribute provider.",
"references": [
{ "kind": "CredentialConfig", "id": "membership", "description": "Membership card" }
]
}
```
Remove `attributeProviderId` from these credential configs, or point it to another provider, then delete the provider. Offers that name the provider in `credentialClaims` do not count: an open offer that still names it fails when the wallet requests the credential. A `replace` [configuration import](../operate/configuration-as-code.md) deletes left-out providers without this check.
---
## Authorization servers
Configure how wallets obtain the access token they present at the credential endpoint. Authorization servers are entries of `authorizationServers` in the [issuance configuration](issuance-configuration.md); an offer selects one by `id`.
### Choose a type
| | `built-in` | `external` | `chained` | `oid4vp` |
| --- | --- | --- | --- | --- |
| User authentication | None (optionally [interactive authorization](interactive-authorization.md)) | Your OAuth 2.0 server | Login at an upstream OpenID provider, brokered by EUDIPLO | Presentation of a credential the wallet already holds |
| Access token issued by | EUDIPLO | Your server | EUDIPLO | EUDIPLO |
| Flows | Pre-authorized code; authorization code, also wallet-initiated | Authorization code offer | Authorization code offer | Authorization code offer |
| Claim source | Any ([Claims](claims.md)) | Offer claims or attribute provider (required) | Any; identity is the upstream user | Any; presented claims are passed on |
| Refresh tokens, DPoP, wallet attestation | EUDIPLO | Your server | EUDIPLO | EUDIPLO |
| Issuer URL | `/issuers/{tenant}` | Your `issuer` | `/issuers/{tenant}/chained-as` | `/issuers/{tenant}/authorization-servers/{id}` |
Typical choices: `built-in` when your backend already knows the user and creates pre-authorized offers; `chained` to issue after a login at your identity provider ([cookbook](../cookbooks/issue-after-login.md)); `oid4vp` to issue after a PID presentation; `external` when your OAuth server already issues JWT access tokens and can carry the offer's `issuer_state`.
### Configure entries
```json
{
"authorizationServers": [
{ "type": "built-in", "id": "issuer-built-in" },
{
"type": "oid4vp",
"id": "pid-login",
"presentationConfigId": "pid",
"requireDPoP": true
}
]
}
```
- Every entry needs a unique `id`; `built-in` and `chained-as` are reserved. `label` is shown in the web client; `enabled: false` disables an entry.
- At least one entry is required, at most one `built-in`. Only the first enabled `chained` entry is used. A new tenant starts with `{ "type": "built-in", "id": "issuer-built-in" }`.
- EUDIPLO publishes the issuer URLs of all enabled entries, in order, as `authorization_servers` in the credential issuer metadata.
- An offer selects an entry with `authorization_server`; without it, the first enabled entry is used. The offer tells the wallet which server to use, also for pre-authorized codes. Only the built-in server redeems pre-authorized codes, so pre-authorized offers must select it (explicitly or as the first enabled entry).
Entries of the types `built-in`, `chained` and `oid4vp` accept:
| Field | Default | Description |
| --- | --- | --- |
| `token.lifetimeSeconds` | `300` (built-in), `3600` (chained, OID4VP) | Access token lifetime, minimum 60. |
| `token.signingKeyId` | The tenant's [authorization server key chain](../trust/keys-and-certificates.md#authorization-server-key-chain) | Key chain with usage type `authorizationServer` that signs the entry's access tokens and is published in its JWKS. Saving a configuration that names a key chain of another usage type answers `400`. |
| `token.refreshTokenEnabled` | `true` | See [Refresh tokens](#refresh-tokens). |
| `token.refreshTokenExpiresInSeconds` | `2592000` (30 days) | Minimum 60. |
| `requireDPoP` | `false` | See [DPoP](#dpop). |
| `walletAttestationRequired`, `walletProviderTrustLists`, `walletAttestationStatusCheckMode` | Issuance configuration values | Wallet attestation at PAR and token endpoints; see [Wallet and key attestation](../trust/attestation.md). |
### Built-in
EUDIPLO's own authorization server at `/issuers/{tenant}/authorize/*` (`par`, `authorize`, `token`, `interactive`), with metadata at `/.well-known/oauth-authorization-server/issuers/{tenant}`. It redeems pre-authorized codes and issues authorization codes without a login step. Wallets may also start an authorization code flow without an offer; they then select credentials with `authorization_details`. The access token's `sub` is the issuance session ID.
### External
Use your own OAuth 2.0 authorization server. EUDIPLO validates its access tokens and maps them to the offer's issuance session.
```json
{
"type": "external",
"id": "corporate-idp",
"issuer": "https://auth.example.com/realms/corp",
"sessionBinding": { "method": "access_token_claim", "claim": "issuer_state" }
}
```
Requirements for your server:
1. It publishes OAuth authorization server or OpenID Connect discovery metadata for `issuer`, including `jwks_uri`.
2. It issues JWT access tokens (`typ: at+jwt`) with `iss`, `sub`, `aud`, `exp`, `iat` and `jti`. `aud` must contain `{PUBLIC_URL}/issuers/{tenant}`.
3. It copies the offer's `issuer_state` unchanged into the access token claim named in `sessionBinding.claim`. Since 10.0 the `issuer_state` is a random value of the offer, not the EUDIPLO session ID, and EUDIPLO does not accept the session ID in that claim.
4. Its metadata, `jwks_uri` and any `introspection_endpoint` are HTTPS URLs on public addresses, as the [outbound URL policy](../concepts/security-model.md#https-and-tls) requires. For a server on HTTP or a private address, set `OUTBOUND_URL_ALLOW_HTTP` or `OUTBOUND_URL_ALLOW_PRIVATE_NETWORK`.
Every token must point to an active offer session that was created for this authorization server; EUDIPLO never creates a session from an external token. With the first credential request, EUDIPLO binds the token's `iss` and `sub` to the session, and later tokens must carry the same identity. The claims must come from the offer or an attribute provider, see [Claims](claims.md#external-authorization-servers-need-a-dynamic-source). External entries do not accept `token`, `requireDPoP` or wallet attestation settings; your server handles those.
:::caution[Offer selection]
EUDIPLO currently binds external tokens only to offers that selected the external server as the default: list it as the first enabled entry of `authorizationServers` and create the offer without `authorization_server`.
:::
### Chained
EUDIPLO acts as the authorization server towards the wallet and delegates the login to an upstream OpenID provider, such as Keycloak. The upstream provider needs no EUDIPLO-specific changes.
```json
{
"type": "chained",
"id": "keycloak-login",
"upstream": {
"issuer": "https://keycloak.example.com/realms/eudiplo",
"clientId": "eudiplo-chained-as",
"clientSecret": "change-me",
"scopes": ["openid", "profile", "email"]
},
"requireDPoP": true
}
```
- Register `{PUBLIC_URL}/issuers/{tenant}/chained-as/callback` as redirect URI of the upstream client.
- EUDIPLO uses OpenID Connect discovery, the authorization code flow with PKCE (`S256`), and sends `client_id` and `client_secret` in the token request body. Omit `clientSecret` for a public client. `scopes` defaults to `["openid"]`. The API returns `clientSecret` as ``; sending `` back keeps the stored secret of the server with the same `id`, unless `upstream.issuer` changes, which needs the secret again.
- EUDIPLO fetches the discovery document and calls the token endpoint under the [outbound URL policy](../concepts/security-model.md#https-and-tls): both need HTTPS on a public address unless `OUTBOUND_URL_ALLOW_HTTP` or `OUTBOUND_URL_ALLOW_PRIVATE_NETWORK` is set, and the token endpoint must answer without a redirect. Each of these requests, and token introspection at an external authorization server, must finish within 10 seconds, body included; a redirect from the introspection endpoint fails the check.
- Attribute providers receive the upstream user as `identity`: `iss` and `sub` of the upstream ID token and the ID token claims merged over the upstream access token claims.
- EUDIPLO's access token contains `issuer_state`, `client_id`, `upstream_iss` and `upstream_sub`; its `sub` is the wallet's `client_id`. Its `issuer_state` claim holds the EUDIPLO session ID, not the `issuer_state` of the offer.
- Endpoints: `/issuers/{tenant}/chained-as/{par,authorize,callback,token}`, metadata at `/.well-known/oauth-authorization-server/issuers/{tenant}/chained-as`, keys at `/.well-known/jwks.json/issuers/{tenant}/chained-as`.
Start chained flows from an authorization code offer; the wallet must send the offer's `issuer_state` in its pushed authorization request.
### OID4VP
The wallet authorizes by presenting a credential, for example a PID, that matches a [presentation configuration](../presentation/configure-verification.md).
```json
{ "type": "oid4vp", "id": "pid-login", "presentationConfigId": "pid", "requireDPoP": true }
```
1. The wallet sends a pushed authorization request to `/issuers/{tenant}/authorization-servers/{id}/par` and opens `…/authorize`. This returns a page with an **Open wallet** link to the presentation request.
2. After a successful presentation, the wallet opens `…/vp-callback` with the presentation's `response_code`. EUDIPLO stores the verified claims on the issuance session, redirects with an authorization code, and issues tokens at `…/token`. If the presentation failed or expired, the callback redirects with an error instead. Since 10.0, a callback without the matching `response_code` while the presentation is still open or has completed answers HTTP `400` and leaves the authorization pending: its `cas` parameter is the presentation session ID, which `GET /api/session` lists.
3. Attribute providers receive the presented claims in `credentials`, see the [Attribute provider API](../reference/attribute-provider-api.md).
Metadata is at `/.well-known/oauth-authorization-server/issuers/{tenant}/authorization-servers/{id}`. Like chained flows, OID4VP flows start from an authorization code offer. `immediateWalletRedirect` is accepted but has no effect.
The VP-backed chained server (`chained-as-vp`) was removed in 9.0; use the `oid4vp` type. See the [upgrade guide](../upgrade/8.x-to-9.0.md).
### Refresh tokens
The built-in, chained and OID4VP servers share one policy (9.0):
- Refresh tokens are enabled by default and valid for 30 days (`token.refreshTokenEnabled`, `token.refreshTokenExpiresInSeconds`).
- A refresh token never lives unbounded. Tokens stored without an expiry by older versions expire 30 days (or the configured lifetime) after their session was created.
- Refreshing keeps the original expiry. Chained and OID4VP servers rotate the refresh token; the built-in server keeps the original one.
- With `refreshTokenEnabled: false`, the token endpoint answers `unsupported_grant_type` and the metadata omits the `refresh_token` grant.
Refresh only helps while the issuance session exists: sessions are removed after the session retention time (`SESSION_TTL`, 24 hours by default, or the tenant's session settings). Expired chained and OID4VP authorization sessions are removed every `SESSION_TIDY_UP_INTERVAL`.
### DPoP
Two settings control DPoP ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)):
| Setting | Default | Enforced at |
| --- | --- | --- |
| Issuance `dPopRequired` | `true` | Built-in token endpoint (all grants) and the credential, deferred credential and notification endpoints. When `true`, these endpoints accept only `DPoP` tokens, no `Bearer`. |
| Per server `requireDPoP` | `false` | Built-in: PAR must carry a DPoP proof or `dpop_jkt`. Chained and OID4VP: PAR and token requests must carry a proof. |
Because `dPopRequired` applies at the credential endpoint for every server, set `requireDPoP: true` on chained and OID4VP servers while `dPopRequired` is `true`; otherwise they may issue `Bearer` tokens that the credential endpoint rejects. A key bound at PAR must sign the proofs at the token and refresh requests. Since 9.0, EUDIPLO verifies every proof: algorithm `ES256`, `ES384` or `ES512`, at most 5 minutes old, `jti` used once, no private key material. Failures answer `invalid_dpop_proof`.
### PKCE, PAR and authorization codes
- **PKCE:** every authorization code requires `S256`, at the built-in, chained, OID4VP and interactive endpoints and on the upstream leg. A missing `code_challenge` or another method answers `invalid_request`.
- **PAR:** the built-in server requires pushed authorization requests with `client_id` and `redirect_uri` (9.0). Its `request_uri` is single use and valid for 60 seconds, its authorization codes for 60 seconds. Chained and OID4VP servers use 600 and 300 seconds.
- **Grant binding (9.0):** a pre-authorized code is redeemable only with the `pre-authorized_code` grant, every other code only with `authorization_code`; otherwise the answer is `invalid_grant`. Codes are single use, bound to the client of the PAR request and, if sent, to its `redirect_uri`.
---
## Claim sources
Decide where the claim values of a credential come from. EUDIPLO picks exactly one source per credential, validates the result against the credential configuration and only then signs.
### Sources and priority
For each credential configuration in an offer, EUDIPLO uses the first source that applies:
| Priority | Source | Where it is set |
| --- | --- | --- |
| 1 | **Offer claims** (`credentialClaims`): `inline` values, an `attributeProvider` reference or a one-off `webhook` | [Offer request](credential-offers.md#choose-the-claim-source) |
| 2 | **Configuration attribute provider** | `attributeProviderId` of the [credential configuration](credential-configuration.md) |
| 3 | **Static defaults** | `defaultValue` of each entry in `fields[]` |
Sources are not merged. If an offer passes inline claims, the configuration's attribute provider is not called and the static defaults are ignored; if an attribute provider answers, its claims replace all defaults. An attribute provider or webhook that answers without claims for the configuration fails the credential request ([errors](../reference/attribute-provider-api.md#errors)); EUDIPLO does not fall back to the static defaults. Return every claim from the source you use, including fixed values such as the issuing country.
An attribute provider or webhook may also answer that the credential is not ready yet; see [Deferred issuance](deferred-issuance.md).
#### When to use which source
- **Static defaults:** demos, tests and credentials whose values never change.
- **Inline offer claims:** your backend already knows the values when it creates the offer, typically with the pre-authorized code flow.
- **Attribute provider:** the values depend on who authenticated (authorization code flow) or on a previous presentation, or you do not want claim values in the offer. Configure it once on the credential configuration; override it per offer with `credentialClaims` only when needed. See [Attribute providers](attribute-provider.md).
### External authorization servers need a dynamic source
When the wallet's access token comes from an [external authorization server](authorization-servers.md#external), static defaults are not accepted: the claims must come from the offer (`credentialClaims`) or from the configuration's attribute provider. Otherwise the credential request fails. In all other flows, credentials without a dynamic source get the static defaults.
### Identity passed to attribute providers
Attribute providers and offer webhooks receive an `identity` object with `iss`, `sub` and `token_claims`. It always describes the access token that the wallet presented at the credential endpoint, with one exception for the chained authorization server:
| Flow | `iss` | `sub` | `token_claims` |
| --- | --- | --- | --- |
| Pre-authorized code, built-in authorization server, [interactive authorization](interactive-authorization.md) | EUDIPLO credential issuer URL | Session ID | Claims of EUDIPLO's access token |
| [External](authorization-servers.md#external) | External authorization server | Subject of its token | Claims of the external access token |
| [Chained](authorization-servers.md#chained) | Upstream OpenID provider | Upstream user ID | Upstream ID token claims merged over the upstream access token claims |
| [OID4VP](authorization-servers.md#oid4vp) | OID4VP authorization server URL | The wallet's `client_id` | Claims of EUDIPLO's access token |
After a presentation (OID4VP authorization server or an interactive authorization presentation step), the request also contains the verified presented claims in `credentials`. The exact request and response format is in the [Attribute provider API](../reference/attribute-provider-api.md).
### Validation
When a credential configuration defines `fields`, EUDIPLO derives a JSON schema from them and validates the final claims of every source right before signing. Since 9.0, this also covers claims returned by attribute providers and webhooks and claims supplied when completing a [deferred transaction](deferred-issuance.md). Inline offer claims are additionally checked when the offer is created; invalid ones are rejected with `409`.
A credential is not issued if the claims:
- miss a claim marked `mandatory: true`,
- contain a value of a different `type`,
- contain a claim that is not defined in `fields` (at the top level or inside an object with `children`), or
- contain an invalid nested structure.
The wallet receives `credential_request_denied` with the affected paths, for example `/address/street_address: must be string`. Claim values are never included in the message.
To allow additional properties inside an object, set `additionalProperties` in its `constraints`. An `object` field without `children` accepts any properties.
```json
{
"path": ["metadata"],
"type": "object",
"constraints": { "additionalProperties": true },
"children": [{ "path": ["source"], "type": "string" }]
}
```
Configurations without `fields` are not validated.
#### Constraints
`constraints` adds JSON Schema 2020-12 rules to a field, for example a `pattern` for a date or `minItems` for an array. It accepts only these keywords, also inside subschemas such as `items` or `properties`:
- validation: `type`, `enum`, `const`, `multipleOf`, `maximum`, `exclusiveMaximum`, `minimum`, `exclusiveMinimum`, `maxLength`, `minLength`, `pattern`, `maxItems`, `minItems`, `uniqueItems`, `maxContains`, `minContains`, `maxProperties`, `minProperties`, `required`, `dependentRequired`;
- subschemas, each an object with these keywords or `true`/`false`: `items`, `contains`, `additionalProperties`, `propertyNames`, `not`, `if`, `then`, `else`, `unevaluatedItems`, `unevaluatedProperties`; a list of them in `prefixItems`, `allOf`, `anyOf`, `oneOf`; a map of them in `properties`, `patternProperties`, `dependentSchemas`;
- annotations: `title`, `description`, `examples`, `deprecated`, `readOnly`, `writeOnly`, `$comment`;
- `default`: fills in the claim at issuance when the claim source leaves it out.
At the top level of `constraints`, the field's own `type` and its display name, as `title`, win over these keywords; inside subschemas they apply as written.
Other keys, such as `format`, `$ref` or `x-` extensions, are refused with HTTP `400`; the error names the field and the keyword. This also keeps form hints like formly's `widget` out of the offer form in the Web Client. Configurations stored before 10.0 may still carry such keys: EUDIPLO ignores them when it validates claims, builds the offer form and exports the configuration, and sending its `fields` again answers `400` until you remove them.
Regular expressions in `constraints` (`pattern`, the keys of `patternProperties`, and `pattern` inside `propertyNames`) are matched with [RE2](https://github.com/google/re2/wiki/Syntax), which runs in linear time, so a pattern cannot stall issuance. `\s`, `\S` and `.` keep their JavaScript meaning. A configuration is rejected when it is saved or imported if a pattern uses lookarounds such as `(?=…)`, backreferences such as `\1`, inline flags, unknown escapes such as `\e`, `\S` inside a character class, the empty classes `[]` and `[^]`, long Unicode property names such as `\p{Letter}` (use `\p{L}`), is longer than 1000 characters or has too many or too large repetitions. A configuration stored before 10.0 with such a pattern fails at issuance until the pattern is replaced.
---
## Configure a credential
A credential configuration defines one credential type your tenant issues: its format, type identifier, claims, wallet display and signing behavior. This page walks through the decisions; every field is listed in the [credential configuration reference](../reference/credential-configuration.md).
**Prerequisites:** a tenant and a client with the `issuance:manage` role, and an issuer [signing key and certificate](../trust/keys-and-certificates.md). The [first-credential cookbook](../cookbooks/first-credential.md) shows the same steps in the web client (**Credential Issuance → Credential Configs**).
### 1. Choose format and type
| Format | `config.format` | Type identifier | Notes |
| --- | --- | --- | --- |
| SD-JWT VC | `dc+sd-jwt` | `vct` (required) | A string is used as is. An object (`name`, `description`, `extends`, `schema_uri`, …) is hosted by EUDIPLO at `/issuers/{tenant}/credentials-metadata/vct/{id}`, and that URL becomes the `vct`. |
| mDOC (ISO 18013-5) | `mso_mdoc` | `config.docType` | Claims are grouped by the `namespace` of each field. |
SD-JWT VCs are issued with `iss` = `{PUBLIC_URL}/issuers/{tenant}` and the certificate chain in the `x5c` header. Set `sdJwtTrustFormat: "federation"` to use the [OpenID Federation](../trust/federation.md) entity ID instead.
### 2. Define the claims
Each entry of `fields[]` describes one claim: its `path`, `type`, whether it is `mandatory` and, for SD-JWT VC, whether it is `disclosable`. Both default to `false`, so set `disclosable: true` for every claim the holder should be able to disclose selectively. `iss`, `nbf`, `exp`, `cnf`, `vct`, `vct#integrity` and `status`, and claims below them, cannot be disclosable: issuing then fails.
```json
{
"fields": [
{
"path": ["name"],
"type": "string",
"mandatory": true,
"disclosable": true,
"display": [
{ "locale": "en", "name": "Name" },
{ "locale": "de", "name": "Name" }
]
},
{
"path": ["address"],
"type": "object",
"disclosable": true,
"children": [
{ "path": ["locality"], "type": "string", "disclosable": true }
]
},
{
"path": ["nationalities"],
"type": "array",
"children": [{ "path": [null], "type": "string" }]
}
]
}
```
- Nest claims with `children`; child paths are relative to the parent. `null` in a path stands for every array element (the web client writes it as `nationalities.*`).
- `display` entries use `{ "locale", "name" }` and are published in the issuer metadata.
- For mDOC, set `namespace` on each field, for example `eu.europa.ec.eudi.pid.1`. Without it, the first segment of a nested path or the document type is used.
- `defaultValue` provides a static value. Where claim values come from and how they are validated is described in [Claims](claims.md).
### 3. Set the wallet display
`config.display[]` controls how wallets render the credential, one entry per locale:
```json
{
"config": {
"format": "dc+sd-jwt",
"display": [
{
"name": "Membership",
"locale": "en",
"description": "Example membership card",
"background_color": "#12107c",
"text_color": "#FFFFFF",
"logo": { "uri": "https://issuer.example.com/logo.png" },
"background_image": { "uri": "https://issuer.example.com/card.png" }
}
]
}
}
```
Only `name` and `locale` are required, and each locale may appear once. Colors are CSS Color Level 3 numerical values, as OID4VCI requires: `#rgb`, `#rrggbb`, `transparent`, or lowercase `rgb()`, `rgba()`, `hsl()` or `hsla()` with comma-separated values, for example `rgb(18, 16, 124)`. Without `background_color` or `text_color`, wallets use their own colors.
Images use `uri`. To host them in EUDIPLO, see [Object storage](../operate/object-storage.md).
### 4. Choose key binding and proofs
- `keyBinding: true` puts the wallet's key into the SD-JWT VC (`cnf`), so the holder must prove possession when presenting. mDOCs always carry the device key.
- Wallets prove their key at the credential endpoint with a JWT proof or a key attestation. `config.proofTypesSupported` limits the accepted proof types (`jwt`, `attestation`; default both). `config.keyAttestationsRequired` requires a trusted key attestation with an accepted `key_storage` and `user_authentication` level for every proof, and publishes it as `key_attestations_required` under both `jwt` and `attestation` in `proof_types_supported`. With the `attestation` proof type, one key attestation may carry up to `batchSize` keys and yields one credential per key. How key attestations are verified and trusted is described in [Wallet and key attestation](../trust/attestation.md).
### 5. Set the lifetime and signing key
- `lifeTime` (seconds) sets the expiry. SD-JWT VCs without `lifeTime` have no `exp`. mDOCs default to one year and never outlive the signing certificate. Issuance and expiry times are rounded to the hour so that credentials of one batch cannot be linked by their timestamps.
- `keyChainId` selects the signing key chain. Without it, the tenant's default attestation key chain signs the credential.
### 6. Enable revocation
Set `statusManagement: true` to add a status list entry to every credential, so you can revoke or suspend it later. See [Revoke and suspend credentials](revocation.md).
#### Keep one active credential per subject
`activeCredentials` keeps at most one active credential of this configuration per person: when the same subject receives a new credential, EUDIPLO revokes the previous ones.
```json
{
"statusManagement": true,
"activeCredentials": { "enabled": true, "tracking": "internal" }
}
```
- Requires `statusManagement: true`. Since 9.0, the API and the configuration import reject the policy without it.
- The subject is the `iss` and `sub` of an [external authorization server's](authorization-servers.md#external) access token. Tokens of the built-in, chained and OID4VP authorization servers carry no durable subject that EUDIPLO binds to the session, so the policy is skipped for them.
- All credentials issued with one access token form one set (for example a batch of 40 fetched in four requests). The first credential issued with a new access token, including a refreshed one, revokes the previous set.
- A different issuer or subject identifier counts as a different person. EUDIPLO stores only a pseudonymous, configuration-scoped fingerprint of the subject, derived from the encryption root key, so that key must stay stable while active credentials exist.
- Revocation is only seen by verifiers that check the status list.
How the fingerprints and the revocation sequence work is described in [Issuance under the hood](../concepts/issuance.md).
#### Revoke credentials with their wallet unit
`revokeWithWalletUnit: true` revokes a credential when the wallet provider revokes the wallet unit attestation (the key attestation of the proof) it was issued to. It requires `statusManagement: true` and `config.keyAttestationsRequired`. See [Revoke credentials with their wallet unit](../trust/attestation.md#revoke-credentials-with-their-wallet-unit).
### 7. Publish EUDI policies (optional)
#### Publish a reuse policy
`config.credentialReusePolicy` publishes how wallets should use a batch of credentials, as defined in ARF Annex II. EUDIPLO publishes it as `credential_metadata.credential_reuse_policy` of the credential configuration in the issuer metadata; it does not enforce it.
```json
{
"config": {
"credentialReusePolicy": {
"id": "arf_annex_ii",
"options": [
{
"details": ["once_only"],
"batch_size": 10,
"reissue_trigger_unused": 2
},
{
"details": ["limited_time"],
"reissue_trigger_lifetime_left": 86400
}
]
}
}
}
```
`details` accepts `once_only`, `limited_time` (or `limited-time`), `rotating-batch` and `per-relying-party`. The required companion fields per value are listed in the [reference](../reference/credential-configuration.md). Wallets fetch several credentials at once only if the issuer's [`batchSize`](issuance-configuration.md) is larger than 1.
#### Publish an embedded disclosure policy
`embeddedDisclosurePolicy` tells wallets to which relying parties the credential may be disclosed. EUDIPLO publishes it as `disclosure_policy` of the credential configuration in the issuer metadata. The `policy` field selects the variant:
| `policy` | `values` |
| --- | --- |
| `none` | none |
| `allowList` | Array of relying party identifiers |
| `rootOfTrust` | One trust anchor identifier |
| `attestationBased` | Array of requirements, each with `credentials` (and optional `claims`, `credential_sets`) the relying party must present |
```json
{
"embeddedDisclosurePolicy": {
"policy": "allowList",
"values": ["https://verifier.example.com"]
}
}
```
Issuer registration certificates are covered in [Registration certificates](../trust/registration-certificates.md#issuer-registration-certificate). TS11 schema metadata (`schemaMeta`) is stored with the configuration; EUDIPLO currently publishes it nowhere ([field reference](../reference/credential-configuration.md)).
### 8. Create the configuration
```bash
curl -X POST "$EUDIPLO_URL/api/issuer/credentials" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @membership.json
```
Update a configuration with `PATCH /api/issuer/credentials/{id}`, list them with `GET /api/issuer/credentials`, and remove one with `DELETE /api/issuer/credentials/{id}`. To manage configurations as files, see [Configuration as code](../operate/configuration-as-code.md).
**Check:** the credential appears in `credential_configurations_supported` of `GET /.well-known/openid-credential-issuer/issuers/{tenant}`. Next, [create an offer](credential-offers.md).
---
## Create credential offers
Start an issuance: your backend creates an offer, EUDIPLO returns an offer URI, and you show it to the wallet as a QR code or link. Which flow to offer is explained in the [issuance overview](index.md).
**Prerequisites:** a [credential configuration](credential-configuration.md), an [authorization server](authorization-servers.md) in the issuance configuration, and a client with the `issuance:offer` role.
### Create the offer
```bash
curl -X POST "$EUDIPLO_URL/api/issuer/offer" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"response_type": "uri",
"flow": "pre_authorized_code",
"credentialConfigurationIds": ["membership"],
"credentialClaims": {
"membership": { "type": "inline", "claims": { "name": "Max", "member_id": "M-001" } }
},
"offerLifetimeSeconds": 600
}'
```
EUDIPLO answers `201` with:
```json
{
"session": "a6318799-dff4-4b60-9d1d-58703611bd23",
"uri": "openid-credential-offer://?credential_offer_uri=https%3A%2F%2Feudiplo.example.com%2Fissuers%2Fmembership-demo%2Fvci%2Fcredential-offers%2F9b1e04c2-…"
}
```
- `uri` is the offer to render as QR code or deep link. The wallet resolves the offer by reference at `/issuers/{tenant}/vci/credential-offers/{offerId}`. `offerId` is the last segment of `credential_offer_uri`, a random value that is also the offer's `issuer_state` in the authorization code flow; it is not `session`, and the session ID is not accepted in its place.
- `session` identifies the issuance session. Use it to follow the status (`GET /api/session/{session}`: `active`, then `fetched` after the first credential, `completed` or `failed` after the wallet's [notification](notifications.md), or `expired`), to [revoke credentials](revocation.md) and to correlate [attribute provider](attribute-provider.md) requests.
`response_type` is required by the schema, but issuance offers always answer with this JSON; use `uri`. Unknown credential configurations and inline claims that do not match the configuration answer `409`, an unknown or disabled `authorization_server` answers `400`.
### Choose the flow and authorization server
| `flow` | Use it when | Authorization server |
| --- | --- | --- |
| `pre_authorized_code` | Your backend already knows the user. The offer contains a pre-authorized code; anyone who has the offer can redeem it, so protect it with a transaction code if needed. | Must be the built-in server (default if it is the first enabled entry). |
| `authorization_code` | The user must authenticate or present a credential first. The offer contains an `issuer_state`: a random value of the offer, not the session ID. | Set `authorization_server` to the `id` of the entry; without it, the first enabled entry is used. |
#### Transaction code
For pre-authorized offers, `tx_code` sets a code the user must type into the wallet; send it on a second channel. EUDIPLO advertises its length and `input_mode` (`numeric` if it consists of digits only, otherwise `text`) and shows `tx_code_description` as hint. A wrong code answers `invalid_grant`. After `txCodeMaxAttempts` failed attempts (issuance configuration, default 5) the pre-authorized code is invalidated, and even the correct code is rejected.
### Choose the claim source
`credentialClaims` sets the claim source per credential configuration of this offer. Keys must appear in `credentialConfigurationIds`; configurations without an entry use their attribute provider or static defaults.
| `type` | Shape | Use it when |
| --- | --- | --- |
| `inline` | `{ "type": "inline", "claims": { … } }` | The values are known now. They are validated when the offer is created. |
| `attributeProvider` | `{ "type": "attributeProvider", "attributeProviderId": "…" }` | Another [attribute provider](attribute-provider.md) than the configuration's should answer. |
| `webhook` | `{ "type": "webhook", "webhook": { "url": "…", "auth": { "type": "none" } } }` | A one-off endpoint with the [attribute provider contract](../reference/attribute-provider-api.md) should answer. |
Priority, identity and validation rules are described in [Claims](claims.md).
### Lifetime and expiry
Since 9.0, an offer can expire:
- `offerLifetimeSeconds` in the request, or the default `offerLifetimeSeconds` of the [issuance configuration](issuance-configuration.md), sets how long the offer can be redeemed. Without both, the offer does not expire until the session is removed by the session retention (`SESSION_TTL`, 24 hours by default).
- After expiry, the offer URI answers `404`, the token endpoint `invalid_grant` ("The credential offer has expired"), and authorization requests with its `issuer_state` are rejected. Tokens issued before keep their own lifetimes.
- The session's `expiresAt` holds the deadline. A maintenance job marks unredeemed offers as `expired` every `SESSION_TIDY_UP_INTERVAL`; expiry is enforced at request time regardless.
- Pre-authorized codes additionally expire with the session retention time (`SESSION_TTL` or the tenant's session settings).
### Single use
- The offer URI can be resolved once; later fetches answer `404`. Set `ISSUER_MULTI_CONSUMPTION=true` to allow repeated fetches, for example for wallets that load the offer twice.
- The code in the offer is redeemed once, at the token endpoint. A second token request answers `invalid_grant` ("The credential offer has already been used"). Refresh tokens stay usable.
- Create a new offer for every issuance.
### Your own reference
`reference` (optional, up to 255 characters) stores an identifier of your system with the session, for example an order or case ID. It is returned in the session list and detail, sent in the session's webhooks, and you can [find the session](../concepts/sessions.md#finding-sessions) by it later.
:::warning
The reference is stored in plaintext, unlike the claims, and stays when sessions are anonymized. Use an opaque identifier, never a name, email address or other personal data.
:::
### Restrict clients
A client with `allowedIssuanceConfigs` can only offer the listed credential configurations; other IDs answer `403`. See [Tenants and access](../operate/tenants-and-access.md).
### Request fields
---
## Deferred issuance
Issue a credential later, for example after a manual review or a background check. Your attribute provider tells EUDIPLO to defer, the wallet polls with a transaction ID, and your backend completes or fails the transaction through the management API.
**Prerequisites:** an [attribute provider](attribute-provider.md) (or offer `webhook` source) for the credential configuration, and a client with the `issuance:offer` role.
```mermaid
sequenceDiagram
autonumber
participant W as Wallet
participant E as EUDIPLO
participant B as Your backend
W->>E: Credential request
E->>B: Attribute provider request
B-->>E: {"deferred": true, "interval": 5}
E-->>W: 202 {"transaction_id", "interval"}
W->>E: Deferred credential request
E-->>W: 400 issuance_pending
B->>E: POST /api/issuer/deferred/{transactionId}/complete
W->>E: Deferred credential request
E-->>W: 200 {"credentials": [{"credential"}]}
```
### 1. Defer in the attribute provider
Answer the attribute provider request with:
```json
{ "deferred": true, "interval": 5 }
```
EUDIPLO stores the wallet's holder key and answers the wallet with HTTP `202` and `{ "transaction_id": "…", "interval": 5 }`. `interval` (seconds, default 5) is the polling interval suggested to the wallet.
Deferred requests must carry exactly one key proof with a `nonce`; batch requests (several proofs) are rejected with `invalid_proof`.
### 2. Let the wallet poll
The wallet polls `POST /issuers/{tenant}/vci/deferred_credential` with `{"transaction_id": "…"}` and the access token of the issuance (with DPoP when `dPopRequired` is set). Like the credential request, the poll can be encrypted and can ask for an encrypted response; see [Encryption flags](issuance-configuration.md#encryption-flags). While the transaction is pending, it receives HTTP `400`:
```json
{ "error": "issuance_pending", "error_description": "The credential issuance is still pending", "interval": 5 }
```
### 3. Complete or fail the transaction
When your process has finished, provide the claims:
```bash
curl -X POST "$EUDIPLO_URL/api/issuer/deferred/$TRANSACTION_ID/complete" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "claims": { "name": "Max", "member_id": "M-001" } }'
```
EUDIPLO signs the credential immediately and answers `200` with `{ "transactionId", "status": "ready", "message" }`. The claims are validated against the configuration's `fields` like every other [claim source](claims.md#validation); `claims` holds the claim values directly, not keyed by configuration ID.
If the credential must not be issued:
```bash
curl -X POST "$EUDIPLO_URL/api/issuer/deferred/$TRANSACTION_ID/fail" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "error": "Identity verification failed" }'
```
`error` is optional; the wallet's next poll receives `invalid_transaction_id` with it as description. `complete` answers `404` for an unknown transaction or one that is no longer pending, `fail` for an unknown transaction.
:::caution[Transaction ID]
EUDIPLO currently does not send the `transaction_id` to your backend: the attribute provider request carries only the session ID, and no management endpoint lists transactions. Only the wallet receives the ID.
:::
### Transaction states
| Status | Meaning | Wallet's next poll |
| --- | --- | --- |
| `pending` | Waiting for complete or fail | `issuance_pending` |
| `ready` | Credential signed | `{"credentials": [{"credential": "…"}]}` (once) |
| `retrieved` | The wallet fetched the credential | `invalid_transaction_id` |
| `failed` | Marked as failed | `invalid_transaction_id` |
| `expired` | 24 hours passed since the transaction was created | `invalid_transaction_id` |
Expired transactions are deleted every hour. A poll with an access token that does not belong to the transaction's session also answers `invalid_transaction_id`.
---
## Issuance
EUDIPLO issues SD-JWT VC (`dc+sd-jwt`) and mDOC (`mso_mdoc`) credentials over OpenID for Verifiable Credential Issuance (OID4VCI). You configure the issuer once, define a credential configuration per credential type, and create an offer for every issuance. Pick the flow that matches how you know the user.
### Choose a flow
| Situation | Offer `flow` | Authorization server | Claims come from | Guide |
| --- | --- | --- | --- | --- |
| Your backend already knows the user, for example in a logged-in portal | `pre_authorized_code`, optionally with a transaction code | [`built-in`](authorization-servers.md#built-in) | Inline offer claims, an attribute provider or static defaults | [First credential](../cookbooks/first-credential.md), [Credential offers](credential-offers.md) |
| The user logs in at your OpenID provider (Keycloak, Entra ID, …) | `authorization_code` | [`chained`](authorization-servers.md#chained) | Attribute provider, with the upstream user as identity | [Issue after login](../cookbooks/issue-after-login.md) |
| Your OAuth server issues the access tokens and can carry the offer's `issuer_state` | `authorization_code` (an offer is required) | [`external`](authorization-servers.md#external) | Offer claims or attribute provider; static defaults are not accepted | [External](authorization-servers.md#external) |
| The user proves who they are with a PID or another credential | `authorization_code` | [`oid4vp`](authorization-servers.md#oid4vp) | Attribute provider, which receives the presented claims | [OID4VP](authorization-servers.md#oid4vp) |
| The user completes steps in the wallet (presentation, web form) before issuance; experimental | `authorization_code` | `built-in` with interactive authorization | Attribute provider, which receives the presented claims | [Interactive authorization](interactive-authorization.md) |
| The wallet starts without an offer | none (wallet-initiated) | `built-in` | Attribute provider or static defaults | [Built-in](authorization-servers.md#built-in) |
Only tokens of an external authorization server need a dynamic claim source (offer claims or an attribute provider); in all other flows, static defaults are accepted, and an attribute provider is the recommended source for user-specific claims. To issue after a manual review, let the attribute provider [defer the credential](deferred-issuance.md).
### Build an issuer
1. [Configure the issuer](issuance-configuration.md): display, authorization servers, batch size, DPoP and offer lifetime.
2. [Configure a credential](credential-configuration.md) per credential type: format, type, claims, display, key binding, lifetime and revocation. All fields: [credential configuration reference](../reference/credential-configuration.md).
3. Decide where claim values come from: [Claims](claims.md), [Attribute providers](attribute-provider.md), [Deferred issuance](deferred-issuance.md).
4. [Create offers](credential-offers.md) from your backend.
5. After issuance: [receive wallet notifications](notifications.md) and [revoke or suspend credentials](revocation.md) ([cookbook](../cookbooks/revocable-credentials.md)).
Which OID4VCI features and formats are supported in detail is listed in [Protocols](../reference/protocols.md). How issuance works internally is described in [Issuance under the hood](../concepts/issuance.md).
---
## Interactive authorization (experimental)
:::caution[Experimental]
The Interactive Authorization Endpoint (IAE) follows a draft extension of OID4VCI. Its behavior may change in minor releases.
:::
Require the user to complete steps in the wallet, such as presenting a PID or finishing a web form, before EUDIPLO issues the authorization code. The steps run at the built-in authorization server's IAE, `POST /issuers/{tenant}/authorize/interactive`, which the server metadata advertises as `interactive_authorization_endpoint`.
**Prerequisites:** the [built-in authorization server](authorization-servers.md#built-in), a [presentation configuration](../presentation/configure-verification.md) for presentation steps, and a wallet that supports the IAE.
### 1. Configure the actions
Add `iaeActions` to the [credential configuration](credential-configuration.md). The wallet completes them in order:
```json
{
"id": "citizen",
"iaeActions": [
{
"type": "openid4vp_presentation",
"label": "Identity verification",
"presentationConfigId": "pid"
},
{
"type": "redirect_to_web",
"label": "Registration",
"url": "https://issuer.example.com/register"
}
]
}
```
| Action | Fields | What the user does |
| --- | --- | --- |
| `openid4vp_presentation` | `presentationConfigId` (required), `label` | Presents credentials matching the presentation configuration. |
| `redirect_to_web` | `url` (required), `label`, `description`, `callbackUrl` | Completes an interaction on your web page. `url`, `description` and `callbackUrl` are stored but not sent to the wallet; you send the user to the page yourself. |
EUDIPLO uses the actions of the credential configuration named in the first entry of the wallet's `authorization_details`. If that configuration has no actions, EUDIPLO picks one step from the wallet's `interaction_types_supported`: a presentation with the tenant's most recent presentation configuration, otherwise a web step.
### 2. Create an authorization code offer
Create an offer with `"flow": "authorization_code"` for the built-in server, see [Credential offers](credential-offers.md). The wallet passes the offer's `issuer_state` to the IAE. Since 9.0 it must belong to an offer that can still be redeemed: an authorization code offer of the tenant that has not expired or finished. Otherwise the IAE answers `invalid_request`.
### 3. Run the steps
The wallet starts with `client_id`, `interaction_types_supported`, `issuer_state`, `authorization_details` and PKCE. Since 9.0, `code_challenge_method` must be `S256`; `plain` is rejected. EUDIPLO answers with the first step and an `auth_session`, valid for 10 minutes:
```json
{ "status": "require_interaction", "type": "openid4vp_presentation", "auth_session": "…", "openid4vp_request": { "request": "client_id=…&request_uri=…" } }
```
**Presentation step.** The wallet resolves the request, then sends `auth_session` and `openid4vp_response`. Since 9.0, `openid4vp_response` must be the OpenID4VP authorization response as a JSON string, with the encrypted `response` (`direct_post.jwt`). EUDIPLO verifies it like any presentation (decryption, `state`, nonce, audience, DCQL and issuer trust) and answers `access_denied` if it fails. The verified claims are stored on the issuance session and sent to attribute providers in `credentials` ([Attribute provider API](../reference/attribute-provider-api.md)). Each presentation step creates a presentation session of its own; since 10.0 its ID, which `GET /api/session` lists, is not the `auth_session`, so it cannot continue the authorization.
**Web step.** EUDIPLO answers with `"type": "redirect_to_web"`. When the user has finished on your page, your backend marks the step as done:
```bash
curl -X POST "$EUDIPLO_URL/issuers/membership-demo/authorize/interactive/complete-web-auth/$AUTH_SESSION" \
-H "Authorization: Bearer $TOKEN"
```
Since 9.0 this call requires a management token with the `issuance:offer` role of the same tenant (`401` without a token, `403` for another tenant). It has no body and answers `{"success": true}`; an unknown or already completed `auth_session` answers `{"error": "not_found"}`. The wallet then sends `auth_session` and its `code_verifier`.
**Completion.** After the last step EUDIPLO answers `{"status": "ok", "code": "…"}`. Since 9.0 the code expires after 60 seconds. The wallet redeems it at `POST /issuers/{tenant}/authorize/token` with `grant_type=authorization_code`, `code` and `code_verifier`.
### Errors
The IAE answers errors with HTTP 400 and `{ "error", "error_description" }`:
| `error` | Typical cause |
| --- | --- |
| `invalid_request` | Missing `client_id`, `interaction_types_supported` or `code_challenge`; method not `S256`; invalid `issuer_state`; unknown, expired or used `auth_session`; reply that does not match the current step; malformed `openid4vp_response`. |
| `access_denied` | The presentation could not be verified, or the web step was not completed. |
| `invalid_grant` | `code_verifier` does not match the `code_challenge`. |
| `server_error` | No presentation configuration available, or the presentation request could not be created. |
---
## Configure the issuer
Set the issuer-wide settings of a tenant: how the issuer is shown in wallets, which authorization servers it offers, and how its token and credential endpoints behave. Each tenant that issues has exactly one issuance configuration; credential types are configured separately in [credential configurations](credential-configuration.md).
**Prerequisites:** a client with the `issuance:manage` role. In the web client, open **Credential Issuance → Issuer Settings**.
### 1. Write the configuration
```json
{
"display": [
{
"name": "Membership Demo",
"locale": "en",
"logo": { "uri": "https://issuer.example.com/logo.png", "alt_text": "Logo" }
}
],
"authorizationServers": [{ "type": "built-in", "id": "issuer-built-in" }],
"batchSize": 10,
"dPopRequired": true,
"offerLifetimeSeconds": 900
}
```
### 2. Store it
```bash
curl -X POST "$EUDIPLO_URL/api/issuer/config" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @issuance.json
```
`POST /api/issuer/config` creates the configuration or updates it field by field: each top-level field you send replaces the stored value as a whole (an `authorizationServers` array replaces all servers), fields you leave out keep their stored value, and `null` clears the settings that accept it (`federation`, `registrationCertificate`, `txCodeMaxAttempts`, `offerLifetimeSeconds`). `GET /api/issuer/config` returns it and creates a default one (a single built-in authorization server) if none exists. To manage it as a file, see [Configuration as code](../operate/configuration-as-code.md).
**Check:** `GET /.well-known/openid-credential-issuer/issuers/{tenant}` shows your `display`, the `authorization_servers` and the endpoints. Until the configuration exists, the well-known metadata and JWKS endpoints of the tenant answer `404`, as for a tenant that only verifies.
### Settings
| Field | Default | Effect |
| --- | --- | --- |
| `display` | none | Issuer name and logo per locale, published as `display` in the credential issuer metadata. Logos use `uri`; to host them in EUDIPLO, see [Object storage](../operate/object-storage.md). |
| `authorizationServers` | built-in server | Required, at least one entry. See [Authorization servers](authorization-servers.md). |
| `batchSize` | `1` | Batch issuance: how many credentials (one per key proof) a wallet may request at once. Values above 1 are published as `batch_credential_issuance.batch_size`. A key attestation proof may carry up to `batchSize` keys. |
| `dPopRequired` | `true` | Require DPoP-bound access tokens at the built-in token endpoint and the credential, deferred credential and notification endpoints. See [DPoP](authorization-servers.md#dpop). |
| `credentialRequestEncryption` | `false` | Sets `encryption_required` of `credential_request_encryption`; plain credential requests are then rejected. |
| `credentialResponseEncryption` | `false` | Sets `encryption_required` of `credential_response_encryption`; requests without response encryption are then rejected. |
| `notificationEndpointEnabled` | `true` | Publish and serve the [notification endpoint](notifications.md). |
| `txCodeMaxAttempts` | `5` | Failed transaction code attempts before a pre-authorized code is invalidated. `null` restores the default. See [Transaction code](credential-offers.md#transaction-code). |
| `offerLifetimeSeconds` | unset | Default lifetime of credential offers (9.0). Unset or `null`: offers do not expire. Offers can override it. See [Lifetime and expiry](credential-offers.md#lifetime-and-expiry). |
| `walletAttestationRequired`, `walletProviderTrustLists` | `false`, none | Defaults for wallet attestation at EUDIPLO's authorization servers; the trust lists also validate key attestations at the credential endpoint. See [Wallet and key attestation](../trust/attestation.md). |
| `walletAttestationStatusCheckMode` | unset (`best_effort`) | How the status list of a key attestation is checked at the credential endpoint, and default for wallet attestations at the authorization servers: `strict`, `best_effort` or `disabled`. `null` restores the default. See [Wallet and key attestation](../trust/attestation.md#2-require-wallet-attestation) and [key attestation](../trust/attestation.md#3-require-key-attestation). |
| `federation` | none | See [OpenID Federation](../trust/federation.md). |
| `registrationCertificate` | none | Publish a registration certificate in `issuer_info`. See [Registration certificates](../trust/registration-certificates.md). |
#### Encryption flags
EUDIPLO always advertises `credential_request_encryption` (its encryption key with `kid` and `alg` `ECDH-ES`, `enc` `A128GCM` or `A256GCM`) and `credential_response_encryption` (`alg` `ECDH-ES`, `enc` `A128GCM` or `A256GCM`). The two flags set `encryption_required` in these objects, and the credential and deferred credential endpoints enforce it. Set them only if every wallet you serve supports encryption.
A wallet that wants an encrypted response must also encrypt its request: a plain request with `credential_response_encryption` is rejected with `invalid_encryption_parameters`. So `credentialResponseEncryption: true` in effect requires encryption in both directions. An encrypted request names the advertised key with `kid` in the JWE header and uses that key's `alg` (`ECDH-ES`) and an `enc` of `A128GCM` or `A256GCM`, without `zip` or `crit`; other headers are rejected with `invalid_encryption_parameters`. An encrypted response names the wallet's key in the JWE header `kid` when that key has one.
The same rules apply when the wallet polls the deferred credential endpoint: it may send `{"transaction_id": "…"}` encrypted (`application/jwt`) and gets the credential back encrypted when the encrypted request carries `credential_response_encryption`. With `credentialRequestEncryption`, every poll must be encrypted; with `credentialResponseEncryption`, every poll must also carry `credential_response_encryption`. Errors such as `issuance_pending` stay plain JSON. See [Deferred issuance](deferred-issuance.md).
---
## Receive wallet notifications
Find out whether the wallet stored, rejected or deleted a credential. Wallets report this to the OID4VCI notification endpoint; EUDIPLO records the event on the issuance session, updates the session status and forwards the event to a webhook endpoint of your choice.
**Prerequisites:** a [webhook endpoint](../reference/webhooks.md) created under `/api/issuer/webhook-endpoints` (web client: **Integrations → Webhook Endpoints**).
### 1. Keep the endpoint enabled
The notification endpoint is enabled by default. EUDIPLO publishes it as `notification_endpoint` in the credential issuer metadata:
```text
POST /issuers/{tenant}/vci/notification
```
Set `notificationEndpointEnabled: false` in the [issuance configuration](issuance-configuration.md) to remove it from the metadata; requests then answer `404`.
### 2. Reference the webhook endpoint in the offer
Set `webhookEndpointId` when you [create the offer](credential-offers.md):
```json
{
"response_type": "uri",
"flow": "pre_authorized_code",
"credentialConfigurationIds": ["membership"],
"webhookEndpointId": "issuance-events"
}
```
Only the offer's `webhookEndpointId` is used. The field of the same name on a credential configuration is stored but ignored for notifications. Without a webhook endpoint, EUDIPLO still records the events on the session.
### 3. Handle the events
Each credential response contains a `notification_id`. The wallet sends it back with one event:
```json
{ "notification_id": "550e8400-e29b-41d4-a716-446655440000", "event": "credential_accepted" }
```
| `event` | Meaning | Session status after the first event |
| --- | --- | --- |
| `credential_accepted` | The wallet stored the credential. | `completed` |
| `credential_failure` | The wallet could not process it. | `failed` |
| `credential_deleted` | A user action stopped the issuance, for example the user rejected the credential. | `failed` |
For `credential_failure` and `credential_deleted`, the event becomes the session's `failureCode`, and `outcome.description` keeps the wallet's `event_description`; see [Session Outcome](../reference/session-outcome.md#issuance-notifications). The Web Client shows both on the session page.
The first event of a session decides its status and result. Later events, for another credential of the same offer or a repeated notification, are stored on their notification and posted to the webhook, but do not change the finished session.
EUDIPLO records the event and, for the first event, the session status, then posts the event to the webhook endpoint. The payload and the authentication options are described in [Webhooks](../reference/webhooks.md). Delivery is best effort and not retried: a failed delivery is logged and changes neither the session status nor the answer to the wallet. Use the notification ID to detect duplicates.
You can also read the recorded events from `notifications` of `GET /api/session/{id}`, for example to catch up after a failed delivery.
### Endpoint behavior
- The request must carry the access token of the issuance, with DPoP when the issuance configuration sets `dPopRequired`. The endpoint works with tokens of every authorization server type: built-in, external, chained and OID4VP.
- The body must contain `notification_id` and `event`. The wallet may add `event_description`, a text of printable ASCII characters without `"` and `\` (OID4VCI `%x20-21 / %x23-5B / %x5D-7E`); EUDIPLO stores it with the event as `eventDescription` and forwards it in the webhook. Other parameters are ignored. A body that breaks these rules answers `400`.
- A successful request answers `201` with an empty body.
- Since 9.0, a `notification_id` that was not issued for the token's session answers `400` with `{"error": "invalid_notification_id"}`. A missing or invalid access token answers `401` with `invalid_token`.
Attribute providers are not notification targets; they supply claims during issuance. See [Attribute providers](attribute-provider.md).
---
## Revoke and suspend credentials
Revoke or suspend credentials you issued, using Token Status Lists ([draft-ietf-oauth-status-list](https://datatracker.ietf.org/doc/draft-ietf-oauth-status-list/)). EUDIPLO assigns every credential an entry in a signed status list that verifiers fetch; you change entries per issuance session. For an end-to-end walkthrough, see the [revocable credentials cookbook](../cookbooks/revocable-credentials.md).
**Prerequisites:** a [credential configuration](credential-configuration.md) and a client with the `issuance:manage` role, which covers configuration and revocation, or `credentials:status` for revocation only. To open the session in the Web Client, the user also needs `issuance:offer` or `sessions:read`.
### 1. Enable status management
Set `statusManagement: true` on the credential configuration. Every credential issued afterwards carries a status reference:
```json
{
"status": {
"status_list": {
"idx": 4711,
"uri": "https://eudiplo.example.com/issuers/membership-demo/status-management/status-list/3f1c…"
}
}
}
```
SD-JWT VCs carry it as the `status` claim, mDOCs in the Mobile Security Object. Credentials issued before you enabled the setting have no status entry and cannot be revoked.
:::warning[Suspension needs 2 bits per entry]
Status lists use 1 bit per entry by default (`STATUS_BITS=1`), which only distinguishes valid and revoked. Suspending a credential on such a list is rejected with `400`. If you want to suspend credentials, set `bits` to `2` or more in the tenant's status list settings (or `STATUS_BITS`) **before** issuing. The `bits` of an existing list cannot be changed.
:::
### 2. Revoke or suspend
Use the session ID returned when you [created the offer](credential-offers.md):
```bash
curl -X POST "$EUDIPLO_URL/api/session/revoke" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "a6318799-dff4-4b60-9d1d-58703611bd23",
"credentialConfigurationId": "membership",
"status": 1
}'
```
| Field | Required | Description |
| --- | --- | --- |
| `sessionId` | yes | Issuance session that issued the credentials. |
| `credentialConfigurationId` | no | Restrict the change to one credential type. Without it, all credentials of the session change. |
| `status` | yes | `0` = valid, `1` = revoked, `2` = suspended. |
- The call answers `204 No Content`. It updates every credential of the session and type, including all credentials of a batch; without `credentialConfigurationId` it updates all credentials of the session. If the session has no status entry for the type, it answers `409`. A value that does not fit a list's bits per entry (for example `2` on a 1-bit list) is rejected with `400` before anything is changed.
- Allowed roles: `credentials:status` or `issuance:manage`. `issuance:offer` creates offers but cannot change the status.
- Revocation is final: setting `0` or `2` on a revoked credential is rejected with `409`, and nothing is changed. A suspension can be lifted (`0`) or turned into a revocation (`1`).
In the web client, open the session under **All Sessions**. The **Credential Status** card lists the credentials of the session per credential type and offers **Revoke**, **Suspend** and **Reinstate** where the change is allowed; Suspend only appears when every list of that type has at least 2 bits per entry. Opening the session needs `issuance:offer`, `presentation:request` or `sessions:read`, and changing the status on the card needs `credentials:status` or `issuance:manage`: `issuance:offer` alone shows the status without the buttons, and `issuance:manage` alone cannot open the session.
### 3. Check the result
Read the current status of a session's credentials:
```bash
curl "$EUDIPLO_URL/api/session/a6318799-dff4-4b60-9d1d-58703611bd23/credential-status" \
-H "Authorization: Bearer $TOKEN"
```
```json
[
{
"credentialConfigurationId": "membership",
"statusListId": "8f1c…",
"index": 42,
"status": 1,
"bits": 2,
"statusUpdatedAt": "2026-10-21T09:12:44.000Z"
}
]
```
There is one entry per issued credential that carries a status, so a batch issuance returns several entries for the same type. The list is empty when no credential of the session carries a status. `statusUpdatedAt` is when the status value last changed, through `POST /api/session/revoke`, when [`activeCredentials`](credential-configuration.md#keep-one-active-credential-per-subject) revokes a previous credential, or when [`revokeWithWalletUnit`](../trust/attestation.md#revoke-credentials-with-their-wallet-unit) revokes it. An update that sets the value the credential already has, or is rejected, does not change it. It is absent if the status has not changed since issuance, or only changed before this field was recorded. Allowed roles: `issuance:offer`, `issuance:manage`, `credentials:status` or `sessions:read`.
Verifiers resolve `status_list.uri` and read the bit at `idx`. Status list tokens are cached:
- By default a token is re-signed only after its `ttl` has passed (`STATUS_TTL`, 3600 seconds). A change becomes visible to verifiers within that time.
- With `immediateUpdate: true` (tenant setting or `STATUS_IMMEDIATE_UPDATE`), EUDIPLO re-signs the list after every change.
Verifiers may cache the token themselves until its `exp`.
### Public endpoints
These endpoints are wallet- and verifier-facing and have no `/api` prefix.
| Endpoint | Response |
| --- | --- |
| `GET /issuers/{tenant}/status-management/status-list/{listId}` | Status list token. JWT (`application/statuslist+jwt`) by default; CWT (`application/statuslist+cwt`) when the `Accept` header contains `application/statuslist+cwt`. |
| `GET /issuers/{tenant}/status-management/status-list-aggregation` | `{"status_lists": ["", …]}` with all lists of the tenant. |
The JWT has `typ: statuslist+jwt` and the signing certificate in `x5c`; its payload contains `sub` (the list URI), `iat`, `exp` (`iat` + `ttl`), `ttl` and `status_list` (`bits`, compressed `lst`). With aggregation enabled (`STATUS_ENABLE_AGGREGATION`, default `true`), tokens include `aggregation_uri` and the authorization server metadata advertises `status_list_aggregation_endpoint`.
### Manage status lists
EUDIPLO allocates entries automatically: first from lists bound to the credential configuration, then from shared lists, and when all are full it creates a new shared list. Indices are assigned in random order. You only need the management API to pre-create, bind or re-key lists. All endpoints require `issuance:manage`.
| Endpoint | Purpose |
| --- | --- |
| `GET /api/status-lists`, `GET /api/status-lists/{listId}` | List status lists with `bits`, `capacity`, `usedEntries`, `availableEntries`, `uri` and token `expiresAt`. |
| `POST /api/status-lists` | Create a list: `credentialConfigurationId` (bind it to one type; omit for a shared list), `keyChainId` (signing key: a `statusList` or `attestation` key chain; default: the tenant's status list key, else its attestation key), `bits` (1, 2, 4 or 8), `capacity` (1000 to 1,000,000). |
| `PATCH /api/status-lists/{listId}` | Change `credentialConfigurationId` or `keyChainId` (`null` resets to shared or default). `bits` and `capacity` are fixed. |
| `DELETE /api/status-lists/{listId}` | Delete an unused list. Lists with entries answer `409`. |
| `GET`, `PUT`, `DELETE /api/status-list-config` | Tenant defaults: `capacity` (minimum 100), `bits`, `ttl` (minimum 60 seconds), `immediateUpdate`, `enableAggregation`. `PUT` replaces the whole object; omitted fields fall back to the environment defaults. `DELETE` resets to them. |
The environment defaults are `STATUS_CAPACITY` (10000), `STATUS_BITS` (1), `STATUS_TTL` (3600), `STATUS_IMMEDIATE_UPDATE` (`false`) and `STATUS_ENABLE_AGGREGATION` (`true`); see [Environment variables](../reference/environment-variables.md#status). `capacity` and `bits` apply to lists created afterwards. Status lists can also be managed as files; see [Configuration as code](../operate/configuration-as-code.md). In the web client, open **Status Lists**.
To keep only one valid credential per person, combine status management with [`activeCredentials`](credential-configuration.md#keep-one-active-credential-per-subject). To revoke credentials when the wallet provider revokes the wallet unit they were issued to, set [`revokeWithWalletUnit`](../trust/attestation.md#revoke-credentials-with-their-wallet-unit).
---
## Configure Verification
A presentation configuration is the reusable definition of a verification: which credentials and claims to request, how long a request is valid, and where results go. Create it once, then start a [presentation request](requests.md) for every verification. All fields are listed in the [presentation configuration reference](../reference/presentation-configuration.md).
### Prerequisites
- A tenant client or user with the `presentation:manage` role.
- An access key chain with an active certificate. EUDIPLO signs every request with it. See [Keys and Certificates](../trust/keys-and-certificates.md).
- A [trust list](../trust/trust-lists.md) or an [OpenID Federation](../trust/federation.md) trust anchor for the issuers you accept. Every credential query must reference one. A trust anchor must first be [registered with its keys](../trust/federation.md#register-trust-anchors), in the Web Client under **Cryptographic Assets → Federation Trust Anchors**, through the API or the config folder.
- Optional: a webhook endpoint that receives the results (see [below](#send-results-to-your-backend)).
### In the Web Client
Open **Credential Verification → Verification Configs** and choose **Create config**. The guided setup has four steps:
1. **Name**: a unique ID (the `requestId` you use later) and an internal description.
2. **Credentials**: **Import from Issuer** reads credential types and claims from an issuer's metadata, **Import from Credential Config** reads them from the credential configs your own tenant issues, so the query asks only for credentials and claims that exist (when there are none yet, it links to create one in a new tab; after the save that tab says to return, and **Reload** lists it), **Import from Schema** starts from TS11 schema metadata at a URL, **Templates** (when creating) starts from a predefined query, and **Add credential** lets you enter the type and claims yourself. An import replaces the whole query and a template all settings except ID and Description; the editor asks first when there is something to lose. To combine credentials, import first, then use **Add credential**.
3. **Settings**: review the request lifetime (default 300 seconds), the status check mode (default strict) and the access key chain (default: the tenant's access key chain). The same section, **Request and verification options**, holds the redirect URI and the [allowed origins](#allowed-origins-digital-credentials-api) for the Digital Credentials API; further sections hold the **Registration certificate**, the webhook endpoint (**Application integration**) and **Transaction data**.
4. **Review**: check the request and choose **Create Verification Config**. Use **New Verification** on the saved configuration to test it with a wallet.
**Switch to editor** shows all sections at once; existing configurations open in this mode. **Use guided setup** returns to the steps. Both modes edit the same form.
#### Visual query builder and JSON
For SD-JWT VC, enter the credential type (VCT) and one field per claim path; use dots for nested paths such as `address.locality`, or paste a list of paths. For mDOC, enter the document type, namespace and element names. Type and paths must match the credential in the wallet, so importing them from the issuer avoids typos. While you type, the builder suggests the types and claims of your own credential configs and marks a claim that the matching credential config does not publish; it never blocks a type or claim, since you may ask for credentials issued elsewhere.
Each claim has optional settings for its ID, accepted values and (mDOC) intent to retain. Remove all claims of a credential to only check that the user holds a valid one ([without claims](dcql.md#check-a-credential-without-requesting-claims)). **Issuer trust** selects a managed trust list, an external trust list or a registered OpenID Federation trust anchor ([Trust Lists](../trust/trust-lists.md), [OpenID Federation](../trust/federation.md); federation works for SD-JWT VCs only, use a trust list for mDOCs); every credential needs at least one. An ETSI TS 119 612 Trusted List for QEAAs is entered with **Edit DCQL JSON** ([Trusted Lists for QEAAs](../trust/trust-lists.md#trusted-lists-for-qeaas)), and a query with one stays in JSON mode. **Accepted credential combinations** defaults to requiring every credential; add alternatives to let the wallet choose (`credential_sets`).
**Edit DCQL JSON** opens the raw query for rules the builder does not cover, such as claim sets. A query that uses such rules stays in JSON mode so they are preserved. See [DCQL](dcql.md) for the query language.
### Via the API
Create the configuration with `POST /api/verifier/config`. This example requests the membership credential from the [cookbook](../cookbooks/first-presentation.md):
```json title="membership-check.json"
{
"id": "membership-check",
"description": "Verify a membership name and ID",
"dcql_query": {
"credentials": [
{
"id": "membership",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:example:membership:1"] },
"claims": [{ "path": ["name"] }, { "path": ["member_id"] }],
"trusted_authorities": [{ "type": "etsi_tl", "values": [{ "trustListId": "membership-issuers" }] }]
}
]
},
"lifeTime": 300,
"webhookEndpointId": "membership-results",
"redirectUri": "https://shop.example.com/verified?session={sessionId}"
}
```
```bash
curl -X POST "$EUDIPLO_URL/api/verifier/config" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data @membership-check.json
```
The schema is strict: unknown fields, such as an inline `webhook` or `registrationCert`, are rejected with `400`. The response contains the stored configuration plus the read-only fields `createdAt` and `updatedAt`; remove them before sending a configuration back.
| Task | Endpoint |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| List configurations | `GET /api/verifier/config` |
| Read one | `GET /api/verifier/config/{id}` |
| Change fields | `PATCH /api/verifier/config/{id}`: omitted fields keep their value, `null` clears a field |
| Delete | `DELETE /api/verifier/config/{id}` |
To manage configurations as files, place them in `config//presentation/.json`; the file name becomes the ID. See [Configuration as Code](../operate/configuration-as-code.md).
### Send results to your backend
A presentation configuration references a webhook endpoint by ID (`webhookEndpointId`); it has no inline webhook. Create the endpoint once per tenant, in the Web Client under **Integrations → Webhook Endpoints** or via the API:
```bash
curl -X POST "$EUDIPLO_URL/api/issuer/webhook-endpoints" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data '{
"id": "membership-results",
"name": "Membership results",
"url": "https://shop.example.com/eudiplo/webhook",
"auth": { "type": "apiKey", "config": { "headerName": "x-api-key", "value": "change-me" } }
}'
```
A single request can override the endpoint with an inline `webhook` object. When the webhook is called and how to handle it is described in [Receive Results](receive-results.md).
### Registration certificate
If the wallet ecosystem requires a registration certificate, request one from the registrar: in the Web Client, **Request from EUDI Hub** on the configuration's **Security** tab ([EUDI Hub](../trust/eudi-hub.md#request-a-registration-certificate)). EUDIPLO stores it in `registration_cert`, together with the purpose and privacy policy it was requested with, which the next request can reuse:
```json
{
"registration_cert": {
"jwt": "eyJ...",
"purpose": [
{ "lang": "de", "content": "Prüfung Ihrer Vereinsmitgliedschaft" },
{ "lang": "en", "content": "Check your club membership" }
],
"privacy_policy": "https://shop.example.com/privacy"
}
}
```
A certificate from another registrar goes into `registration_cert.jwt` the same way. It must be valid and cover the DCQL query exactly; request a new one after you change the query. The checks are described in [Registration Certificates](../trust/registration-certificates.md).
### Allowed origins (Digital Credentials API)
[DC API requests](requests.md#digital-credentials-api) (`dc-api` and `iso-18013-7`) are bound to the origin of the page that calls the wallet: OpenID4VP requests carry it in the signed `expected_origins` claim, ISO 18013-7 requests in the session transcript. The wallet checks it against the origin the browser reports and refuses requests from other pages. Your backend names that origin in each request (`expected_origin`). To limit which origins any caller may name, list them in `allowedOrigins`:
```json
{
"allowedOrigins": ["https://shop.example.com"]
}
```
With the list, EUDIPLO creates `dc-api` and `iso-18013-7` requests only for these origins, and a request without `expected_origin` uses the only listed origin. Without it, any origin the request names is accepted. `uri` requests do not use the list. Each entry is an origin in serialized form, such as `https://shop.example.com` or `http://localhost:4200`; the exact rules are in the [validation rules](../reference/presentation-configuration.md#validation-rules).
Set the list when callers you do not fully control create requests, for example a client whose secret runs in a browser. To start DC API requests from the Web Client for a configuration with the list, add the Web Client's origin as well, for example `http://localhost:4200`. Since 10.0.
### Reader authentication (ISO 18013-7)
Set `readerAuth: true` to sign the `DeviceRequest` of [ISO 18013-7 requests](requests.md#iso-18013-7-annex-c) with the access key chain (`accessKeyChainId`, or the [default access key chain](../trust/keys-and-certificates.md#default-access-key-chain)). The wallet then validates the reader certificate chain before it releases data. The setting has no effect on OpenID4VP requests, which are always signed.
Reader authentication signs with the stored private key, so it needs an access key chain on the `db` [KMS provider](../operate/kms.md). Access keys in an external KMS cannot be used for it.
### Next steps
- [DCQL](dcql.md): alternatives, claim sets and trusted issuers.
- [Create presentation requests](requests.md).
- [Receive results](receive-results.md).
---
## DCQL (Digital Credentials Query Language)
The `dcql_query` of a presentation configuration tells the wallet which credentials and claims to present. EUDIPLO uses the [DCQL of OpenID4VP 1.0](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-digital-credentials-query-l) and checks the response against the same query. Every field is listed in the [presentation configuration reference](../reference/presentation-configuration.md).
### Request a credential
Each entry in `credentials` is one credential query. `id`, `format`, `meta` and `trusted_authorities` are required; `meta` identifies the credential type, `trusted_authorities` the issuers you accept ([below](#accept-only-trusted-issuers)). The examples on this page leave `trusted_authorities` out to focus on the other options.
```json
{
"credentials": [
{
"id": "membership",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:example:membership:1"] },
"claims": [{ "path": ["name"] }, { "path": ["member_id"] }]
}
]
}
```
For mDOC, `meta.doctype_value` names the document type and each claim path is `[namespace, element]`:
```json
{
"credentials": [
{
"id": "pid",
"format": "mso_mdoc",
"meta": { "doctype_value": "eu.europa.ec.eudi.pid.1" },
"claims": [
{ "path": ["eu.europa.ec.eudi.pid.1", "given_name"] },
{ "path": ["eu.europa.ec.eudi.pid.1", "family_name"] }
]
}
]
}
```
- `credentials` needs at least one query. Query IDs use letters, digits, `_` and `-` and are unique; results, `credential_sets` and transaction data refer to them. EUDIPLO rejects configurations that break these rules.
- SD-JWT VC paths are property names, with numbers as array indexes (`["address", "locality"]`, `["nationalities", 0]`).
- Without `claim_sets`, the presented credential must disclose every listed claim; otherwise the presentation fails.
### Check a credential without requesting claims
Leave out `claims` to only check that the user holds a valid credential of a type, for example a valid membership, without asking for any of its data:
```json
{
"credentials": [
{
"id": "membership",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:example:membership:1"] }
}
]
}
```
The wallet then presents only what the credential always discloses: for SD-JWT VC the issuer-signed JWT with its claims that are not selectively disclosable, for mDOC no data elements. EUDIPLO checks signature, issuer trust, status and holder binding as usual. OpenID4VP does not allow an empty `claims` array, so leave the field out instead, and leave out `claim_sets` as well. In the Web Client, remove all claims of the credential ([visual query builder](configure-verification.md#visual-query-builder-and-json)).
This works for OpenID4VP requests; for [ISO 18013-7 requests](requests.md#iso-18013-7-annex-c) request at least one mDOC claim.
### Accept specific values
`values` lists the accepted values of a claim: strings, integers or booleans. It is sent to the wallet, which only offers matching credentials:
```json
{ "path": ["membership_level"], "values": ["gold", "platinum"] }
```
In OpenID4VP flows EUDIPLO checks the presented value again, because a wallet may ignore the constraint. The disclosed value must equal one of the listed values in type and value: `true` does not match `"true"`, and `18` does not match `"18"`. Otherwise the presentation fails with the code `claim_value_mismatch` ([failure codes](../reference/session-outcome.md#failure-codes)). A yes/no check, such as an age check, therefore only completes with the expected answer:
```json
{ "path": ["age_equal_or_over", "18"], "values": [true] }
```
With `claim_sets`, a set counts only if all its claims are disclosed with accepted values. If a path selects several array elements, one of them must match. mDOC values are compared by element name, like the presence check. [ISO 18013-7 requests](requests.md#iso-18013-7-annex-c) do not check `values`.
### Alternative claims
`claim_sets` lists alternative claim combinations by claim `id`. The credential must disclose every claim of at least one set; list the preferred set first. Each ID must match the `id` of a claim in the same query, otherwise the configuration is rejected:
```json
{
"id": "pid",
"format": "mso_mdoc",
"meta": { "doctype_value": "eu.europa.ec.eudi.pid.1" },
"claims": [
{ "id": "over18", "path": ["eu.europa.ec.eudi.pid.1", "age_over_18"] },
{ "id": "birth_date", "path": ["eu.europa.ec.eudi.pid.1", "birth_date"] }
],
"claim_sets": [["over18"], ["birth_date"]]
}
```
### Alternative credentials
`credential_sets` combines credential queries by `id`. Each entry has `options`, a list of alternatives; every option lists queries that must be presented together. A set is required unless it has `"required": false`. Without `credential_sets`, every query in `credentials` is required.
This query accepts the PID either as SD-JWT VC or as mDOC, and optionally a membership credential:
```json
{
"credentials": [
{
"id": "pid_sd_jwt",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:eudi:pid:1"] },
"claims": [{ "path": ["family_name"] }]
},
{
"id": "pid_mdoc",
"format": "mso_mdoc",
"meta": { "doctype_value": "eu.europa.ec.eudi.pid.1" },
"claims": [{ "path": ["eu.europa.ec.eudi.pid.1", "family_name"] }]
},
{
"id": "membership",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:example:membership:1"] },
"claims": [{ "path": ["member_id"] }]
}
],
"credential_sets": [
{ "options": [["pid_sd_jwt"], ["pid_mdoc"]] },
{ "options": [["membership"]], "required": false }
]
}
```
EUDIPLO rejects a response that does not satisfy one option of every required set. Your backend sees which queries were answered by the `id` of each entry in the result.
### Several credentials of one type
By default a query matches one credential, and a response with several presentations for the same query fails. Set `"multiple": true` to accept several, for example all employee badges in the wallet:
```json
{
"id": "badges",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:example:employee-badge:1"] },
"multiple": true,
"claims": [{ "path": ["badge_id"] }]
}
```
### Intent to retain (mDOC)
For `mso_mdoc` claims, `intent_to_retain: true` tells the wallet and the user that you store the element after the presentation. It is sent in OpenID4VP requests; [ISO 18013-7 requests](requests.md#iso-18013-7-annex-c) always send `false`.
```json
{ "path": ["eu.europa.ec.eudi.pid.1", "family_name"], "intent_to_retain": true }
```
### Accept only trusted issuers
Every credential query names the issuers it accepts in `trusted_authorities`, from a trust list or an OpenID Federation:
```json
{
"trusted_authorities": [{ "type": "etsi_tl", "values": [{ "trustListId": "membership-issuers" }] }]
}
```
How trust lists are resolved, what the wallet receives (`aki` values) and how the issuer chain is checked is described in [Trust Lists](../trust/trust-lists.md#use-a-trust-list-in-a-presentation); federation trust anchors in [OpenID Federation](../trust/federation.md).
A presentation configuration with a credential query without `trusted_authorities` is rejected with `400`, and a configuration stored before 9.0 without them fails verification. For development and interoperability tests, `SKIP_TRUST_AUTHORITY=true` allows such queries; EUDIPLO then verifies the signature but not who issued the credential. See [Skip flags](../reference/environment-variables.md#skip-flags).
---
## Credential Presentation
EUDIPLO verifies credentials from EUDI wallets with OpenID4VP and, for mDOCs in the browser, ISO/IEC 18013-7 Annex C. You define what to request once in a presentation configuration and create one request per verification. Pick the flow that matches where the user and the wallet are.
### Choose a flow
| Flow | When to use | Request (`response_type`) | How the result reaches you |
| ---------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------- |
| QR code (cross-device) | The user opens your page on a computer and scans with the phone wallet. | `uri`, show `crossDeviceUri` as QR code | Webhook, SSE or polling; the wallet does not redirect |
| Same-device redirect | Your page and the wallet run on the same phone. | `uri`, open `uri`, set `redirectUri` | The wallet returns the browser to `redirectUri` with `response_code` |
| Digital Credentials API | A browser that supports the DC API asks the wallet directly, without QR code or app switch. | `dc-api` | The browser posts the wallet response; webhook, SSE or polling |
| ISO 18013-7 Annex C (`org-iso-mdoc`) | mDOC requests in browsers without the OpenID4VP profile of the DC API, such as Safari. | `iso-18013-7` | The browser posts the encrypted response; webhook, SSE or polling |
Presentations can also be part of issuance, for example to issue a credential only after the wallet presents a PID. See [Interactive Authorization](../issuance/interactive-authorization.md) and [Authorization Servers](../issuance/authorization-servers.md).
### Pages in this section
1. [Configure verification](configure-verification.md): create the reusable presentation configuration in the Web Client or via the API.
2. [DCQL](dcql.md): describe which credentials and claims to request.
3. [Create presentation requests](requests.md): start a verification for each flow above.
4. [Transaction data](transaction-data.md): bind a transaction, such as a payment, to the presentation.
5. [Receive results](receive-results.md): get the verified claims by webhook, SSE, polling or redirect.
6. [Sign-in with OpenID Connect](openid-connect.md): let an application that speaks OpenID Connect receive the verified claims in an ID token.
Field and status references: [Presentation configuration](../reference/presentation-configuration.md), [Session outcome](../reference/session-outcome.md), [Webhooks](../reference/webhooks.md). For how a presentation works internally, see [Presentation concepts](../concepts/presentation.md).
To try the complete flow with a wallet, follow the [cookbook](../cookbooks/first-presentation.md).
---
## 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](../cookbooks/sign-in-with-wallet.md). This is the opposite direction of [Other OIDC providers](../operate/oidc-provider.md), where EUDIPLO trusts an external provider for its own management API.
### Before you start
- A [presentation configuration](configure-verification.md) that requests what the user presents. It must not define [transaction data](transaction-data.md): 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:
```bash
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.
- **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](https://www.rfc-editor.org/rfc/rfc9126)); 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 `/.well-known/openid-configuration`:
```text
https://eudiplo.example.com/verifiers//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](../trust/keys-and-certificates.md#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](../reference/webhooks.md):
```json
{
"iss": "https://eudiplo.example.com/verifiers/root/oidc",
"sub": "3f0c1d9e-4c1b-4f63-9a59-2f4f0b6a2c11",
"aud": "",
"auth_time": 1760000000,
"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.
```json
{
"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:
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.
---
## Receive Results
After you [create a presentation request](requests.md), the result arrives in the session whose ID the request returned. Your backend can be called by a webhook, follow a stream of status events, or poll the session; same-device flows also return the user's browser to you. States, failure codes and the `outcome` structure are listed in the [session outcome reference](../reference/session-outcome.md).
| Method | Use when |
| ----------------------------------------------- | ------------------------------------------------------------------------ |
| [Webhook](#webhook) | Your backend should be told about every completed or failed presentation. |
| [Server-Sent Events](#server-sent-events) | A page or service waits for one session, for example next to a QR code. |
| [Polling](#polling) | You cannot receive webhooks or keep a stream open. |
| [Same-device redirect](#same-device-redirect) | The wallet runs on the same device and should return the user to your page. |
### Webhook
EUDIPLO calls a webhook when a presentation reaches `completed` or `failed`. It uses the inline `webhook` of the request if present, otherwise the webhook endpoint referenced by the configuration's `webhookEndpointId` ([Configure Verification](configure-verification.md#send-results-to-your-backend)). Expiry does not trigger a webhook.
The body always contains `status`, `outcome` and `session`, plus `transaction_data` if the request used it. Only a completed presentation also carries `credentials`, the disclosed claims per DCQL credential query ID:
```json
{
"status": "completed",
"outcome": { "result": "success", "source": "verifier", "credentials": [{ "id": "membership", "verified": true, "trust": { "matchedIssuer": "Membership Demo", "matchMode": "ca" } }] },
"credentials": [{ "id": "membership", "values": [{ "name": "Max", "member_id": "M-001" }] }],
"session": "3f0c1d9e-4c1b-4f63-9a59-2f4f0b6a2c11"
}
```
A failed presentation, for example because the user declined, sends `"status": "failed"` with the reason in `outcome` and no credentials. The complete payload is described in [Webhooks](../reference/webhooks.md).
- **Raw tokens:** list credential query IDs in `includeRawTokensFor` of an inline request `webhook` to also receive the presented token (for example the SD-JWT) as `rawToken`. Webhook endpoints have no such option.
- **Redirect override:** answer with `{ "redirectUri": "https://shop.example.com/done" }` to send the user there instead of the configured `redirectUri`. This works for completed and, for OpenID4VP, failed presentations.
- **Delivery:** EUDIPLO makes one delivery attempt (following [redirects](../reference/webhooks.md#delivery)) and does not retry. A failed delivery is logged and does not change the session, so reconcile missed results by [polling](#polling). Webhook URLs must pass the [outbound URL policy](../reference/webhooks.md).
### Server-Sent Events
Subscribe from your backend to `GET /api/session/{id}/events` with the access token in the `Authorization` header. The stream is authorized like `GET /api/session/{id}`, so presentation sessions need `presentation:request` (or `sessions:read`, which reads sessions without creating requests). Tokens in the URL are not accepted, which keeps management tokens out of access logs. The browser's `EventSource` cannot send headers: read the stream in your backend and pass the status on to your page, and never hand the management token to the browser.
```bash
curl -N "$EUDIPLO/api/session/$SESSION/events" -H "Authorization: Bearer $TOKEN"
```
With [`@eudiplo/sdk-core`](../reference/api.md#eudiplosdk-core), `subscribeToSession()` reads the stream with `fetch` and the client's token:
```javascript
const subscription = await client.subscribeToSession(sessionId, {
onStatusChange: ({ status }) => {
if (["completed", "failed", "expired"].includes(status)) {
// Read the result with GET /api/session/{id} and tell your page.
}
},
});
```
- The first event carries the current status, so a late subscriber does not miss a result.
- Each event has the form `{ "id": "", "status": "fetched", "updatedAt": "" }`; every status is sent once.
- The stream ends after `completed`, `failed` or `expired`. Changes processed by another replica arrive within a few seconds.
- A missing or invalid token returns `401`, a token without a session role `403`, an unknown session or one of the other type than the client's roles cover `404`.
### Polling
Read the session with `GET /api/session/{id}`. The caller needs the `presentation:request` role, or `sessions:read` to read results without creating requests; a client with only issuance roles gets `404` for presentation sessions. With `sessions:read` but without `presentation:request`, the session answers `404` until the wallet answered and then comes without `responseCode`, so polling and the [same-device check](#same-device-redirect) need `presentation:request`. Poll every one or two seconds until `status` is `completed`, `failed` or `expired`:
```json
{
"id": "3f0c1d9e-4c1b-4f63-9a59-2f4f0b6a2c11",
"status": "completed",
"requestId": "membership-check",
"expiresAt": "2026-10-03T10:05:00.000Z",
"consumedAt": "2026-10-03T10:01:12.000Z",
"responseCode": "6b1f0d0e-1c4e-4a54-8f7e-0b8f1c2d3e4f",
"credentials": [{ "id": "membership", "values": [{ "name": "Max", "member_id": "M-001" }] }],
"outcome": { "result": "success", "source": "verifier", "credentials": [{ "id": "membership", "verified": true, "trust": { "matchedIssuer": "Membership Demo", "matchMode": "ca" } }] }
}
```
The response contains further session fields; the result fields are explained in the [session outcome reference](../reference/session-outcome.md). A request that runs out its lifetime is rejected immediately, but its status changes to `expired` only when the session maintenance job runs (`SESSION_TIDY_UP_INTERVAL`, default one hour). Stop waiting once `expiresAt` has passed.
### Same-device redirect
When the request has a `redirectUri`, the wallet sends the user's browser back to it after the presentation. EUDIPLO replaces `{sessionId}` and appends a one-time `response_code`:
```text
https://shop.example.com/verified?session=3f0c1d9e-4c1b-4f63-9a59-2f4f0b6a2c11&response_code=6b1f0d0e-1c4e-4a54-8f7e-0b8f1c2d3e4f
```
Before you accept the result for this browser:
1. Read the session with `GET /api/session/{id}` from your backend.
2. Check that `status` is `completed` and that `responseCode` equals the `response_code` from the URL.
3. Only then attach the verified claims to the browser's session.
The check proves that this browser received the redirect, so an attacker cannot make a victim complete a session the attacker started ([OID4VP §13.3](../concepts/sessions.md#session-binding-oid4vp-133)). EUDIPLO has no lookup by response code; always start from the session ID you stored when you created the request.
If the presentation fails, the redirect carries `error` and `error_description` instead of a `response_code`. A declined request uses the wallet's error code, such as `access_denied`; a failed verification uses `invalid_request`. ISO 18013-7 requests redirect only after success.
Requests are single-use, and sessions are deleted or anonymized after the tenant's retention time; see [Sessions](../concepts/sessions.md).
---
## Create Presentation Requests
Every verification starts with `POST /api/verifier/offer`. It creates a session from a [presentation configuration](configure-verification.md) and returns what you hand to the wallet or the browser. The caller needs the `presentation:request` or `presentation:manage` role; `presentation:request`, or `sessions:read`, can also read the resulting session ([what `sessions:read` sees](../operate/tenants-and-access.md#api-clients-with-least-privilege)). An API client with `allowedPresentationConfigs` may only use the listed configurations.
### Request body
The annotated body below is generated from the request schema at build time. Placeholder values and comments are for reference; it is not a ready-to-send payload. The nested webhook authentication shows one variant inline and the other as a comment.
A minimal request only names the flow and the configuration:
```json
{
"response_type": "uri",
"requestId": "membership-check"
}
```
#### Override rules
`webhook`, `redirectUri`, `transaction_data` and `skewSeconds` in the request replace the values of the presentation configuration for this session only. Values are replaced, not merged: a request `webhook` replaces the configuration's webhook endpoint, and request `transaction_data` replaces the whole configured list. `clientIdScheme`, `expected_origin` and `reference` exist only on requests. ISO 18013-7 requests use only `webhook`, `skewSeconds`, `expected_origin` and `reference`, and refuse transaction data (see [below](#iso-18013-7-annex-c)).
`reference` (optional, up to 255 characters) stores an identifier of your system with the session, for example an order or case ID. It is returned with the session, sent in the presentation webhook, and you can [find the session](../concepts/sessions.md#finding-sessions) by it later. It is stored in plaintext and stays when sessions are anonymized, so it must never contain personal data.
#### Response
```json
{
"uri": "openid4vp://?client_id=x509_hash%3A...&request_uri=https%3A%2F%2Feudiplo.example.com%2Fpresentations%2F%2Foid4vp%2Frequest&request_uri_method=get",
"crossDeviceUri": "openid4vp://?client_id=x509_hash%3A...&request_uri=https%3A%2F%2Feudiplo.example.com%2Fpresentations%2F%2Foid4vp%2Frequest%2Fno-redirect&request_uri_method=get",
"session": "3f0c1d9e-4c1b-4f63-9a59-2f4f0b6a2c11"
}
```
| Field | Use |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uri` | Same-device flow: open it on the phone. After the presentation the wallet sends the user to the `redirectUri`, if one is set. |
| `crossDeviceUri` | QR code for a wallet on another device. The wallet fetches the request from `.../request/no-redirect`, so it never redirects, even if `redirectUri` is set. |
| `session` | Session ID for [receiving the result](receive-results.md). The wallet never sees it; its URLs carry a separate random `walletNonce`. |
The request expires after the configuration's `lifeTime` (default 300 seconds). Create a new request for every verification: each one can be answered only once.
| Status | Cause |
| ------ | ---------------------------------------------------------------------------------------- |
| `400` | The body does not match the schema, `x509_san_dns` was requested for a certificate without DNS name, or `openid_federation` for a tenant without federation verifier entity, or, for `dc-api` and `iso-18013-7`, `expected_origin` is missing (unless `allowedOrigins` lists exactly one origin), not an `http(s)` origin, or not in the configuration's [`allowedOrigins`](configure-verification.md#allowed-origins-digital-credentials-api). Also when a `transaction_data` entry, from the request or else the configuration, breaks the rules in [Which credentials an entry may reference](transaction-data.md#which-credentials-an-entry-may-reference), or an `iso-18013-7` request would carry transaction data. |
| `403` | The API client is not allowed to use this `requestId`. |
| `404` | No presentation configuration with this `requestId` exists, or no usable access key chain: none exists, `accessKeyChainId` points to none, or its certificate is invalid. |
### QR code and same-device redirect
Use `response_type: "uri"` for both. Show `crossDeviceUri` as QR code when the user is on a computer; open `uri` when your page runs on the phone that has the wallet. For a same-device redirect, set `redirectUri`, for example `https://shop.example.com/verified?session={sessionId}`. EUDIPLO replaces `{sessionId}` and appends a one-time `response_code`, which your backend must check before it trusts the result ([Receive Results](receive-results.md#same-device-redirect)).
#### Client identifier
The wallet identifies EUDIPLO by the `client_id` in the request, set by `clientIdScheme`:
- `x509_hash` (default): `x509_hash:`. Works with any access certificate, including self-signed ones.
- `x509_san_dns`: `x509_san_dns:`. Use it when a wallet only accepts DNS-based client identifiers. Certificates that EUDIPLO generates contain the host name of `PUBLIC_URL`; an imported certificate without DNS name fails with `400`.
- `openid_federation`: `openid_federation:` of the tenant's [OpenID Federation entity](../trust/federation.md#oid4vp-requests-with-a-federation-client-identifier). The request object carries no certificate (`x5c`); the wallet picks the access key by its `kid` from the federation metadata, and the wallet takes the verifier metadata from the trust chain. Needs `openid_credential_verifier` in `federation.entityTypes` and a valid `federation.entityId` ([rule](../trust/federation.md#configure-federation-for-issuance)) in the issuance configuration, else `400`.
### Digital Credentials API
With `response_type: "dc-api"` the browser asks the wallet through `navigator.credentials.get()`; no QR code or app switch is needed. The wallet encrypts its answer for EUDIPLO (`response_mode: dc_api.jwt`) and binds it to the page's origin.
1. **Your backend creates the request** and passes the origin of the page that will call the DC API:
```json
{
"response_type": "dc-api",
"requestId": "membership-check",
"expected_origin": "https://shop.example.com"
}
```
`expected_origin` is required. Take it from your own configuration, never from end-user input: if your backend passes on the `Origin` header of the browser request it received, any website can have your verifier sign requests for it. The value is an `http` or `https` origin or URL; a path in it is ignored (`https://shop.example.com/checkout` stands for `https://shop.example.com`), and a value without scheme fails with `400`. If the presentation configuration has [`allowedOrigins`](configure-verification.md#allowed-origins-digital-credentials-api), the value must be one of them, and with exactly one listed origin you can leave it out. The `Origin` and `Host` headers of this call are not used; before 10.0, EUDIPLO fell back to them.
2. **Your backend reads the signed request object** from `GET /api/session/{session}` (field `requestObject`) and hands it to the page.
3. **The page calls the wallet:**
```javascript
const credential = await navigator.credentials.get({
mediation: "required",
digital: {
requests: [
{ protocol: "openid4vp-v1-signed", data: { request: requestObject } },
],
},
});
```
4. **The page posts the wallet response unchanged** to the `response_uri` claim of the request object (`/presentations//oid4vp`):
```javascript
const result = await fetch(responseUri, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(credential.data),
});
```
EUDIPLO verifies the presentation and answers `200` with `{}` or `{ "redirect_uri": "..." }`. A presentation that fails verification is answered with `400`; see [What the wallet or browser receives](../reference/session-outcome.md#what-the-wallet-or-browser-receives). Your backend receives the result by webhook, SSE or polling as in the other flows. If the body also contains `"sendResponse": true` and no redirect is configured, the answer contains the verified credentials.
`@eudiplo/sdk-core` wraps these steps. `isDcApiAvailable()` checks for browser support, and `verifyWithDcApi()` creates the request, calls the wallet and posts the response:
```typescript
import { EudiploClient, isDcApiAvailable } from "@eudiplo/sdk-core";
const client = new EudiploClient({ baseUrl, clientId, clientSecret });
if (isDcApiAvailable()) {
const { credentials } = await client.verifyWithDcApi({ configId: "membership-check" });
}
```
`verifyWithDcApi()` runs entirely in the browser and needs the API client's secret there. Use it for demos only; in production, keep steps 1 and 2 on your backend. Anyone who copies the secret can create requests for any origin, so set [`allowedOrigins`](configure-verification.md#allowed-origins-digital-credentials-api) on the configurations such a client may use.
### ISO 18013-7 Annex C
`response_type: "iso-18013-7"` uses the `org-iso-mdoc` protocol of the DC API, for browsers that do not support the OpenID4VP profile, such as Safari on iOS and macOS. It only requests mDOCs:
```json
{
"response_type": "iso-18013-7",
"requestId": "pid-mdoc",
"expected_origin": "https://shop.example.com"
}
```
The response carries CBOR structures instead of a request URI (`uri` and `crossDeviceUri` are empty):
```json
{
"session": "",
"uri": "",
"crossDeviceUri": "",
"org_iso_mdoc": {
"device_request": "",
"encryption_info": "",
"response_uri": "https://eudiplo.example.com/presentations//iso-18013-7"
}
}
```
The page passes `device_request` and `encryption_info` to `navigator.credentials.get()` with protocol `org-iso-mdoc` and posts the wallet's encrypted response as `{ "data": "" }` to the `response_uri`. It ends with a random `walletNonce`, not the session ID: the endpoint answers the session ID with `404`, so someone who only knows the session ID from the management API or a webhook cannot answer in the holder's place. Since 10.0; in 9.x the page posted to `/presentations/{session}/iso-18013-7`. EUDIPLO answers `200` with `{}` or `{ "redirect_uri": "..." }`; a failed verification returns `400` with `error` and `message` ([failure codes](../reference/session-outcome.md#failure-codes)).
Differences from the OpenID4VP flows:
- Only the first `mso_mdoc` credential of the DCQL query is requested; its `meta.doctype_value` is required. Other credentials, `credential_sets` and `claim_sets` are ignored.
- Every element is requested with intent to retain `false`, whatever `intent_to_retain` says.
- Request at least one claim. Without `claims`, EUDIPLO still sends the request with an empty element list, which ISO 18013-5 does not allow, so wallets may reject it.
- `redirectUri` and `clientIdScheme` from the request are ignored; the configuration's `redirectUri` still applies after a successful presentation.
- The request cannot carry transaction data, so it answers `400` when the request sets `transaction_data` entries, or the configuration has some and the request does not send `"transaction_data": []`. Otherwise the session would complete without the holder authorizing the transaction.
- `expected_origin` must equal the origin of the page that calls the DC API, because the session transcript is bound to it. The same rules as for `dc-api` apply: it is required unless the configuration's [`allowedOrigins`](configure-verification.md#allowed-origins-digital-credentials-api) lists exactly one origin, and must be one of them when they are set.
- Elements the wallet does not return are not rejected separately, and `values` constraints are not checked; check the claims in the result.
- Set [`readerAuth`](configure-verification.md#reader-authentication-iso-18013-7) to sign the request so the wallet can authenticate the verifier.
---
## Transaction Data
Transaction data binds a presentation to a concrete transaction, such as a payment. The wallet shows it to the user, and the holder's signature over the presentation includes a hash of it, so your backend knows the user approved exactly this transaction. EUDIPLO implements [OpenID4VP transaction data](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-transaction-data) and validates the TS12 strong customer authentication types.
### Add transaction data
Set `transaction_data` in the presentation configuration, or per request in `POST /api/verifier/offer`. Request-level `transaction_data` replaces the configured list for that session; the two are not merged. ISO 18013-7 requests cannot carry transaction data: creating one answers `400` when there are entries to send, so send `"transaction_data": []` to use a configuration with transaction data over ISO 18013-7.
Each entry needs:
| Field | Description |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `type` | Transaction data type. Wallets must reject types they do not support, so use one your target wallets know, such as a TS12 type. |
| `credential_ids` | IDs of the DCQL credential queries that may authorize the transaction. Each must be a `dc+sd-jwt` query of the DCQL query ([see below](#which-credentials-an-entry-may-reference)). |
| `transaction_data_hashes_alg` | Optional non-empty array of hash algorithms the wallet may use for this entry, for example `["sha-256", "sha-384"]`. Defaults to `sha-256` only. EUDIPLO can check `sha-256`, `sha-384` and `sha-512`; a hash with another listed algorithm fails. |
| other fields | Type-specific content. TS12 types put it in `payload`. |
EUDIPLO sends each entry base64url-encoded as JSON in the `transaction_data` parameter of the signed request.
#### Which credentials an entry may reference
`credential_ids` tells the wallet which credentials it may authorize the entry with. EUDIPLO checks transaction data only in SD-JWT VC presentations, so every ID must be a `dc+sd-jwt` query: a wallet that authorized with an mDOC would be rejected. Saving the configuration and `POST /api/verifier/offer` answer `400` when an entry:
- names no credential query,
- names an ID that is not a query of the configuration's DCQL query (`transaction_data[].credential_ids names ids that are not in the DCQL query: ...`), or
- names an `mso_mdoc` query (`transaction_data[].credential_ids names credential queries that are not dc+sd-jwt: ...`).
`` is the entry's zero-based position in `transaction_data`. The offer checks the transaction data it sends, so a configuration stored by an earlier version that breaks the rule answers `400` for every request that does not set its own `transaction_data`. In a [configuration bundle](../reference/config-bundle-format.md) or configuration folder, such a presentation configuration fails with `TRANSACTION_DATA_UNCHECKABLE`.
An entry may reference queries that `credential_sets` offer as alternatives. The wallet must then present one of the credentials the entry references and authorize the entry with it; the response fails otherwise (see below).
### TS12 SCA transaction data
Types starting with `urn:eudi:sca:` are validated when you save the configuration or create the request. Unsupported `urn:eudi:sca:` types and incomplete payloads are rejected with `400`.
| `type` | Required `payload` fields |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `urn:eudi:sca:payment:1` | `transaction_id`, `payee.name`, `payee.id`, `currency` (three upper-case letters), `amount` (number) |
| `urn:eudi:sca:login_risk_transaction:1` | `transaction_id`, `action` |
| `urn:eudi:sca:account_access:1` | `transaction_id` |
| `urn:eudi:sca:emandate:1` | `transaction_id` |
A payment confirmation request, with the credential query `payment_credential` defined in the configuration's DCQL query:
```json
{
"response_type": "uri",
"requestId": "payment-confirmation",
"transaction_data": [
{
"type": "urn:eudi:sca:payment:1",
"credential_ids": ["payment_credential"],
"payload": {
"transaction_id": "order-4711",
"payee": { "name": "Example Shop", "id": "merchant-001" },
"currency": "EUR",
"amount": 49.99
}
}
]
}
```
For TS12 entries, every key binding JWT that carries the entry's hash must additionally contain:
- a non-empty `jti`,
- `response_mode` equal to the request's response mode (`direct_post.jwt`, or `dc_api.jwt` with the DC API),
- `transaction_data_hashes_alg` set to `sha-256`,
- an `amr` array with factors from at least two of the categories `knowledge`, `possession` and `inherence`.
### How EUDIPLO checks the binding
The check applies to SD-JWT VC credentials; EUDIPLO does not check transaction data in mDOC presentations, whose format OpenID4VP leaves to each transaction data type. It runs once all credentials in the response are verified.
The wallet uses only one of the credentials an entry's `credential_ids` reference to authorize it ([OpenID4VP 1.0, section 5.1](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#section-5.1)). So for every entry, at least one presented SD-JWT VC it references must carry the entry's hash in `transaction_data_hashes` of its key binding JWT. The other referenced credentials do not need it. For example, with `"credential_ids": ["pid", "bank_card"]` and both credentials presented, the hash in the `bank_card` key binding JWT is enough. If a credential query allows several presentations (`multiple: true`) and the wallet uses that credential, each of its presentations must carry the hash, because the result does not say which one authorized the transaction; the hash in only some of them fails the response. Since mDOC presentations are not checked, a session created before the upgrade to 10.0 whose entry references an mDOC query needs the hash in a presented SD-JWT VC.
An entry for which the response contains no SD-JWT VC it references fails the response with `Transaction data entry references no presented SD-JWT VC (...)`. This happens when the wallet answers `credential_sets` with an option that leaves out every credential the entry references. A hash of the entry in another credential's key binding JWT does not count.
Each hash is computed over the base64url-encoded entry exactly as sent in the request, with the algorithm from `transaction_data_hashes_alg` in the key binding JWT (`sha-256` when absent). The algorithm must be one the entry's own `transaction_data_hashes_alg` allows, so `sha-384` and `sha-512` are only accepted when the entry lists them. Hashes may come in any order.
EUDIPLO also rejects the response when:
- two identical entries share one hash: each entry needs a hash of its own,
- the key binding JWT of a credential that an entry references contains a hash that matches no entry referencing that credential, for example the hash of an entry whose `credential_ids` do not list it, or of data EUDIPLO never sent. The same entry's hash in several referenced credentials is accepted. Key binding JWTs of credentials that no entry references are not checked.
- the key binding JWT of a credential that an entry references has `transaction_data_hashes` that is not an array of strings, or a `transaction_data_hashes_alg` that is not a string.
If a hash is missing or does not match, the presentation fails and the session is set to `failed` (see [Session Outcome](../reference/session-outcome.md)). On success, the session and the [webhook](../reference/webhooks.md) contain the `transaction_data` that was sent, so your backend can match the result to its transaction.
---
## Wallet and Key Attestation
During issuance, EUDIPLO can check two statements signed by the wallet provider: a wallet attestation, which proves that the wallet app is a genuine instance of a trusted wallet, and a key attestation, which describes how the holder keys are protected. Both are trusted through wallet-provider trust lists.
| | Wallet attestation | Key attestation |
| ------------------ | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Proves | The wallet, as OAuth client, is an app of a trusted wallet provider | The holder keys and their storage and user-authentication level |
| Checked at | PAR and token endpoints of EUDIPLO-managed authorization servers (`built-in`, `chained`, `oid4vp`) | Credential endpoint, including deferred issuance |
| Required by | `walletAttestationRequired` of the authorization server, else of the issuance configuration | Proof types allowed by the credential configuration (`config.proofTypesSupported`) |
| Trusted through | `walletProviderTrustLists` of the authorization server, else of the issuance configuration | `walletProviderTrustLists` of the issuance configuration only |
### 1. Provide wallet-provider trust lists
Wallet-provider trust lists are LoTE JWTs whose entities offer the service types `http://uri.etsi.org/19602/SvcType/WalletSolution`, `.../WalletSolution/Issuance` or `.../WalletSolution/Revocation`. In an `EUWalletProvidersList` where no service has a type, every service counts as `WalletSolution/Issuance` ([Service status and type](trust-lists.md#service-status-and-type)). Wallet and key attestations must be signed under a certificate listed as `WalletSolution` or `WalletSolution/Issuance`; a certificate listed only as `WalletSolution/Revocation` signs status lists, not attestations. A certificate the list names takes the place of a certificate in the attestation's `x5c` with the same subject and key. When the list names several such certificates, for example a provider's CA and its renewal, attestations are chained to the one that is currently valid, whichever the list names first. A list without a valid `NextUpdate`, or whose `NextUpdate` has passed, is discarded like every [trust list](trust-lists.md#how-a-trust-list-is-used): providers listed only in it are not trusted, providers in the other lists still are. Reference the lists like any [trust list](trust-lists.md):
- **External list**, for example the wallet provider list published for your ecosystem: `{ "url": "https://...", "verifierX509Der": "MIIB..." }`. Instead of the certificate, you can pin the signer's public key: as a JWK in `verifierKey`, or as a PEM public key (`-----BEGIN PUBLIC KEY-----`) in `verifierKeyPem`. The Web Client asks only for the certificate, as PEM or Base64 DER, and stores it as `verifierX509Der`; a public key already on an entry is kept until you enter a different certificate, and while it is there EUDIPLO verifies the list with the key only. Obtain this material through a trusted channel; it authenticates the list, not the providers in it.
- **Managed list** of this tenant: `{ "trustListId": "wallet-providers" }`. Create it under **Trust Lists** and set **Provider type → Wallet provider** on each entity (`"providerType": "wallet-provider"`). EUDIPLO then publishes `WalletSolution/Issuance` and `WalletSolution/Revocation` services; a list with only wallet-provider entities uses the wallet-provider scheme of ETSI TS 119 602 Annex E. In the Web Client, **Add managed trust list** offers the lists of the tenant that have a wallet provider entity; a list without one cannot match any attestation. If wallet and key attestations are signed by different provider CAs, list both.
Put the lists into the issuance configuration so that both checks can use them:
```json
{
"walletProviderTrustLists": [{ "trustListId": "wallet-providers" }],
"authorizationServers": [
{ "type": "built-in", "id": "issuer-built-in", "walletAttestationRequired": true }
]
}
```
Merge these fields into your issuance configuration ([Issuance Configuration](../issuance/issuance-configuration.md)). A presented wallet or key attestation without a configured trust list is always rejected; plain holder proofs without key attestation need no trust list.
### 2. Require wallet attestation
When wallet attestation is used, the wallet sends two headers to the PAR and token endpoints, following [OpenID4VCI Appendix E](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#appendix-E):
- `OAuth-Client-Attestation`: the attestation JWT signed by the wallet provider, with its certificate chain in `x5c` and the wallet instance key in `cnf`,
- `OAuth-Client-Attestation-PoP`: a proof of possession signed with that instance key.
EUDIPLO verifies both signatures, builds a certificate path from `x5c` to a wallet provider in the trust lists (an `x5c` may hold at most 10 certificates in total, a trust anchor included if it is sent, and should hold only the signing certificate and its intermediates; a longer one is rejected before a path is built, and so is a longer one on the attestation's status list), requires every certificate of that path, from the one that signs the attestation to the one the list names, to be within its validity period at the time of the request (both `notBefore` and `notAfter` included, without `CRYPTO_TOLERANCE`) and, if the attestation has a `status` claim, checks its entry in the status list. The status list must be signed under one of the provider's revocation certificates (any of its `WalletSolution/Revocation` services, or else any of its `EAA/Revocation` services), or under the certificate that signs its attestations if the provider lists neither. Every certificate of the list's path, from the one in its `x5c` that signs it to that revocation or attestation certificate, must be within its validity period at the time of the check, by the same rule as the attestation's path; for a listed end-entity certificate that signs the list itself, only that certificate. When the provider lists a revocation CA (or, without one, an attestation CA) and its renewal with the same subject and key, the list is chained to the one that is currently valid, whichever the trust list names first. It must also be typed `statuslist+jwt`, carry the attestation's status list URI as `sub`, have an `iat`, not be past its `exp` (allowing `CRYPTO_TOLERANCE` seconds of clock skew) and contain the attestation's index ([Token Status List, Section 8.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-status-list#section-8.3)). A list that decompresses to more than 16 MiB is rejected. `walletAttestationStatusCheckMode` decides what happens when the check fails or cannot be completed:
| Mode | Revoked or suspended | Status list cannot be fetched (network error, timeout, non-2xx, blocked URL) | Status list unreadable, not the named list, expired, index outside the list |
| ----------------------- | -------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------- |
| `strict` | Rejected | Rejected | Rejected |
| `best_effort` (default) | Rejected | Accepted, with a warning in the log | Rejected |
| `disabled` | Accepted | Accepted, the list is not fetched | Accepted |
A status list signed by another key, or under a certificate that has expired or is not yet valid, is rejected unless the mode is `disabled`, and so is a malformed `status` claim: one that is not a JSON object, an empty object, or one whose `status_list` is not an object with a `uri` that is an absolute URI and a non-negative integer `idx`. An attestation without a `status` claim is accepted in every mode, as is one whose `status` claim has no `status_list` (another status mechanism, which EUDIPLO does not check).
Each EUDIPLO-managed authorization server resolves three settings independently:
| Setting | Value used |
| ---------------------------------- | ------------------------------------------------------------------------------------ |
| `walletAttestationRequired` | The authorization server's value, else the issuance configuration's, else `false` |
| `walletProviderTrustLists` | The authorization server's list, else the issuance configuration's, else none |
| `walletAttestationStatusCheckMode` | The authorization server's value, else the issuance configuration's, else `best_effort` |
With `true`, requests without attestation are rejected; with `false`, a wallet may omit it, but an attestation it sends must still be valid and trusted. An empty list on the authorization server disables inheritance and rejects every presented attestation. The authorization server metadata advertises `attest_jwt_client_auth` only when attestation is required. In the Web Client, the authorization server settings offer **Use issuer default** (for **Wallet Attestation** and **Wallet Attestation Status Check**) and **Use shared wallet provider trust lists**. An external authorization server checks wallets according to its own configuration.
### 3. Require key attestation
Key attestations are configured per credential type, in the credential configuration's `config`:
```json
{
"config": {
"proofTypesSupported": ["attestation"],
"keyAttestationsRequired": {
"key_storage": ["iso_18045_high"],
"user_authentication": ["iso_18045_high"]
}
}
}
```
- `proofTypesSupported` limits the accepted proof types, `jwt` and `attestation` (default: both). A proof of another type is rejected with `invalid_proof`.
- `keyAttestationsRequired` is published as `key_attestations_required` for every supported proof type in the issuer metadata and enforced at the credential endpoint:
- Every proof must carry a key attestation: an `attestation` proof or a `jwt` proof with `key_attestation`.
- Every key the proof proves must be listed in the attestation's `attested_keys`.
- For a non-empty `key_storage` or `user_authentication` list, the attestation must state at least one of the listed values in the claim of the same name.
An empty object requires a key attestation without level constraints; empty lists add no constraint and are not published. A proof that fails is rejected with `invalid_proof`. Without `keyAttestationsRequired`, a key attestation is optional.
Wallets send key attestations in two ways:
- **`attestation` proof** (`proofs.attestation`): the key attestation JWT itself. EUDIPLO issues one credential per key in its `attested_keys`, at most the issuance `batchSize`.
- **`jwt` proof with `key_attestation` header**: a holder proof whose signing key must be one of the attested keys.
Every presented key attestation must be signed by a wallet provider in the issuance-level `walletProviderTrustLists`, whether it is required or not; lists on an authorization server are not used for keys. The certificates of its path must be within their validity period, and its `x5c` may hold at most 10 certificates, as for a [wallet attestation](#2-require-wallet-attestation).
If a key attestation has a `status` claim, its status list entry is checked like that of a [wallet attestation](#2-require-wallet-attestation), in the issuance configuration's `walletAttestationStatusCheckMode` (default `best_effort`): the same signer rules, the same checks of the list and the same table of modes. A rejected key attestation answers `invalid_proof` with a message that starts with `Key attestation` instead of `Wallet attestation`. In the EUDI Wallet, the key attestation is the wallet unit attestation (WUA), and its status list says whether the wallet provider revoked the wallet unit.
#### Revoke credentials with their wallet unit
A wallet provider revokes a wallet unit attestation when the wallet unit can no longer be trusted, for example after its device was compromised. Credentials issued to that wallet unit should be revoked as well. Set `revokeWithWalletUnit: true` on the credential configuration:
```json
{
"statusManagement": true,
"revokeWithWalletUnit": true,
"config": {
"keyAttestationsRequired": {}
}
}
```
In the Web Client, turn on **Revoke with Wallet Unit** under **Credential Features** in the credential configuration's settings. While it is on, **Status Management** and **Require Key Attestation** stay on and cannot be turned off.
- Requires `statusManagement: true` and `config.keyAttestationsRequired`; the API and the configuration import reject it otherwise.
- At issuance, EUDIPLO stores the status list reference (`status.status_list`) and the `x5c` of the key attestation with the status entry of every credential issued for the keys it attests. A key attestation without `status_list`, or with a malformed `status` claim, is not followed.
- Every `WALLET_UNIT_STATUS_CHECK_INTERVAL` seconds (default 3600, `0` turns the check off), and once after startup, EUDIPLO reads the status of every followed wallet unit. The provider must still be in the issuance configuration's `walletProviderTrustLists`, and its status list must pass the checks above. The validity periods of the key attestation's certificates are not checked again, so a wallet unit can still be revoked after they have expired. Those of the status list's certificates are checked on every read, so that a list signed under a retired key cannot revoke credentials. A provider that lists no revocation certificate signs its list under its attestation certificate, so for it, wallet units are no longer revoked once that certificate has expired: list a revocation certificate for providers whose attestation certificates expire before the credentials issued under them. A fetched list is reused for its `ttl` (5 minutes without one), at most one hour and not past its `exp`.
- When the status is revoked (`1`), EUDIPLO revokes the credentials issued under that wallet unit attestation and sends the [wallet unit revocation webhook](../reference/webhooks.md#wallet-unit-revocation-webhook). Within a run, a status list is verified once per attestation certificate chain and batch of up to 500 credentials. Revocation is final. Other values, such as suspended (`2`), are logged and change nothing.
- When the status cannot be read (the list cannot be fetched or verified, is signed under a certificate that has expired or is not yet valid, or the provider is no longer in the trust lists), nothing is revoked: the reason is logged as a warning and the next run tries again.
- A credential is no longer checked once it is revoked, has expired (its `lifeTime`, one year for mDOC credentials without one; an mDOC also expires with its signing certificate), or its configuration no longer has `revokeWithWalletUnit`. The setting applies to credentials issued while it is enabled.
- The check does not use `walletAttestationStatusCheckMode`: with `disabled`, issuance accepts revoked key attestations, but their status list reference is still recorded and the check still revokes the credentials once the wallet unit is revoked. Set `revokeWithWalletUnit: false` to stop following it.
- Several instances sharing one database each run the check; a revocation is applied once, but its webhook may be sent by more than one instance.
### Troubleshooting
| Symptom | Cause and fix |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Wallet attestation is required but not provided` | The wallet sends no attestation headers. Use a wallet that supports wallet attestation, or set `walletAttestationRequired: false`. |
| `No wallet provider trust lists configured ...` | Neither the authorization server nor the issuance configuration has `walletProviderTrustLists` (for key attestations: the issuance configuration). |
| `No trusted wallet providers found in configured trust lists` | The lists contain no entity with a `WalletSolution`, `WalletSolution/Issuance` or `WalletSolution/Revocation` service, or all such services are ignored for their `ServiceStatus` or a missing type ([Service status and type](trust-lists.md#service-status-and-type)). Check that you reference the wallet-provider list, not a list of credential issuers. If the message ends with `(... outdated trust list(s) left out ...)`, the providers may be in a list discarded as outdated: `Discarded outdated trust list(s) ...` in the log names it. |
| `Wallet provider certificate is not trusted ...` or `... signer is not trusted by configured wallet provider trust lists` | The provider's certificate is not in the lists, is listed without a `WalletSolution` or `WalletSolution/Issuance` service type (a `WalletSolution/Revocation` service does not sign attestations), or its service is ignored for its `ServiceStatus` or a missing type ([Service status and type](trust-lists.md#service-status-and-type)). If the message ends with `(... outdated trust list(s) left out ...)`, the provider may be listed only in a list discarded as outdated: `Discarded outdated trust list(s) ...` in the log names it. |
| `Wallet attestation certificate chain is not valid: ...` or `Attestation proof certificate chain is not valid: ...` | If the message continues with `x5c holds ... certificates` or `Certificate path ...`, see the next rows. Otherwise, a certificate of the attestation's path has expired or is not yet valid at the time of the request. The message names it, `Signing certificate` (the one in `x5c` that signs the attestation), `Intermediate certificate` or `Trust list certificate` (the one the wallet-provider list names), with its `notAfter` or `notBefore` and the time of the check. A certificate the list names that signs attestations itself, such as a listed end-entity certificate, is reported as `Signing certificate`. Ask the wallet provider to sign its attestations under a current certificate, or the list's publisher to list a current one; for a listed certificate that signs attestations itself, both. For `is not yet valid`, check the clocks of the server and of the wallet provider. |
| `... x5c holds ... certificates; at most 10 are accepted` | The `x5c` of the wallet or key attestation, or of its status list, holds more than 10 certificates. The built-in token endpoint answers `Wallet attestation certificate chain is not valid: ...`, the credential endpoint `invalid_proof` with `Attestation proof certificate chain is not valid: ...`, and for a status list both answer `Status list JWT signature verification failed - certificate chain is not valid: ...`; the wallet unit status check logs it and revokes nothing. The limit counts every certificate of the `x5c`, a trust anchor too; an `x5c` should hold only the signing certificate and its intermediates: ask the wallet provider to send only those. |
| `... Certificate path not found within 64 signature checks` or `... Certificate path is longer than 16 certificates` | The certificate path of the wallet or key attestation, or of its status list, could not be built within the [size limits](trust-lists.md#size-limits): the wallet-provider lists put many certificates with the subject name of the attestation's issuer before the one it needs, typically without Subject Key Identifier, or the path through the listed certificates is longer than 16. The answers and the wallet unit status check are those of the row above. Ask the list's publisher to list each CA once, with its Subject Key Identifier. |
| `The credential configuration requires a key attestation ...` | The wallet sent a `jwt` proof without `key_attestation`. Use a wallet that sends key attestations, or remove `keyAttestationsRequired`. |
| `The key attestation does not state an accepted key_storage value ...` (or `user_authentication`) | The attested level is not in the configured list. Add the level your wallets attest, if it meets your requirements. |
| `The proof contains a key that is not listed in attested_keys ...` | The `jwt` proof is signed with a key the attestation does not cover. |
| `Wallet attestation status check failed` | The attestation's `status` claim is malformed, or the status list could not be fetched (`strict` only), is not a status list JWT, or its signature could not be checked. The server log names the reason, and the list if the claim names one. A malformed claim is a problem of the wallet provider's attestation format. Otherwise, check that the wallet provider serves the list at the `status.status_list.uri` of the attestation. To accept attestations while the list is unreachable, set `walletAttestationStatusCheckMode: "best_effort"`. |
| `Wallet attestation is not valid: ...` | The wallet provider has revoked or suspended this wallet instance. |
| `Status list JWT signature verification failed - certificate chain is not valid: ...` | If the message continues with `x5c holds ... certificates` or `Certificate path ...`, see the rows for those messages above. Otherwise, a certificate of the status list's path has expired or is not yet valid at the time of the check. The message names it, `Signing certificate` (the one in the list's `x5c` that signs it), `Intermediate certificate` or `Trust list certificate` (the provider's revocation or attestation certificate that the wallet-provider list names), with its `notAfter` or `notBefore` and the time of the check. A listed certificate that signs the list itself is reported as `Signing certificate`. Ask the wallet provider to sign its status list under a current certificate, or the list's publisher to list a current revocation certificate. For `is not yet valid`, check the clocks of the server and of the wallet provider. The wallet unit status check logs the same reason and revokes nothing. |
| `Status list JWT signature verification failed - not signed by ...` or `Wallet attestation status list rejected: ...` | The attestation's status list has no `x5c` header or is signed under another certificate than the provider's revocation or attestation certificate, or it is not the list the attestation names (`sub`), has expired, is not typed `statuslist+jwt` or does not contain the index. Add the provider's status list signing certificate to the trust list as a `WalletSolution/Revocation` service, or ask the provider to fix the list. |
| `Key attestation is not valid: ...`, `Key attestation status list rejected: ...` or `Key attestation status check failed` | Answer of the credential endpoint (`invalid_proof`) for the key attestation's status list, with the causes of the rows above for wallet attestations. A status list signed by the wrong certificate, or under one outside its validity period, answers `Status list JWT signature verification failed ...` here too. |
| `Client attestation validation failed` | `error_description` of the `invalid_client` answer for every rejected wallet attestation at the PAR endpoint of each EUDIPLO-managed authorization server (HTTP 400) and at the token endpoint of chained and OID4VP authorization servers (HTTP 401). The built-in token endpoint answers `invalid_client` with HTTP 401 and, as `error_description`, the reason when it is about the attestation or its provider, such as one of the messages above, and a fixed text when the server failed: `Wallet attestation status check failed` (above) or one of the next two rows. At each of these endpoints, the server log line `Client attestation validation failed for ...: ...` has the reason. |
| `Wallet provider trust lists could not be loaded` or `Attestation proof x5c chain could not be validated` | A wallet-provider list cannot be fetched or read, or its signature does not match `verifierX509Der`, `verifierKey` or `verifierKeyPem`, or the lists together hold more than 1,000 certificates ([Size limits](trust-lists.md#size-limits); the log says `brings the certificates of its source to ...`). The credential endpoint also answers its message when the key attestation's header cannot be read or its `x5c` holds a certificate that cannot be parsed. The answer names no list: it reaches the wallet, and the URL of a managed list can name an internal address (`INTERNAL_URL`). For wallet attestations, the log line `Client attestation validation failed for ...: Wallet provider trust lists could not be loaded: ...` names the list and the reason; for key attestations at the credential endpoint, the log line `Key attestation validation failed for tenant ...: Attestation proof x5c chain could not be validated: ...` does. The credential endpoint also answers this text for a wallet-provider reference that defines no `verifierX509Der`, `verifierKey` or `verifierKeyPem` with content, for example one that is only whitespace. |
| `Wallet attestation verification failed` | Answer of the built-in token endpoint for any other server-side failure, for example a `verifierX509Der` that is only whitespace. The log line `Client attestation validation failed for ...: Wallet attestation verification failed: ...` has the reason. With `: ...` after it in the answer, the text gives the reason: about the attestation the wallet sent, for example its signature, audience or expiry, or, with `No configured trust list is current`, every wallet-provider list is outdated (next row). |
| `... No configured trust list is current ...` | Every configured wallet-provider list is outdated: no valid `NextUpdate` or one that has passed, or no valid `LoTESequenceNumber` or a lower one than a list accepted before ([Older versions of a list](trust-lists.md#older-versions-of-a-list)). The built-in token endpoint answers `Wallet attestation verification failed: No configured trust list is current ...`, the credential endpoint `invalid_proof` with this text. `Discarded outdated trust list(s), no current list is left: ...` in the log names the lists. Ask their publisher for current ones; for a managed list, look for `Failed to renew trust list` in the log. |
---
## EUDI Hub
The German EUDI Hub ([portal.eudi-hub.gov.de](https://portal.eudi-hub.gov.de/)) is the registrar of the German wallet ecosystem and the registrar EUDIPLO integrates with: organizations register there and get access and registration certificates for their relying parties. EUDIPLO requests an access certificate for one of its access key chains, so the private key stays in EUDIPLO, and registration certificates for its presentation configurations and its issuer. It works with an access token you copy from the portal, so there is no EUDI Hub configuration to save. [Certificates from the EUDI Hub](../cookbooks/eudi-hub-certificates.md) walks through all three requests for the cookbook tenant.
### Prerequisites
- The `registrar:manage` role; for registration certificates also `presentation:manage` (verifier) or `issuance:manage` (issuer).
- An organization at the EUDI Hub, and a portal user assigned to it that may issue certificates. Create and verify the organization in the portal; EUDIPLO does not do that.
- For an access certificate, a standalone access key chain in EUDIPLO, for example created in **Cryptographic Assets → Keys → Create Key** with **Access Certificate → Self-Signed Certificate**.
- EUDIPLO must reach the EUDI Hub API under the [outbound URL policy](../concepts/security-model.md#https-and-tls); with `OUTBOUND_URL_ALLOWED_HOSTS` set, list `api.eudi-hub.gov.de` and the host from which the EUDI Hub serves the CA that issues access certificates (the URL its certificates name under Authority Information Access). Without that host, access certificates are stored without their issuing CA.
### Copy the access token
The EUDI Hub API only accepts access tokens issued to its portal; it offers no accounts for other software. The token is valid for a few minutes, is sent with your request only and is not stored.
1. Sign in to the [EUDI Hub portal](https://portal.eudi-hub.gov.de/).
2. Open the developer tools of your browser and select the **Network** tab.
3. Open a page of the portal that loads data, such as **Access certificates**, and select a request to `api.eudi-hub.gov.de`.
4. Copy the value of its `Authorization` request header. It works with or without the `Bearer` prefix.
Treat the token like a password: it acts as your portal user until it expires. Copy a fresh one if EUDIPLO reports that the EUDI Hub did not accept it.
### Request an access certificate
Open the access key chain under **Cryptographic Assets → Keys** and select **Request from EUDI Hub** on its **Active Certificate** card. The action needs the `registrar:manage` role and is shown for standalone access key chains only; on a key chain provisioned from a configuration file it is locked. In the dialog:
- **Access token**: the token you copied.
- **Organization**: select **Load Organizations** to list the organizations of the token's user, or enter the organization ID (a UUID) by hand.
- **Environment**: **Sandbox** or **Live**. Live needs an organization the EUDI Hub has promoted to live.
- **Support URI**: where people can reach your organization about this certificate.
- **Certificate name**: the name shown in the portal; empty uses the key chain's description, else its ID.
**Request Certificate** (**Request Live Certificate** for Live) sends a certificate signing request (CSR) for the key chain's active key to the EUDI Hub, downloads the issued certificate and stores it as the key chain's active certificate. The EUDI Hub hands out the certificate without the CA that issued it, which wallets need in `x5c` to reach the root they trust; EUDIPLO fetches that CA from the URL the certificate names (Authority Information Access, under the outbound URL policy) and stores it after the certificate when it issued it and is not a self-signed root. If it cannot be fetched, for example because the outbound URL policy blocks its host, the certificate is stored alone and the log says so. The key stays the same; the key chain keeps its description, and one without a description gets `Access certificate from the EUDI Hub (, ID: )`. The Web Client asks first if the active certificate was issued by someone else, or if the key chain rotates automatically, since its next rotation would replace the certificate with a self-signed one for a new key. If the request fails, the dialog stays open and shows the reason.
Via the API, with the EUDIPLO token in the `Authorization` header and the portal token in the body:
```bash
curl -X POST "$EUDIPLO_URL/api/eudi-hub/organizations" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data '{ "token": "" }'
curl -X POST "$EUDIPLO_URL/api/eudi-hub/access-certificate" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data '{
"token": "",
"organizationId": "",
"keyId": "",
"environment": "sandbox",
"supportUri": "https://verifier.example/support"
}'
```
`name` is optional. The response contains `id` (the certificate ID at the EUDI Hub), `certId` (the key chain), `crt` (the certificate as PEM), `environment`, and, as the EUDI Hub reports them, `clientId` and `expirationDate`.
### Request a registration certificate
A registration certificate tells wallets what a verifier may request and why, or which credentials an issuer provides ([Registration Certificates](registration-certificates.md)). At the EUDI Hub, a verifier certificate is issued for a _credential request_ and an issuer certificate for _credential issuances_; EUDIPLO registers these for you. EUDIPLO stores the certificate in the configuration ([Registration Certificates](registration-certificates.md)). It cannot reach the EUDI Hub without a fresh token, so it does not renew the certificate: request a new one before it expires, and after you change the DCQL query or the credential types.
**Verifier:** open the presentation configuration, go to the **Security** tab and select **Request from EUDI Hub** (needs `registrar:manage` and `presentation:manage`; locked on a configuration provisioned from a configuration file). EUDIPLO turns the DCQL query, with `` resolved, into a credential request: for each credential query the format, its single `vct` or `docType` and the claim paths. It uses an existing credential request of the organization in that environment with the same credentials, privacy policy and purpose texts sent to the EUDI Hub (texts that are not sent do not count), else it creates one. The configuration's `registration_cert` then holds the certificate (`jwt`) with the `purpose` and `privacy_policy` it was requested with; storing runs the [checks of every registration certificate](registration-certificates.md#validation), including the overasking check. A request that leaves out the purpose or the privacy policy uses the ones `registration_cert` keeps, so renewing a certificate needs only the token and the organization's fields; without either, the request is refused with `400` before the EUDI Hub is called. A DCQL query is refused with `400` before the EUDI Hub is called when a credential query lists several `vct_values`, has meta other than `vct_values` or `doctype_value`, uses a format other than `dc+sd-jwt` or `mso_mdoc`, lists no claims, or has a claim path with an array index or wildcard (`null`), since the EUDI Hub registers none of these and the certificate would then fail the overasking check.
**Issuer:** open **Issuer Settings**, go to the **Registration Certificate** tab and select **Request from EUDI Hub** (needs `registrar:manage` and `issuance:manage`; locked when the issuance configuration is provisioned from a configuration file). EUDIPLO registers the `vct` of each SD-JWT VC and the `docType` of each mDOC credential configuration as a credential issuance, unless the organization has one for that format and type in that environment, requests a certificate for all of them and checks that it lists every type. When the EUDI Hub does not register a type, the error names it and every other type the EUDI Hub did not register (the server log has the reasons for the other types), and no certificate is requested; issuances created for the other types stay at the EUDI Hub and the next request reuses them. It stores the certificate and the support URI in the issuance configuration's `registrationCertificate` and turns it on (`enabled: true`); other settings such as the privacy policy stay.
In both dialogs, after you paste the token and choose the organization, EUDIPLO reads the organization's identifier, service description, privacy policy and contact URLs from the EUDI Hub and fills empty fields with them. The EUDI Hub needs:
- **Identifier**: an official identifier of the organization, such as its EUID or Handelsregisternummer.
- **Service description** and, for a verifier, **Purpose**: each in German and English. The dialog lists purposes the configuration keeps in other languages below the fields and stores them again with the new certificate; only those with a two-letter language code reach the EUDI Hub (see the API description below). A regional German or English text that filled a field, such as `de-DE` without `de`, is saved as `de` or `en`, and kept texts without a valid language tag or text, or beyond 50 texts, are removed.
- **Support URI** and **Info URI**; for a verifier also the **Privacy policy**.
Via the API, with the EUDIPLO token in the `Authorization` header and the portal token in the body:
```bash
curl -X POST "$EUDIPLO_URL/api/eudi-hub/registration-certificate/presentation" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data '{
"token": "",
"organizationId": "",
"environment": "sandbox",
"presentationConfigId": "",
"identifier": { "type": "http://data.europa.eu/eudi/id/EUID", "value": "DE/HRB123456B" },
"serviceDescription": [
{ "lang": "de", "content": "Altersprüfung im Online-Shop" },
{ "lang": "en", "content": "Age verification in the online shop" }
],
"purpose": [
{ "lang": "de", "content": "Prüfung, ob Sie volljährig sind" },
{ "lang": "en", "content": "Checks that you are of age" }
],
"privacyPolicy": "https://verifier.example/privacy",
"supportUri": "https://verifier.example/support",
"infoUri": "https://verifier.example"
}'
```
`purpose` and `privacyPolicy` are optional when the presentation configuration's `registration_cert` keeps them. `purpose` needs a German (`de`) and an English (`en`) text and may hold up to 50 texts with language tags such as `fr` or `pt-BR`. All of them are stored in `registration_cert.purpose`, but the EUDI Hub accepts only two-letter language codes, at most 24 texts: texts with a region or a three-letter code, such as `pt-BR` or `eng`, are kept in the configuration for the next request or another registrar, but are not part of the certificate. Beyond 24 texts, EUDIPLO sends `de`, `en` and then the first others in request order; the rest is stored only. `POST /api/eudi-hub/registration-certificate/issuer` takes the same fields without `presentationConfigId`, `purpose` and `privacyPolicy`. `name` is optional for both. `POST /api/eudi-hub/organization-details` with `token` and `organizationId` returns the data the dialog fills in. The response contains `id` (the certificate ID at the EUDI Hub), `environment`, `expirationDate`, and `credentialRequestId` with `reusedCredentialRequest` for a verifier or `credentialIssuanceIds` for an issuer.
When EUDIPLO cannot download or store a registration certificate the EUDI Hub issued, or an issuer certificate does not list every credential type, it revokes the certificate at the EUDI Hub (reason `cessationOfOperation`). A certificate that a new one replaces is not revoked; revoke it in the portal.
### Errors
- `400`: the request is invalid, the key chain is not a standalone access key chain, the DCQL query or the credential types cannot be registered, neither the request nor `registration_cert` has a purpose or privacy policy, the kept privacy policy is not an http or https URL, the purpose (of the request or kept in `registration_cert`) lacks a German or English text, gives a language twice, uses something other than a language tag, has more than 50 texts or an empty or overlong text, the certificate fails the checks of a registration certificate, the outbound URL policy blocks the EUDI Hub URL, or the EUDI Hub refused. A refused token (expired, or not from the portal) is reported as `400` naming HTTP 401 of the EUDI Hub, not as `401`, since your EUDIPLO session is fine. Missing permissions at the EUDI Hub are reported as `400` naming HTTP 403 of the EUDI Hub; other refusals carry the EUDI Hub's reason. A certificate for another key, which EUDIPLO does not store, is a `400` as well.
- `403`: a role is missing.
- `404`: the key chain or the presentation configuration does not exist.
- `502`: the EUDI Hub could not be reached, answered with a server error, answered with something other than what its API describes, or issued an issuer certificate that does not list every credential type. When registering the credential types of an issuer certificate fails this way for one type, the answer is `502` even if the EUDI Hub refused another type. A `502` before EUDIPLO asked for a registration certificate, while it read or registered the credential issuances of an issuer or found or registered the credential request of a verifier, has `"code": "EUDI_HUB_NO_CERTIFICATE_REQUESTED"`: EUDIPLO requested no certificate and stored nothing; credential issuances or a credential request created on the way stay at the EUDI Hub, and the next request reuses them. After any other `502` a certificate may have been stored anyway, for example when a proxy gave up while EUDIPLO went on; look at the presentation or issuance configuration, or the key chain for an access certificate, before you request again.
When an access certificate request gets no answer or the EUDI Hub fails with a server error, the EUDI Hub may still have issued the certificate. EUDIPLO then looks among the first 100 listed certificates of that environment, downloading at most 5 valid ones of the same name, for one with the key's public key, other than the one the key chain already holds, and stores it as if the request had succeeded. When EUDIPLO cannot download or store a certificate this request issued, it revokes it at the EUDI Hub (reason `cessationOfOperation`); if that fails too, the log names the certificate ID to revoke in the portal.
### Configuration
EUDIPLO talks to the production EUDI Hub at `https://api.eudi-hub.gov.de/org-management`. To use another environment of the EUDI Hub, set `EUDI_HUB_API_URL` ([Environment Variables](../reference/environment-variables.md#registrar)). EUDIPLO sends pasted tokens only to that URL.
### Limits
- Certificates from the EUDI Hub are not renewed automatically; request new ones with a fresh token.
- EUDIPLO looks for an existing credential request or credential issuance among the first 100 of the organization in that environment.
- All EUDI Hub operations are marked as drafts in its API description and may change.
---
## OpenID Federation
EUDIPLO can use [OpenID Federation](https://openid.net/specs/openid-federation-1_0.html) trust anchors to decide whether to trust external authorization servers, the upstream provider of a chained authorization server, and the issuers of presented SD-JWT VCs. It resolves the trust chain from the entity to a configured trust anchor and verifies every statement in it, or delegates this to an external trust engine. Every trust anchor must be [registered with its federation keys](#register-trust-anchors), which you obtain out of band.
A tenant can also take part in a federation itself, as a leaf entity: EUDIPLO then publishes its signed entity configuration, issues SD-JWT VCs that federation verifiers check through its credential issuer metadata, and can identify its OID4VP requests by its entity ID ([Publish your entity configuration](#publish-your-entity-configuration)).
### How trust is decided
For an entity ID and the configured trust anchors, EUDIPLO:
1. fetches the entity's entity configuration from `{entityId}/.well-known/openid-federation` and follows its `authority_hints` up to a trust anchor;
2. fetches each superior's subordinate statement about the entity below it from the superior's `federation_fetch_endpoint`;
3. validates the chain as [Section 10](https://openid.net/specs/openid-federation-1_0.html#section-10) describes: every statement is signed, current (`iat`, `exp`) and has no unknown `crit` claims; an entity configuration is about the requested entity (`sub`) and signed with a key its superior lists; each subordinate statement is issued by the superior about the subject and signed with a key the statement above lists; the last one with the trust anchor's keys. The trust anchor's own entity configuration must be signed with one of the keys you [registered](#register-trust-anchors) for it ([Section 10.2](https://openid.net/specs/openid-federation-1_0.html#section-10.2)), so a host serving other keys for the trust anchor is not trusted;
4. applies the `max_path_length` and `allowed_entity_types` constraints and the metadata policies of the chain, and returns the entity's resolved metadata.
An entity is not trusted because its entity configuration names a trust anchor in `authority_hints`: the trust anchor, or an intermediate below it, must list it in a signed subordinate statement.
Protocol keys come from the resolved metadata, never from the federation keys of the entity configuration: the key that signs a credential is looked up by `kid` in `metadata.openid_credential_issuer.jwks`.
Resolution uses [`@owf/openid-federation`](https://github.com/openwallet-foundation-labs/identity-common-ts/tree/main/packages/openid-federation). Not supported:
- Chains with `naming_constraints` are rejected, as the constraint is not evaluated.
- Trust marks are not verified, and they do not decide trust.
- A credential without a `kid` header is rejected, also when the issuer's metadata lists one key.
- An authorization server's federation metadata must have an `issuer` equal to its entity ID. The metadata EUDIPLO uses for the server is still fetched from its `.well-known` URL; policies of the chain do not change it.
- Protocol keys must be in `jwks`; `jwks_uri` and `signed_jwks_uri` in the metadata are not used.
- EUDIPLO only acts as a leaf entity: it issues no subordinate statements and offers no fetch, list, resolve or trust mark endpoints. Trust marks you configure are published as given, not checked.
### Register trust anchors
A trust anchor is trusted only when the tenant has registered it with its federation keys. Get the keys out of band, for example from the federation operator's published key set, not from the trust anchor's `.well-known` URL alone. Register each trust anchor once per tenant (`POST /api/federation-trust-anchor`, with `issuance:manage` or `presentation:manage`); issuance configurations and DCQL queries then name it by entity ID:
```json
{
"id": "example-federation",
"entityId": "https://ta.example.org",
"description": "Example federation",
"jwks": {
"keys": [{ "kty": "EC", "crv": "P-256", "kid": "ta-2026", "x": "...", "y": "..." }]
}
}
```
| Field | Behavior |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Identifier in the tenant, also the file name in the config folder (`federation-trust-anchors/.json`, [format](../reference/config-bundle-format.md)). |
| `entityId` | The trust anchor's entity ID, an `https` URL without query or fragment, compared exactly. Each entity ID can be registered once per tenant. |
| `description` | Optional text for operators. |
| `jwks` | The trust anchor's federation keys: 1 to 20 public `EC`, `RSA` or `OKP` keys, each with a unique `kid` and at most 8192 characters of JSON. Private key members are rejected. |
In the Web Client, open **Cryptographic Assets → Federation Trust Anchors** (with `issuance:manage` or `presentation:manage`). **Register a trust anchor** asks for the ID, the entity ID and an optional description, and takes the keys as a JWK set in a JSON editor that checks them against the schema above. A trust anchor's page lists the pinned keys and which configurations name its entity ID; edit or delete it there. Where issuer settings and presentation configurations name a trust anchor, they offer the registered ones to choose from, flag an entity ID that is not registered and link to **Register trust anchor**, which opens in a new tab with the entity ID filled in. Once the trust anchor is registered, that tab says to return to the form instead of opening the trust anchor, and the form lists it once you are back.
`GET`, `PATCH` and `DELETE /api/federation-trust-anchor/{id}` read, change and remove a registration. For a key rollover, add the new key before the trust anchor signs with it and remove the old one afterwards. A change that adds an entity ID the tenant has not registered to an issuance configuration's `federation`, or to a presentation configuration's `openid_federation` entry (in a query without an `etsi_tl` entry, where federation decides), is rejected with `400`; so is a new configuration or an import naming one. A stored configuration naming an unregistered trust anchor still loads and can be changed otherwise; nothing is trusted through that trust anchor until it is registered. A configuration import ([config bundle or folder](../reference/config-bundle-format.md)) checks this in its plan, against the trust anchors of the tenant and of the import: a new or changed document is `blocked` with `MISSING_RESOURCE_REFERENCE`, so the import applies nothing, when it names an entity ID neither registers: a presentation config for every such entity ID, the issuance configuration only for one its stored version does not already name. A bundle can bring the trust anchor and the configurations naming it together.
#### Delete a trust anchor
`DELETE /api/federation-trust-anchor/{id}`, and a `PATCH` that changes `entityId`, answer `409` while an issuance or presentation configuration of the tenant still names the entity ID: in the issuance configuration's `federation.trustAnchors`, or in an `openid_federation` entry of a query without an `etsi_tl` entry. The response names the configurations in `message` and lists them in `references`. Configurations the caller's roles cannot read are only counted, without ID and description: the issuance configuration needs `issuance:manage`, presentation configs `presentation:manage` or `presentation:request`. Changing `description` or `jwks` is not refused.
```json
{
"statusCode": 409,
"timestamp": "2026-10-17T12:00:00.000Z",
"path": "/api/federation-trust-anchor/example-federation",
"code": "FEDERATION_TRUST_ANCHOR_IN_USE",
"message": "Federation trust anchor \"example-federation\" (https://ta.example.org) is still named by 1 presentation config (\"pid\") and the issuance configuration (federation.trustAnchors). Remove these references before deleting it.",
"references": [
{ "kind": "PresentationConfig", "id": "pid", "description": "PID check" },
{ "kind": "IssuanceConfig" }
]
}
```
Remove the entity ID from these configurations first. To move to a new entity ID, register it as another trust anchor, switch the configurations to it, then delete the old registration. A configuration import that would give a trust anchor another entity ID, in any mode, or delete it, in `replace` mode, while a configuration surviving the import still names the old entity ID is `blocked` with `FEDERATION_TRUST_ANCHOR_IN_USE`; configurations the same import deletes or rewrites without the entity ID do not count.
### Where federation is checked
| Check | Configured in | Behavior |
| -------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| External authorization servers, chained upstream provider | `federation` of the issuance configuration | The server's issuer URL must be a federation entity with `oauth_authorization_server` or `openid_provider` metadata whose chain leads to a trust anchor; there is no LoTE fallback. Without `federation`, no check. |
| Issuers of presented SD-JWT VCs | `openid_federation` in DCQL `trusted_authorities` | Without an `etsi_tl` entry in the same query, the credential's `iss` must be a federation entity whose chain leads to one of the listed trust anchors, and the credential must be signed with the key `kid` of its `openid_credential_issuer` metadata. An `x5c` header is not used. With an `etsi_tl` entry, the trust list decides. |
| Status lists of those SD-JWT VCs | the same | The status list JWT must be signed with a key `kid` of the same entity's `openid_credential_issuer` metadata. |
mDOCs cannot be verified through OpenID Federation, as they name no issuer entity: a query for `mso_mdoc` with only an `openid_federation` entry rejects every presentation. Use an `etsi_tl` trust list for mDOCs.
`mode` accepts `hybrid` (default) and `federation-only`; both check authorization servers the same way. For LoTE-only behavior, leave `federation` unset or `null`.
### Choose the resolver
`FEDERATION_RESOLVER` selects who resolves trust chains for the whole instance ([environment variables](../reference/environment-variables.md#federation)):
| Value | Behavior |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `local` (default) | EUDIPLO fetches and validates the statements itself. |
| `http` | EUDIPLO sends `POST {FEDERATION_RESOLVER_URL}/resolve` to an external trust engine, with `FEDERATION_RESOLVER_TOKEN` as bearer token, and uses its answer. |
The trust engine receives:
```json
{
"entityId": "https://issuer.example.org",
"trustAnchors": [
{ "entityId": "https://ta.example.org", "jwks": { "keys": [{ "kid": "ta-2026", "kty": "EC", "...": "..." }] } }
],
"metadataTypes": ["openid_credential_issuer"]
}
```
and answers with a `2xx` status and the validated resolution (redirects are not followed):
```json
{
"entityId": "https://issuer.example.org",
"trustAnchor": "https://ta.example.org",
"trustChain": ["", "", ""],
"metadata": {
"openid_credential_issuer": { "jwks": { "keys": [{ "kid": "credential-key", "kty": "EC", "...": "..." }] } }
},
"expiresAt": "2026-10-18T12:00:00Z"
}
```
This is an EUDIPLO-specific API, not the Resolve endpoint of OpenID Federation (Section 8.3), and the answer is not signed. `metadata` is the metadata after the chain's policies were applied; `expiresAt` is the earliest `exp` of the chain. `trustAnchors` carries the registered keys of each trust anchor; the engine must accept only chains whose trust anchor entity configuration is signed with one of them, and must take the metadata from such a chain. EUDIPLO checks that the answer is about the requested entity and one of the requested trust anchors, that the last entry of `trustChain` is the trust anchor's entity configuration signed with a registered key, that it has not expired and that it contains one of the requested metadata types. A `4xx` answer other than `401`, `403`, `408` and `429` means the entity is not trusted; those (for `401` and `403`, check `FEDERATION_RESOLVER_TOKEN`), `5xx` answers, invalid answers and failed requests (10 seconds, 1 MiB) mean the federation is unavailable. Apart from the trust anchor's entity configuration, EUDIPLO trusts the engine's validation and does not check the chain again: the check proves that the engine resolved to the genuine trust anchor, not that the subordinate statements and `metadata` come from it. A compromised engine can still decide which keys are accepted, so run it with the same care as EUDIPLO.
### Limits and outbound requests
Entity configurations name the URLs EUDIPLO fetches, so every request goes through the [outbound URL policy](../concepts/security-model.md#https-and-tls) (HTTPS and public addresses unless allowed otherwise, `OUTBOUND_URL_ALLOWED_HOSTS`), except requests to EUDIPLO's own `PUBLIC_URL` or `INTERNAL_URL` origin. TLS certificates of federation entities are always verified, also outside `NODE_ENV=production`. The request to a trust engine is subject to the policy as well; its URL must use HTTPS.
One local resolution follows at most 8 superiors and 10 distinct `authority_hints` per entity, sends at most 32 requests, waits at most 5 seconds per request and reads at most 256 KiB per statement. Statements may differ from EUDIPLO's clock by `CRYPTO_TOLERANCE` seconds.
### Caching
A resolution is cached for `cacheTtlSeconds` of the issuance configuration (default 300, at least 5 seconds), never beyond the `exp` of its trust chain; DCQL queries use the default. Tenants with the same trust anchors and the same registered keys share the cache, and each uses a resolution only within its own `cacheTtlSeconds`. A failed resolution is retried after 10 seconds. `DELETE /api/cache/trust-list` and `DELETE /api/cache` clear the resolutions your tenant used, also for the tenants that share them; with `tenants:manage`, they clear all. A resolution another tenant still uses stays available to it as the fallback described below, for your tenant too.
When the federation cannot be reached (a timeout, a failed request, a `429` or `5xx` answer), the last successful resolution is used for at most 15 minutes after it was obtained, and only while its chain is valid. A chain that fails validation (a signature, an expired statement, an entity the superior does not list) is rejected and never replaced by an earlier resolution.
### Configure federation for issuance
Set `federation` in the issuance configuration (`POST /api/issuer/config`, or **Issuer Settings**, then **Edit**, the **Trust** tab and **OpenID Federation** in the Web Client):
```json
{
"federation": {
"mode": "hybrid",
"entityId": "https://eudiplo.example.com/issuers/membership-demo",
"cacheTtlSeconds": 300,
"trustAnchors": [
{
"entityId": "https://ta.example.org",
"entityConfigurationUri": "https://ta.example.org/.well-known/openid-federation"
}
]
}
}
```
| Field | Behavior |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `trustAnchors[].entityId` | Trust anchor, [registered](#register-trust-anchors) with its keys. Its entity configuration is fetched from `{entityId}/.well-known/openid-federation`. Entity IDs are compared exactly, so `https://ta.example.org/` and `https://ta.example.org` are different trust anchors. |
| `trustAnchors[].entityConfigurationUri` | Required by the schema but not used. |
| `entityId` | Your entity ID: `iss` of SD-JWT VCs with the `federation` trust format (below), `iss` and `sub` of the [published entity configuration](#publish-your-entity-configuration) and the `openid_federation:` client identifier. Leave it empty to only evaluate trust. Otherwise it must be an `https` URL with a host and without query, fragment, credentials or whitespace (OpenID Federation 1.0 Section 1.2); `POST /api/issuer/config` answers `400` for another value, and a startup import or bundle with one fails. `http` is accepted only with `OUTBOUND_URL_ALLOW_HTTP=true`, for local setups whose federation also allows it. |
| `cacheTtlSeconds` | How long resolutions are cached; default 300, at least 5. See [Caching](#caching). |
| `role` | Only `leaf` (the default) is accepted; EUDIPLO does not act as a trust anchor or intermediate. |
| `enforceSigningPolicy` | Only `true` (the default) is accepted; federation checks are always enforced. |
The fields of the published entity configuration are described [below](#publish-your-entity-configuration).
With this configuration, external authorization servers are checked before EUDIPLO fetches their metadata, and a chained authorization server's upstream provider before its discovery document is fetched.
#### SD-JWT VC trust format
A credential configuration can sign SD-JWT VCs for federation instead of X.509: set `sdJwtTrustFormat` to `federation` (**Credential Configs → SD-JWT Trust Format**). EUDIPLO then sets `iss` to the federation `entityId`, sets the `kid` header to the `kid` of the signing key and omits the `x5c` header. It falls back to `x5c` (the default) when no federation `entityId` or no trust anchor is configured, when a stored `entityId` breaks the rule above, or when `entityTypes` leaves out `openid_credential_issuer`, as verifiers would find the key nowhere else. The signing key chain is used in both cases.
```json
{ "alg": "ES256", "typ": "dc+sd-jwt", "kid": "" }
```
A verifier finds that key in the `openid_credential_issuer` metadata of your entity configuration, which lists the public keys of all attestation and status list key chains of the tenant, the previous key of a rotation included. Status list JWTs always carry the `kid` of their signing key, so a verifier checks them against the same metadata. With `includeTrustChain`, the credential also carries your trust chain in the `trust_chain` header (Section 4.3 of OpenID Federation), resolved to your trust anchors like any other chain (and cached the same way); issuance fails when the chain cannot be resolved.
### Publish your entity configuration
A tenant with a federation `entityId` and at least one trust anchor publishes its signed entity configuration at:
```http
GET /issuers/{tenantId}/.well-known/openid-federation
```
The answer has the content type `application/entity-statement+jwt`; a tenant without `entityId` or trust anchors answers `404`. A federation fetches the entity configuration from `{entityId}/.well-known/openid-federation`, so set `entityId` to `{PUBLIC_URL}/issuers/{tenantId}`, the same identifier as the credential issuer. Another entity ID only works if your reverse proxy serves this endpoint at `{entityId}/.well-known/openid-federation`; `iss` and `sub` are always the configured `entityId`.
1. **Create a federation key** with usage type `federation` (**Cryptographic Assets → Keys → Create Key → OpenID Federation Entity Key**, or `POST /api/key-chain` with `"usageType": "federation", "type": "standalone"`). It only signs the entity configuration; credentials, status lists and requests are signed by the other key chains.
2. **Register the entity with your trust anchor** (or an intermediate): it needs the entity ID and the public key of the federation key chain for the subordinate statement it issues about you.
Register the trust anchor with its keys in EUDIPLO too ([Register trust anchors](#register-trust-anchors)); without pinned keys it is not trusted, and `includeTrustChain` cannot resolve your chain.
3. **Configure the entity** in the `federation` block of the issuance configuration. The block describes the tenant's one federation entity, also when it acts only as a verifier:
```json
{
"federation": {
"entityId": "https://eudiplo.example.com/issuers/membership-demo",
"trustAnchors": [
{
"entityId": "https://ta.example.org",
"entityConfigurationUri": "https://ta.example.org/.well-known/openid-federation"
}
],
"entityTypes": ["openid_credential_issuer", "openid_credential_verifier"],
"authorityHints": ["https://ta.example.org"],
"entityMetadata": { "organization_name": "Example Membership" },
"includeTrustChain": false
}
}
```
| Field | Behavior |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entityTypes` | Metadata the entity configuration publishes: `openid_credential_issuer` (default) and `openid_credential_verifier`. |
| `authorityHints` | `authority_hints`: HTTPS entity IDs of the superiors that issue a subordinate statement about you. Defaults to the trust anchor entity IDs. |
| `entityKeyChainId` | The federation key chain that signs the entity configuration. Without it, a key chain with usage type `federation` is used; set it when the tenant has several. |
| `entityConfigurationLifetimeSeconds` | `exp - iat` of the entity configuration, 60 to 31536000 seconds; default 86400. |
| `trustMarks` | Trust mark JWTs issued to you, published in `trust_marks` with the `trust_mark_type` of each JWT. Saving a trust mark without `trust_mark_type` fails with `400`. |
| `entityMetadata` | `organization_name`, `contacts`, `logo_uri`, `policy_uri` and `homepage_uri` (HTTPS URLs) of the `federation_entity` metadata. |
| `includeTrustChain` | Adds your trust chain as `trust_chain` header to federation SD-JWT VCs and to requests with the `openid_federation` client identifier. |
The entity configuration contains `iss` and `sub` (the entity ID), `iat`, `exp`, the active and previous public keys of the federation key chain in `jwks`, `authority_hints`, `trust_marks` and this `metadata`, built from the metadata EUDIPLO serves anyway:
| Metadata type | Content |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `federation_entity` | `entityMetadata`. No federation endpoints, as EUDIPLO provides none. |
| `openid_credential_issuer` | The [credential issuer metadata](../issuance/issuance-configuration.md) and, in `jwks`, the public keys of all attestation and status list key chains (`use: sig`). |
| `oauth_authorization_server` | The metadata of the built-in authorization server, when it is advertised and its issuer equals the entity ID. External authorization servers publish their own entity. |
| `openid_credential_verifier` | `vp_formats_supported`, `encrypted_response_enc_values_supported` and, in `jwks`, the public keys of all access key chains (`use: sig`) and the tenant encryption key (`use: enc`). |
EUDIPLO signs the entity configuration again at most once a minute, and at once after the `federation` block or the issuance configuration changes; a failure is answered for ten seconds before the next attempt. A key chain created, rotated or deleted in between shows within a minute. Only public key members (`kty`, `crv`, `x`, `y`, `n`, `e`, `kid`, `alg`, `use`) are published. `POST /api/issuer/config` replaces the whole `federation` block, so send the entity fields along with every update.
#### Use an external trust engine
With `FEDERATION_ENTITY_PROVIDER=http`, EUDIPLO does not sign the entity configuration itself but sends `GET {FEDERATION_ENTITY_PROVIDER_URL}/entities/{tenantId}/entity-configuration` with `FEDERATION_ENTITY_PROVIDER_TOKEN` as bearer token, and serves the answer unchanged ([environment variables](../reference/environment-variables.md#federation)). Like a locally signed one, the answer is reused for up to a minute, or until the issuance configuration changes. The trust engine answers with `application/entity-statement+jwt` and the signed entity configuration; EUDIPLO only checks that it is an entity statement (`typ: entity-statement+jwt`) whose `iss` and `sub` equal the configured `entityId`. The trust engine then decides the keys and metadata, and the federation key chain and entity settings above other than `entityId` and `trustAnchors` are not used. The request is subject to the outbound URL policy, redirects are not followed, and an error answer, an invalid answer or a failed request (10 seconds, 256 KiB) answers `503`.
#### OID4VP requests with a federation client identifier
With `openid_credential_verifier` in `entityTypes`, a presentation request can use `"clientIdScheme": "openid_federation"` ([Create requests](../presentation/requests.md#client-identifier)). The request then has `client_id` `openid_federation:`, and its request object is signed with the access key chain as before, with a `kid` header of a key in the `openid_credential_verifier` metadata instead of `x5c`. A wallet takes the verifier metadata from your trust chain and ignores `client_metadata` (OID4VP 1.0 Section 5.9.3), so it encrypts the response to the tenant encryption key published there instead of a key for this request. Unlike `x509_hash` and `x509_san_dns` requests, whose response key exists only for one session, these responses can be decrypted with the long-lived tenant key: a leaked key exposes every captured federation response of the tenant. A response is still bound to its session by the `nonce` and `state` it must carry. Wallets may keep your trust chain until its `exp`, so after replacing the tenant encryption key, responses encrypted to the old key fail for up to `entityConfigurationLifetimeSeconds`. With `includeTrustChain`, the request object carries the trust chain in its `trust_chain` header; it is not sent as request parameter, because wallets built on `@openid4vc/openid4vp` 0.7 reject that parameter together with an `openid_federation:` client identifier. These wallets read the chain only from the parameter, so they ignore the header and resolve your trust chain themselves.
### Reference trust anchors in DCQL
Add an `openid_federation` entry with the entity IDs of [registered](#register-trust-anchors) trust anchors to `trusted_authorities`; without an `etsi_tl` entry in the query, a configuration naming an unregistered one is rejected. The entry is sent to the wallet unchanged. If it is the only entry, EUDIPLO accepts only SD-JWT VCs whose issuer chains to one of these trust anchors. An `etsi_tl` entry in the same query takes precedence: the issuer must then be in the trust list, as a credential is checked one way.
```json
{
"trusted_authorities": [
{ "type": "openid_federation", "values": ["https://ta.example.org"] }
]
}
```
A credential verified through federation needs an `iss` claim and a `kid` header:
```json
{ "alg": "ES256", "typ": "dc+sd-jwt", "kid": "credential-key" }
```
### Errors
| Where | Error |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Chained authorization server | `400`: `Upstream issuer is not trusted by OpenID Federation policy: ` |
| External authorization server | `400`: `Authorization server is not trusted by OpenID Federation policy: ` |
| Credential verification | Failure code `no_trust_chain_to_root` (no valid chain, or no key `kid`), `trust_list_unavailable` (federation unreachable), `signature_invalid` or `verification_error` (no `iss` or `kid`, or an mDOC); the reason is in the server log |
| Issuance configuration | `400`: `Only the federation role 'leaf' is supported ...` or `enforceSigningPolicy cannot be disabled ...` |
| Entity configuration endpoint | OpenID Federation error responses (Section 8.9): `404` `not_found` when the tenant has no `entityId` or trust anchor, a stored `entityId` that the rule for `entityId` above refuses, for example one saved before 10.0 (the reason is in the server log), no key chain with usage type `federation`, or `entityKeyChainId` names no federation key chain; `503` `temporarily_unavailable` when the trust engine (`FEDERATION_ENTITY_PROVIDER=http`) does not deliver it; `500` `server_error` otherwise, with the reason in the server log |
| Presentation request | `400`: `clientIdScheme openid_federation needs federation.entityId, at least one trust anchor and openid_credential_verifier in federation.entityTypes ...`, or `clientIdScheme openid_federation needs a valid federation.entityId ...` with the reason for a stored `entityId` saved before 10.0 |
| Request object fetched by the wallet | `400`: `The OpenID Federation verifier identity of this request is no longer configured`, when `entityId` or `entityTypes` changed after the request was created |
| Issuance or presentation configuration | `400`: `OpenID Federation trust anchors without pinned keys: . ...`; [register](#register-trust-anchors) them first |
| Trust anchor registration | `400` for an invalid entity ID or key; `409`: `Federation trust anchor '' already exists`, `Trust anchor is already registered as ''`, or `FEDERATION_TRUST_ANCHOR_IN_USE` ([Delete a trust anchor](#delete-a-trust-anchor)) |
Common reasons:
- ` does not chain to a configured trust anchor`: the `authority_hints` do not lead to a configured trust anchor.
- `no trust anchor of is registered with pinned keys`: none of the trust anchors is registered for the tenant, for example a configuration stored before 10.0 that names a trust anchor you have not registered yet. A warning in the log names trust anchors without keys.
- `... entity configuration of trust anchor '' is not signed with a configured key` (local resolver) or `entity configuration of trust anchor is not signed with a pinned key`: the trust anchor's host serves keys you did not register. Check the registered `jwks`, for example after a key rollover.
- `no valid trust chain from to a configured trust anchor: `: a chain was found but failed validation, for example `... has expired`, `... is not signed with a key listed by ...`, `request to '?sub=...' failed with status 404` (the superior does not list the entity) or `... has subject ...` (an entity configuration about another entity).
- `could not fetch federation statements for : `: a timeout (5 seconds), a failed request or a URL the outbound URL policy blocks, and no valid earlier resolution.
- `federation entity has no oauth_authorization_server or openid_provider metadata` (or `openid_credential_issuer`).
- `oauth_authorization_server issuer of is missing or not its entity identifier`.
- `openid_credential_issuer metadata of has no key ''`.
- `trust chain resolution exceeded 32 requests` or `... entity visits`: too many entities or `authority_hints`.
- `federation mode requires trust anchors, none configured`.
### Troubleshooting
| Symptom | Fix |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `could not fetch federation statements` | Check that the entity configurations and fetch endpoints are reachable over HTTPS with a valid certificate on a public address, and answer with `application/entity-statement+jwt`. |
| `not signed with a configured key` or `... with a pinned key` | Compare the trust anchor's published keys with the registered `jwks` through a channel you trust, and update the registration. |
| `does not chain to a configured trust anchor` | Check the trust anchor entity IDs, compared exactly, and the entity's `authority_hints`. |
| `failed with status 404` from a fetch endpoint | The superior does not list the entity as its subordinate; register the entity there. |
| `has no key ''` | The credential's `kid` must be in the `jwks` of the issuer's `openid_credential_issuer` metadata. |
| Your entity is not trusted by a verifier | Fetch `{entityId}/.well-known/openid-federation` and check `iss`, `authority_hints` and the keys; the trust anchor's subordinate statement must list the public key of your federation key chain. |
| A federation verifier rejects your credential's `kid` | The `kid` must be in `openid_credential_issuer.jwks` of your entity configuration; it is renewed at most a minute after a key chain is created or rotated. |
| A changed federation still gives the old decision | Resolutions are cached (see [Caching](#caching)). Clear your tenant's resolutions with `DELETE /api/cache/trust-list` or `DELETE /api/cache`. |
Cache activity is reported as the OpenTelemetry counters `federation_trust_cache_hits_total`, `federation_trust_cache_misses_total`, `federation_trust_cache_stale_total` and `federation_trust_fetches_total`.
---
## Trust
Wallets and verifiers only accept EUDIPLO if they trust its certificates, and EUDIPLO only accepts credentials and wallets it can trust. This section covers both directions. Pick the page for your task:
| I want to... | Read |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Create or import the keys that sign credentials, status lists, trust lists and requests | [Keys and Certificates](keys-and-certificates.md) |
| Know which certificates a specific wallet needs | [Wallet and Registrar Requirements](wallet-registrars.md) |
| Get access and registration certificates from the German EUDI Hub | [EUDI Hub](eudi-hub.md) |
| Tell wallets what my verifier may request or which credentials my issuer provides | [Registration Certificates](registration-certificates.md) |
| Accept credentials only from specific issuers, or publish a list of my own issuers | [Trust Lists](trust-lists.md) |
| Decide trust through OpenID Federation trust anchors | [OpenID Federation](federation.md) |
| Issue only to trusted wallet apps and to keys with a certain security level | [Wallet and Key Attestation](attestation.md) |
### Who proves what to whom
| Direction | What is presented | Checked against |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| EUDIPLO as verifier → wallet | Presentation requests signed with the **access certificate**, optionally with a **registration certificate** that authorizes the requested data | The wallet's trust in the access certificate's issuer and the registrar |
| EUDIPLO as issuer → wallet | Credentials signed with an **attestation** key chain; optionally signed issuer metadata (access certificate) and a registration certificate in `issuer_info` | Trust lists or the ecosystem's trust anchors, in the wallet |
| Wallet → EUDIPLO as verifier | Credentials with the issuer's certificate chain, status lists signed by the revocation certificate that belongs to the matched issuance service (or the issuance certificate if the issuer lists none, [details](trust-lists.md#how-a-trust-list-is-used)) | [Trust lists](trust-lists.md) in `trusted_authorities`: LoTEs, and ETSI TS 119 612 Trusted Lists for QEAAs |
| Wallet → EUDIPLO as verifier, federation | SD-JWT VCs with `iss` and `kid`, signed with a key of the issuer's federation metadata; status lists signed with a key of the same metadata | [Federation](federation.md) trust anchors in `trusted_authorities` |
| Wallet → EUDIPLO as issuer | **Wallet attestation** at the authorization server, **key attestation** for holder keys | [Wallet-provider trust lists](attestation.md) |
Wallets never present registration certificates; issuers and verifiers present theirs to wallets.
Where keys are stored (database, Vault, AWS KMS, HSM and others) is an operator decision: see [KMS](../operate/kms.md).
---
## Keys and Certificates
A key chain is a signing key together with its certificate chain. Each tenant needs one per purpose: an access key chain to sign presentation requests, an attestation key chain to sign credentials, and optionally status list and trust list key chains. The key chain that signs access tokens is created by EUDIPLO ([Authorization server key chain](#authorization-server-key-chain)). Create them in the Web Client under **Cryptographic Assets → Keys → Create Key**, or with the API below; where the private keys live is set by the [KMS provider](../operate/kms.md).
**Prerequisites:** the `issuance:manage`, `presentation:manage` or `keys:manage` role.
### Usage types
| `usageType` | Signs | Web Client option |
| ------------- | ---------------------------------------------------------------------------------------------- | --------------------------------- |
| `access` | Presentation requests (it determines the `client_id`), signed issuer metadata, ISO 18013-7 `readerAuth` | Access Certificate |
| `authorizationServer` | The access tokens of EUDIPLO's [authorization servers](../issuance/authorization-servers.md) and the ID tokens of the [OpenID Provider](../presentation/openid-connect.md) ([details](#authorization-server-key-chain)) | Authorization Server |
| `attestation` | Issued credentials (SD-JWT VC and mDOC) | Credential Signing (Attestation) |
| `statusList` | Status lists for [revocation](../issuance/revocation.md) | Status List Signing |
| `trustList` | [Trust lists](trust-lists.md) you publish | Trust List Signing |
| `federation` | The [OpenID Federation entity configuration](federation.md#publish-your-entity-configuration) of the tenant | OpenID Federation Entity Key |
`encrypt` is reserved for the tenant's encryption key, which EUDIPLO creates and manages itself. It is not listed with the other key chains, and the key chain endpoints do not change it: updating, rotating, deleting, exporting or creating a CSR for its ID answers `404`, and an import with its ID answers `409`. Configuration bundles leave it out and skip a document with its ID ([Config Bundle Format](../reference/config-bundle-format.md#import-modes-and-plan-actions)).
### Key chain types
| Type | Created with | Certificate | On rotation |
| ----------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| Standalone | `POST /api/key-chain` with `"type": "standalone"` | Self-signed; subject is the tenant name, DNS name the host of `PUBLIC_URL` | New key with a new self-signed certificate |
| Internal chain | `POST /api/key-chain` with `"type": "internalChain"` | EUDIPLO creates a root CA (valid 10 years) and a leaf certificate signed by it | New leaf key signed by the same root |
| Imported key | `POST /api/key-chain/import` with `"type": "standalone"` | Your chain from `crt` (leaf first), or a self-signed certificate valid 365 days if `crt` is omitted | New key with a self-signed certificate (see warning below) |
| External CA chain | `POST /api/key-chain/import` with `"type": "internalChain"` | `key` is your CA key and the last `crt` entry its CA certificate, or a self-signed CA certificate EUDIPLO creates if `crt` is omitted; EUDIPLO generates leaf keys signed by it | New leaf key signed by your CA |
In the Web Client, attestation and status list keys offer **Key Chain with Root CA** (internal chain), **Standalone Key** and **External CA Chain** (external CA chain; the last certificate must be the CA certificate); access keys offer **Self-Signed Certificate** and **External Certificate**; a self-signed access key chain can then get its certificate from the [EUDI Hub](eudi-hub.md#request-an-access-certificate). Standalone Key and the other usage types except OpenID Federation Entity Key and Authorization Server, which are always created, offer an external certificate with **Use a certificate from an external CA**. For an external certificate, choose **Import a key and the certificate chain issued for it**, or **Create the key in EUDIPLO and request its certificate with a CSR** ([details](#request-a-certificate-with-a-csr)). Key Chain with Root CA and External CA Chain rotate the signing key by default; with **Enable automatic key rotation** off, the signing certificate expires after **Certificate Validity** and is renewed only once you turn rotation on by editing the key chain. The other options create key chains without rotation. When EUDIPLO creates the key, **Signing Algorithm** offers the algorithms of the selected KMS provider, starting with its default; imported keys keep the algorithm of their curve. The wizard accepts pasted PEM values and PEM, CRT, CER or DER files; EUDIPLO checks that key and certificate match.
Use an internal or external CA chain for attestation and status list keys: trust lists publish the CA certificate, so entries stay valid when the leaf key rotates.
### Create a key chain
```bash
curl -X POST "$EUDIPLO_URL/api/key-chain" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data '{
"usageType": "attestation",
"type": "internalChain",
"description": "Membership signing key",
"rotationPolicy": { "enabled": true, "intervalDays": 90, "certValidityDays": 365 }
}'
```
The response is `{ "id": "" }`. `kmsProvider` selects a provider ID from `kms.json`; without it the default provider is used. `alg` selects the signing algorithm and with it the curve: `ES256` (P-256, the default), `ES384` (P-384) or `ES512` (P-521), as far as the provider offers it ([signing algorithms](../operate/kms.md#signing-algorithms)). The root CA and every rotated key use the same algorithm; `GET /api/key-chain/{id}` returns it as `alg`. Wallets only have to support `ES256`. `certValidityDays` defaults to 365. `intervalDays` is required when `rotationPolicy.enabled` is `true`; without rotation the key is only rotated on request.
`GET /api/key-chain/{id}` and `GET /api/key-chain` return the active key's public key as a JWK in `activePublicKey` (after a rotation, the old one in `previousPublicKey`), without private key material. In the Web Client, federation and authorization server key chains show it on their **Public Key** card with **Copy Public Key (JWK)**; for other key chains, **View as JSON** shows it.
### Import a key and certificate
Import material issued by your own PKI or an ecosystem operator with `POST /api/key-chain/import`. Provide exactly one of `key` (EC private key as JWK) or `keyPem` (PKCS#8 PEM). The key may be on P-256, P-384 or P-521; its curve sets the key chain's algorithm (`ES256`, `ES384` or `ES512`), which must be one the provider offers:
```json
{
"usageType": "access",
"description": "Access certificate from the ecosystem operator",
"keyPem": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
"crt": [
"-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----",
"-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----"
]
}
```
A private key whose `d` is missing or does not belong to its public key (`x` and `y` of a `key`, or the public key a `keyPem` carries) is refused with `400`. For an imported key, the first certificate must contain the public key of the imported private key. For an **external CA chain**, add `"type": "internalChain"` and pass the CA key and a chain whose last certificate is the CA certificate (`CA=true`, matching the key); the certificates before it are not used. EUDIPLO then creates the signing leaf itself, and rotates it with `"rotationPolicy": { "enabled": true, "intervalDays": 30, "certValidityDays": 365 }`. With rotation enabled, a missing `intervalDays` becomes 90 and a missing `certValidityDays` 365; without rotation, no intervals are stored. For an external CA chain, `certValidityDays` (default 365) also sets the validity of the first signing certificate, with or without rotation.
Without `type`, as in files written before 10.0, the import decides from `rotationPolicy`: with rotation enabled it is an external CA chain, unless `crt` is one self-signed certificate that is not a CA (the export of a standalone key chain); otherwise it is an imported key.
To provision key chains as files, put the same JSON into `config//key-chains/`; see [Configuration as Code](../operate/configuration-as-code.md). `GET /api/key-chain/{id}/export` returns a key chain in this format, with its `type`, and needs `tenant:admin` or `tenants:manage`. For an internal or external CA chain it contains the CA key and certificate but not the signing key, so its import keeps the CA and creates a new signing key, as a rotation does. For the `db` provider the export contains the private key; for an external KMS only the public key, because the private key never leaves the KMS, so that file cannot be imported again. **Download configuration** on a key's page in the Web Client saves `GET /api/config-bundles/resources/KeyChain/{id}/document` instead: a document that also contains the signing key of a CA chain, so its import keeps both keys ([single resources](../reference/config-bundle-format.md#single-resources)). For 9.x exports, see the [10.0 upgrade guide](../upgrade/9.x-to-10.0.md#configuration-files). A startup import does not apply an unchanged file again and so renews no certificate ([details](../reference/config-bundle-format.md#import-modes-and-plan-actions)).
### Request a certificate with a CSR
To keep the private key in EUDIPLO, in its KMS, and still get the certificate from your own CA or an ecosystem operator, create a standalone key chain and send your CA a certificate signing request (CSR) for it:
1. Create a standalone key chain without rotation, as above with `"type": "standalone"`. Until step 3 it has a self-signed certificate.
2. Create the CSR. `subject` is the distinguished name your CA should certify; without it, the subject is `CN=`. EUDIPLO encodes the attributes in the order you write them, so write them in certificate order, country first.
```bash
curl -G "$EUDIPLO_URL/api/key-chain/$KEY_ID/csr" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "subject=C=DE, O=Example Org, CN=Example Verifier"
```
The response is `{ "csr": "-----BEGIN CERTIFICATE REQUEST-----\n..." }`, a PKCS#10 request signed by the active key. A subject that is not a distinguished name or is longer than 1024 characters is refused with `400`.
3. Store the certificate your CA issued, leaf first, followed by any issuing certificates:
```bash
curl -X PUT "$EUDIPLO_URL/api/key-chain/$KEY_ID" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data '{ "activeCertificate": "-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----" }'
```
EUDIPLO refuses with `400` a value without a PEM certificate, a first certificate that does not hold the public key of the active key, such as one issued for a CSR from before a rotation, and a chain in which a certificate did not issue the one before it. Wallets validate the chain in that order.
In the Web Client, the page of a standalone or imported key chain, except an OpenID Federation entity key, has the card **Certificate from an External CA** for steps 2 and 3: **Request Certificate from External CA**, **Create CSR**, then **Copy CSR** or **Download CSR**, and **Store Certificate** for the issued chain. For a key chain managed by a configuration file, add the issued chain to `crt` in that file instead. To renew the certificate, create a new CSR for the same key and store the new certificate; do not rotate the key chain.
### Rotate keys
- **Automatic:** once a day, every key chain with `rotationPolicy.enabled` and an `intervalDays` that has passed since creation or the last rotation is rotated.
- **Manual:** `POST /api/key-chain/{id}/rotate` rotates immediately (`204`).
- **Change the policy:** `PUT /api/key-chain/{id}` with `rotationPolicy` or `description`. Enabling rotation needs `intervalDays`, unless the key chain already has one.
Rotation creates a new key and certificate as listed in the table above. The JWKS of an authorization server keeps the previous key of its authorization server key chain for one access token lifetime after the rotation, so tokens signed just before stay valid. Credentials issued before keep their certificate chain in `x5c`; with an internal or external CA chain, old and new credentials chain to the same CA, so trust lists need no update.
:::warning[Rotating imported keys]
Rotating a standalone or imported key chain replaces its certificate with a self-signed one. Do not rotate key chains whose certificate comes from a registrar or an external PKI; import the renewed key and certificate, [request a renewed certificate with a CSR](#request-a-certificate-with-a-csr), or use an external CA chain.
:::
### Authorization server key chain
The hosted [authorization servers](../issuance/authorization-servers.md) (built-in, chained and OID4VP) sign their access tokens only with a key chain of usage type `authorizationServer`, never with the access certificate or a credential signing key. Only EUDIPLO verifies these tokens, with the keys in the authorization server's JWKS (`/.well-known/jwks.json/issuers/{tenant}` for the built-in server), so the key chain needs no certificate from a CA. The tenant's [OpenID Provider](../presentation/openid-connect.md) signs its ID tokens with the tenant's authorization server key chain too; relying parties verify them with `/verifiers/{tenant}/oidc/jwks`, so a rotation reaches them through that JWKS.
An authorization server uses, in this order:
1. The key chain in `token.signingKeyId` of its entry. In the Web Client, choose it as **Authorization Server Key** of the authorization server in the issuance configuration; the list offers only authorization server key chains.
2. The `authorizationServer` entry of the tenant's key chain defaults. It is set only in a [config folder or bundle](../operate/configuration-as-code.md), as `authorizationServer` in `key-chain-defaults.json`, for example `{ "authorizationServer": "my-token-key" }`; the star in the Web Client and `PUT /api/key-chain/access/default` set only the `access` entry.
3. The tenant's authorization server key chain created first (by creation time, then ID).
4. Without any, EUDIPLO creates a standalone key chain with ID `authorization-server` on the first token request, with the tenant's default KMS provider. Its key in the KMS gets a random name, so tenants that share a KMS never share or delete each other's key. A JWKS requested before that is empty.
A named key chain that does not exist or has another usage type is never replaced by another one:
- Saving an issuance configuration whose `token.signingKeyId` names one answers `400`.
- A configuration bundle or config folder reports `MISSING_RESOURCE_REFERENCE` for a missing key chain and `KEY_CHAIN_USAGE_MISMATCH` for another usage type, for `token.signingKeyId` and for the `authorizationServer` entry of the key chain defaults. A `token.signingKeyId` of another usage type that the stored issuance configuration already has gets only a warning, so an unchanged folder still imports; a missing key chain is still reported. A key chain file of the same bundle or folder sets the usage type only if the import writes it ([plan actions](../reference/config-bundle-format.md#import-modes-and-plan-actions)).
- A configuration stored before 10.0, which can only name another usage type, fails the token requests of that authorization server with `500` while the backend log names the key chain. Remove the value or choose an authorization server key chain.
If a key chain with ID `authorization-server` and another usage type exists, EUDIPLO cannot create its key chain; token requests then fail and the log says so until you create an authorization server key chain.
The JWKS publishes the active key and, for one access token lifetime of that authorization server after a [rotation](#rotate-keys), the previous key. To replace the key, rotate the key chain with `POST /api/key-chain/{id}/rotate`, or create another authorization server key chain and choose it; tokens signed with the old key fail once it has left the JWKS.
### Delete a key chain
`DELETE /api/key-chain/{id}` answers `204` and, where the KMS provider supports it, also deletes the key in the KMS. It answers `409` while a configuration of the tenant names the key chain, because that configuration could no longer sign or publish the key chain's certificate. These fields count:
- an entry of the tenant's key chain defaults, `access` ([Default access key chain](#default-access-key-chain)) or `authorizationServer` ([Authorization server key chain](#authorization-server-key-chain)),
- `token.signingKeyId` of each authorization server of the issuance configuration,
- `keyChainId` of a credential configuration,
- `accessKeyChainId` of a presentation configuration,
- `keyChainId` of a status list,
- `keyChainId` of a [trust list](trust-lists.md), which the key chain signs, and `issuerKeyChainId` or `revocationKeyChainId` of its internal entities. Deleting the signing key chain would also delete the trust list.
A configuration that leaves the field out uses the tenant's default key chain of the usage type and does not count, so a default key chain picked by rule can be deleted; such configurations then use another key chain of that usage type, or fail until one exists. Authorization servers use another authorization server key chain, or a new `authorization-server` key chain if none is left ([Authorization server key chain](#authorization-server-key-chain)). Trust lists are the exception: a trust list created without `keyChainId` stores the trust list key chain picked at creation, so that key chain counts until the trust list is deleted, also when a bundle rewrites the trust list without `keyChainId`.
The response names the configurations in `message` and lists them in `references`. An entry of the key chain defaults is a reference of kind `KeyChainDefaults`, without ID. Configurations the caller's roles cannot read are only counted, without ID and description: the issuance configuration, credential configs and status lists need `issuance:manage`, presentation configs `presentation:manage` or `presentation:request`, and trust lists `issuance:manage` or `presentation:manage`.
```json
{
"statusCode": 409,
"timestamp": "2026-10-17T12:00:00.000Z",
"path": "/api/key-chain/pid-signing",
"code": "KEY_CHAIN_IN_USE",
"message": "Key chain \"pid-signing\" is still used by the issuance configuration and 1 credential config (\"pid\"). Remove these references before deleting the key chain.",
"references": [
{ "kind": "IssuanceConfig" },
{ "kind": "CredentialConfig", "id": "pid", "description": "Personal ID" }
]
}
```
Point the configurations to another key chain, or remove the field, then delete the key chain. In the Web Client, deleting a key chain from the key list or its page shows this message; the tenant's default access key chain is refused before any request, with a note to stop using it as default first. An unknown ID answers `404`. Sessions that are already running are not checked; an OpenID4VP request whose key chain is deleted before the wallet fetches it cannot be used ([Default access key chain](#default-access-key-chain)).
A [configuration bundle](../operate/configuration-as-code.md#plan-and-import) or a [config folder](../operate/configuration-as-code.md#provision-tenants-from-a-folder) imported in `replace` mode deletes a key chain that it created and no longer contains. Its plan is blocked with `KEY_CHAIN_IN_USE` on that key chain while a configuration that survives the import names it by the rules above: a stored configuration the import neither deletes nor rewrites, or a document of the bundle with its new content. A document of the bundle that names the key chain is also blocked with `MISSING_RESOURCE_REFERENCE`. Keep the key chain in the bundle, or remove the references, then plan again.
### Certificates
Certificates always belong to a key chain. Which one a wallet or verifier has to trust depends on its use:
| Certificate | Who checks it | Typical source |
| --------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Access certificate | Wallets, when they receive a presentation request or signed issuer metadata | Self-signed for development; registrar or ecosystem operator for production ([wallet requirements](wallet-registrars.md)) |
| Attestation certificate | Wallets and verifiers, through the `x5c` chain in each credential and a trust list | Internal or external CA chain; your issuer PKI |
| Status list certificate | Verifiers, as the revocation certificate of your trust list entry | Internal or external CA chain; standalone |
| Trust list certificate | Consumers of your trust list, who pin it as `verifierX509Der` | Standalone or internal chain |
A presentation configuration uses the access key chain in `accessKeyChainId`, or the default access key chain when it is not set. Registration certificates are JWTs issued by a registrar, not key chains; see [Registration Certificates](registration-certificates.md).
#### Certificate profile
Certificates that EUDIPLO creates follow the X.509 profiles of ISO/IEC 18013-5 Annex B for mdoc issuers, apart from the deviations listed below:
- A root CA that EUDIPLO creates, for an internal chain or an external CA chain imported without `crt`, follows the IACA profile for every usage type: a random serial number, key usage `keyCertSign` and `cRLSign` only, `CA=true` with path length 0, and an IssuerAlternativeName with `PUBLIC_URL`.
- The signing certificates of `attestation` key chains follow the document signer profile: the critical extended key usage `1.0.18013.5.1.2` (mDL document signer) and an IssuerAlternativeName. Under a CA, the IssuerAlternativeName is copied from the CA certificate, or is `PUBLIC_URL` when the CA certificate has none or one that is not a valid GeneralNames value, and the subject takes country (`C`) and state (`ST`) from the CA certificate. A self-signed attestation certificate gets the same extensions, but verifiers expect a document signer issued by a CA (IACA).
- Signing certificates of the other usage types carry no extended key usage.
An attestation key chain signs SD-JWT VCs with the same certificate. SD-JWT VC defines no extended key usage, but a verifier that applies RFC 5280 strictly (a certificate with this extension may be used only for the purposes it lists) rejects these SD-JWT VCs; make sure your SD-JWT VC verifiers accept the extended key usage, or import an attestation certificate of your own PKI. A status list signed with an attestation key chain ([which ones](../issuance/revocation.md#manage-status-lists)) carries the extended key usage too; use a `statusList` key chain if your verifiers check the extended key usage of status list certificates.
Deviations from Annex B:
- No CRLDistributionPoints extension. EUDIPLO publishes no CRL for the CAs it creates, and a distribution point without a CRL would make verifiers that fetch it fail.
- The country is `DE` in the certificates EUDIPLO creates, except where a document signer takes it from an imported CA certificate.
- Annex B allows document signer certificates at most 457 days of validity. EUDIPLO does not enforce it; keep `certValidityDays` of attestation key chains at 457 or less.
Existing key chains get the profile with their next signing certificate: when they rotate, or when an import makes EUDIPLO create the signing certificate (a key without `crt`, or an external CA chain). Existing root CA certificates are kept.
#### Default access key chain
Presentation requests (OID4VP and ISO 18013-7) of a configuration without `accessKeyChainId` and signed issuer metadata use the tenant's default access key chain. A presentation configuration's `accessKeyChainId` always takes precedence; the issuer metadata has no such field, so all issuance of a tenant uses the default.
To choose the default, set `access` of the tenant's key chain defaults:
- In the Web Client, select the star (**Use as default access key chain**) on an access key chain in the key list or on its page. The list marks the default with **Default**, or with **Default by rule** while none is set. Select the star again to remove the setting.
- Through the API, `PUT /api/key-chain/access/default` with `{"defaultAccessKeyChainId": ""}`, or `null` to remove it; `GET` returns the setting and the key chain in use (`keyChainId`). Both need `issuance:manage`, `presentation:manage` or `keys:manage`.
- In a [config folder or bundle](../operate/configuration-as-code.md), as `access` in `key-chain-defaults.json` next to `info.json` (resource `KeyChainDefaults/defaults`, [format](../reference/config-bundle-format.md#resource-types-and-versions)), for example `{ "access": "registrar-access" }`. The file may name a key chain of the same folder. A file without `access` removes the setting, and a `replace` import without the file deletes defaults it applied before. If it names no access key chain of the tenant, the plan is blocked with `MISSING_RESOURCE_REFERENCE` or `KEY_CHAIN_USAGE_MISMATCH`: a bundle import is refused, and at startup the import of that tenant's folder fails while the log names the key chain; the stored setting stays. While the file is file-managed, the API and the Web Client cannot change the setting: [detach](../operate/configuration-as-code.md#configuration-model) `KeyChainDefaults/defaults` first. Startup imports then skip the file until you reset it to the file version. The tenant settings in `info.json` stay file-managed.
The key chain must belong to the tenant and have usage type `access`, else the request answers `400`. While it is the default, deleting it is refused with `KEY_CHAIN_IN_USE` ([Delete a key chain](#delete-a-key-chain)). If it is gone anyway, requests that need the default fail instead of falling back to another certificate; the backend log names the key chain, `GET /api/key-chain/access/default` returns the setting without `keyChainId`, and the Web Client's key list shows a warning with **Remove default**.
Without the setting, EUDIPLO picks one of the tenant's access key chains in this order:
1. A certificate that is valid now before an expired or not yet valid one, which could not sign.
2. The kind of the active certificate: one issued by another CA, such as a registrar certificate or that of an imported key, before an internal chain (an External CA chain included), before a self-signed certificate.
3. The key chain created first.
A new access key chain therefore only becomes the default when its certificate is of a better kind, or when the certificate of the current default is no longer valid. To use a particular key chain, set the default access key chain, or `accessKeyChainId` for one presentation configuration.
An OpenID4VP request keeps the access key chain chosen when it was created: the request object a wallet fetches later is signed with the key chain its `client_id` was derived from, even when the default or the configuration's `accessKeyChainId` has changed in between. If that key chain is deleted or rotated before the wallet fetches the request, the wallet cannot use the request; create a new one.
#### Revocation check
Before a key chain signs, EUDIPLO checks that its leaf certificate is within its validity period and, if the certificate names a CRL distribution point, that the CRL does not list it. A key chain whose certificate is expired or revoked does not sign, and the requests that need it fail.
CRLs are usually served over plain HTTP, so a CRL only counts if it names the leaf's issuer and is signed by the issuing CA certificate. EUDIPLO looks for that certificate in the key chain: the certificates after the leaf in `crt` of an import or in `activeCertificate` of `PUT /api/key-chain/{id}`, or the root CA certificate of an internal or external CA chain. If the issuing CA certificate is not there, or no CRL can be fetched or passes these checks, EUDIPLO logs a warning and keeps signing. Self-signed certificates are not checked against a CRL, because no CA can revoke them. Certificates that EUDIPLO creates name no CRL distribution point.
---
## Registration Certificates
A registration certificate is a JWT, issued by a registrar, that states what a relying party is registered for: a verifier the data it may request and why, an issuer the attestations it provides. EUDIPLO presents it to wallets, which can warn about or refuse requests that go beyond it; wallets do not present registration certificates. EUDIPLO requests certificates from the German EUDI Hub ([EUDI Hub](eudi-hub.md#request-a-registration-certificate)) and stores them; a certificate from another registrar is stored the same way. EUDIPLO does not renew certificates: request a new one before it expires.
### Verifier registration certificate
Set `registration_cert` in a [presentation configuration](../presentation/configure-verification.md#registration-certificate). EUDIPLO adds the certificate to the signed request as `verifier_info: [{ "format": "registration_cert", "data": "" }]`.
| Field | Meaning |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jwt` | The certificate, attached to every request object as is. Without it, requests carry no registration certificate. |
| `purpose` | Why the data is requested (GDPR purpose), `[{ "lang", "content" }]`. Used when a certificate is requested from a registrar; the EUDI Hub needs `de` and `en`. |
| `privacy_policy` | URL of the privacy policy for this request. Used when a certificate is requested from a registrar. |
A request to the EUDI Hub stores all three, so a later request for a new certificate, for example after the DCQL query changed or before the certificate expires, can leave out the purpose and privacy policy. You can also set `purpose` and `privacy_policy` before the first request.
```json
{
"registration_cert": {
"jwt": "eyJ...",
"purpose": [
{ "lang": "de", "content": "Prüfung Ihrer Vereinsmitgliedschaft" },
{ "lang": "en", "content": "Check your club membership" }
],
"privacy_policy": "https://verifier.example/privacy"
}
}
```
#### Validation
The certificate is checked before every use:
- **Time:** `exp` and `nbf` with 60 seconds tolerance.
- **Overasking:** the certificate's authorized `credentials` must cover the request exactly; see [Overasking check](#overasking-check).
The certificate is checked when the configuration is created and when an update changes `registration_cert` or `dcql_query`; the API refuses a failed check with `400` and the reason. The plan of a [configuration bundle](../operate/configuration-as-code.md#plan-and-import) (`eudiplo config plan`) or a [config folder](../operate/configuration-as-code.md#provision-tenants-from-a-folder) runs the same check for each presentation config it creates or updates: the item is `blocked` with `REGISTRATION_CERTIFICATE_REFUSED` at `/spec/registration_cert` and the reason as message, so the import applies nothing. At startup, EUDIPLO then logs the issue and imports none of that tenant's files until the file is fixed. Exports of bundles and of single presentation configs keep the `jwt`, and a plan treats a changed `jwt` as a change. A presentation config the plan leaves `unchanged` or skips is not checked again, so a certificate that expires after it was imported does not block later imports. Any other change to that file, even to its description, checks the certificate again.
Every presentation request checks the certificate again; when it has expired since it was stored, or no longer covers the DCQL query, the request fails with `400`. EUDIPLO does not check which access certificate the registration certificate belongs to: it is attached whichever access key chain signs the request. When you change the access key chain of a presentation configuration, or the tenant's default access key chain, request a new registration certificate for it.
#### Overasking check
EUDIPLO only sends a registration certificate whose authorized `credentials` cover the request exactly. Each credential query of the DCQL query, with `` resolved, must equal one authorized credential in `format`, `meta` and the claim paths; the order of the claims, claim IDs, `values` and `intent_to_retain` are ignored. Requesting fewer claims than authorized also fails ("Registration certificate does not authorize the requested DCQL credentials"). After you change the DCQL query, request a new certificate. For development and interoperability tests only, `SKIP_OVERASKING_CHECK=true` disables the check; see [Skip Flags](../reference/environment-variables.md#skip-flags).
### Issuer registration certificate
Set `registrationCertificate` in the issuance configuration to publish a certificate in the credential issuer metadata as `issuer_info: [{ "format": "registration_cert", "data": "" }]`:
```json
{
"registrationCertificate": {
"enabled": true,
"jwt": "eyJ...",
"privacyPolicy": "https://issuer.example.com/privacy",
"supportUri": "https://issuer.example.com/support"
}
}
```
| Field | Meaning |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| `enabled` | Publish the certificate. |
| `jwt` | The certificate, published while it is within `nbf`/`exp` (30 seconds tolerance). An expired one is left out and logged. |
| `privacyPolicy` | Privacy policy URL of the issuer. Stored only; neither EUDIPLO nor the EUDI Hub request uses it. |
| `supportUri` | Support URI of the issuer, kept for requesting a new certificate. A request to the EUDI Hub stores the one it used. |
The certificate must list the credential types of the issuer: the `vct` of each SD-JWT VC configuration (for a `vct` object, its [hosted VCT URL](../issuance/credential-configuration.md)) and the `docType` of each mDOC configuration. A request to the EUDI Hub registers exactly these and refuses a certificate that misses one. After you add a credential type, request a new certificate.
### Verifier and issuer compared
| | Verifier (presentation configuration) | Issuer (issuance configuration) |
| --------------------- | ------------------------------------------- | ------------------------------------------------ |
| Certificate | `registration_cert.jwt` | `registrationCertificate.jwt` with `enabled: true` |
| Kept request values | `purpose`, `privacy_policy` | `supportUri` |
| Checks | Time (60 s tolerance) and overasking | Time (30 s tolerance) |
| After a change | New DCQL query: request a new certificate | New credential type: request a new certificate |
| Replaced certificate | Not revoked; revoke it at the registrar | Not revoked; revoke it at the registrar |
---
## Trust Lists
A trust list names the issuers you accept. EUDIPLO uses Lists of Trusted Entities (LoTE, ETSI TS 119 602) as signed JWTs: it publishes lists you manage and reads lists published by others. To accept qualified electronic attestations of attributes (QEAAs), it also reads ETSI TS 119 612 Trusted Lists in XML, directly or through a list of trusted lists such as the EU's ([Trusted Lists for QEAAs](#trusted-lists-for-qeaas)); it does not publish them. For a complete walkthrough, follow [chapter 3 of the cookbook](../cookbooks/first-presentation.md), which publishes a trust list and verifies against it, and [Accept only trusted issuers](../cookbooks/trusted-issuers.md), which tests an untrusted issuer and an external list.
### How a trust list is used
Each trusted entity has an issuance certificate and a revocation certificate that signs its status lists. Lists you manage in EUDIPLO always include both; lists published by others may omit the revocation certificate. Services of a LoTE are read by the rules of the list's `LoTEType` (ETSI TS 119 602 V1.1.1), in every LoTE and also in wallet-provider lists ([Service status and type](#service-status-and-type)); Trusted Lists have their own rules ([Trusted Lists for QEAAs](#trusted-lists-for-qeaas)). A list without a valid `NextUpdate`, or whose `NextUpdate` has passed, is discarded as expired (ETSI TS 119 602 §6.3.15), in every position and also as a wallet-provider list; a closed list, whose `NextUpdate` is null, too. By then its publisher has issued a newer list, and an older one, though validly signed, may still name an issuer that the newer list removed or withdrew. For the same reason, a list numbered lower (`LoTESequenceNumber`) than one EUDIPLO already accepted from the same URL is discarded, even while its `NextUpdate` is ahead, and so is a list without a valid `LoTESequenceNumber` (`TSLSequenceNumber` for a Trusted List, [Older versions of a list](#older-versions-of-a-list)). The issuers of a discarded list are not trusted, while the other lists referenced with it still count. The log names each discarded list with its `NextUpdate` or its sequence number (`Discarded outdated trust list(s) ...`, or `Discarded outdated or unavailable trust list(s) ...` when a Trusted List reached through a list of trusted lists could not be loaded). Only when every list referenced together is discarded does the check fail as if no list could be loaded. When a credential is presented, EUDIPLO:
1. loads every list of the credential query's `etsi_tl` entry, checks its signature and discards it if it is outdated or older than a list accepted before,
2. builds a certificate path from the credential's `x5c` chain to a certificate listed as a PID, Pub-EAA or EAA issuance service of a LoTE (`http://uri.etsi.org/19602/SvcType/PID/Issuance`, `.../PubEAA/Issuance` or `.../EAA/Issuance`), or as a granted qualified service for the issuance of QEAAs of a Trusted List (`http://uri.etsi.org/TrstSvc/Svctype/EAA/Q`, [Trusted Lists for QEAAs](#trusted-lists-for-qeaas)). Other service types are ignored for credentials: a credential under the `.../WalletSolution/Issuance` or `.../WRPAC/Issuance` certificate of an entity is rejected, even when the same entity is also listed as a PID provider,
3. if status checks are enabled, requires the status list of the credential (SD-JWT VC or mDOC) to be signed under a revocation certificate of the **same** entity whose type belongs to the matched issuance service: `.../PID/Revocation` for `.../PID/Issuance`, `.../PubEAA/Revocation` for `.../PubEAA/Issuance` and `.../EAA/Revocation` for `.../EAA/Issuance`. If the entity lists no revocation service of that type, its `.../EAA/Revocation` services count instead. The status list must be signed below that certificate if it is a CA, or with it if it is an end-entity certificate. An entity listed without such a revocation certificate must sign its status lists under the certificate the credential matched, in the same way; so must every QTSP of a Trusted List, since ETSI TS 119 612 defines no service for the status of attestations. A status list signed by any other key rejects the credential, also one under a revocation certificate of the same entity for another service, such as `.../WalletSolution/Revocation`. The chain comes from the status list's `x5c` header (SD-JWT VC) or `x5chain` (mDOC). Every certificate from the signer up to the listed one, included, must be within its validity period at verification time; otherwise the credential is rejected, also with `statusCheckMode: best_effort`, because the list was fetched.
A credential's `x5c` (SD-JWT VC) or `x5chain` (mDOC), and the one of its status list or identifier list, may hold at most 10 certificates in total, a trust anchor included if it is sent; it should hold only the signing certificate and its intermediates. A longer chain is rejected before a certificate path is built from it; the path has its own [size limits](#size-limits). A credential with such a chain fails with `verification_error`, also when no trust list is configured; the wallet and the session get the short message of `verification_error`, and the server log, and the session log when it is enabled, names the number, for example `x5c holds 11 certificates; at most 10 are accepted`. A credential whose status list carries such a chain fails too, also with `statusCheckMode: best_effort`: an mDOC with `verification_error`, an SD-JWT VC whose issuer matched a trust list with `Status List JWT verification failed`, as for a status list with another signer, while the server log names the number.
A listed CA certificate accepts every credential issued below it; a listed end-entity certificate only accepts credentials signed with exactly that certificate. Wallet-provider lists, used to trust wallet and key attestations during issuance, are described in [Wallet and Key Attestation](attestation.md).
#### Service status and type
A service whose `ServiceStatus` does not approve it is ignored, and so is an entity whose services are all ignored:
| `LoTEType` | Service read when `ServiceStatus` is | Service ignored when `ServiceStatus` is |
| --- | --- | --- |
| `EUPubEAAProvidersList` (Annex H) | `http://uri.etsi.org/19602/PubEAAProvidersList/SvcStatus/notified`, or absent (with a warning, since Annex H requires it) | any other value, including `.../SvcStatus/withdrawn` |
| `EUPIDProvidersList` (Annex D) | absent, or `http://uri.etsi.org/19602/PidProvidersList/SvcStatus/notified`, which PID lists in use set although Annex D says "The ServiceStatus component shall not be used" | any other value |
| `EUWalletProvidersList`, `EUWRPACProvidersList`, `EUWRPRCProvidersList`, `EURegistrarsAndRegistersList` (Annexes E to G and I) | absent | any value: these profiles say "The ServiceStatus component shall not be used" |
| any other, including `EUEAAProvidersList` and lists without `LoTEType` | absent, `.../PubEAAProvidersList/SvcStatus/notified` or `http://uri.etsi.org/19602/commons/schemeApprovalGranted` | any other value, including `.../commons/schemeApprovalWithdrawn` |
A status URI a scheme defines itself (§6.6.4) is not known to EUDIPLO, so services carrying it are ignored. So are services with an ETSI TS 119 612 type, such as `http://uri.etsi.org/TrstSvc/Svctype/EAA/Q`: only a Trusted List can grant a qualified status ([Trusted Lists for QEAAs](#trusted-lists-for-qeaas)).
A service without `ServiceTypeIdentifier` is read only in a list where no service has a type (§6.6.0, NOTE 2). It then gets the issuance type of the list's profile: `SvcType/PID/Issuance` in a PID providers list, `SvcType/WalletSolution/Issuance` in a wallet providers list, `SvcType/PubEAA/Issuance` in a Pub-EAA providers list and `SvcType/EAA/Issuance` in an `EUEAAProvidersList`. NOTE 2 does not say which type that is; EUDIPLO assumes the providers' issuing services, which is what a list of one type lists. If a publisher lists only revocation services without a type, their certificates are trusted to sign credentials or attestations, so ask it to set `ServiceTypeIdentifier`. In a list whose other services have a type, or whose type implies none, it is ignored.
For each list, one warning in the log names the services ignored or read despite a missing status (at most ten of each, then a count), with entity, service type, status and reason: `Trust list : left out N service(s): ...`, `Trust list : read N service(s) despite: ...`, or both parts in one line. Lists managed in EUDIPLO always set the type and no status, so they produce no warning.
#### Size limits
Every check reads all certificates of the lists it uses, and builds its certificate path from them. So that a list's publisher, or a tenant through a managed list, cannot decide how long a check takes on a shared instance, two limits apply:
- **At most 1,000 certificates** in the lists used together: the lists of a credential query's `etsi_tl` entry, or the `walletProviderTrustLists` that wallet and key attestations are checked against. Every certificate of each entity EUDIPLO keeps from them counts, also those of the entity's other services: for credentials, an entity is kept when it has a PID, Pub-EAA or EAA issuance service; for attestations, when it has a `WalletSolution` service of any kind. Of a Trusted List, only the certificates of granted qualified QEAA services count, also for the national lists reached through a list of trusted lists. When the lists hold more, EUDIPLO uses none of them and does not load the lists after the one that goes over the limit. The check fails as when a list cannot be loaded: a presented credential with `trust_list_unavailable`, a wallet or key attestation with `Wallet provider trust lists could not be loaded` or `Attestation proof x5c chain could not be validated`. The server log names the list, for example `Trust list https://trust.example.org/lists/pid.jwt brings the certificates of its source to 1001; at most 1000 are accepted`, and such lists are not fetched again for one minute. Requests send such an `etsi_tl` entry as plain URLs ([What the wallet receives](#what-the-wallet-receives)). A managed list may still hold more certificates for others who read it.
- **At most 16 certificates and 64 signature checks per certificate path**, from the certificate that signs a credential, status list or attestation to the certificate the path ends at, both included. For each certificate of the path, EUDIPLO checks its signature against the certificates of the `x5c` or `x5chain` and of the lists whose subject is that certificate's issuer, in turn, until one verifies; one whose Subject Key Identifier differs from the certificate's Authority Key Identifier is skipped without a check. A path past either limit is rejected: a presented SD-JWT VC with `no_trust_chain_to_root`, an mDOC with `verification_error` (or `no_trust_chain_to_root` when only EUDIPLO's own check of the issuer's path, after the mDOC library's, goes past a limit), an SD-JWT VC whose status list has such a path with `Status List JWT verification failed`, and a wallet or key attestation or its status list with `... certificate chain is not valid: ...` ([Wallet and Key Attestation](attestation.md#troubleshooting)). The server log names the limit, `Certificate path not found within 64 signature checks` or `Certificate path is longer than 16 certificates`, and so does the session log when it is enabled, except for an SD-JWT VC's status list. A chain with the signing certificate and its intermediates, checked against lists whose CA certificates carry a Subject Key Identifier, needs a few checks. Lists that put many certificates with one subject name and no Subject Key Identifier before the one a path needs can make the path fail, also for the other lists used with them.
#### Older versions of a list
`NextUpdate` only limits how long an older version of a list stays usable: served again before its `NextUpdate` has passed, a validly signed older list would still name an issuer that the newer list removed or withdrew. EUDIPLO therefore also reads the list's `LoTESequenceNumber`, which its publisher raises with every list it issues and never lowers (ETSI TS 119 602 §6.3.2), or the `TSLSequenceNumber` of a Trusted List (ETSI TS 119 612 clause 5.3.2). This applies to every list, also to wallet-provider lists and to the national lists reached through a list of trusted lists:
- For each tenant and list URL, EUDIPLO remembers the highest number of a list it accepted. The numbers are kept in the database, so they hold after a restart and for every instance.
- A list numbered lower is discarded like an outdated list, and so is a list whose `LoTESequenceNumber` or `TSLSequenceNumber` is missing or not a whole number from 1. The log names the numbers, for example `Discarded outdated trust list(s), using the current lists: https://trust.example.org/lists/pid.jwt (LoTESequenceNumber 3 is lower than 5 accepted before) ...`. A list with the same number as before is accepted.
- A managed list of this EUDIPLO instance, referenced by `trustListId` or by a URL below `PUBLIC_URL` or `INTERNAL_URL` such as `/trust-list/`, is compared with the number it has in storage instead, and nothing is remembered for it: that number is always the current one, also for a list that was deleted and created again, which starts at 1.
A publisher that numbers its list from 1 again breaks this rule, and the list stays discarded until its number is higher than the one remembered. Another EUDIPLO instance does this when one of its managed lists is created anew: deleted and created again, dropped by a `replace` import and added back later, or imported into an empty database. To accept such a list, call `DELETE /api/cache/trust-list/sequence-numbers` (role `issuance:manage` or `presentation:manage`): it forgets the numbers of your tenant and clears your tenant's trust list cache. The next list fetched from each URL then sets its number again, whichever version it is, so only do this once the publisher has confirmed the new numbering. Deleting a tenant deletes its numbers.
### Publish a managed trust list
Create the list in the Web Client under **Cryptographic Assets → Trust Lists**, or with `POST /api/trust-list` (role `issuance:manage` or `presentation:manage`):
```json
{
"id": "membership-issuers",
"description": "Issuers of membership credentials",
"entities": [
{
"type": "internal",
"issuerKeyChainId": "",
"revocationKeyChainId": "",
"info": {
"name": "Example Club",
"country": "DE",
"contactUri": "info@club.example",
"website": "https://club.example/"
}
},
{
"type": "external",
"issuerCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
"revocationCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
"info": {
"name": "Partner Club",
"contactUri": "mailto:office@partner.example",
"website": "https://partner.example/",
"phone": "+49-30-1234567"
}
}
]
}
```
- **Internal** entities reference key chains of this tenant. EUDIPLO lists the last certificate of each chain, the root CA for internal and external CA chains, so the entry survives key rotation. `issuerKeyChainId` must name a key chain with usage type `attestation`, and `revocationKeyChainId` one with `statusList` or `attestation`, since [status lists](../issuance/revocation.md#manage-status-lists) are signed with the attestation key chain when they are pinned to it or the tenant has no status list key chain. Otherwise `POST` and `PUT` answer `400`, with an entry per field in `errors` (`path` `["entities", , "issuerKeyChainId"]` or `revocationKeyChainId`), and a [configuration bundle or config folder](../operate/configuration-as-code.md#plan-and-import) is blocked with `KEY_CHAIN_USAGE_MISMATCH`. A key chain that the stored list already names in that field is still accepted, so lists saved before 10.0 can be updated: the plan only warns about it, as it does for a list the import skips, for example a detached one. EUDIPLO checks only the usage type: name the key chains that sign the issuer's credentials and its status lists, as wallets and verifiers check signatures against these certificates. A status list that is not pinned is signed by one of the tenant's `statusList` key chains, else by one of its `attestation` key chains, without a defined order; with several key chains of that usage type, pin the issuer's status lists (`keyChainId`) to the key chain named in `revocationKeyChainId`. In the Web Client, the **Issuer Key Chain** select offers `attestation` key chains, and the **Revocation Key Chain** select offers `statusList` key chains and, after them, `attestation` ones, with a hint on which status lists an `attestation` key chain signs. Both selects mark a stored key chain of another usage type, or one that no longer exists.
- **External** entities carry the certificates of issuers outside this tenant, as PEM or Base64 DER.
- `info` describes the entity in the published list, as ETSI TS 119 602 requires: `country` is an ISO 3166-1 alpha-2 code in capital letters (clause 6.1.5), with `UK` for the United Kingdom, `EL` for Greece and `EU` for the European Union, and defaults to `EU`; `lang` is an IETF RFC 5646 language tag in lower case (clause 6.1.4), for example `en` or `de-at`, and defaults to `en`, for the entity's name, postal address, electronic address and information URI. With another language, for example `de-at`, the list publishes these texts in that language and again under `en` with the same text, since every list supports English (clause 6.1.4); give the name in a form English readers recognize, such as the legal name. Service names are English labels and are published under `en` only. `uri` is an absolute URI written as a URL parser serializes it, for example with spaces percent-encoded. `contactUri` and `website` are required, because clause 6.5.3.2 makes an e-mail address and a web site mandatory in the entity's `TEElectronicAddress`: `contactUri` is one e-mail address in ASCII characters, bare (`info@example.com`) or as a `mailto:` URI, published as `mailto:info@example.com`; `website` is an absolute `http` or `https` URI in serialized form, for example `https://example.com/`; the optional `phone` is a number in international form without spaces, for example `+49-30-1234567` or `tel:+49-30-1234567`, published as a `tel:` URI. All three are published per language like the other texts. `uri` is published separately, as `TEInformationURI`. Other values, such as `country` `de`, `GB` or `Germany` or `lang` `EN`, answer `400` with an entry at `["entities", , "info", ]` in `errors`, and the [plan](../operate/configuration-as-code.md#plan-and-import) of a configuration bundle or config folder blocks the document; a missing `contactUri` or `website` answers the same way. Trust list files of format v1 (9.x) have no `website` field, so their upgrade on import always stops with the required input `TRUST_LIST_WEBSITE_MISSING` per entity: change `$schema` to `https://eudiplo.dev/schemas/v2/TrustListConfigFile.schema.json`, add `website` and fix the other values the upgrade names: `TRUST_LIST_CONTACT_URI_MISSING` or `TRUST_LIST_CONTACT_URI_INVALID` for the e-mail address, `TRUST_LIST_COUNTRY_INVALID` or `TRUST_LIST_LANGUAGE_INVALID`, whose message names the value to write when only the case or `GB`/`GR` is wrong (for example `UK` for `gb`), or `TRUST_LIST_URI_INVALID`. The list carries `ListIssueDateTime` and `NextUpdate` in whole UTC seconds, for example `2026-11-06T12:00:00Z` (clause 6.1.3).
- The list is signed with the `trustList` key chain in `keyChainId`. Without `keyChainId`, a new list uses a `trustList` key chain of the tenant, so create one first ([Keys and Certificates](keys-and-certificates.md)), and an update keeps the key chain the list is signed with. That key chain must still have usage type `trustList`: if a key chain import with its ID gave it another usage type, the update fails until it names a `trustList` key chain in `keyChainId`. The API answers `409`. In the Web Client, **Any trust list key chain of the tenant** (create) and **Keep the current key chain** (edit) leave `keyChainId` out; the form does not save while the signing key chain it names or keeps is gone or lacks usage type `trustList`, or while a new list has no `trustList` key chain to use. When the tenant has none, it links to create one. The [plan](../operate/configuration-as-code.md#plan-and-import) of a configuration bundle or config folder blocks a `TrustList` document that would change such a list, or that names a key chain without usage type `trustList` in `keyChainId`, with `KEY_CHAIN_USAGE_MISMATCH`, so the import applies nothing; a startup import skips the tenant and logs the issue. The plan takes the usage type from a `KeyChain` document of the same bundle that the import writes, else from the stored key chain. A document that leaves the list unchanged gets the issue only as a warning, as the import does not write the list; it shows in a bundle plan (`eudiplo config plan` or **Plan and validate** in the Web Client), not in the startup log.
`POST` and `PUT` check the whole body before they sign the list and answer `400` with an entry per refused field in `errors`, each with `path`, `code` and `message`. `path` is an array, for example `["keyChainId"]` or `["entities", 0, "issuerKeyChainId"]`. Entries at `info` itself follow only once no other field is refused. `country`, `lang`, `uri`, `contactUri`, `website` and `phone` that do not fit (see above) are refused earlier by the body schema, also with `400` at their path:
| `code` | Field | Refused value |
| -------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `key_chain_not_found` | `keyChainId`, `entities..issuerKeyChainId` or `revocationKeyChainId` | a key chain the tenant does not have |
| `key_chain_usage_mismatch` | the same fields | a key chain of another usage type, as described above |
| `invalid_certificate` | `entities..issuerCertPem` or `revocationCertPem` | no X.509 certificate in PEM or Base64 DER |
| `invalid_entity_info` | `entities..info` | values the LoTE format does not take that the body schema let through |
`409` remains for a save that the stored state blocks: a `POST` without `keyChainId` when the tenant has no `trustList` key chain or the one EUDIPLO picks has no valid certificate, an update without `keyChainId` whose kept key chain lost usage type `trustList`, and an update that another update or a renewal overtook; name a `trustList` key chain in `keyChainId` for the first two. `PUT /api/trust-list/{id}`, `GET /api/trust-list/{id}`, `GET /api/trust-list/{id}/export`, `GET /api/trust-list/{id}/versions` and `GET /api/trust-list/{id}/versions/{versionId}` answer `404` for a list or version the tenant does not have.
EUDIPLO publishes the signed JWT at `GET /issuers/{tenantId}/trust-list/{id}` without authentication, so others can use your list.
| Task | Endpoint |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| Replace entities | `PUT /api/trust-list/{id}` with the complete body; publishes the next sequence number |
| Version history | `GET /api/trust-list/{id}/versions`, `GET /api/trust-list/{id}/versions/{versionId}` |
| List, read, export, delete | `GET /api/trust-list`, `GET /api/trust-list/{id}`, `GET /api/trust-list/{id}/export`, `DELETE /api/trust-list/{id}` |
`DELETE` refuses a list that configurations still use ([Delete a trust list](#delete-a-trust-list)). In the Web Client, the page of a list shows the credential configurations (with `issuance:manage`) and the presentation configurations (with `presentation:manage` or `presentation:request`) that reference it, and the delete button (**Delete list**) says so instead of sending the request. The page does not show `walletProviderTrustLists` of the issuance configuration; check those as described in [Wallet and Key Attestation](attestation.md#1-provide-wallet-provider-trust-lists).
To manage lists as files, put the same JSON into `config//trust-lists/` ([Configuration as Code](../operate/configuration-as-code.md)). `GET /api/trust-list/{id}/export` returns a list in this format; **Download configuration** in the Web Client saves it as a document with `$schema` and `spec` ([single resources](../reference/config-bundle-format.md#single-resources)).
#### Delete a trust list
`DELETE /api/trust-list/{id}` answers `409` while a configuration of the tenant still references the list, because that configuration would fail without it. The response names the configurations in `message` and lists them in `references`. Configurations the caller's roles cannot read are only counted, without ID and description: credential configs and the issuance configuration need `issuance:manage`, presentation configs `presentation:manage` or `presentation:request`.
```json
{
"statusCode": 409,
"timestamp": "2026-10-11T12:00:00.000Z",
"path": "/api/trust-list/membership-issuers",
"code": "TRUST_LIST_IN_USE",
"message": "Trust list \"membership-issuers\" is still referenced by 1 presentation config (\"membership-check\") and the issuance configuration (wallet provider trust lists). Remove these references before deleting the trust list.",
"references": [
{ "kind": "PresentationConfig", "id": "membership-check", "description": "Verify a membership name and ID" },
{ "kind": "IssuanceConfig" }
]
}
```
These entries count as a reference. "The list URL" is `/trust-list/` or any URL that ends in `/issuers//trust-list/` with the list's own tenant; a trailing slash, a query or a fragment is ignored:
- an `etsi_tl` entry in the `trusted_authorities` of a presentation config, by `trustListId` or `url`,
- an entry of `schemaMeta.trustedAuthorities` in a credential config, by `trustListId`, or with `frameworkType: "etsi_tl"` by a `value` that is the list URL or the bare list ID,
- an entry of `walletProviderTrustLists` in the issuance configuration, shared or of an authorization server, by `trustListId` or `url`.
Remove these references, or point them to another list, then delete the list. Deleting an unknown ID answers `204`. EUDIPLO does not see references from other tenants or other systems that fetch the list from its public URL.
A [configuration bundle](../operate/configuration-as-code.md#plan-and-import) or a [config folder](../operate/configuration-as-code.md#provision-tenants-from-a-folder) imported in `replace` mode (`CONFIG_IMPORT_MODE=replace` at startup) deletes a list that it created and no longer contains. Its plan is blocked with `TRUST_LIST_IN_USE` on that list while a configuration that survives the import references it by the rules above: a stored configuration the import neither deletes nor rewrites, or a document of the bundle with its new content. A document the plan skips, for example a detached one, counts with its stored content. The message names the configurations; a document of the bundle that names the list by `trustListId` is also blocked with `MISSING_RESOURCE_REFERENCE`. Keep the list in the bundle, or remove the references (in the bundle or through the API), then plan again.
#### Validity and renewal
A managed list is valid for 30 days (`NextUpdate`). EUDIPLO renews it automatically in the last 10 days: it re-signs the unchanged entities with the next sequence number and a new `NextUpdate`, and keeps the previous version in the history. A renewal signs with the key chain the list is signed with, even one that no longer has usage type `trustList`; only an update refuses that key chain. The check runs every hour and at startup, so lists that expired while EUDIPLO was stopped are renewed when it starts. A managed list is checked like any other list when it is used: if its renewal keeps failing until its `NextUpdate` (the log shows `Failed to renew trust list ...`), it is discarded, and credentials and wallet and key attestations that only it covers are rejected.
Renewals and updates never publish the same sequence number twice. If a renewal or another update was published between reading and writing, `PUT` fails with `409`; read the list again and retry. An import updates an existing list in the same way, with the next sequence number, or leaves it unchanged. A list that is created anew (deleted and created again, dropped by a `replace` import and added back later, or imported into an empty database) starts again at sequence number 1, so verifiers outside this instance that remember a higher number discard it ([Older versions of a list](#older-versions-of-a-list)).
#### Fields
`data` is accepted but ignored; EUDIPLO builds the list content from `entities`.
### Use a trust list in a presentation
Reference trust lists in the `trusted_authorities` of a [DCQL](../presentation/dcql.md) credential query:
```json
{
"trusted_authorities": [
{
"type": "etsi_tl",
"values": [
{ "trustListId": "membership-issuers" },
{ "url": "https://trust.example.org/lists/pid.jwt", "verifierX509Der": "MIIB..." }
]
}
]
}
```
- `trustListId` references a managed list of this tenant. EUDIPLO fetches it from `/issuers//trust-list/` and pins the certificate that signs it. `INTERNAL_URL` defaults to `http://127.0.0.1:`; with `TLS_ENABLED=true` or a `PORT` that is not a number it has no default, and the list is fetched from `PUBLIC_URL`. Set `INTERNAL_URL` if the backend reaches itself at another address.
- `url` references an external LoTE JWT. `verifierX509Der` (base64 DER certificate) or `verifierKey` (public JWK) is required to check its signature; without them loading the list fails (`trust_list_unavailable`). `` in the URL is replaced with `/issuers/`.
- Put several lists into the `values` of one `etsi_tl` entry: only the first `etsi_tl` entry of a credential query is used for verification.
Every credential query needs `trusted_authorities`; EUDIPLO rejects a presentation configuration without them. For development and interoperability tests, `SKIP_TRUST_AUTHORITY=true` allows such queries, which are then verified without checking who the issuer is. An mDOC's presented certificate chain is still checked: its signatures and the validity period of every certificate (`certificate_expired`).
#### Trusted Lists for QEAAs
A QEAA is trusted through the qualified service of the QTSP that issued it, as published in an ETSI TS 119 612 (V2.4.1) Trusted List (ARF Annex 2 OIA_13). Reference the list with `format: "trusted-list"` in the `etsi_tl` entry of the credential query that requests the QEAA:
```json
{
"trusted_authorities": [
{
"type": "etsi_tl",
"values": [
{
"format": "trusted-list",
"url": "https://ec.europa.eu/tools/lotl/eu-lotl.xml",
"signingCertificates": ["MIIH...", "MIIH..."],
"schemeTerritories": ["DE", "FR"]
}
]
}
]
}
```
- `url` is a list of trusted lists (`TSLType` `.../EUlistofthelists`), such as the EU LOTL, or a Member State's Trusted List. `` is replaced as for a LoTE.
- `signingCertificates` (base64 DER, required) are the certificates one of which must have signed the list: for a list of trusted lists, the signing certificates its operator publishes, for the EU LOTL the set the European Commission publishes in the Official Journal of the European Union; for a Member State's list, its scheme operator certificates. A list signed with another key fails like a LoTE with a bad signature (`trust_list_unavailable`).
- `schemeTerritories` is only read for a list of trusted lists: the `SchemeTerritory` of the lists to follow, for example `DE`. Without it, every list it points to is followed.
A list of trusted lists names no QTSPs itself. EUDIPLO follows its pointers (`OtherTSLPointer`) to lists of `TSLType` `.../EUgeneric`, one level deep, and checks each of them against the certificates the list of trusted lists publishes in its pointer. Pointers to other lists of trusted lists are not followed, nor are pointers whose media type is not XML, such as the PDF versions of a list. A Trusted List and a LoTE can be named in the same `etsi_tl` entry; each still only adds the issuers of its own kind.
From each Trusted List, EUDIPLO trusts the certificates of every service whose `ServiceTypeIdentifier` is exactly `http://uri.etsi.org/TrstSvc/Svctype/EAA/Q` and whose current `ServiceStatus` is exactly `http://uri.etsi.org/TrstSvc/TrustedList/Svcstatus/granted`. Not trusted are:
- a withdrawn qualified service: the current status decides, so a QEAA its QTSP issued before the withdrawal is rejected too; the service history is not read,
- a service that is not qualified, such as `.../Svctype/EAA` with the status `.../recognisedatnationallevel`, and a service of any other type, such as `.../Svctype/CA/QC`,
- a service identified only by its subject name or key identifier, without an `X509Certificate`: a certificate path must end at a certificate.
Service information extensions, such as `TakenOverBy` or additional service information, are not read, also when they are marked critical, although ETSI TS 119 612 asks to reject what a critical extension it does not understand applies to. Of a service identity with several `X509Certificate` elements, such as a re-certified CA, only the first is a trust anchor.
The categories stay apart (ARF Annex 2, OIA_15 note): a Trusted List adds only QEAA issuers, and a LoTE never does. A LoTE service with an ETSI TS 119 612 type, such as `.../Svctype/EAA/Q`, is ignored with a warning (`... an ETSI TS 119 612 service type, which only a Trusted List can grant`). A QEAA issuer is never a PID issuer, so the rule for PIDs without status information ([`statusCheckMode`](../reference/presentation-configuration.md)) does not apply to its credentials: a QEAA without status information is accepted, as an EAA is. Which category a credential query accepts is chosen by the lists in its `etsi_tl` entry. The status list of a QEAA must be signed under the certificate its credential matched ([How a trust list is used](#how-a-trust-list-is-used)): ETSI TS 119 612 defines no service for the status of attestations.
Every list is checked on its own, the list of trusted lists and each list it points to: one whose `NextUpdate` has passed or is empty (a closed list), or whose `TSLSequenceNumber` is lower than one accepted before from the same URL ([Older versions of a list](#older-versions-of-a-list)), is discarded, and an outdated list of trusted lists takes the lists it points to with it. A list reached through a list of trusted lists that cannot be fetched or whose signature does not verify is discarded on its own as well, so an unreachable Member State list does not stop the QEAAs of the others; the log names it, for example `Discarded outdated or unavailable trust list(s), using the current lists: https://tl.example/de.xml (could not be loaded: "...")`. A list of trusted lists, or a Trusted List referenced directly, that cannot be loaded fails like a LoTE. When no list of the `etsi_tl` entry is left, presented credentials fail with `trust_list_unavailable`, and the lists are not fetched again for one minute. When another list of the entry is left, such as a LoTE, or a list of trusted lists has nothing to follow, for example because `schemeTerritories` names no territory it points to, QEAAs fail as not trusted (`no_trust_chain_to_root` or `trust_chain_not_trusted`). The lists are cached like LoTEs ([Caching](#caching)), up to the earliest `NextUpdate` of the list of trusted lists and the lists it points to.
Limits, besides the [1,000 certificates](#size-limits) of a source: a Trusted List may be at most 10 MiB; a list with a document type declaration (`` unless it is the last
instance. Keep credentials out of instance URLs: `add` and `update` warn that
they are stored in plain text, the CLI cannot use them for its requests, and
its output masks them as `https://***@host/` (`open` leaves them out of the
browser launch; `open --print`, and `open` outside a terminal, print the URL
as configured).
Commands that call the management API read credentials from the environment,
never from the instance file (see [Environment variables](#environment-variables)).
### Demo or init
| Command | Purpose | Compose project | Credentials | Binds to |
| ---------------- | ----------------------------------------------- | --------------- | -------------------------- | -------------- |
| `eudiplo demo` | Throwaway local demo with the demo tenant | `eudiplo-demo` | `root` / `root` | `127.0.0.1` |
| `eudiplo init` | A deployment you keep and configure | `eudiplo` | generated client secret | `0.0.0.0` |
Both register the instance `local` and use ports 3000 and 4200. Stop the demo
with `eudiplo down` before you run `init`, or the new stack fails on the ports
and `init` replaces the `local` registration. Use `init --instance ` to
keep both registrations.
Both use the image tag `latest` unless you pass `--image-tag` or set
`EUDIPLO_IMAGE_TAG` (a release such as `10.0.0`, `main`, or `sha-`).
Pick a release of the CLI's version or newer (`eudiplo --version`): the CLI
writes `config/kms.json` and tenant files in its own configuration format
versions, and format versions also rise in minor releases, so older images may
refuse them.
`init` asks for the directory, [preset](index.md#presets-and-profiles), public
URL and auth client; in scripts pass them as flags with `--no-interactive`. It
writes `.eudiplo.env` (owner-only permissions), `eudiplo.compose.yaml` and a
`config/` folder that is mounted at `/app/config` and imported on start
(`CONFIG_IMPORT_MODE=create`). The
[production VM cookbook](../cookbooks/production-vm.md) walks through it.
### Compose instances
```bash
eudiplo up # docker compose up -d
eudiplo ps
eudiplo logs # recent logs of all services, then exit
eudiplo logs --service eudiplo --follow --tail 100 --since 10m
eudiplo restart --service eudiplo-client
eudiplo down # add --volumes to delete the data
```
`logs` prints and exits unless you pass `--follow`. `--service` must name a
service of the project. Options that `up`, `down`, `ps`, `logs`, `restart` and
`pull` do not define, and everything after `--`, are passed to
`docker compose`, for example `eudiplo down --volumes --remove-orphans`. Write
`--volumes` in full: `-v` prints the CLI version.
#### Upgrade the application
`eudiplo upgrade` changes the backend and client images of a Compose instance,
not the CLI:
```bash
eudiplo upgrade --image-tag 10.0.1
```
It changes only the `EUDIPLO_IMAGE` and `EUDIPLO_CLIENT_IMAGE` lines of the
env file. Before asking for confirmation it shows the old and new tags, links
the upgrade guide for every major version you cross, and warns about downgrades
and tags it cannot compare, such as `latest`. It then pulls the images and
recreates the services; if the pull fails, the old tags are restored.
Non-interactive runs need `--yes`. Lines that still point at
`ghcr.io/openwallet-foundation/` (releases up to 8.1.0) are moved to
`ghcr.io/eudiplo/`. If a line points at another image (another registry, a
digest or no tag), `upgrade` stops without changing anything; update that line
yourself.
Migrations run when the new backend starts and cannot be undone by going back
to the old tag, so [back up](production-checklist.md#backups) first.
`eudiplo pull` downloads the configured images without changing anything.
Neither command removes volumes.
### Kubernetes instances
The CLI never applies manifests. It inspects and restarts the workloads you
deployed (see [Kubernetes](kubernetes.md)):
```bash
eudiplo instance add production \
--target kubernetes \
--url https://eudiplo.example.com \
--context production \
--namespace eudiplo
eudiplo ps --instance production
eudiplo logs --instance production --service backend --follow --tail 100
eudiplo restart --instance production --service backend
```
- `--context` and `--namespace` are passed explicitly to every `kubectl` call,
so a command never acts on your current kubeconfig context.
- The workloads default to `backend=deployment/eudiplo` and
`client=deployment/eudiplo-client`. Override them with
`--workload backend=deployment/eudiplo-api,client=deployment/eudiplo-web`.
`logs` and `restart` need `--service` when more than one workload is
configured.
- `restart` prints workload, namespace and context, runs
`kubectl rollout restart` and waits for the rollout (`--no-wait` returns
immediately).
- `--read-only` registers an instance on which `restart` is refused.
- Options that `ps`, `logs` and `restart` do not define are passed to
`kubectl`, for example `--timestamps` for `logs`.
- Set `EUDIPLO_KUBECTL` to use a `kubectl` binary that is not on the `PATH`.
`eudiplo doctor` reads the namespace and checks the permissions with
`kubectl auth can-i`. `restart` waits with `kubectl rollout status`, which
watches the deployment (not with `--no-wait`). A Role for the CLI:
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: eudiplo-cli
namespace: eudiplo
rules:
- apiGroups: [""]
resources: ["namespaces"] # in a Role: only the Role's own namespace
verbs: ["get"]
- apiGroups: [""]
resources: ["pods", "pods/log"]
verbs: ["get", "list"]
- apiGroups: ["discovery.k8s.io"]
resources: ["endpointslices"]
verbs: ["get", "list"]
- apiGroups: ["apps"]
resources: ["deployments"]
verbs: ["get", "list", "watch", "patch"] # drop watch and patch for --read-only instances
```
### Check an instance with doctor
```bash
export EUDIPLO_CLIENT_ID=root EUDIPLO_CLIENT_SECRET=''
eudiplo doctor --instance production --strict
```
`doctor` checks the public URL (HTTPS), API reachability, `/health`, TLS
certificate expiry (warning within 30 days), authentication, CLI/backend
version compatibility, KMS provider health and web client reachability, plus
the driver: the container runtime, Compose files and container health for
Compose; `kubectl`, namespace, permissions, workloads and service endpoints for
Kubernetes.
Each check reports `PASS`, `WARN`, `FAIL` or `SKIP`. The exit code is 1 if a
check failed; `--strict` also fails on warnings, `SKIP` never fails. `--all`
checks every registered instance.
The CLI gets its token from the built-in `POST /api/oauth2/token`. Without
`EUDIPLO_CLIENT_ID` and `EUDIPLO_CLIENT_SECRET`, the authentication check warns
(which fails `--strict`) and the version and KMS checks are skipped. With an
external OIDC provider that endpoint is disabled, so the authenticated checks
fail when the variables are set.
KMS provider health is read per tenant, so with the root client the KMS check
is skipped; a
[tenant client](tenants-and-access.md#api-clients-with-least-privilege) with
`issuance:manage`, `presentation:manage` or `keys:manage` covers it too.
### Environment variables
| Variable | Effect |
| -------------------------------------------- | ----------------------------------------------------------------------------- |
| `EUDIPLO_CLI_HOME` | Directory of `config.json` (default `~/.eudiplo`) |
| `EUDIPLO_CLI_CONFIG` | Path of the CLI config file; overrides `EUDIPLO_CLI_HOME` |
| `EUDIPLO_CLIENT_ID`, `EUDIPLO_CLIENT_SECRET` | Client credentials for the authenticated `doctor` checks |
| `EUDIPLO_TOKEN` | Access token for `config export`, `plan`, `import`, `operations`, `recover` (or `--token`) |
| `EUDIPLO_IMAGE_TAG` | Image tag for `demo` and `init` (default `latest`) |
| `EUDIPLO_CONTAINER_RUNTIME` | `docker` or `podman` for Compose instances |
| `EUDIPLO_KUBECTL` | Path of the `kubectl` binary for Kubernetes instances |
| `EUDIPLO_INSTALL_DIR` | Install directory used by `install.sh` (default `~/.local/bin`) |
### Shell completion
```bash
source <(eudiplo completion bash) # zsh: eudiplo completion zsh
eudiplo completion fish | source
```
Save the output in your shell's completion directory to load it permanently.
---
## Configuration as Code
Keep tenant configuration in files, validate it in CI, and move it between
instances with reviewed plans. The file layout, envelope, versions and plan
semantics are specified in the [config bundle format](../reference/config-bundle-format.md).
The [Manage an instance with the CLI](../cookbooks/manage-with-cli.md) cookbook
walks through a tenant folder from creation to CI.
### Configuration model
A tenant's configuration (credential, issuance and presentation configs, key
chains, clients, trust lists, KMS settings, …) consists of JSON
documents with a `$schema`, optional `metadata` and the `spec`. The backend
stores them in the database. They get there in three ways:
| Way | Use it for | Ownership after the write |
| ----------------------- | ---------------------------------------------- | --------------------------- |
| Startup import | Tenant folders in `CONFIG_FOLDER`, GitOps | `file-managed` |
| Bundle import (API/CLI) | Promoting a tenant between instances | `file-managed` |
| Management API, web client | Ad-hoc changes | `unmanaged` |
A `file-managed` resource rejects API and web client edits with `409 Conflict`,
so a later import cannot silently overwrite manual changes. Detach it to edit it
by hand:
```bash
curl -X POST "$EUDIPLO_URL/api/config-bundles/resources/PresentationConfig/age-check/detach" \
-H "Authorization: Bearer $EUDIPLO_TOKEN"
```
A detached resource has the ownership `detached` and stays detached while you
edit it. The startup import skips it with the warning `RESOURCE_DETACHED`, and
the rest of the tenant is still imported. This also holds for the tenant
settings in `info.json` (resource `Tenant/tenant`), such as the session and
status list settings; the log names it as `Tenant 'tenant'`. The default key
chains (`access` and `authorizationServer`) are a resource of their own,
`KeyChainDefaults/defaults` in `key-chain-defaults.json`, so they are detached
and reattached apart from them.
To discard your edits and return to the file version, reattach the resource. Plan
first, review the changes, then apply with the plan's fingerprint:
```bash
curl -X POST "$EUDIPLO_URL/api/config-bundles/resources/PresentationConfig/age-check/reattach/plan" \
-H "Authorization: Bearer $EUDIPLO_TOKEN"
curl -X POST "$EUDIPLO_URL/api/config-bundles/resources/PresentationConfig/age-check/reattach?planFingerprint=$FINGERPRINT" \
-H "Authorization: Bearer $EUDIPLO_TOKEN"
```
Reattaching reads the resource from the tenant folder in `CONFIG_FOLDER`,
applies it, and makes the resource `file-managed` again. Its stored generation
becomes the file's generation, so later startups apply the folder again.
Both endpoints first read and upgrade the files of the requested kind in the
tenant folder, for example every file in `clients/` for a `Client`, as the
startup import does; reattaching `Tenant/tenant` reads only `info.json`. Files
of other kinds are not read, so a broken trust list file does not block
reattaching a client. If a file of the requested kind cannot be imported, for
example a trust list file of 9.x without `contactUri` and `website` when you
reattach a trust list, they answer `400` with the code
`CONFIG_FOLDER_INVALID`, the `file` relative to the tenant folder and the
blocking `issues` of that file, each with the JSON pointer `path`, the issue
`code` and the `resource`, in the shape the [plan](#plan-and-import) of a
bundle uses for a `blocked` item. A file that cannot be read as a
document, for example one that is no JSON, holds another resource kind or has
an unresolved `${VAR}` placeholder, gets one issue `CONFIG_FILE_INVALID` with
the reason as its `message`, an empty `path` and no `resource`. The startup
import logs the same `message` as `Failed to import tenant`, without an
operation report, since nothing was applied. Fix the file and plan again:
```json
{
"code": "CONFIG_FOLDER_INVALID",
"message": "trust-lists/eaa.json: TRUST_LIST_CONTACT_URI_MISSING in TrustList/eaa at /spec/entities/0/info/contactUri: Add contactUri: ...; TRUST_LIST_WEBSITE_MISSING in TrustList/eaa at /spec/entities/0/info/website: Add website ...",
"file": "trust-lists/eaa.json",
"issues": [
{
"severity": "required-input",
"code": "TRUST_LIST_CONTACT_URI_MISSING",
"path": "/spec/entities/0/info/contactUri",
"message": "Add contactUri: ...",
"resource": { "kind": "TrustList", "id": "eaa" }
},
{
"severity": "required-input",
"code": "TRUST_LIST_WEBSITE_MISSING",
"path": "/spec/entities/0/info/website",
"message": "Add website ...",
"resource": { "kind": "TrustList", "id": "eaa" }
}
]
}
```
The web client lists ownership and offers **Detach** and **Reset to file**, and
for clients from the config folder **Apply from file**, under
**Settings > Config Portability** (shown to a tenant's clients and users with
`tenant:admin` or `tenants:manage`). Its resource table filters by kind and
ownership and searches its Resource and Source columns; the select-all checkbox
in the table header and **Detach selected** act only on the `file-managed` rows
the filters show. On the screens of a `file-managed` resource it shows a lock
notice and disables editing and deleting, also for clients that only have the
role managing that resource, such as `issuance:manage` for credential configs.
### Provision tenants from a folder
Mount a config root with one folder per tenant and enable the startup import:
```env
CONFIG_FOLDER=/app/config
CONFIG_IMPORT_MODE=create
```
| `CONFIG_IMPORT_MODE` | On every start |
| -------------------- | ----------------------------------------------------------------------------------- |
| `disabled` (default) | Nothing is imported |
| `create` | Creates missing resources, leaves existing ones untouched |
| `upsert` | Creates missing and updates existing resources |
| `replace` | Like `upsert`, and deletes resources this folder created earlier but no longer contains |
If a resource in the folder has a lower `metadata.generation` than the stored
one, it was changed through the API or web client. The startup import skips it
with the warning `STALE_GENERATION` and imports the rest of the tenant. Reattach
the resource to apply the file version, or raise `metadata.generation` in the
file to at least the stored generation shown under **Settings > Config
Portability**.
A folder of a tenant that does not exist yet is imported only if it contains
`info.json`. String values can reference environment variables as `${VAR}` or
`${VAR:default}`; with the default `CONFIG_VARIABLE_STRICT=skip`, an unresolved
placeholder fails the import of that tenant while other tenants continue.
Restart the backend to apply changed files. The folder layout is listed in the
[format reference](../reference/config-bundle-format.md#tenant-folder-layout).
With `OIDC_PROVIDER=generic`, the identity provider manages the clients, so
leave `clients/` out of the folder: a client file fails the import of its
tenant, and the other tenants are still imported. Create the clients in the
identity provider
([details](../reference/config-bundle-format.md#clients-with-another-identity-provider)).
#### Clients with generated secrets
A client file with `"secret": "!generate"` gets a random secret when it is first
imported from this folder or the content of its file changes, but a startup import cannot return it. The backend
writes a warning to its application log (not to the audit log) that names the
client, never the secret:
```text
[acme] Client 'shop-backend' got a generated secret ("secret": "!generate"), which a startup import does not show. ...
```
To get a secret you can use, apply the client from the file again: choose
**Apply from file** in its row under **Settings > Config Portability**, or
reattach it through the API as above, with `Client/shop-backend` in the path.
The client stays `file-managed`, its old secret stops working, and the new one
is shown once in the result. Later startups keep the secret while the content of the
file does not change; a newer `$schema` alone, as `eudiplo config upgrade`
writes it, keeps it too. To skip this step, give the secret in the file as an environment
variable, for example `"secret": "${SHOP_BACKEND_SECRET}"`.
### Validate in CI
The CLI validates tenant folders against the same schemas as the backend,
without a running instance:
```bash
eudiplo config validate tenants ./config --format json # every tenant folder
eudiplo config tenant validate acme --config-directory ./config
eudiplo config upgrade ./config --check # exit 1 if a file needs an upgrade
```
The commands exit non-zero on any invalid document, which is enough for a CI
gate. The backend runs a few checks on top that the schemas cannot express,
such as the check of a presentation configuration's registration certificate,
so an import can still fail on a folder that passed validation. Like the
backend, the validator resolves `${VAR}` placeholders from its environment and
fails on one without a value or default, so give the CI job a dummy value for
each; the real secrets stay on the instance. A file the backend skips does not
fail validation: a `registrar.json` left from the removed sandbox registrar
integration prints `warning registrar.json: …` under its tenant, and the JSON
report lists it in the tenant's `warnings[]` (`file`, `message`).
`eudiplo config upgrade --check` counts such a file as needing an upgrade and
exits `1` until it is deleted. A workflow
that validates every tenant folder and checks for pending upgrades:
```yaml title=".github/workflows/config.yml"
jobs:
validate:
runs-on: ubuntu-latest
env:
SHOP_BACKEND_SECRET: ci-placeholder # one per ${…} placeholder
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npx @eudiplo/cli@10 config validate tenants ./config
- run: npx @eudiplo/cli@10 config upgrade ./config --check
```
Use the CLI major version that matches your backend. For completion and inline
validation in VS Code, run `eudiplo config editor setup` in the repository; it
copies the schemas of the installed CLI to `.vscode/eudiplo-schemas/` and adds
the file associations to `.vscode/settings.json`.
### Export a tenant
Bundle commands act on one tenant and need a token bound to that tenant with the
`tenant:admin` role (or `tenants:manage`). The tenant-less root client cannot
export. Create an admin client for the tenant once, for example with
`POST /api/tenant` and `"roles": ["tenant:admin"]` (see
[Tenants and access](tenants-and-access.md#create-a-tenant)), then:
```bash
export EUDIPLO_TOKEN="$(curl -s -X POST https://eudiplo.example.com/api/oauth2/token \
-d grant_type=client_credentials -d client_id=acme-admin -d client_secret="$SECRET" \
| jq -r .access_token)"
eudiplo config export --instance production --output acme.zip
```
The export never contains secrets or database-held private keys. It replaces
secrets with `${…}` placeholders and private keys with
`keySource: { "type": "required" }`, and lists both as requirements in
`manifest.json`; supply the values on the target instance or let the import
generate them (see
[secret and key policy](../reference/config-bundle-format.md#secret-and-key-policy)).
To keep a tenant in Git as a tenant folder instead of a bundle, see
[Keep a tenant in Git](tenant-folders-in-git.md).
### Download one resource
**Download configuration** on the page of a credential, issuance or
presentation configuration, a webhook endpoint, an attribute provider, a trust
list or a key chain saves the resource as a document named `.json`, ready
for the config folder. The API is
`GET /api/config-bundles/resources///document`
([single resources](../reference/config-bundle-format.md#single-resources)).
Secrets are `${…}` placeholders, as in a bundle export; the Web Client names
the environment variables to set before the import. **Choose bundle or
document** under **Settings > Config Portability** also takes the file and
plans it like a bundle with that one resource. A key chain document
contains the private keys of a `db` key chain and needs `tenant:admin` or
`tenants:manage`.
### Upgrade old files
After a backend upgrade, files and bundles in an older format keep working on
import, but upgrade them in your repository to stay on the current schemas.
One exception: trust list files of 9.x (format v1) lack the web site that
10.0 requires, so their import and `eudiplo config upgrade` stop until you
rewrite them as v2 ([Upgrading from 9.x to 10.0](../upgrade/9.x-to-10.0.md#trust-lists-v1-files-must-be-rewritten)).
```bash
eudiplo config upgrade acme.zip --dry-run
eudiplo config upgrade acme.zip --output acme-upgraded.zip
eudiplo config upgrade ./config --output ./config-upgraded --diff
```
The command writes to a separate output, never invents missing security-relevant
values, and leaves the output untouched when validation fails. A bundle exported
by a newer release cannot be imported into a release that does not know its
format versions, for example a 10.0 bundle into 9.x
([format versions](../reference/config-bundle-format.md#resource-types-and-versions)).
### Plan and import
Always review the server-side plan, then import exactly that plan:
```bash
eudiplo config plan acme-upgraded.zip --instance staging --mode upsert --diff --output plan.json
eudiplo config import acme-upgraded.zip --instance staging --mode upsert --plan plan.json
```
The plan lists every resource as `create`, `update`, `unchanged`, `skip`,
`delete` or `blocked`, with its field changes (secrets redacted). A plan with a `blocked` item
cannot be applied: fix the reported issue (missing secret, stale generation,
unknown reference, including an OpenID Federation trust anchor that is not
registered, client ID used by another tenant, a deleted trust list or trust
anchor that a configuration still uses) and plan again. A plan
that grants roles beyond the caller's own, changes a client with more roles,
or creates a client that takes over a Keycloak client with more roles, answers
`403` ([granting roles](../reference/roles.md#granting-roles)). The import sends the plan's fingerprint; if
the bundle, the mode or the target configuration changed in between, it fails
with `CONFIG_PLAN_STALE` before writing anything.
`config plan` prints the plan as JSON; `--format text` (or its alias `--diff`)
prints one line per resource with its field changes instead.
`config plan` and `config import` also take a tenant folder instead of a
bundle; see [Keep a tenant in Git](tenant-folders-in-git.md#plan-and-import-the-folder).
The web client does the same under **Settings > Config Portability**:
**Plan and validate** lists each changed field with its current value and its
value after the import, marking secrets as `secret`, values whose type changes
as `changed`, and values the import deletes as `removed`, and **Apply bundle**
imports that plan. It asks for confirmation before applying a plan that removes
stored values, and before every `replace` import.
`replace` deletes resources that the same bundle source created earlier and the
bundle no longer contains. The plan blocks deleting a trust list that a
configuration surviving the import still references, including a configuration
created through the API or Web Client (`TRUST_LIST_IN_USE`, see
[Delete a trust list](../trust/trust-lists.md#delete-a-trust-list)),
deleting a federation trust anchor whose entity ID such a configuration still
names (`FEDERATION_TRUST_ANCHOR_IN_USE`, see
[Delete a trust anchor](../trust/federation.md#delete-a-trust-anchor)),
or deleting a key chain that such a configuration names (`KEY_CHAIN_IN_USE`, see
[Delete a key chain](../trust/keys-and-certificates.md#delete-a-key-chain)). It does
not block deleting an attribute provider that such a configuration still names.
It needs its own plan and an explicit confirmation:
```bash
eudiplo config plan acme.zip --instance staging --mode replace --output replace-plan.json
eudiplo config import acme.zip --instance staging --mode replace \
--plan replace-plan.json --confirm-replace
```
Client secrets generated during the import (`"secret": "!generate"`) are
returned once in the import result; store them immediately. The client keeps its
secret on later imports of the same document from the same source; change the
document or raise `metadata.generation` to get a new one
([details](../reference/config-bundle-format.md#import-modes-and-plan-actions)).
A startup import cannot return the secret; see
[clients with generated secrets](#clients-with-generated-secrets).
### Plans, locks and recovery
One configuration writer per tenant runs at a time, across all replicas. Imports,
config API edits and asset uploads take this lock; issuance, presentations and
status updates continue.
An import is not one transaction. If a step fails, the API returns
`CONFIG_APPLY_FAILED` with an ordered report: completed steps stay applied, the
failed step may be partial, later steps (including deletions) do not run.
Inspect the affected resources, fix the cause, and plan again.
`eudiplo config import` shows that report as one line per resource and exits
with `1`:
```text
Import stopped at resource TrustList/eu: 2 completed, 1 failed, 2 not started.
completed images/logo.jpg
completed KeyChain/signing
failed TrustList/eu
pending PresentationConfig/pid
pending Client/legacy (delete)
Completed resources stay applied; the failed one may have partial effects.
Inspect the report with: eudiplo config operations 708f0de1-…
Then run plan again before retrying.
```
The full report goes to standard output as JSON. It includes any client secrets
generated before the failure (`generatedSecrets`); they are not shown again, so
store them immediately. Progress is also stored in the database:
```bash
eudiplo config operations --instance staging # latest 50 operations
eudiplo config operations --instance staging # one report
```
If the backend crashed during an import, the operation stays `running` and keeps
the tenant lock. Make sure the original process is stopped on every replica,
then release the lock:
```bash
eudiplo config recover --instance staging --confirm-worker-stopped
```
Recovery marks the operation `interrupted`; it does not undo or replay steps.
Check the resource the report shows as `running`, then create a new plan. Rotate
any client secret whose import response was lost.
---
## Database
Connect EUDIPLO to SQLite or PostgreSQL, understand how schema migrations run,
and set how long session data is kept. Sensitive columns are encrypted; the key
is configured in [Encryption keys](encryption-keys.md).
### Choose a database
`DB_TYPE` accepts `sqlite` (default) and `postgres`.
| Database | Use it for | Data location |
| ---------- | ---------------------------------------------------------------- | ----------------------------------- |
| SQLite | One backend process: tests, demos, small single-VM installations | `/service.db` |
| PostgreSQL | Production, and every setup with more than one backend replica | Your PostgreSQL server |
`FOLDER` is `/app/config` in the container image (so the file is
`/app/config/service.db`); outside the image it defaults to `../../tmp` relative
to the working directory. With SQLite, `DB_HOST`, `DB_DATABASE` and the other
connection variables are ignored.
### Connect to PostgreSQL
```env
DB_TYPE=postgres
DB_HOST=postgres.internal
DB_PORT=5432
DB_USERNAME=eudiplo
DB_PASSWORD=
DB_DATABASE=eudiplo
```
All five connection variables are required with `postgres`. In the bundled
Compose and Kubernetes setups the host is `postgres`.
For servers that require TLS, typically managed cloud databases:
```env
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true # default; keep it in production
DB_SSL_CA_PATH=/certs/postgres-ca.crt # for private CAs
DB_SSL_CERT_PATH=/certs/client.crt # client certificate, if required
DB_SSL_KEY_PATH=/certs/client.key
DB_SSL_KEY_PASSPHRASE= # for an encrypted client key
```
`DB_SSL_REJECT_UNAUTHORIZED=false` accepts any server certificate; use it only
for local tests. All variables are listed under
[Database](../reference/environment-variables.md#database).
**Checkpoint:** `GET /health` reports `"database": { "status": "up" }`.
### Migrations
The backend applies pending schema migrations on start (`DB_MIGRATIONS_RUN=true`,
the default). A fresh, empty database is created by the same migrations, so
leave `DB_SYNCHRONIZE=false` from the first start on; `DB_SYNCHRONIZE=true`
lets TypeORM change the schema from the entity definitions and is meant for
development only. With `DB_MIGRATIONS_RUN=false`, the backend logs a warning
when migrations are pending; to apply them, start a single backend instance
once with `DB_MIGRATIONS_RUN=true`, wait until `GET /health` is `ok`, and
start the other instances afterwards.
Plan upgrades with migrations in mind:
- **Back up the database before every upgrade.** Some migrations convert or
remove data and cannot be reverted (for example the move of keys into key
chains, or the removal of `provided_attestations` in 9.0). Starting the
previous image afterwards does not restore the old schema. To roll back,
restore the backup and run the previous version.
- **Let one process migrate.** With several replicas, scale to one replica (or
start one new replica first), wait until it is healthy, then scale up.
Developers who create migrations find the commands in the
[backend architecture guide](../contributing/backend-architecture.md).
### Session retention
The backend checks sessions every `SESSION_TIDY_UP_INTERVAL` seconds (default
`3600`). It marks open sessions whose lifetime has passed as `expired`, and
handles sessions older than the retention period:
| Variable | Default | Meaning |
| ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `SESSION_TTL` | `86400` | Retention period in seconds |
| `SESSION_CLEANUP_MODE` | `full` | `full` deletes old sessions; `anonymize` keeps status and timestamps but removes credentials, claims, offers, requests and keys |
A tenant can override both with `PUT /api/session-config` (roles
`issuance:manage` or `presentation:manage`), or under
**Sessions → Session Settings** in the web client:
```json
{ "ttlSeconds": 3600, "cleanupMode": "anonymize" }
```
`ttlSeconds` must be a whole number of at least 60. Fields left out of the
request keep their stored value, and `"ttlSeconds": null` removes only the TTL
override. A stored `cleanupMode` cannot be removed on its own:
`DELETE /api/session-config` restores the global defaults for both fields.
The settings belong to the tenant, so for a file-managed tenant both requests
return `409 Conflict` ([Configuration as Code](configuration-as-code.md#configuration-model)).
[Session logs](logging.md#session-logs) are deleted together with their
session; `anonymize` keeps them.
---
## Compose without the CLI
Run EUDIPLO with the Compose file in `deployment/docker-compose` and manage it
with `docker compose` yourself. If you prefer generated files and
`eudiplo up`/`upgrade`/`doctor`, follow the
[production VM cookbook](../cookbooks/production-vm.md) instead; the CLI uses
the same Compose file.
### Before you start
- Docker with Compose v2, or Podman with `podman compose`
- A checkout of the repository, or a copy of `deployment/docker-compose/`
- A choice of [preset](index.md#presets-and-profiles): `minimal`, `standard` or `full`
### 1. Create the environment file
```bash
cd deployment/docker-compose
cp .env.standard.example .env # or .env.minimal.example, .env.full.example
```
Replace every placeholder secret before the first start:
```bash
openssl rand -base64 32 # MASTER_SECRET
openssl rand -base64 24 # AUTH_CLIENT_SECRET, DB_PASSWORD, RUSTFS_SECRET_KEY
```
`MASTER_SECRET`, `AUTH_CLIENT_ID` and `AUTH_CLIENT_SECRET` have no defaults; the
backend does not start without them. In `standard` and `full`, set
`S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY` to the same values as
`RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY`. Set `PUBLIC_URL`
to the URL wallets use to reach the backend.
### 2. Start a profile
```bash
docker compose up -d # minimal: backend and web client
docker compose --profile standard up -d # + PostgreSQL and RustFS
docker compose --profile full up -d # + Vault; create the key first, see below
```
Combine single components with `--profile postgres`, `--profile s3` and
`--profile vault`. Use the same profile flags for every later `docker compose`
command, otherwise Compose ignores the profile's services.
#### Create the encryption key for `full`
`.env.full.example` sets `ENCRYPTION_KEY_SOURCE=vault`, and nothing creates the
key, so the backend does not start until it exists in Vault. Before the first
start, start Vault, create the key and keep a copy:
```bash
docker compose --profile full up -d vault
KEY="$(openssl rand -base64 32)"
echo "Store this key in your password manager: $KEY"
docker compose --profile full exec \
-e VAULT_ADDR=http://127.0.0.1:8200 -e VAULT_TOKEN=root \
vault vault kv put secret/eudiplo/encryption-key key="$KEY"
docker compose --profile full up -d
```
Use your `VAULT_TOKEN` instead of `root`. If `exec` fails right after the start,
Vault is not listening yet; run it again.
The bundled Vault runs in development mode and keeps everything in memory.
Every restart of the `vault` container, for example after `down`, a host
reboot or a Docker update, deletes the key. The running backend keeps working,
but it does not start again until the key is back: write the stored key with
the same `vault kv put` command. Never create a new key, because the data
encrypted so far could no longer be decrypted. Use `full` only to evaluate
Vault. In production, use a Vault with persistent storage or another
[key source](encryption-keys.md#choose-a-key-source), and back up the key.
**Checkpoint:** `curl http://localhost:3000/health` returns
`{"status":"ok",...}` and the web client opens at `http://localhost:4200`.
### Services
| Service | Profiles | Ports | Purpose |
| ---------------- | --------------------------- | ---------------------- | ---------------------------------------------------- |
| `eudiplo` | always | 3000 | Backend |
| `eudiplo-client` | always | 4200 → 8080 | Web client. The browser calls the backend directly ([which addresses](#web-client-addresses)); `API_BASE_URL` prefills the login page |
| `postgres` | `postgres`, `standard`, `full` | - | PostgreSQL 16; set `DB_HOST=postgres` in `.env` |
| `rustfs` | `s3`, `standard`, `full` | 9000 (S3), 9001 (console) | S3-compatible object storage |
| `rustfs-init` | `s3`, `standard`, `full` | - | Creates `S3_BUCKET` once and exits |
| `vault` | `vault`, `full` | 8200 | HashiCorp Vault in development mode, data in memory only ([see above](#create-the-encryption-key-for-full)), token from `VAULT_TOKEN` (default `root`) |
All published ports bind to `EUDIPLO_BIND_ADDRESS`. The backend reaches
PostgreSQL, RustFS and Vault over the Compose network, and files are downloaded
through the backend, so no other host needs ports 9000, 9001 or 8200. With the
default `0.0.0.0` they are open on every interface: set
`EUDIPLO_BIND_ADDRESS=127.0.0.1` behind a reverse proxy on the same host, or
block the ports in a firewall in front of the host (Docker bypasses host
firewalls such as `ufw`).
The Compose file also reads these variables from `.env`:
| Variable | Default | Use |
| ----------------------- | ---------------------------------------------------- | ----------------------------------------------------------- |
| `EUDIPLO_IMAGE` | `ghcr.io/eudiplo/eudiplo:latest` | Backend image; pin a release tag in production |
| `EUDIPLO_CLIENT_IMAGE` | `ghcr.io/eudiplo/eudiplo-client:latest` | Web client image; keep it on the same tag as the backend |
| `EUDIPLO_BIND_ADDRESS` | `0.0.0.0` | Host address of all published ports (3000, 4200, 9000, 9001, 8200); `127.0.0.1` behind a local reverse proxy |
| `EUDIPLO_CONFIG_MOUNT` | named volume `eudiplo-config:/app/config` | What is mounted at `/app/config` |
| `EUDIPLO_ENV_FILE` | `.env` | Environment file passed to the backend |
| `API_BASE_URL` | `http://localhost:3000` | Backend URL prefilled on the web client's login page; set it to the URL your browser uses for the backend. The login page asks before signing in at another instance that a link (`?apiUrl=`) chose |
| `CLIENT_BASE_HREF` | `/` | Path of the web client behind a reverse proxy ([TLS and reverse proxy](tls.md#serving-the-client-from-a-subpath)) |
#### Web client addresses
The web client runs in the browser, so the browser sends its requests, to two
addresses. It reads the discovery document and sends every API call to the
**EUDIPLO Instance** entered on the login page. For the client-credentials
login and every token refresh, it uses the token endpoint that discovery names:
`PUBLIC_URL/api/oauth2/token`, or the provider's token endpoint when `OIDC` is
set. Both addresses must be reachable from the browser, accept the web client's
origin (`CORS_ORIGINS` on the backend, the allowed web origins at the
provider), and pass any proxy or WAF in front of them. They differ when, for
example, the login page uses `http://localhost:3000` while `PUBLIC_URL` is a
tunnel or the public host name.
#### Links to the login page
A link to `/login?apiUrl=` opens the login page with
that **EUDIPLO Instance** filled in; with `clientId` and `clientSecret` as well,
it signs in with these credentials at once. The instance receives the access
token after a single sign-on, or the client secret, so the login page asks
before it signs in at an instance that a link chose, unless `API_BASE_URL`
names it or the browser last signed in there with single sign-on or a client
secret the user entered. The web client sends the access token only to the
instance it is signed in to.
### Data and configuration folders
The image sets `FOLDER=/app/config` and `CONFIG_FOLDER=/app/config/config`:
- `FOLDER` holds the SQLite database (`service.db`) and, unless
`LOCAL_STORAGE_DIR` is set, the uploaded files. The example `.env` files set
`LOCAL_STORAGE_DIR=/app/uploads`, which is the `eudiplo-uploads` volume.
- `CONFIG_FOLDER` holds the global `kms.json` and one folder per tenant for
[configuration import](configuration-as-code.md). Every directory in it is
treated as a tenant folder.
To provision tenants from files, mount your config root and enable the import:
```env
EUDIPLO_CONFIG_MOUNT=./config:/app/config
CONFIG_FOLDER=/app/config
CONFIG_IMPORT_MODE=create
```
With this mount the SQLite database is written to `./config/service.db`, which
is how CLI-managed projects are laid out. Mounting the config folder at
`/app/config` without setting `CONFIG_FOLDER=/app/config` makes the backend look
for tenants in `./config/config/`.
### Day-to-day commands
```bash
docker compose --profile standard ps
docker compose --profile standard logs -f eudiplo
docker compose --profile standard restart eudiplo
docker compose --profile standard down
```
`docker compose down -v` also deletes the volumes, including the database,
uploads and RustFS data.
To upgrade, [back up](production-checklist.md#backups) the database and object
storage, set the new tag in `EUDIPLO_IMAGE` and `EUDIPLO_CLIENT_IMAGE`, then run
`docker compose --profile standard pull` and `up -d`. Database migrations run on
the first start of the new backend; read the [upgrade guide](../upgrade/index.md)
for every major version you cross.
### Migrating existing MinIO storage
Since 9.0 the bundled object storage is RustFS instead of MinIO, with new
service names, credentials and volumes; follow the
[upgrade guide](../upgrade/8.x-to-9.0.md#bundled-object-storage-minio-replaced-by-rustfs)
to move existing objects.
---
## Encryption Keys
Choose where the key for data at rest comes from and keep it stable. EUDIPLO
encrypts private keys, secrets in the configuration and personal session data in
the database with AES-256-GCM under one 256-bit key, which the backend loads at
startup from `ENCRYPTION_KEY_SOURCE`.
### What is encrypted
| Table | Columns |
| ---------------------------------- | --------------------------------------------------------------------------------------- |
| Key chains | `rootJwk`, `activeJwk`, `previousJwk` (private keys of `db` key chains) |
| Webhook endpoints, attribute providers | The API key in `auth` (`config.value`) |
| Issuance configuration | The upstream client secret of chained authorization servers in `authorizationServers` |
| Sessions | `credentials` (verified presentations), `credentialPayload` (offer claims), `offer`, `auth_queries`, `responseEncryptionPrivateJwk` (per-request key that decrypts the wallet response), the webhook API key in `parsedWebhook` |
| Interactive authorization sessions | `authorizationDetails`, `presentationData`, `completedStepsData` |
| Chained authorization sessions | `upstreamIdTokenClaims`, `upstreamAccessTokenClaims` |
In JSON columns that mix settings and secrets, only the secret value is
encrypted, so the rest of the setting stays readable in the database. Refresh
tokens, authorization codes and pre-authorized codes of the built-in and chained
authorization servers are stored as SHA-256 hashes and API client secrets as
bcrypt hashes. The pre-authorized code is still part of the encrypted `offer`,
which the wallet fetches. Public keys, certificates and the
rest of the configuration are stored in plain text. Keys in an
external [KMS](kms.md) never reach the database. Secrets stored by 8.x are
encrypted by a migration on the first start of 9.0.
The same key also derives the HMAC key for the pseudonymous subject keys of the
single-active-credential policy, so the slot of a returning user is found again
without storing their identity.
### Choose a key source
| `ENCRYPTION_KEY_SOURCE` | Key comes from | Use |
| ----------------------- | ----------------------------------------------------------------- | --------------------------------------- |
| `env` (default) | Derived from `MASTER_SECRET` with HKDF-SHA256 | Any installation, no extra service |
| `vault` | A HashiCorp Vault KV v2 secret | Optional, key managed in Vault |
| `aws` | An AWS Secrets Manager secret | Optional, on AWS |
| `azure` | An Azure Key Vault secret | Optional, on Azure |
The default needs no secret store: keep `MASTER_SECRET` random and as protected
as the database credentials, because whoever has both `MASTER_SECRET` and a copy
of the database can decrypt the stored data. An external key source is an
optional extra step: with `vault`, `aws` and `azure` the key exists only in the
backend's memory, not in its environment, and `MASTER_SECRET` no longer protects
stored data. The key must be 32 bytes, stored as base64 (44 characters) or hex
(64 characters):
```bash
openssl rand -base64 32
```
#### Vault
```env
ENCRYPTION_KEY_SOURCE=vault
VAULT_ADDR=https://vault.example.com:8200
VAULT_TOKEN=
VAULT_ENCRYPTION_KEY_PATH=secret/data/eudiplo/encryption-key # default
```
```bash
vault kv put secret/eudiplo/encryption-key key="$(openssl rand -base64 32)"
```
The backend reads `/v1/` and expects the
key in the field `key`. `VAULT_ADDR` and `VAULT_TOKEN` can also be referenced as
`${VAULT_ADDR}`/`${VAULT_TOKEN}` from `kms.json`, but Vault as a key provider for
signing keys is configured separately in [KMS](kms.md).
#### AWS Secrets Manager
```env
ENCRYPTION_KEY_SOURCE=aws
AWS_REGION=eu-central-1
AWS_ENCRYPTION_SECRET_NAME=eudiplo/encryption-key
AWS_ENCRYPTION_SECRET_KEY=key # JSON field, default "key"
```
```bash
aws secretsmanager create-secret --name eudiplo/encryption-key \
--secret-string "$(openssl rand -base64 32)"
```
The secret can be the plain key, a JSON object with the key in
`AWS_ENCRYPTION_SECRET_KEY`, or a 32-byte binary secret. Credentials come from
the AWS SDK default chain (IAM role, IRSA, or `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`).
#### Azure Key Vault
```env
ENCRYPTION_KEY_SOURCE=azure
AZURE_KEYVAULT_URL=https://myvault.vault.azure.net
AZURE_ENCRYPTION_SECRET_NAME=eudiplo-encryption-key
```
```bash
az keyvault secret set --vault-name myvault --name eudiplo-encryption-key \
--value "$(openssl rand -base64 32)"
```
Credentials come from `DefaultAzureCredential` (managed identity, or
`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`).
**Checkpoint:** with `LOG_LEVEL=info` (the image logs only warnings by default),
the startup log shows `Initializing encryption with key provider: `,
and for `vault`, `aws` and `azure` a short key fingerprint. All replicas must
log the same fingerprint.
### Keep the key stable
There is no key rotation: the backend does not re-encrypt stored data. If the
key changes, or with `env` the `MASTER_SECRET` changes:
- private keys of `db` key chains and stored session data can no longer be
decrypted,
- the single-active-credential policy no longer recognizes earlier subjects, so
their existing credentials stop counting against the limit,
- with the built-in OAuth2 server, all management tokens become invalid
(they are signed with `MASTER_SECRET`),
- with any key source, a change of `MASTER_SECRET` changes the `sub` that
OpenID Provider clients with a
[`subject`](../presentation/openid-connect.md#stable-subject-and-top-level-claims)
receive, so relying parties see every user as new.
Store the key, or `MASTER_SECRET`, in your secret manager with versioning, and
include it in the [backup plan](production-checklist.md#backups): a database
backup is useless without it.
### Switch to an external key source
The data encrypted so far is bound to the current key. To move from `env` to
`vault`, `aws` or `azure` without losing data, the external secret must contain
the key that `env` derived from your `MASTER_SECRET`, which you can compute
offline:
```bash
node -e 'const c=require("node:crypto");console.log(Buffer.from(c.hkdfSync("sha256",process.argv[1],"","eudiplo-encryption-at-rest",32)).toString("base64"))' "$MASTER_SECRET"
```
Store the output as the key in the external source, then switch
`ENCRYPTION_KEY_SOURCE`. Test the procedure on a copy of the database first.
---
## Operate EUDIPLO
These guides cover running EUDIPLO yourself: choosing a deployment, configuring
storage, keys and access, and keeping the instance observable. Before you expose
an instance to real wallets and users, work through the
[production checklist](production-checklist.md).
### Choose a deployment
| Deployment | Use it when | What manages it | Guide |
| ----------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------- |
| CLI-managed Compose on one VM | You run one instance on one server and want generated config, upgrades and checks from one tool | `eudiplo init`, `up`, `upgrade`, `doctor` | [Cookbook: Production on one VM](../cookbooks/production-vm.md) |
| Compose without the CLI | You keep your own Compose files, for example in an existing infrastructure repository | `docker compose` with the files in `deployment/docker-compose` | [Compose without the CLI](docker-compose.md) |
| Kubernetes | You deploy to a cluster with Kustomize and bring your own database, object storage and secrets | `kubectl apply -k`, optionally the CLI for checks | [Kubernetes](kubernetes.md) |
All three run the same images, `ghcr.io/eudiplo/eudiplo` (backend)
and `ghcr.io/eudiplo/eudiplo-client` (web client). The bundled
manifests and Compose files run one backend replica. Several replicas can share
one PostgreSQL database and one S3 bucket, but configuration changes of a tenant
are serialized by a database lock (see
[configuration as code](configuration-as-code.md#plans-locks-and-recovery)), and
the bundled PostgreSQL, RustFS and Vault services are single-instance
development services.
For a first local try, use `eudiplo demo` from the
[Foundation cookbook](../cookbooks/foundation.md) instead.
### Presets and profiles
The CLI presets, the Compose profiles in `deployment/docker-compose` and the
Kubernetes overlays in `deployment/k8s/overlays` share three names:
| Name | Database | Object storage | Vault | CLI | Compose | Kubernetes |
| ---------- | ---------- | ------------------- | -------------------------- | ------------------- | --------------------- | ----------------------------- |
| `minimal` | SQLite | Local filesystem | - | `--preset minimal` | no profile | `overlays/minimal` |
| `standard` | PostgreSQL | S3 (bundled RustFS) | - | `--preset standard` | `--profile standard` | `overlays/standard` |
| `full` | PostgreSQL | S3 (bundled RustFS) | Bundled Vault in dev mode | `--preset full` | `--profile full` | `overlays/full` |
Vault serves a different purpose depending on where `full` comes from:
- **CLI `--preset full`** writes a `vault` provider to `config/kms.json` and makes
it the default [KMS provider](kms.md) for new signing keys.
- **Compose `.env.full.example` and the Kubernetes `full` overlay** set
`ENCRYPTION_KEY_SOURCE=vault`, so Vault holds the
[encryption key](encryption-keys.md) for data at rest. Signing keys stay in
the database unless you add a `kms.json`.
The CLI also accepts `--database`, `--storage` and `--kms` to mix components,
and Compose accepts the single profiles `postgres`, `s3` and `vault`.
The bundled Vault runs in development mode with the root token `root` and keeps
everything in memory, so `full` is for evaluation only. When its container or
pod restarts, its data is gone: the encryption key has to be written again from
your copy ([Compose](docker-compose.md#create-the-encryption-key-for-full),
[Kubernetes](kubernetes.md#encryption-key-in-the-bundled-vault-full)), and
signing keys that EUDIPLO created in Vault with `--preset full` are lost,
because they are not exportable. In production, use a Vault with persistent
storage.
### Configure the instance
Set these variables in every deployment. All others have defaults, listed in
the [environment variable reference](../reference/environment-variables.md).
| Variable | Why |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `PUBLIC_URL` | The URL wallets and browsers use. It appears in offers, metadata and redirects. Default `http://localhost:3000`. |
| `MASTER_SECRET` | Signs management tokens of the built-in OAuth2 server, derives the [encryption key](encryption-keys.md) with the default `ENCRYPTION_KEY_SOURCE=env`, and, with any key source, the key of the [OpenID Provider's](../presentation/openid-connect.md) pairwise subjects. At least 32 characters. |
| `AUTH_CLIENT_ID`, `AUTH_CLIENT_SECRET` | The first management client, created with the `tenants:manage` role on the first start. Required unless `OIDC` is set for single sign-on, for example with [Keycloak](keycloak.md); unused with `OIDC_PROVIDER=generic`. |
Without further settings, the backend uses SQLite and local file storage in
`FOLDER` (`/app/config` in the image). A minimal container start:
```bash
MASTER_SECRET="$(openssl rand -base64 32)"
AUTH_CLIENT_SECRET="$(openssl rand -base64 24)"
echo "Store these: MASTER_SECRET=$MASTER_SECRET AUTH_CLIENT_SECRET=$AUTH_CLIENT_SECRET"
docker run -d --name eudiplo -p 3000:3000 \
-e PUBLIC_URL=http://localhost:3000 \
-e MASTER_SECRET="$MASTER_SECRET" \
-e AUTH_CLIENT_ID=root \
-e AUTH_CLIENT_SECRET="$AUTH_CLIENT_SECRET" \
-v eudiplo-data:/app/config \
ghcr.io/eudiplo/eudiplo:latest
curl http://localhost:3000/health
```
Keep `MASTER_SECRET` for the lifetime of the data: with the default key source
it derives the key that decrypts private keys and session data.
### Guides
| Topic | Guide |
| --------------------------------------------- | ------------------------------------------------------------- |
| HTTPS, reverse proxy, web client on a subpath | [TLS and reverse proxy](tls.md) |
| WAF rules for wallet and management routes | [Web application firewall](waf.md) |
| CLI install, instances and drivers | [CLI](cli.md) |
| Export, validate and import configuration | [Configuration as code](configuration-as-code.md) |
| Tenants, API clients, users and SSO | [Tenants and access](tenants-and-access.md), [Keycloak](keycloak.md) |
| Database, migrations, session retention | [Database](database.md) |
| Encryption of data at rest | [Encryption keys](encryption-keys.md) |
| Files, images and logos | [Object storage](object-storage.md) |
| Signing keys in Vault, AWS KMS, HSM | [Key management (KMS)](kms.md) |
| Logs, metrics, traces | [Logging](logging.md), [Monitoring](monitoring.md) |
| Capacity tests | [Load testing](load-testing.md) |
| Upgrades between major versions | [Upgrade](../upgrade/index.md) |
---
## Keycloak SSO
Use Keycloak as the identity provider of the management API: people sign in to
the web client with their Keycloak account, and EUDIPLO creates tenant service
clients and users in Keycloak. What changes in this mode is summarized in
[Tenants and access](tenants-and-access.md#external-oidc-provider-and-human-users).
For another provider, such as Authentik, Zitadel, Auth0 or Entra ID, see
[Other OIDC providers](oidc-provider.md).
Keycloak as the login for *wallet users* during credential issuance (chained
authorization server) is a different setup, configured per tenant in the
[authorization servers](../issuance/authorization-servers.md) guide; the
[Issue after login](../cookbooks/issue-after-login.md) cookbook walks through it.
### Before you start
- Keycloak 22 or later, reachable from the EUDIPLO backend and from browsers
- EUDIPLO and the web client deployed at their final HTTPS URLs
- A realm for EUDIPLO, for example `eudiplo`
EUDIPLO uses two Keycloak clients:
| Client | Type | Purpose | Setting |
| --------------- | ------------ | ------------------------------------------------------------------------------- | ----------------------------------------- |
| `eudiplo-admin` | Confidential | Backend access to the Keycloak admin API: realm roles, users, tenant clients | `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` |
| `eudiplo-ui` | Public | Sign-in to the web client with authorization code and PKCE | `OIDC_UI_CLIENT_ID` (default `eudiplo-ui`) |
### 1. Create the admin client
1. In the realm, go to **Clients > Create client** and create the OpenID Connect
client `eudiplo-admin`.
2. Enable **Client authentication** and **Service account roles**; disable
**Standard flow** and **Direct access grants**.
3. Under **Service account roles**, assign the `realm-management` role
`realm-admin`. EUDIPLO creates realm roles and manages users, clients, client
secrets and service-account role mappings. To use a narrower role set, check
that it covers all of these.
4. In the client's **Advanced** settings, enable
**Use refresh tokens for client credentials grant**. Without it, startup can
fail with `Cannot read properties of undefined (reading 'split')`.
5. Copy the secret from the **Credentials** tab.
### 2. Configure EUDIPLO
```env
OIDC=https://keycloak.example.com/realms/eudiplo
OIDC_CLIENT_ID=eudiplo-admin
OIDC_CLIENT_SECRET=
PUBLIC_URL=https://eudiplo.example.com
MASTER_SECRET= # derives the default encryption key
OIDC_UI_URL=https://console.example.com # where the web client is served, comma-separated for several
# Optional, defaults shown
# OIDC_UI_CLIENT_ID=eudiplo-ui
# OIDC_SUB=tenant_id # claim that carries the tenant
# OIDC_ALGORITHM=RS256 # RS256, PS256 or ES256
# OIDC_INTERNAL_ISSUER_URL= # expected token issuer, defaults to OIDC
# OIDC_AUDIENCE= # aud value tokens must carry, checked only when set (see below)
# OIDC_ROLES_CLAIM= # claim with the roles; leave unset with Keycloak (see step 3)
# Optional: a Keycloak client with tenants:manage for automation
AUTH_CLIENT_ID=root
AUTH_CLIENT_SECRET=
```
EUDIPLO validates access tokens against the issuer `OIDC_INTERNAL_ISSUER_URL`
(default: `OIDC`) and loads the signing keys from
`/protocol/openid-connect/certs`. Leave it unset unless the `iss` of
your tokens differs from `OIDC`.
`OIDC_AUDIENCE` is off by default: Keycloak access tokens carry `aud: account`.
To require your own audience, create a client scope with an **Audience** mapper
that adds the value to the access token, and make it a **Default** client scope
of the realm (**Client scopes**, type **Default**), so that `eudiplo-ui`, the
clients EUDIPLO creates and the `AUTH_CLIENT_ID` client all get it. Then set
`OIDC_AUDIENCE` to that value.
Keycloak adds a realm default client scope only to clients created after it
became a default, and EUDIPLO assigns no scopes when it creates or updates a
client. On an existing installation, also add the scope to `eudiplo-ui`, the
`AUTH_CLIENT_ID` client and every tenant client created before: open the
client under **Clients**, then **Client scopes > Add client scope**, type
**Default**. Otherwise their tokens get `401` once `OIDC_AUDIENCE` is set.
Only bearer access tokens are accepted. The realm signs the ID tokens of all
its clients with the keys of its access tokens, so EUDIPLO answers `401` "Not
an access token" to a token whose `typ` claim is present and not `Bearer` (ID
tokens carry `ID`, DPoP-bound access tokens `DPoP`), to one that carries
`at_hash`, `c_hash` or `s_hash`, and to one whose JWS header names another
`typ` than `JWT` or `at+jwt`. A token without `exp` gets `401` "Access token
has no expiry". Send `access_token` from Keycloak's token
response, never `id_token`; the web client, the CLI and `@eudiplo/sdk-core`
already do.
Every client of the realm gets access tokens with `aud: account` and the
realm roles of the person or service account. Without `OIDC_AUDIENCE`,
EUDIPLO therefore accepts only access tokens issued to its own clients: the
token's `azp` (or, without it, `client_id`) must be `eudiplo-ui`
(`OIDC_UI_CLIENT_ID`), the `AUTH_CLIENT_ID` client (only when
`AUTH_CLIENT_SECRET` is set too, as EUDIPLO creates it only then), or a client
EUDIPLO manages, that is one that `GET /api/client` lists for a tenant: created
through EUDIPLO and not deleted since, also not with its tenant. Tokens of
other clients in the realm, such as another application, Keycloak's account
console or `eudiplo-admin`, get `401` "This token was issued to a client of
the realm that EUDIPLO does not manage". A client you created in Keycloak
yourself is refused too, even with EUDIPLO roles: create it through EUDIPLO
instead, or set `OIDC_AUDIENCE` and add the audience to its tokens.
With `OIDC_AUDIENCE` set, the audience alone decides: every client whose
tokens carry it is accepted. A realm default client scope gives it to every
client created later in the realm, other applications too, so use one only
in a realm of EUDIPLO's own, or remove the scope from the clients that must
not call EUDIPLO.
On every start, EUDIPLO:
- creates the missing realm roles (the [EUDIPLO roles](../reference/roles.md)),
- creates or updates the public client `eudiplo-ui` (see below) and sets its
valid post-logout redirect URIs to `+` (the redirect URIs), so logging out in
the web client also ends the Keycloak session and returns to the web client
(the web client sends the ID token in a form POST, not in the address),
- creates or updates the `AUTH_CLIENT_ID` client with `tenants:manage`, if both
`AUTH_CLIENT_ID` and `AUTH_CLIENT_SECRET` are set.
`eudiplo-ui` is a public client: whoever receives one of its authorization codes
can exchange it for the signed-in person's tokens. Keycloak must therefore send
codes only to the web client. With `OIDC_UI_URL` set, EUDIPLO sets the client's
redirect URIs to the pages under each URL (`https://console.example.com/*`) and
its web origins to their origins, on every start. A path, as in
`https://example.com/eudiplo-client/` for a web client behind
`CLIENT_BASE_HREF`, is kept.
Without `OIDC_UI_URL`, EUDIPLO keeps the redirect URIs and web origins set in
Keycloak, so you can manage them there, but removes the redirect URI `*`, which
EUDIPLO 9.x set and which lets any website receive codes. A web origin `*`
becomes `+` (the origins of the redirect URIs), as does an empty list of web
origins. If no redirect URI is left, the backend logs a warning and nobody can
sign in to the web client with SSO.
**Checkpoint:** the backend log shows `Mode: External OIDC (keycloak)` and no
warning about `eudiplo-ui`, and the web client's login page offers single
sign-on after you enter the backend URL.
### 3. Put the tenant into user tokens
EUDIPLO reads the tenant from the `tenant_id` claim (`OIDC_SUB`) and the roles
from `roles` or `realm_access.roles`. Service clients created through EUDIPLO
get both claims automatically, so leave `OIDC_ROLES_CLAIM` unset with Keycloak:
a claim these clients do not carry leaves them without roles. For people, add
the tenant claim once:
1. In Keycloak 24 or later, declare the user attribute `tenant_id` in
**Realm settings > User profile** (or enable unmanaged attributes), so Keycloak
keeps the attribute that EUDIPLO sets on users.
2. Create a client scope, for example `eudiplo-tenant`, with a **User Attribute**
mapper: user attribute `tenant_id`, token claim name `tenant_id`, added to the
access token.
3. Add the scope as a **Default** client scope of `eudiplo-ui`.
Realm roles are in `realm_access.roles` by default.
### 4. Give people access
- **Platform administrators:** assign the realm role `tenants:manage`. They do
not need a `tenant_id`.
- **Tenant users:** create them in the web client or with `POST /api/user`
(role `users:manage`). EUDIPLO stores them in Keycloak with the `tenant_id`
attribute of the caller's tenant, assigns the requested roles and returns a
temporary password. Do not change that attribute in Keycloak; EUDIPLO uses it
to keep users in their tenant.
- **Applications:** create service clients in the web client or with
`POST /api/client`. EUDIPLO creates them in Keycloak with mappers for
`tenant_id` and `roles`; they get tokens from Keycloak's token endpoint with
the client credentials grant.
Choose the roles from the [roles reference](../reference/roles.md), for example
`issuance:manage` and `presentation:manage` for people who configure a tenant,
or `sessions:read` and `credentials:status` for support staff who look up
sessions and revoke credentials.
Tenant administrators need `clients:manage` and `users:manage` plus every role
they hand out ([granting roles](../reference/roles.md#granting-roles)), or
`tenant:admin`, which also allows key export and KMS settings. Roles you assign
in Keycloak, also through groups, count for that check. When an update of a
user or client (`PATCH /api/user/{id}`, `PATCH /api/client/{id}` or a
configuration bundle) sets `roles`, EUDIPLO replaces only the EUDIPLO realm
roles mapped directly to it; Keycloak's default roles, other realm roles and
roles from groups stay. An update without `roles` keeps all of them.
Creating a client whose ID already exists in Keycloak with the `tenant_id` of
the tenant takes over that Keycloak client and replaces its EUDIPLO realm roles
the same way. This happens when `POST /api/tenant` is sent again for the
tenant's `-admin` client, and when `POST /api/client`, a configuration
bundle or a tenant folder creates a client that exists in Keycloak but not
among EUDIPLO's clients of the tenant. Through `POST /api/client` or a bundle
import, the caller must be allowed to manage that Keycloak client, as for an
update, and to grant each requested role. A
Keycloak client without that attribute, or with another tenant's, is never
taken over.
**Checkpoint:** sign in to the web client as a tenant user. The dashboard loads
and shows only that tenant's data.
### Troubleshooting
| Symptom | Cause | Fix |
| ---------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Startup fails with `reading 'split'` | Refresh tokens for client credentials disabled on `eudiplo-admin` | Enable **Use refresh tokens for client credentials grant** |
| Keycloak shows "Invalid parameter: redirect_uri" after **Login with SSO** | The web client's URL is not a redirect URI of `eudiplo-ui` | Add it to `OIDC_UI_URL` and restart the backend, or add `/*` as redirect URI of `eudiplo-ui` in Keycloak when `OIDC_UI_URL` is unset |
| API calls return 401 after login | Token `iss` differs from `OIDC_INTERNAL_ISSUER_URL`/`OIDC`, or wrong `OIDC_ALGORITHM` | Compare the `iss` and `alg` of a token with the configuration |
| API calls return 401 since `OIDC_AUDIENCE` was set | The token's `aud` lacks the value | Add the audience mapper to a realm default client scope, as in [step 2](#2-configure-eudiplo). Clients that existed before the scope became a default need it added in each client's **Client scopes** tab |
| API calls return 401 "This token was issued to a client of the realm that EUDIPLO does not manage" | Without `OIDC_AUDIENCE`, the token's `azp` is not `eudiplo-ui`, `AUTH_CLIENT_ID` (with `AUTH_CLIENT_SECRET` set) or a client EUDIPLO manages | Get the token with one of these clients, create the client through EUDIPLO, or set `OIDC_AUDIENCE` as in [step 2](#2-configure-eudiplo) |
| `This endpoint requires a tenant context` | User token has no `tenant_id` claim, or it names a tenant that does not exist | Add the mapper from [step 3](#3-put-the-tenant-into-user-tokens) and check the user's attribute against the tenant ID |
| `403` on an endpoint | Missing realm role | Assign the role listed for the endpoint in the [roles reference](../reference/roles.md#endpoints) |
| `403` "Cannot grant …" or "Cannot manage …" | The roles involved go beyond the caller's own | Assign the realm role to the caller in Keycloak ([granting roles](../reference/roles.md#granting-roles)). A target with a `realm-management` role or another client role can only be managed in Keycloak |
---
## Key Management (KMS)
Choose where the private keys of signing key chains live and configure the
provider in `kms.json`. By default every key is created by the `db` provider and
stored encrypted in the database (see [Encryption keys](encryption-keys.md)).
Every field of `kms.json` is listed in the [KMS config reference](../reference/kms-config.md).
### Choose a provider
| `type` | Private key lives in | Create | Import | Delete | Use it for |
| --------- | --------------------------------------------- | ------ | ------ | ------ | ---------------------------------------------------- |
| `db` | The EUDIPLO database, encrypted | yes | yes | yes | Development, small installations |
| `vault` | HashiCorp Vault Transit engine | yes | yes | yes | Self-hosted production |
| `aws-kms` | AWS KMS (`ECC_NIST_P256`, `ECC_NIST_P384` or `ECC_NIST_P521`, `SIGN_VERIFY`) | yes | no | yes (7-day deletion window) | Production on AWS |
| `pkcs11` | A hardware security module via PKCS#11 | yes | no | yes | HSMs (SoftHSM, YubiHSM, CloudHSM, …) |
| `http` | Your own remote signing service | yes | if `canImport` | yes | Custom key management |
| `csc` | A Cloud Signature Consortium (CSC v2) service | yes | no | no | Qualified remote signing |
Encryption keys for credential and response encryption always use the `db`
provider. Keys that cannot be imported must be created in the provider, so plan
the provider before you create key chains.
### Signing algorithms
A signing key chain uses one ECDSA algorithm, which also fixes its curve:
`ES256` (P-256), `ES384` (P-384) or `ES512` (P-521). It is chosen when the key
chain is created (`alg`) or, for an imported key, taken from the key's curve.
Rotation keeps it, and every signature of the key chain (credentials, status
lists, trust lists, tokens, request objects, certificates) uses it.
`ES256` is the default and the only algorithm wallets have to support (HAIP).
Choose `ES384` or `ES512` only when the wallets and relying parties you serve
accept it. This matters most for `access` key chains: they sign OID4VP
request objects and signed issuer metadata, which every wallet must validate,
and EUDIPLO does not ask the wallet which algorithms it supports. Keep access
key chains on `ES256` unless you know every wallet accepts the other algorithm.
What a provider offers for new and imported key chains is set per provider in
`kms.json`:
- `algorithms` lists the algorithms new and imported key chains may use.
Without it, `db`, `vault` and `aws-kms` offer all three; `pkcs11`, `http` and `csc` offer only
their `defaultAlgorithm`, because their backends may not support every curve.
List the curves your token, service or CSC credential supports.
- `defaultAlgorithm` is used when a key chain is created without `alg`. It must
be in `algorithms`; without it, `ES256` is used if allowed, otherwise the
first entry of `algorithms`.
```json title="kms.json"
{
"providers": [
{ "id": "db", "type": "db", "algorithms": ["ES256", "ES384"] },
{
"id": "hsm",
"type": "pkcs11",
"library": "${PKCS11_LIBRARY}",
"slot": "${PKCS11_SLOT}",
"pin": "${PKCS11_PIN}",
"algorithms": ["ES256", "ES384"],
"defaultAlgorithm": "ES384"
}
]
}
```
The list also limits every import: `POST /api/key-chain/import`, key-chain
files in the config folder and `KeyChain` documents in a configuration bundle
(private keys, internal chains with private keys, which go into the `db`
provider, and external key references), including an import that replaces an
existing key chain. `POST /api/key-chain/import` refuses a key outside it with
400. A bundle plan checks against the KMS configuration in place and reports
such a key as the blocking issue `UNSUPPORTED_KEY_ALGORITHM`, so the apply
answers 400 `CONFIG_APPLY_BLOCKED` and applies nothing. If the bundle also
contains a `KmsConfig`, the plan only warns with `KMS_PREFLIGHT_DEFERRED`; the
apply checks the key against the new configuration and, when the key is
outside its list, stops at that key chain with `CONFIG_APPLY_FAILED` while
earlier steps, such as the new `KmsConfig`, stay applied
([recovery](./configuration-as-code.md#plans-locks-and-recovery)). An existing key chain
keeps signing and rotating with its algorithm after you remove it from
`algorithms`.
`GET /api/key-chain/providers` returns each provider's offer as
`capabilities.supportedAlgs` and `capabilities.defaultAlg`.
### Configure `kms.json`
The global file is `/kms.json` (`/app/config/config/kms.json` in
the image, `config/kms.json` in CLI projects). It is read at startup:
```json title="kms.json"
{
"defaultProvider": "vault",
"providers": [
{ "id": "db", "type": "db" },
{
"id": "vault",
"type": "vault",
"description": "Production Vault",
"vaultUrl": "${VAULT_ADDR}",
"vaultToken": "${VAULT_TOKEN}"
}
]
}
```
Without the file, only the `db` provider exists. `defaultProvider` (default
`db`) must match a provider `id`; provider IDs must be unique. Write secrets as
`${VAR}` placeholders and set the variables in the backend's environment; an
unset variable stops the startup. The schema is strict, so unknown fields are
rejected.
`eudiplo init` and `eudiplo demo` write it as a `KmsConfig` document with this
content in `spec` ([file forms](../reference/kms-config.md)).
**Checkpoint:** `GET /api/key-chain/providers` lists the providers and the
default; `GET /api/key-chain/providers/health` reports `ok` for each, and
`eudiplo doctor` includes the same check.
### Provider notes
**Vault.** Only `vaultUrl` and `vaultToken` are supported; there is no AppRole
login. Keys are created in the Transit engine mounted at `transit`, which the
backend enables if it is missing; the mount path is not configurable. Give the
token permissions on `transit/*` (and on `sys/mounts/transit` for the automatic
mount). Since 9.0, Vault holds signing keys only through `kms.json`; the old
`KM_TYPE`, `VAULT_NAMESPACE` and `VAULT_MOUNT_PATH` variables have no effect.
The encryption key for data at rest is a separate setting
([Encryption keys](encryption-keys.md#vault)).
**AWS KMS.** Omit `accessKeyId` and `secretAccessKey` to use the AWS SDK
default credential chain (IAM role, IRSA). The backend calls `CreateKey` (with a
tag, so `kms:TagResource` is needed as well), `GetPublicKey`, `Sign`,
`ScheduleKeyDeletion` and, for the health check, `ListKeys`.
**PKCS#11.** The vendor's PKCS#11 library must be available in the backend
container; `slot` is the slot index or the token label. `readOnly: true` opens a
read-only session, which cannot create or delete keys. Keys are created with
`CKM_EC_KEY_PAIR_GEN` on the curve of the key chain's algorithm and sign with
`CKM_ECDSA` over the matching SHA-2 digest.
**CSC.** A CSC credential holds one key on one curve, so set `algorithms` to
the algorithm of that curve, for example `["ES384"]` for a P-384 credential.
Creating a key chain with another algorithm fails. Without `hashAlgorithmOid`
and `signAlgorithmOid`, the OIDs follow the algorithm (SHA-256/384/512 and
ecdsa-with-SHA256/384/512).
**HTTP.** EUDIPLO calls your service for key generation, signing, deletion and
health. Authenticate it with `auth` of type `bearer`, `oauth2-client-credentials`
or `mtls` (or `none` on a trusted network). The endpoints your service must
implement are specified in the
[reference](../reference/kms-config.md#http-provider-api).
### Create a key in a provider
Choose the provider per key chain with `kmsProvider`; without it the
`defaultProvider` is used:
```bash
curl -X POST https://eudiplo.example.com/api/key-chain \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"usageType": "attestation",
"type": "standalone",
"kmsProvider": "vault",
"alg": "ES256",
"description": "Credential signing key"
}'
```
`usageType` is one of the [usage types](../trust/keys-and-certificates.md#usage-types)
of a signing key chain; `type` is `standalone` or `internalChain`; `alg` is one
of the provider's [signing algorithms](#signing-algorithms) and defaults to its
`defaultAlgorithm`. Certificates,
rotation and key import are covered in [Keys and certificates](../trust/keys-and-certificates.md).
A key chain stays with its provider; to move it, create a new key chain in the
target provider and switch the configurations that reference it.
### Per-tenant providers
A tenant can add or override providers without touching the global file. Its
`kms.json` is stored at `//kms.json` and merged over
the global one: providers with the same `id` replace the global entry, and the
tenant's `defaultProvider` wins. A tenant created before 10.0 whose ID is no
folder name has no tenant file and always uses the global configuration; `PUT`
and `DELETE` below answer `400` for it
([upgrade guide](../upgrade/9.x-to-10.0.md#tenants-ids-must-be-a-folder-name)).
Manage it through the API (roles
`tenant:admin` or `tenants:manage`, because the configuration contains provider
credentials):
| Request | Effect |
| ------------------------------------------- | ------------------------------------------------------------------------- |
| `GET /api/key-chain/providers/config` | `tenantConfig` (the tenant file or `null`) and `effectiveConfig` (merged) |
| `PUT /api/key-chain/providers/config` | Validate and write the tenant file, body as in `kms.json` |
| `DELETE /api/key-chain/providers/config` | Remove the tenant file; the global configuration applies again |
The API never returns credentials (`vaultToken`, `secretAccessKey`, `pin`,
`auth.token`, `auth.clientSecret`, `clientSecret`, `sad` and
`authorizeAuthData[].value`); it returns `` instead. In
`tenantConfig`, a credential stored as a `${ENV_VAR}` placeholder is returned as
the placeholder. Providers of the global file appear in `effectiveConfig` with
their non-secret settings only.
A `PUT` replaces the whole tenant file. To keep a stored credential, send
`` back unchanged: it is replaced by the stored value of the provider
with the same `id` and `type`. Any other value, including a placeholder,
replaces the credential. `` for a credential the tenant file does not
store, for example of a global provider copied from `effectiveConfig`, is
rejected with `400`.
A stored credential is also kept only while the setting that says where it is
sent stays the same: `vaultUrl` for `vaultToken`, `baseUrl` for an `http`
bearer `token` and for the CSC `sad` and `authorizeAuthData` values,
`auth.tokenUrl` and `tokenUrl` for OAuth client secrets, and `library` for the
PKCS#11 `pin`. A `PUT` that changes one of these settings must send the
credential again; with `` it is rejected with `400`, so that nobody
who may edit the configuration can redirect a credential they cannot read. The
AWS secret access key only signs requests and is kept when `region` changes.
The API needs `CONFIG_FOLDER` to be writable. The tenant `kms.json` is also part
of [configuration bundles](configuration-as-code.md), with secrets exported as
placeholders.
---
## Kubernetes
Deploy EUDIPLO to a cluster with the Kustomize overlays in `deployment/k8s`.
The overlays are a starting point: each workload runs one replica, and the
bundled PostgreSQL, RustFS and Vault are single-instance development services.
For production, keep the base manifests and point EUDIPLO at a managed database,
object store and secret store.
### Before you start
- `kubectl` with access to the cluster, and a storage class for persistent volumes
- An ingress controller of your choice. The bundled `Ingress`
(`base/ingress.yaml`) uses the class `nginx`; set `spec.ingressClassName` to
your controller's class (`kubectl get ingressclass`). The Kubernetes project
retired ingress-nginx in March 2026. With the Gateway API, route your
`HTTPRoute`s to the services `eudiplo` (port 3000) and `eudiplo-client`
(port 80), and remove the `Ingress` in your overlay with a `$patch: delete`
patch.
- A choice of overlay: `minimal`, `standard` or `full` (see
[presets and profiles](index.md#presets-and-profiles))
The `minimal` overlay mounts `/app/config` as an `emptyDir`, so the SQLite
database is lost when the pod restarts. Use it for short tests only.
### 1. Create the namespace and secret
```bash
cd deployment/k8s
cp overlays/standard/.env.example overlays/standard/.env
# Replace MASTER_SECRET, AUTH_CLIENT_SECRET, DB_PASSWORD and the RustFS/S3 keys
kubectl create namespace eudiplo
kubectl -n eudiplo create secret generic eudiplo-env \
--from-env-file=overlays/standard/.env
```
The backend reads every variable from the `eudiplo-env` secret. `DB_HOST`,
`DB_PORT` and `S3_ENDPOINT` are set by the `postgres` and `rustfs` components.
To change a value later, recreate the secret with
`--dry-run=client -o yaml | kubectl apply -f -` and restart the deployment.
### 2. Pin the image version
The base manifests pin `9.0.0`; releases don't update that tag. Set the version
you want to run in your overlay's `kustomization.yaml`, and keep backend and web
client on the same version:
```yaml title="overlays/standard/kustomization.yaml"
images:
- name: ghcr.io/eudiplo/eudiplo
newTag: "9.0.0"
- name: ghcr.io/eudiplo/eudiplo-client
newTag: "9.0.0"
```
Release images are tagged `X.Y.Z`, `X.Y`, `X` and `latest`; `main` and
`sha-` are builds of the main branch. For reproducible deployments use
`X.Y.Z` or an image digest (`digest: sha256:…` instead of `newTag`). The web
client shows a warning banner when it and the backend come from different
builds.
To upgrade later, back up the database, change `newTag` for both images, and
apply the overlay again. The new backend runs the database migrations on start;
with more than one replica, let one replica finish the migration before scaling
up ([Database](database.md#migrations)). Read the
[upgrade guide](../upgrade/index.md) for every major version you cross.
### 3. Apply the overlay
```bash
kubectl apply -k overlays/standard
kubectl -n eudiplo get pods -w
```
The `full` overlay additionally needs `VAULT_TOKEN` in the secret; see
[below](#encryption-key-in-the-bundled-vault-full).
**Checkpoint:** all pods are `Running`, the `rustfs-bucket-bootstrap` job is
`Completed`, and the health endpoint answers:
```bash
curl http://eudiplo.localtest.me/health
```
```json
{
"status": "ok",
"info": { "database": { "status": "up" } },
"error": {},
"details": { "database": { "status": "up" } }
}
```
`/health` checks only the database connection. The running version is returned
by the authenticated `GET /api/version`.
#### Encryption key in the bundled Vault (`full`)
The `vault-bootstrap` job of the `full` overlay writes a random encryption key
to the bundled Vault if none exists. The backend runs with
`ENCRYPTION_KEY_SOURCE=vault`; its init container `wait-for-vault` holds it
back until the key exists.
The bundled Vault runs in development mode and keeps everything in memory.
When the `vault` pod restarts, the key is gone: running backend pods keep
working, new ones wait in `wait-for-vault`. Save the key after the first start
(use the `VAULT_TOKEN` of your secret instead of `root`):
```bash
kubectl -n eudiplo exec deploy/vault -- env VAULT_ADDR=http://127.0.0.1:8200 \
VAULT_TOKEN=root vault kv get -field=key secret/eudiplo/encryption-key
```
After a Vault restart, write the saved key back the same way with
`vault kv put secret/eudiplo/encryption-key key=`. Don't delete and
re-run the bootstrap job instead: it would create a new key, and the data
encrypted with the old one could no longer be decrypted. Use `full` only to
evaluate Vault. In production, use a Vault with persistent storage or another
[key source](encryption-keys.md#choose-a-key-source), and back up the key.
### Access the services
The ingress routes `eudiplo.localtest.me` to the backend and
`eudiplo-client.localtest.me` to the web client; `localtest.me` resolves to
`127.0.0.1`. Change the hosts in `base/ingress.yaml` (or patch them in your
overlay) and set `PUBLIC_URL` to the public backend URL. TLS termination is
covered in [TLS and reverse proxy](tls.md).
Without an ingress, forward the ports:
```bash
kubectl -n eudiplo port-forward svc/eudiplo 3000:3000
kubectl -n eudiplo port-forward svc/eudiplo-client 4200:80
```
### Use managed services
Create your own overlay that includes only `../../base` and set the connection
variables in the secret instead of adding the `postgres`, `rustfs` or `vault`
components:
```yaml title="overlays/production/kustomization.yaml"
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: eudiplo
resources:
- ../../base
images:
- name: ghcr.io/eudiplo/eudiplo
newTag: "9.0.0"
- name: ghcr.io/eudiplo/eudiplo-client
newTag: "9.0.0"
```
The variables are described in [Database](database.md),
[Object storage](object-storage.md), [Encryption keys](encryption-keys.md) and
[KMS](kms.md). The base deployment mounts `/app/config` as an `emptyDir`; mount
a ConfigMap or volume there if you use a global `kms.json` or tenant config
folders.
### Manage the deployment with the CLI
Register the cluster as a `kubernetes` instance to run `eudiplo doctor`,
`ps`, `logs` and `restart` against it. The CLI never applies manifests; see
[CLI: Kubernetes instances](cli.md#kubernetes-instances) for registration and
the required RBAC permissions.
### Troubleshooting
| Symptom | Cause | Fix |
| ----------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Pod in `CrashLoopBackOff` right after start | Missing `MASTER_SECRET`, `AUTH_CLIENT_ID` or `AUTH_CLIENT_SECRET`, or an invalid variable | `kubectl -n eudiplo logs deployment/eudiplo` shows the validation error |
| Ingress gets no address, or requests answer 404 | No ingress controller serves the class `nginx` | Set `spec.ingressClassName` to a class from `kubectl get ingressclass` |
| Backend cannot reach PostgreSQL | Database not ready or wrong credentials in the secret | `kubectl -n eudiplo exec statefulset/postgres -- pg_isready`, then fix the secret and restart |
| `ErrImagePull` or `ImagePullBackOff` | The image tag does not exist; release tags have no `v` prefix | `kubectl -n eudiplo describe pod ` shows the image; correct `newTag` in `images:` ([step 2](#2-pin-the-image-version)) |
| Pods run an older version than expected | The overlay sets no `images:`, so the base tag `9.0.0` is used | Set `images:` in the overlay ([step 2](#2-pin-the-image-version)) |
| `kubectl apply` fails with `field is immutable` for a Job | The job's template changed in newer manifests | Delete the completed job (`kubectl -n eudiplo delete job `) and apply again. `vault-bootstrap` keeps an existing key; after a Vault restart, [restore the key](#encryption-key-in-the-bundled-vault-full) first |
| `kubectl` reports an expired certificate for `127.0.0.1:6443` | Docker Desktop's local cluster certificate expired | Reset Kubernetes in Docker Desktop settings |
### Migrating existing MinIO storage
Since 9.0 the bundled object storage is RustFS instead of MinIO, with a new
`rustfs-data` volume; follow the
[upgrade guide](../upgrade/8.x-to-9.0.md#bundled-object-storage-minio-replaced-by-rustfs)
to move existing objects.
---
## Load Testing
Measure how a deployment handles token requests, pre-authorized issuance,
complete OID4VP presentations and status-list reads, alone or as a mixed
workload, with the k6 suite in `scripts/load-test`. The runner can start the repository's Compose stack or
target a deployment that is already running.
### Before you start
- [k6](https://grafana.com/docs/k6/latest/set-up/install-k6/) 2.0 or newer
- Docker, only if the runner should start the local stack
- Node.js 22.18 or newer for the resource table, the baseline comparison and the
unit tests of the suite
- For a running deployment: an OAuth client and a tenant with issuance and
presentation configurations (the local stack imports the demo tenant)
### Run against the local stack
```bash
./scripts/load-test/run-all.sh --once
```
The runner starts `deployment/docker-compose` with the `standard` profile
(`COMPOSE_PROFILE`) and the env file `deployment/docker-compose/k6.env`
(`K6_ENV_FILE`; a relative path is resolved against the current directory),
waits for `/health` and runs every scenario once. `k6.env` mounts
`assets/config` and imports the demo tenant on startup, with the client
`test-client` that the scenarios use by default. Another env file must set
`EUDIPLO_ENV_FILE` to its own path, as `k6.env` does, so that the backend reads
it too. If a backend already answers at `HEALTH_URL`, the runner uses it instead
of starting the stack. When the runner starts the stack it applies
`scripts/load-test/compose.limits.yml`, which limits the backend to 2 CPUs and
2 GB and Postgres to 1 CPU and 1 GB, so that results are comparable between runs
and k6 is not competing with the backend for the same cores. Change the limits
with `LOADTEST_BACKEND_CPUS`, `LOADTEST_BACKEND_MEMORY`, `LOADTEST_DB_CPUS` and
`LOADTEST_DB_MEMORY`, or start without them with `LOADTEST_LIMITS=false`.
### Run against a deployment
`--external` does not start Docker and requires an explicit target. Start with
`--once` before applying sustained load:
```bash
BASE_URL=https://eudiplo.example.com \
TENANT_ID=load-test \
CLIENT_ID=load-test-client \
CLIENT_SECRET= \
./scripts/load-test/run-all.sh --external --once
```
Use a dedicated test environment: the issuance and presentation scenarios create
persistent sessions and revoke credentials, and the `load`, `stress` and `spike`
profiles generate substantial traffic. Use [least-privilege client roles](tenants-and-access.md#api-clients-with-least-privilege)
for the test client: `issuance:offer` and `presentation:request` for the flows,
and `credentials:status` for revocations (or `REVOKE_RATIO=0`). The presentation scenario issues its test
credentials in setup, so the tenant needs an issuance configuration whose
credentials the presentation configuration accepts.
The wallet steps follow the URLs in offers and request objects, which the
backend builds from `PUBLIC_URL`, so k6 must reach the backend at that address.
The runner waits for `BASE_URL/health`. Set `HEALTH_URL` if health checks are
exposed elsewhere, or `SKIP_HEALTH_CHECK=true` if a gateway hides them; the
first request then serves as the connectivity check. For private certificate
authorities, `K6_INSECURE_SKIP_TLS_VERIFY=true` disables certificate checks; use
it only in a controlled test environment.
### Profiles
Each scenario states the rate it should sustain under `load` (for example 10
issuances per second) and the latency it must meet at that rate. The profile in
`K6_PROFILE` (default `smoke`, `--once` forces `once`) turns that into the
actual workload:
| Profile | Workload | Thresholds |
| -------- | --------------------------------------------------------- | ------------------------------------------- |
| `once` | One iteration with one virtual user | As written, at most 1 % failed requests |
| `smoke` | 10 % of the scenario rate for 1 minute | As written, at most 1 % failed requests, no dropped iterations |
| `load` | Ramp to the scenario rate in 1 minute, hold 5 minutes | As written, at most 1 % failed requests, no dropped iterations |
| `stress` | Ramp to 2× and 4× the scenario rate | Latency ×3, up to 5 % failed requests |
| `spike` | Jump to 10× the scenario rate for 1 minute, then recover | Latency ×5, up to 10 % failed requests |
All profiles except `once` use k6's arrival-rate executors: k6 starts iterations at the
stated rate whether or not earlier ones have finished, as independent wallets
would. When the backend slows down, the load does not back off; latency grows
and k6 reports `dropped_iterations` once it runs out of virtual users. In
`smoke` and `load` a dropped iteration fails the run; in `stress` and `spike` it
marks the point where the deployment saturates.
Every scenario also requires more than 99 % of its checks to pass.
Under `load` and `stress` the flows pause 1–5 seconds between the operator
creating an offer and the wallet using it, and again before the wallet answers
a presentation request, like a user scanning a QR code and confirming the
disclosure. This keeps sessions open concurrently as in production. Set
`THINK_TIME_MIN` and `THINK_TIME_MAX` (seconds) to change it; `once` and `smoke`
default to no pause and `spike` to 0–1 seconds.
### Scenarios
Without scenario arguments the runner executes all five. Name scenarios to run a
subset:
```bash
K6_PROFILE=load ./scripts/load-test/run-all.sh --external api-auth pre-auth-issuance
```
| Scenario | Rate under `load` | Exercises |
| --------------------- | ------------------ | ------------------------------------------------------------------ |
| `api-auth` | 30/s | `POST /api/oauth2/token` |
| `pre-auth-issuance` | 10/s | Offer, token, nonce and credential request of the pre-authorized flow with a generated holder key; revokes a share of the issued credentials, which re-signs the status list |
| `oid4vp-presentation` | 10/s | Presentation request, request object, and the wallet response: an SD-JWT VC presentation with key binding, encrypted for the verifier, so signature, trust-list, status-list and DCQL checks run under load |
| `status-list` | 200/s | Status list discovery and downloads; when the tenant has no status list yet, setup issues one credential |
| `mixed` | 10 + 10 + 100 + 5/s | Issuance, presentation, status-list reads and token requests at the same time |
`mixed` is the scenario for a capacity figure: the flows compete for the same
database, keys and CPUs as in production. Its rates default to 10 issuances,
10 presentations, 100 status checks and 5 token requests per second and are set
with `MIXED_ISSUANCE_RATE`, `MIXED_PRESENTATION_RATE`, `MIXED_STATUS_LIST_RATE`
and `MIXED_AUTH_RATE`.
The flows request the operator token once in setup and reuse it, renewing it
shortly before it expires; only `api-auth` and the token flow of `mixed` request
a token per iteration. Requests made in setup are not part
of the per-stage latencies.
### Variables
| Variable | Default | Meaning |
| ------------------- | ------------------------ | ----------------------------------------------------------- |
| `K6_PROFILE` | `smoke` | `once`, `smoke`, `load`, `stress` or `spike` |
| `TENANT_ID` | `demo` | Tenant used by the scenarios |
| `CLIENT_ID`, `CLIENT_SECRET` | `test-client`, `test-client-secret` | OAuth client of that tenant |
| `CREDENTIAL_CONFIG_ID` | `pid` | Credential configuration issued by the flows |
| `REQUEST_ID` | `age-over-18` | Presentation configuration used by the presentation flow |
| `REVOKE_RATIO` | `0.1` | Share of issued credentials that are revoked (0 to 1) |
| `CREDENTIAL_POOL_SIZE` | `5` | Credentials issued in setup for the presentation flow |
| `CREDENTIAL_JWT`, `HOLDER_PRIVATE_JWK` | - | Present this SD-JWT VC, bound to this key, instead of issuing credentials in setup |
| `DCQL_CREDENTIAL_ID` | first `dc+sd-jwt` query | DCQL credential query the wallet answers |
| `CHECK_SESSION_RESULT` | `false` | Also read each presentation session and expect `completed` |
| `THINK_TIME_MIN`, `THINK_TIME_MAX` | per profile | Seconds the user pauses between steps |
| `SEED_SESSIONS` | `0` | Sessions created in setup before the measured run (see below) |
| `SEED_BATCH_SIZE` | `50` | Parallel requests per seeding batch |
| `K6_SETUP_TIMEOUT` | `15m` | Time allowed for setup: credential pool and seeding |
| `MAX_LISTS` | `5` | Maximum number of status lists fetched per iteration |
| `SUMMARY_DIR` | `scripts/load-test/results` | Output directory |
| `CLEAN_RESULTS` | `true` | Delete earlier results before the run |
| `START_STACK` | `true` | Start the Compose stack when no backend answers at `HEALTH_URL` |
| `PAUSE_BETWEEN` | `5` | Seconds between scenarios (`--once` sets 0) |
| `PROMETHEUS_RW_URL` | - | Also push k6 metrics to a Prometheus remote-write endpoint |
| `BASELINE_TOLERANCE` | `0.2` | Allowed p95 increase over the baseline |
| `BASELINE_MIN_MS` | `5` | Ignore p95 increases of at most this many milliseconds |
| `BASELINE_ENFORCE` | `false` | Fail the run when a stage exceeds the tolerance |
| `RESOURCE_STATS` | see [Results](#results) | Sample `docker stats`, capture the backend log and count its errors |
### Existing data
A fresh stack has empty session tables, so slow queries and missing indexes only
show once data accumulates. With `SEED_SESSIONS=20000`, the setup of
`pre-auth-issuance`, `oid4vp-presentation` and `mixed` creates that many
sessions, half issuance offers and half presentation requests, before the
measured run starts. Each of these scenarios seeds on its own, so a run of all
scenarios adds the sessions three times; `api-auth` and `status-list` ignore
`SEED_SESSIONS`. The sessions are never redeemed, like abandoned QR codes:
```bash
K6_PROFILE=load SEED_SESSIONS=20000 ./scripts/load-test/run-all.sh mixed
```
### Results
For each scenario the runner writes to `SUMMARY_DIR`, with the run's timestamp
and profile in the file name:
| File | Content |
| ------------------------ | ---------------------------------------------------------- |
| `….json` | Metrics, thresholds and checks; contains no key material |
| `….md`, `….txt` | Latency per stage (median, p95, p99, max) with thresholds |
| `….log` | k6 output |
| `…-docker-stats.jsonl` | `docker stats` samples of the stack, with `RESOURCE_STATS` (see below) |
| `…-backend.log` | The backend's log lines during the scenario, with `RESOURCE_STATS` |
Once per run, except with `once`, the runner also writes `…-baseline.md` with the
baseline comparison.
When the target is the repository's Compose stack, whether the runner started
it or found it running, the runner samples `docker stats` during each scenario.
The Markdown report then lists the peak CPU and memory per container and the
number of `ERROR`/`FATAL` and `WARN` lines the backend logged during the run.
`RESOURCE_STATS=true` or `false` overrides this. In GitHub Actions the reports
are added to the job summary, and every failed scenario gets an error
annotation on the checks with the breached thresholds, failed checks, the most
frequent k6 errors (for a rejected presentation, with the verifier's reason) and,
with `RESOURCE_STATS`, the most frequent backend `WARN`, `ERROR` and `FATAL`
messages.
After the scenarios, the runner compares the p95 of every stage with
`scripts/load-test/baseline.json` for the same profile and reports stages that
are more than `BASELINE_TOLERANCE` (20 %) and more than `BASELINE_MIN_MS` (5 ms)
slower. Set `BASELINE_ENFORCE=true` to fail the run on such a regression. `once`
runs are not compared, and a profile or scenario without a recorded baseline is
reported as such and never fails. A stage in the baseline that the run did not
measure is listed as missing. Without Node.js the comparison is skipped with a
warning, and `BASELINE_ENFORCE=true` then fails the run. To record a new baseline from a run, for
example after an intended change or on different hardware:
```bash
node scripts/load-test/compare-baseline.mjs --update scripts/load-test/results/*-smoke-*.json
```
Baselines depend on the hardware and the resource limits; compare runs from the
same environment.
### Continuous integration
The `Load Tests` workflow builds the backend image and runs the suite against
the local stack:
- on pull requests that change `scripts/load-test`, `deployment/docker-compose`
or the workflow: all scenarios with `smoke`
- every Monday: all scenarios with `smoke`
- every Wednesday: `mixed` with `load` on 20 000 pre-seeded sessions
- manually, with a scenario, profile and number of seeded sessions of your choice
The results are uploaded as the `k6-results-` artifact, together with
the logs of the stack in `compose.log`. Before the backend is built, the
workflow runs the unit tests of the suite:
```bash
node --import ./scripts/load-test/test/shims/register.mjs --test 'scripts/load-test/test/*.test.mjs'
```
To see the backend side of a run, start the [monitoring stack](monitoring.md)
and set `PROMETHEUS_RW_URL=http://localhost:9090/api/v1/write`.
---
## Logging
Set the log level and destinations, keep per-session protocol logs for
troubleshooting, and bound the audit log. Metrics and traces are covered in
[Monitoring](monitoring.md).
### Log level and destinations
`LOG_LEVEL` accepts `trace`, `debug`, `info`, `warn`, `error` and `fatal`. Its
default is `debug`, but `warn` when `NODE_ENV=production`, which the container
image sets. Set `LOG_LEVEL=info` to see startup and flow messages in a container.
The backend writes logs to up to three destinations at the same level:
| Destination | Format | Enabled by |
| ---------------------- | ------------------------------ | ---------------------------------------------------- |
| Console (stdout) | Human-readable (pino-pretty) | always |
| File | JSON, one object per line | `LOG_TO_FILE=true`, path `LOG_FILE_PATH` |
| OpenTelemetry (Loki) | OTLP log records with trace IDs | always, unless `OTEL_SDK_DISABLED=true` ([Monitoring](monitoring.md)) |
For structured logs in a log platform, use the OpenTelemetry export or the JSON
file. The file is not rotated; use `logrotate` or similar.
### HTTP request logs
`LOG_ENABLE_HTTP_LOGGER=true` logs requests and responses of the wallet-facing
endpoints. Management API calls (`/api/...`) and `/health` are never logged this
way. With `LOG_REDACT_SENSITIVE_DATA=true` (default), these values are replaced
by `[redacted]`: the `Authorization`, `Cookie`, `DPoP`,
`OAuth-Client-Attestation` and `OAuth-Client-Attestation-PoP` request headers,
`Set-Cookie`, and the response fields `access_token`, `refresh_token`,
`id_token`, `c_nonce`, `credential`, `credentials` and `attestation_challenge`.
`LOG_HTTP_RESPONSE_BODY=true` adds response bodies (up to
`LOG_HTTP_RESPONSE_BODY_MAX_LENGTH` bytes). Bodies can contain credentials and
personal data; enable it only while debugging.
To inspect decrypted wallet responses during local debugging, set both
`LOG_LEVEL=trace` and `LOG_OID4VP_DECRYPTED_RESPONSE=true`. These logs contain
personal data; never enable this in shared or production environments.
### Session logs
Session logs record the protocol steps of one issuance or presentation
session, for example authorization, token exchange, credential issuance or
presentation verification, with errors. Enable them and choose what is stored
in the database:
```env
LOG_ENABLE_SESSION_LOGGER=true
LOG_SESSION_STORE=errors
```
| `LOG_SESSION_STORE` | Stored |
| ------------------- | ----------------------------------------------------------------------- |
| `off` (default) | Nothing; events go only to the log destinations |
| `errors` | Warnings and errors |
| `all` | All events |
| `verbose` | All events with full request and response bodies and error stacks |
`LOG_SESSION_STORE` has no effect without `LOG_ENABLE_SESSION_LOGGER=true`.
Read the entries with `GET /api/session/:id/logs` (role `issuance:offer` for
issuance sessions, `presentation:request` for presentation sessions,
`sessions:read` for both) or in the **Logs** tab of a session in the web client.
They are deleted with their session ([session retention](database.md#session-retention)).
`verbose` stores personal data and much more volume; use it for debugging only.
### Correlate logs with sessions
Once a request has resolved its session (by offer ID, `walletNonce`, `issuer_state`, code or access token), every following log line of that request, including the HTTP request log, carries `sessionId` and `tenantId`. This works with or without OpenTelemetry; with it, the request span and the span handling the session also get `session.id`.
- Wallet-facing paths carry the session's `walletNonce`, with which anyone can fetch the credential offer or answer the presentation request. Logged URLs and the `url.path` span attribute replace it with `[redacted]` in `/issuers/{tenant}/vci/credential-offers/{walletNonce}`, `/presentations/{walletNonce}/oid4vp/...` and `/presentations/{walletNonce}/iso-18013-7`, and the `auth_session` in `/issuers/{tenant}/authorize/interactive/complete-web-auth/{auth_session}`. Since 10.0; 9.x logged the nonce in the URL and as `req.walletNonce`.
- The values of the query parameters `q` (session and audit log search; a session search can contain a pre-authorized code), `issuer_state`, `request_uri`, `code` and `response_code` are always replaced by `[redacted]` in logged URLs and in the `url.query` span attribute.
To go from a log line or a pasted offer link to the session, search the session list with `GET /api/session?q=...` ([Finding sessions](../concepts/sessions.md#finding-sessions)).
### Audit log
Changes to a tenant and to its credential, issuance, presentation and
status-list configurations, webhook endpoints, attribute providers,
federation trust anchors and the clients of the
[OpenID Provider](oidc-provider.md) and their secrets are recorded with actor, time and changed fields, as are bundle imports, exports,
exports of single resources as documents (`config_resource_exported`, with kind
and ID), detach and reattach actions, generated client secrets and cancelled sessions (with the
reason). Secrets are not recorded: the API keys of webhook endpoints and
attribute providers and the upstream client secrets of chained authorization
servers appear as `[REDACTED]`, and a changed secret is still listed among the
changed fields. Not audited: key chains, trust lists, API clients and users (including
role changes and secret rotation), KMS provider configuration,
and session retention settings.
Read the audit log under **Administration → Activity Logs** in the web client,
or with role `audit:read` or `clients:manage` through the API:
| Endpoint | Returns |
| --- | --- |
| `GET /api/admin/audit-logs/search` | One page (`page`, `pageSize` up to 100) of the matching entries, newest first, with `total` |
| `GET /api/admin/audit-logs` | The newest matching entries as an array, at most `limit` (1–500, default 100) |
| `GET /api/admin/audit-logs/retention` | The retention limits below, so a client can tell pruned entries from a quiet period |
Both list endpoints take the same filters; all given filters must match. The
search endpoint rejects unknown parameters, the list endpoint ignores them:
| Parameter | Matches |
| --- | --- |
| `from`, `to` | Recorded at or after / at or before this time, ISO 8601 with offset |
| `actionType` | One of these actions, e.g. `oidc_client_deleted`; repeat the parameter for several |
| `objectType` | All actions on one kind of object, e.g. `oidc_client` (not its secrets, which are `oidc_client_secret`) |
| `actorType`, `actorId` | `user`, `client` or `system`; the id of the user or client |
| `q` | Text in the action (`credential_config_created` or `Credential Config Created`), in the actor's id or the client it used (`actorId`, `actorDisplay`), or in a changed field's name. Ignores case; on SQLite only for ASCII letters |
| `requestId` | The `X-Request-Id` header of the call that caused the entry, to match it with your proxy or client logs. Recorded only when the caller or a reverse proxy sets the header |
```http
GET /api/admin/audit-logs/search?from=2026-11-17T14:00:00Z&to=2026-11-17T14:30:00Z&objectType=oidc_client
```
The web client keeps its filters in the URL, so a filtered view can be shared.
The audit log is kept forever unless the operator limits it. Tenants cannot
delete entries; a daily job at 03:00 applies these limits to every tenant:
```env
AUDIT_LOG_RETENTION_DAYS=365 # delete entries older than this, 0 = keep
AUDIT_LOG_MAX_ENTRIES_PER_TENANT=10000 # keep only the newest N per tenant, 0 = all
```
Each run writes one `audit_log_pruned` entry from the `system` actor for each
tenant whose entries it deleted. `after.deletedEntries` is the number of deleted
entries, and `after` names the limits that deleted them: `retentionDays` with
`olderThan`, `maxEntriesPerTenant`, or both. With
`AUDIT_LOG_MAX_ENTRIES_PER_TENANT`, that entry counts towards the limit. Earlier
`audit_log_pruned` entries are deleted like any other entry but are not counted,
and a run that deletes only those writes no new entry, so a tenant without other
activity does not get a new entry every night.
Use session logs to answer "what happened in this flow?" and the audit log for
"who changed the configuration, and when?".
---
## Monitoring
Collect EUDIPLO's metrics, traces and logs with OpenTelemetry and view them in
Grafana. The backend pushes all three signals over OTLP/HTTP to a collector; it
has no `/metrics` endpoint to scrape. The `monitor/` folder of the repository
contains a ready-made stack.
```mermaid
flowchart LR
Backend["EUDIPLO backend"] -- "OTLP/HTTP :4318" --> Collector["OTel Collector"]
Collector --> Prometheus["Prometheus (metrics)"]
Collector --> Tempo["Tempo (traces)"]
Collector --> Loki["Loki (logs)"]
Prometheus --> Grafana
Tempo --> Grafana
Loki --> Grafana
```
### Configure the backend
```env
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 # default http://localhost:4318
OTEL_SERVICE_NAME=eudiplo-backend # default
```
The exporter speaks OTLP over HTTP (protobuf) only; point it at the collector's
port 4318, not the gRPC port 4317. Metrics are pushed every 30 seconds. Set
`OTEL_SDK_DISABLED=true` to turn off all export, for example when no collector
runs.
With `GRAFANA_URL`, the web client links sessions to their traces and logs in
Grafana; the datasource UIDs must match your Grafana setup.
### Run the bundled stack
```bash
cd monitor
docker compose up -d
```
| Service | Image | Port |
| ---------------- | --------------------------------------- | ---------------------------------------- |
| `otel-collector` | `otel/opentelemetry-collector-contrib` | 4318 (OTLP/HTTP), 4317 (gRPC), 8889 (Prometheus exporter) |
| `prometheus` | `prom/prometheus` | 9090 |
| `tempo` | `grafana/tempo` | 3200 |
| `loki` | `grafana/loki` | 3100 |
| `grafana` | `grafana/grafana` | 3001 (user `admin`, password `admin`) |
The services share the Compose network `monitoring`, which Docker names
`monitor_monitoring` when started from the `monitor` folder. Inside a container,
`localhost` is the container itself, so a containerized backend must share a
network with the collector.
**Compose without the CLI:** attach the backend to the monitoring network with an
override file. Compose reads `docker-compose.override.yml` automatically when you
run `docker compose` without `-f`:
```yaml title="docker-compose.override.yml (next to your EUDIPLO Compose file)"
services:
eudiplo:
environment:
OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
networks:
- default
- monitoring
networks:
monitoring:
name: monitor_monitoring
external: true
```
**CLI-managed instances:** the CLI passes its Compose files with `-f`, so
Compose ignores an override file in the project directory, and
`eudiplo init --force` rewrites `eudiplo.compose.yaml`. Attach the collector to
the instance's network instead, with an override file in the `monitor` folder:
```yaml title="monitor/docker-compose.override.yml"
services:
otel-collector:
networks:
- monitoring
- eudiplo
networks:
eudiplo:
name: eudiplo_eudiplo-network # _eudiplo-network, see docker network ls
external: true
```
Then, in the instance's project directory, set the endpoint and apply it:
```bash
echo 'OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318' >> .eudiplo.env
eudiplo up # recreates the backend with the new variable
```
Start the instance before the monitoring stack, because the network must
exist. While the collector is attached, `eudiplo down` keeps the network and
reports it as still in use. A collector elsewhere works the same way: set
`OTEL_EXPORTER_OTLP_ENDPOINT` in `.eudiplo.env` to an address the container can
reach.
A backend running directly on the host reaches the collector at the default
`http://localhost:4318`. Running the backend from source with `pnpm dev` is
described in [Development setup](../contributing/development-setup.md).
Grafana is provisioned from `monitor/grafana/provisioning/`: the datasources
Prometheus (`prometheus`), Tempo (`tempo`) and Loki (`loki`) with trace-to-log
and log-to-trace links, the alert rule below, and the **EUDIPLO overview**
dashboard from `monitor/grafana/dashboards/`.
**Checkpoint:** `http://localhost:9090/targets` shows the `otel-collector`
target as up, and after a few requests Grafana's **Explore > Loki** returns logs
for `{service_name="eudiplo-backend"}`.
### Metrics
| Metric | Type | Labels | Meaning |
| ---------------------------------------------- | --------- | --------------------------------------------------------- | ---------------------------------------------------------- |
| `http_server_request_duration_seconds` | histogram | `http_route`, `http_request_method`, `http_response_status_code` | Duration of handled HTTP requests |
| `sessions` | gauge | `tenant_id`, `session_type` (`issuance`, `verification`), `status` (`active`, `fetched`, `completed`, `expired`, `failed`, `cancelled`) | Current number of sessions in the database |
| `tenant_total` | gauge | - | Number of tenants |
| `federation_trust_cache_hits_total`, `_misses_total`, `_stale_total` | counter | `entity` | OpenID Federation trust cache |
| `federation_trust_fetches_total` | counter | `entity` | OpenID Federation trust chain resolutions |
| `oid4vci_as_metadata_cache_hits_total`, `_misses_total`, `_stale_total` | counter | - | Cache of external authorization server metadata |
| `oid4vci_as_metadata_fetches_total` | counter | - | Outbound authorization server metadata fetches |
| `chained_as_discovery_cache_hits_total`, `_misses_total`, `_stale_total` | counter | - | Cache of the chained authorization server's upstream discovery |
| `chained_as_discovery_fetches_total` | counter | - | Outbound upstream discovery fetches |
The backend also exports process and host metrics (CPU, memory) and the
automatic Node.js instrumentation traces.
Since 9.0, `sessions` is read from the database (at most every 30 seconds), so
every replica reports the same values. Deduplicate with `max` before summing:
```text
sum by (tenant_id) (max by (tenant_id, session_type, status) (sessions{status="active"}))
```
### Alerts
`monitor/prometheus/rules/eudiplo.yml`:
| Alert | Fires when | Severity |
| ------------------ | ------------------------------------------------------------------ | -------- |
| `HighErrorRate` | More than 0.1 responses per second with status 5xx, for 2 minutes | warning |
| `ServiceDown` | The collector's scrape target is down for 1 minute | critical |
| `HighResponseTime` | 95th percentile of request duration above 2 s, for 5 minutes | warning |
| `HighMemoryUsage` | Memory use of the host the backend runs on (a container's Docker host or Kubernetes node) above 80 % for 5 minutes, from the backend's host metric `system_memory_utilization` | warning |
The file also defines the recording rule `tenant:active_sessions`. Prometheus
has no Alertmanager configured (the `alerting` block in
`monitor/prometheus/prometheus.yml` is commented out), so these alerts are only
visible in Prometheus until you add one.
Grafana evaluates **High Session Error Rate**
(`monitor/grafana/provisioning/alerting/session-alerts.yml`) every 5 minutes: it
fires when more than 10 % of a tenant's finished sessions failed, for 2 minutes.
Add a contact point in Grafana (**Alerting > Contact points**) to receive it.
### Before production
- Change the Grafana admin password and put Prometheus, Tempo and Loki behind
authentication; the bundled stack has none.
- The stack stores data in local volumes; Prometheus keeps 200 hours. Use
object storage and retention settings that fit your needs for Tempo and Loki.
- Pin the image versions; most services use `latest`.
---
## Object Storage
Configure where EUDIPLO stores uploaded files: credential images, logos and the
`images/` of imported tenant configurations. Use the local filesystem for a
single backend, and S3-compatible storage (RustFS in the bundled stacks, AWS S3
or another provider) when several replicas run or the data must live outside the
host.
### Local storage
```env
STORAGE_DRIVER=local
LOCAL_STORAGE_DIR=/app/uploads # default: /uploads
```
Each file is stored under a random UUID, with a `.meta` file for its
content type. Put the directory on a persistent volume and include it in your
backups. Replicas cannot share it.
### S3-compatible storage
```env
STORAGE_DRIVER=s3
S3_REGION=eu-central-1
S3_BUCKET=eudiplo-files
# For RustFS or other S3-compatible services:
S3_ENDPOINT=http://rustfs:9000
S3_FORCE_PATH_STYLE=true
# Static credentials; omit both to use the AWS SDK default chain (IAM role, IRSA)
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=
```
At startup, the backend sends a `HeadObject` request for a key that does not
exist. A "not found" answer proves access; any other error (credentials, bucket,
region, network) stops the startup with a message. The check needs object-level
read permission only, not `s3:ListBucket`.
The bucket does not have to be public: wallets and browsers download files
through the backend. Every write sets the `public-read` ACL: uploads through the
API and the images imported from tenant config folders and configuration
bundles. If your bucket has ACLs disabled (on AWS the default object ownership
*Bucket owner enforced*), these writes fail with `AccessControlListNotSupported`,
so uploads and imports that contain images fail; allow ACLs on the bucket or use
a provider that ignores them. The bundled
`rustfs-init` job creates `S3_BUCKET` and grants anonymous `s3:GetObject`;
remove that policy if the bucket must stay private.
**Checkpoint:** upload an image in the web client (for example a credential
logo) and open its URL.
### How files are served
| Endpoint | Access | Purpose |
| --------------------- | ----------------------------------------------- | ---------------------------------------------------------------- |
| `POST /api/storage` | `issuance:manage`, multipart field `file`, up to 5 MB | Upload a file for the token's tenant; returns key and URL |
| `GET /storage/:key` | public | Download; the URL is `/storage/` |
Downloads are public because wallets fetch logos and credential images without
credentials. A file is protected only by its random key, so do not store
confidential content. The mapping of keys to tenants and file names is kept in
the database; deleting a tenant deletes its files.
A download answers 404 when no file is stored under the key. Any other storage
failure, for example an unreachable S3 endpoint, answers 500 without details;
the cause is in the backend log.
To move to another storage driver, copy the objects with their keys (for local
storage the files and their `.meta` files) and switch the variables. Moving
existing MinIO data to RustFS is described in the
[upgrade guide](../upgrade/8.x-to-9.0.md#bundled-object-storage-minio-replaced-by-rustfs).
---
## Other OIDC providers
Use an OpenID Connect provider other than Keycloak, such as Authentik, Zitadel,
Auth0 or Entra ID, to sign in to the management API and the web client
(`OIDC_PROVIDER=generic`). The provider manages people and API clients; EUDIPLO
only checks its access tokens. For Keycloak, where EUDIPLO also manages clients
and people, see [Keycloak SSO](keycloak.md).
### Before you start
- A provider that issues **JWT** access tokens signed with RS256, PS256 or
ES256 and publishes an OpenID Connect discovery document
- EUDIPLO and the web client deployed at their final HTTPS URLs
- The EUDIPLO tenants your people and machine clients belong to
### 1. Plan the token claims
EUDIPLO accepts an access token only when all of this holds:
| Check | Requirement |
| ----- | ----------- |
| Format | A JWT (three parts). Opaque tokens get `401` "Access token is not a JWT" |
| Token type | The JWS header has no `typ`, or `JWT` or `at+jwt` (also with the `application/` prefix, in any case), and the token carries no `at_hash`, `c_hash` or `s_hash`, which only ID tokens carry. Otherwise `401` "Not an access token: …" |
| `iss` | Exactly `OIDC`, including a trailing slash |
| Signature | A key from the discovery document's `jwks_uri` (or `OIDC_JWKS_URI`), algorithm `OIDC_ALGORITHM` |
| `aud` | Contains `OIDC_AUDIENCE` |
| `exp` | Present and in the future |
| Tenant | The claim named by `OIDC_SUB` (default `tenant_id`) holds an existing tenant ID. Without it, tenant endpoints answer `403` |
| Roles | The claim named by `OIDC_ROLES_CLAIM`, or `roles` / `realm_access.roles` without it, holds [EUDIPLO role names](../reference/roles.md) |
`OIDC_ROLES_CLAIM` is a claim name or a dot path into nested claims
(`resource_access.eudiplo.roles`); a claim with exactly that name wins, so
namespaced names such as `https://eudiplo.example.com/roles` work. The claim is
an array of role names, or an object whose keys are role names. A string holds
no roles.
Choose an audience that only EUDIPLO's access tokens carry, such as an API
identifier. Some providers also put a client ID into ID tokens; with that as
audience, an ID token of the same client passes the audience check. The token
type check refuses it only when it carries one of the hashes above. Where the
provider offers no other audience and its ID tokens carry no hash, as in the
[Authentik example](#example-authentik), keep its token lifetimes short.
### 2. Configure EUDIPLO
```env
OIDC=https://auth.example.com/application/o/eudiplo/ # the issuer, exactly as the discovery document names it
OIDC_PROVIDER=generic
OIDC_AUDIENCE=
PUBLIC_URL=https://eudiplo.example.com
MASTER_SECRET= # derives the default encryption key
# Optional
# OIDC_INTERNAL_ISSUER_URL= # where the backend loads the discovery document, if not from OIDC
# OIDC_JWKS_URI= # where the backend loads the signing keys, if not from the document's jwks_uri; HTTPS, or HTTP only inside a private network
# OIDC_SUB=tenant_id # claim with the tenant
# OIDC_ROLES_CLAIM= # claim or dot path with the roles
# OIDC_ALGORITHM=RS256 # RS256, PS256 or ES256
# OIDC_UI_CLIENT_ID= # public client of the web client; no default, SSO only when set (step 3)
```
At startup, EUDIPLO loads `/.well-known/openid-configuration`,
retrying for up to 60 seconds while the provider starts. It does not follow
redirects. Startup fails when the document names another issuer than `OIDC`,
lacks `issuer`, `jwks_uri` or `token_endpoint`, or names a key set over plain
HTTP at another origin (scheme, host and port) than the discovery document;
setting `OIDC_JWKS_URI` skips that last check. `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_UI_URL`,
`AUTH_CLIENT_ID` and `AUTH_CLIENT_SECRET` are not used. All variables are listed
in the [environment variable reference](../reference/environment-variables.md#authentication).
**Checkpoint:** the backend log shows `External OIDC (generic)` as the mode, and
`GET /.well-known/oauth-authorization-server` names the provider's
`token_endpoint`.
### 3. Let people sign in to the web client
1. Create a public client at the provider with Authorization Code and PKCE.
2. Register `/login` and `/silent-check-sso.html`
as redirect URIs, the web client's URL as post-logout redirect URI, and its
origin for CORS.
3. Set `OIDC_UI_CLIENT_ID` to the client's ID and restart the backend.
The web client then offers an **SSO** tab and reads the provider's endpoints
from its discovery document. It requests the scope `openid` only, so the
provider must put the audience and the claims of step 1 into that access token
(see the provider notes below). Most providers issue a refresh token only for
the scope `offline_access`, which the web client does not request, so it cannot
renew that token: when it expires, the web client says that the session has
expired, and **Log in** signs the person in again and returns to the page,
without asking while their session at the provider lasts. The access token
lifetime is therefore also the longest the web client stays signed in.
When the provider has an `end_session_endpoint`, logging out also goes there,
and the provider sends the browser back to the web client if its URL is
registered as a post-logout redirect URI. Whether the provider's own session
ends depends on its settings (for Authentik, see step 6 of the example). The
web client opens it with a GET, which every provider accepts, so the
`id_token_hint` is part of the address and can reach the browser history and
access logs.
What changes in this mode, such as the hidden **API Clients** and **Users**
pages, is summarized in
[Tenants and access](tenants-and-access.md#external-oidc-provider-and-human-users).
**Checkpoint:** sign in with SSO as a person of a tenant. The menu shows the
pages of their roles; `GET /api/auth/me` returns their tenant and roles.
### 4. Machine clients
Backends and scripts get tokens with the client credentials grant at the
provider's token endpoint (advertised as `token_endpoint` in
`/.well-known/oauth-authorization-server`). Those tokens need the same audience,
tenant and roles claims as people's tokens; map them on the provider's machine
client or service account. The CLI's `config export`, `plan`, `import`,
`operations` and `recover` commands take the provider's token through `--token`
or `EUDIPLO_TOKEN` ([CLI](cli.md#environment-variables)). `EudiploClient` of
`@eudiplo/sdk-core` and the CLI's other commands fetch tokens only from the
built-in server, so pass the provider's token yourself
([`@eudiplo/sdk-core`](../reference/api.md#eudiplosdk-core)). Which client
limits these tokens get is described in
[Tenants and access](tenants-and-access.md#external-oidc-provider-and-human-users).
### Example: Authentik
1. Create an **OAuth2/OpenID Provider** with an application, for example with the
slug `eudiplo`. The issuer is
`https://auth.example.com/application/o/eudiplo/`, with the trailing slash.
Set **Client type** to **Public**, and under **Allowed grant types** select
**Authorization code**, plus **Client credentials** for machine clients.
Authentik refuses every grant type that is not selected; the browser then
returns to the web client with `invalid_request`.
2. Select a **Signing Key**. Without one, Authentik signs with HS256 and the
client secret, and publishes no keys.
3. Create a property mapping of type **OAuth2/OIDC scope mapping** with the scope
name `openid` that returns the tenant and the roles of the user, for example
from user attributes. Of the scopes that carry claims, the web client
requests only `openid`, so a mapping under another scope name never reaches
its tokens. Authentik merges it with its built-in `openid` mapping.
```python
return {
"tenant_id": user.attributes.get("tenant_id"),
"roles": user.attributes.get("eudiplo_roles", []),
}
```
4. Add the mapping to the provider's scopes and enable
**Include claims in id_token**; without it, the claims reach only the
userinfo endpoint, not the access token.
5. Add the provider's **Redirect URIs** of step 3: `/login`
and `/silent-check-sso.html` of the type **Authorization**,
and the web client's URL, with the trailing slash, of the type **Logout**.
Without the logout entry, logging out ends on an Authentik page instead of
the web client. Set `OIDC_UI_CLIENT_ID` to the provider's client ID.
6. Set the provider's **Invalidation flow** to `default-invalidation-flow`
(**Logout**). The preset `default-provider-invalidation-flow` only logs out
of the application and keeps the Authentik session, so the next
**Login with SSO** signs the person in again without asking.
7. Decode an access token and set `OIDC_AUDIENCE` to its `aud` value. Authentik
puts the provider's client ID there. Its access token is its ID token plus
`azp`, `uid` and `scope`, with the same audience and no hash, so EUDIPLO
cannot tell them apart and also accepts the provider's ID tokens as access
tokens. When someone logs out, the web client passes the
ID token to Authentik in the logout address (`id_token_hint`), where it can
end up in browser history and proxy or access logs. Keep the provider's
**Access token validity** short, to limit how long such a token can be used.
When it expires, the web client asks the person to log in again, which
happens without a password prompt while their Authentik session lasts.
For machine clients, create a service account with the `tenant_id` and
`eudiplo_roles` attributes and an app password. It gets tokens with
`grant_type=client_credentials`, the provider's `client_id`, the service
account's name as `username`, the app password as `password`, and
`scope=openid`. The details are in Authentik's
[machine-to-machine documentation](https://docs.goauthentik.io/add-secure-apps/providers/oauth2/machine_to_machine/).
### Provider notes
- **Zitadel** issues opaque access tokens by default: set the application's token
type to JWT. Project roles arrive in `urn:zitadel:iam:org:project:roles` when
the project asserts roles on authentication; set `OIDC_ROLES_CLAIM` to that
name. EUDIPLO reads only the role names in that claim and ignores the
organizations that granted them, so a role granted in any organization counts
for the token's tenant. Grant the project's roles only in the organization
that maps to that tenant, and add the tenant claim with an action.
- **Auth0** issues a JWT access token only for an API audience. Create an API,
set its identifier as `OIDC_AUDIENCE` and as the tenant's default audience,
because the web client sends no `audience` parameter. Custom claims must have
namespaced names; add them in an action and set `OIDC_SUB` and
`OIDC_ROLES_CLAIM` to those names.
- **Entra ID** must issue v2 access tokens (`requestedAccessTokenVersion: 2` in
the app manifest); v1 tokens carry another issuer than the discovery document.
App roles arrive in `roles`. Entra ID issues a token for your API only when a
scope of that API is requested, which the web client does not do, so use it
for machine clients.
### Troubleshooting
When startup fails at the discovery document, the error starts with "Could not
load the OIDC discovery document from ``:", followed by one of the reasons
in the first four rows.
| Symptom | Cause | Fix |
| ------- | ----- | --- |
| Startup fails: "the document names the issuer '…', but OIDC is '…'" | `OIDC` differs from the provider's issuer, often by the trailing slash | Copy `issuer` from the discovery document into `OIDC` |
| Startup fails: "…neither HTTPS nor at the origin of the discovery document" | The provider names its keys over plain HTTP at another origin (scheme, host and port) than the discovery document | Set `OIDC_JWKS_URI` to an HTTPS URL of the key set, or a plain HTTP URL only inside the deployment's private network (such as a Compose service name). Setting it skips the check, and whoever can change the keys on the way can sign tokens for any tenant |
| Startup fails: "the document has no valid issuer, jwks_uri, token_endpoint" (the missing values) | The URL in the error does not serve the provider's discovery document, or the document lacks these values | Check `OIDC`, or `OIDC_INTERNAL_ISSUER_URL` when set; the backend appends `/.well-known/openid-configuration` itself |
| Startup fails after about 60 seconds with a network error, "status code …" or a JSON error | The backend cannot reach the provider at the URL in the error, or something else answers there | Set `OIDC_INTERNAL_ISSUER_URL` to the address the backend reaches, or start the provider first |
| Startup warns: "The discovery document names the token endpoint … at the internal address" | The provider builds its URLs from the address the backend used (`OIDC_INTERNAL_ISSUER_URL`). EUDIPLO advertises this token endpoint to machine clients, which cannot reach it | Configure the provider's public host name, so its discovery document names public URLs |
| `401` "Access token is not a JWT…" | The provider issues opaque access tokens | Switch it to JWT access tokens (see the provider notes) |
| `401` "Not an access token: …" | The caller sent an ID token or another kind of token, or the provider puts another `typ` than `JWT` or `at+jwt` into its access tokens' header | Send the access token of the token response, not the ID token. If real access tokens get this, check their header's `typ` |
| `401` "Access token has no expiry" | The provider issues access tokens without `exp` | Give the provider's access tokens a lifetime |
| `401` without a reason | Wrong `aud`, `iss`, key or algorithm | Decode a token and compare it with step 1 |
| "This endpoint requires a tenant context" | The token has no tenant claim, or the tenant does not exist | Map the claim named by `OIDC_SUB`, and create the tenant |
| `403` on an endpoint | The roles claim lacks the role, or is not where `OIDC_ROLES_CLAIM` points | Check `GET /api/auth/me`, then the claim mapping |
| **Login with SSO** returns to the web client with `invalid_request` | The provider does not allow the authorization code grant for this client | Allow it on the provider's client; in Authentik, under **Allowed grant types** |
| Signed in, but `GET /api/auth/me` shows no tenant or roles | The provider adds the claims only for a scope the web client does not request | Add them for the scope `openid`, as in step 3 of the Authentik example |
| **Login with SSO** comes back from the provider to the login page; the browser console shows "Unable to decode token, payload not found" | The provider sent a refresh token that is not a JWT, which the web client cannot read | Do not let the web client's provider client issue refresh tokens, for example by not granting it `offline_access` |
| "Your session has expired" each time the access token expires | The provider issues the web client no refresh token (step 3) | Select **Log in**. A longer access token lifetime keeps people signed in longer, and keeps a leaked token usable longer too |
| After logging out, **Login with SSO** signs in without asking | Logging out ended only the web client's session, not the provider's | Make the provider end its session at its `end_session_endpoint`; in Authentik, with step 6 of the example |
| **Login with SSO** ends at the provider with an unknown client or redirect URI | `OIDC_UI_CLIENT_ID` is not the provider's public client, or its redirect URIs lack the web client's pages | Compare `ui_client_id` in `/.well-known/oauth-authorization-server` with the provider's client, and register the redirect URIs of step 3 |
---
## Production Checklist
Work through this list before an instance serves real wallets and users, and
again after major upgrades. Each item links to the guide that explains it.
### Secrets
- [ ] `MASTER_SECRET` is a random value of at least 32 characters
(`openssl rand -base64 32`), kept in a secret manager and never changed
while the data exists ([Encryption keys](encryption-keys.md#keep-the-key-stable)).
- [ ] The encryption key is backed up: `MASTER_SECRET` with the default
`ENCRYPTION_KEY_SOURCE=env`, or the key in `vault`, `aws` or `azure`
([Encryption keys](encryption-keys.md#choose-a-key-source)). An external
key source is optional; it keeps the key out of the backend's
environment. The bundled Vault of the `full` preset runs in development
mode and loses the key on every restart
([presets](index.md#presets-and-profiles)).
- [ ] `AUTH_CLIENT_SECRET` is random. Changing it in the environment later has
no effect; rotate it with `POST /api/client//rotate-secret`
([Tenants and access](tenants-and-access.md#built-in-oauth2-server)).
- [ ] No default or example credentials remain: database password, RustFS/S3
keys, Vault token `root`, Grafana `admin`/`admin`, the demo client
`root`/`root`.
- [ ] No demo tenant or bundled demo keys (`eudiplo demo`, `--demo-tenant`,
`--template demo`) are deployed.
- [ ] Secrets in tenant config files are `${VAR}` placeholders, not literal values
([Configuration as code](configuration-as-code.md#provision-tenants-from-a-folder)).
### Network and TLS
- [ ] `PUBLIC_URL` is the public `https://` URL, and its certificate is issued by
a public CA. The backend is served at the root of its host name
([TLS and reverse proxy](tls.md)).
- [ ] The backend port is reachable only through the reverse proxy
(`EUDIPLO_BIND_ADDRESS=127.0.0.1` in Compose).
- [ ] RustFS (ports 9000 and 9001) and Vault (8200) are not reachable from other
hosts. The current Compose file binds them to `EUDIPLO_BIND_ADDRESS` like
the backend. Older Compose files, including the `eudiplo.compose.yaml` of
existing CLI projects, publish them on all interfaces: remove those
`ports:` entries or block the ports in a firewall in front of the host
([Compose](docker-compose.md#services)).
- [ ] `CORS_ORIGINS` lists exactly the origins of the web client and of your own
frontends that call `/api/*` from the browser, for example
`CORS_ORIGINS=https://console.example.com`. Protocol endpoints stay open.
- [ ] The reverse proxy, API gateway or WAF rate-limits the token, PAR and
credential endpoints and the management API; EUDIPLO has no built-in rate
limiting. Where possible, restrict `/api/*` to known networks, and
exclude the WAF rules that block wallet requests
([Web application firewall](waf.md)).
- [ ] `OUTBOUND_URL_ALLOW_HTTP` and `OUTBOUND_URL_ALLOW_PRIVATE_NETWORK` stay
`false` (the default since 9.0). Webhooks, attribute providers, metadata,
trust lists, status lists, federation entities, the EUDI Hub, external
authorization servers and the upstream provider
of a chained authorization server then need public HTTPS targets; CRLs
may use HTTP.
`OUTBOUND_URL_ALLOWED_HOSTS` additionally limits them to the listed
hosts; it does not exempt a host from either check, so a webhook on a
private address still needs `OUTBOUND_URL_ALLOW_PRIVATE_NETWORK=true`.
- [ ] Egress is restricted at the network level if EUDIPLO must not reach
internal services: KMS providers, including those in a tenant's KMS
configuration, are called without the outbound URL policy
([security model](../concepts/security-model.md#https-and-tls)).
- [ ] Services with private CAs (Vault, KMS, webhooks, PostgreSQL) are trusted
through `NODE_EXTRA_CA_CERTS` or `DB_SSL_CA_PATH`, never by disabling
certificate checks.
### Access
- [ ] Each application has its own API client with only the roles it needs,
usually `issuance:offer` and `presentation:request`, limited with
`allowedIssuanceConfigs` and `allowedPresentationConfigs`
([Tenants and access](tenants-and-access.md#api-clients-with-least-privilege)).
- [ ] `tenants:manage` and `tenant:admin` are held only by operators and the
configuration pipeline ([Roles](../reference/roles.md)).
- [ ] People sign in through your identity provider rather than with shared
client secrets ([Keycloak SSO](keycloak.md)).
### Keys, certificates and checks
- [ ] Signing keys live in the KMS your security model requires
([KMS](kms.md)); the `db` provider stores them encrypted in the database.
- [ ] Access and registration certificates come from your registrar instead of
self-signed certificates ([EUDI Hub](../trust/eudi-hub.md),
[Registration certificates](../trust/registration-certificates.md)), and
you know when they expire: EUDIPLO does not renew them.
- [ ] No `SKIP_*` flag is set; the startup log lists active ones
([Skip flags](../reference/environment-variables.md#skip-flags)).
- [ ] Outside the container image, for example with `node dist/main.js` from a
source build, `NODE_ENV=production` is set. Otherwise EUDIPLO skips TLS
certificate checks when it fetches status lists and trust lists, returns internal error messages to API
callers, and `LOG_LEVEL` defaults to `debug` instead of `warn`
([Environment variables](../reference/environment-variables.md#general)).
- [ ] Issuance configurations require DPoP and wallet attestation where your use
case demands it ([Authorization servers](../issuance/authorization-servers.md)).
### Data and logs
- [ ] PostgreSQL is used for anything beyond a single small instance, with
`DB_SSL=true` when it is not on the same host ([Database](database.md)).
- [ ] Session retention (`SESSION_TTL`, `SESSION_CLEANUP_MODE`) and audit log
retention (`AUDIT_LOG_RETENTION_DAYS`, `AUDIT_LOG_MAX_ENTRIES_PER_TENANT`)
match your data protection rules ([Database](database.md#session-retention),
[Logging](logging.md#audit-log)).
- [ ] Logs do not capture personal data: `LOG_REDACT_SENSITIVE_DATA=true`,
`LOG_HTTP_RESPONSE_BODY=false`, `LOG_OID4VP_DECRYPTED_RESPONSE=false`,
`LOG_SESSION_STORE` not `verbose` ([Logging](logging.md)).
### Backups
Back up all of these together; a restore needs every part:
| What | How |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| Database | `pg_dump` (bundled stack: `docker compose exec -T postgres pg_dump -U eudiplo -Fc eudiplo > eudiplo.dump`), or the SQLite file `/service.db` while the backend is stopped |
| Object storage | Bucket versioning or replication, or a copy of `LOCAL_STORAGE_DIR` |
| Encryption key | `MASTER_SECRET` (with `ENCRYPTION_KEY_SOURCE=env`) or the external key, in your secret manager |
| Signing keys in a KMS | The KMS's own backup (Vault snapshots, AWS KMS key policies, HSM backup) |
| Configuration | The config folder in version control, or `eudiplo config export` per tenant |
| Environment | The env file or Kubernetes secret, without which the backend does not start |
- [ ] Backups run on a schedule and a restore has been tested on a separate
instance.
- [ ] A backup is taken before every upgrade; migrations cannot be undone
([Database](database.md#migrations)).
### Operations
- [ ] Image versions are pinned to a release (`X.Y.Z`), and backend and web
client run the same version ([Kubernetes](kubernetes.md#2-pin-the-image-version),
[CLI](cli.md#upgrade-the-application)).
- [ ] Metrics, traces and logs reach your monitoring, and someone receives the
alerts ([Monitoring](monitoring.md)).
- [ ] `eudiplo doctor --strict` passes, also as a scheduled check with
`EUDIPLO_CLIENT_ID` and `EUDIPLO_CLIENT_SECRET` set ([CLI](cli.md#check-an-instance-with-doctor)).
With the root client the KMS check is skipped; a tenant client with
`issuance:manage` checks the KMS providers as well:
```bash
eudiplo doctor --instance production --strict
```
---
## Keep a Tenant in Git
Export a tenant from a running instance as a
[tenant folder](../reference/config-bundle-format.md#tenant-folder-layout),
commit it, and plan and import changes to it from the folder. Bundles, plans and
ownership are explained in [Configuration as code](configuration-as-code.md);
this page uses the same commands and token
([Export a tenant](configuration-as-code.md#export-a-tenant)).
### Export the tenant as a folder
End `--output` with a slash, or name an existing empty directory:
```bash
eudiplo config export --instance production --output ./config/acme/
```
Any other `--output` writes a bundle file: JSON for `.json`, a ZIP otherwise,
also without an extension.
- **Names.** Files are named after the resource ID (`clients/.json`,
`key-chains/.json`, `issuance/issuance.json`, …). An ID that is no valid
file name on every system, that is longer than 80 characters or that differs
from another only in case gets a short hash suffix; the ID inside the
document is what counts.
- **Stable output.** Keys are sorted and indented by two spaces, so exporting
the same configuration again writes the same files and `git diff` shows only
real changes.
- **Secrets.** Placeholders and `keySource: { "type": "required" }` are written
as the export has them. Instead of a `manifest.json`, the command lists each
value to supply with its file:
```text
2 value(s) to supply before this folder can be imported:
clients/portal.json /spec/secret: ${CLIENT_PORTAL_SECRET} (CLIENT_SECRET_REQUIRED)
key-chains/signing.json /spec/keySource: private key (PRIVATE_KEY_REQUIRED)
```
- **Target.** The directory must not exist or must be empty; the folder is
written in full or not at all. Name it after the tenant: the startup import
takes the tenant from the folder name, and a CLI import uses it as the
bundle source.
### Plan and import the folder
`config plan` and `config import` take the folder in place of a bundle:
```bash
eudiplo config plan ./config/acme --instance staging --mode upsert --diff --output plan.json --allow-env PORTAL_SECRET
eudiplo config import ./config/acme --instance staging --mode upsert --plan plan.json --allow-env PORTAL_SECRET
```
1. The CLI validates the folder offline, like
[`eudiplo config tenant validate`](configuration-as-code.md#validate-in-ci).
A folder with errors exits with `1` and is not sent, and so is a folder
with a symbolic link that points outside it or does not resolve.
2. It fills in `${VAR}` placeholders from the variables named in
`--allow-env` (see below). A placeholder without a value is named in a
warning and sent as it is; the plan blocks that resource with
`SECRET_REQUIRED` until the variable is set and named.
3. It sends the folder as a bundle archive, `info.json` and `images/` included.
The bundle is the same for the same files and environment, so the import
matches the reviewed plan.
The tenant comes from the access token, not from the folder name.
Planning a freshly exported folder against the same instance shows every
resource as `unchanged`, except those with a requirement: a client whose secret
is a placeholder is `blocked` with `SECRET_REQUIRED`, and a key chain with
`"type": "required"` with `PRIVATE_KEY_REQUIRED`, as when the bundle export
itself is planned.
### Placeholders and the CLI's environment
A placeholder can sit in any field, and the plan shows field values. So that a
change to the folder cannot copy a value out of the environment the CLI runs in,
for example a CI runner:
- `${VAR}` placeholders resolve only from the variables named in
`--allow-env` (comma-separated). The CLI reads no other variable, and the
option applies to a folder only; a bundle's placeholders are resolved by the
server.
- `EUDIPLO_TOKEN`, `EUDIPLO_CLIENT_ID` and `EUDIPLO_CLIENT_SECRET` hold the
CLI's own credentials and are refused in `--allow-env`.
- The plan or result that `config plan` and `config import` print or save,
and an error the API answers, show each filled-in value as its placeholder
again, in field values and messages; kinds, IDs and the plan fingerprint stay
as they are. A value shorter than eight characters is only replaced where it
is the whole value.
`config import` still stores the filled-in values: review which variables a
change adds to `--allow-env` before you import it. The startup import fills
placeholders from the backend's whole environment.
### Folder imports and the startup import
Every import records its source on the resources it writes: a CLI import of a
folder `bundle:`, the startup import the folder in
`CONFIG_FOLDER`. `replace` mode deletes only resources whose recorded source is
its own. If both import the same tenant, each takes over the resources it
writes: switching between them gives `!generate` clients a new secret, applies
unchanged key chains again (a `regenerate` key source gets new keys), and a
`replace` of one does not delete resources last written by the other. Manage a
tenant with one of the two.
---
## Tenants and Access
Create tenants, give applications least-privilege API clients, and let people
sign in. Every management endpoint (`/api/...`) needs an OAuth 2.0 bearer token;
the roles and tenant of its client or person decide what the caller may do. The
roles are listed in the [roles reference](../reference/roles.md).
### Tenants
A tenant is one issuer and/or verifier: its credential, issuance and presentation
configurations, keys, trust lists, sessions and clients belong to it. All
records carry the tenant ID, and every request is scoped to the tenant in the
access token. Tenants have no lifecycle states besides `active`; to take a
tenant offline, delete it (below). Deleting its clients only ends their API
access ([revoke access](#revoke-access)): people who sign in with Keycloak keep
theirs, and wallets can still finish the offers and requests already sent.
#### Create a tenant
With a token that has `tenants:manage` (for example the root client below):
```bash
curl -X POST https://eudiplo.example.com/api/tenant \
-H "Authorization: Bearer $ROOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "acme",
"name": "Acme GmbH",
"roles": ["issuance:manage", "presentation:manage", "tenant:admin"]
}'
```
`POST /api/tenant` accepts only IDs that use lowercase letters, digits, `-` and
`_`, start with a letter or digit and have at most 63 characters, since the ID
is also the name of the tenant's folder in `CONFIG_FOLDER`; other IDs answer
`400`. The startup import does not check folder names against this rule, so
name tenant folders by it as well.
If you pass `roles`, EUDIPLO also creates the client `acme-admin` with
`clients:manage` plus these roles, and returns its secret once in the response.
Use that client to set up the tenant and to create narrower clients. It can
hand out only `clients:manage` and these roles, unless they include
`tenant:admin` ([granting roles](../reference/roles.md#granting-roles)), so
choose them with that in mind. The root client has no tenant and cannot change
a tenant's clients, but sending `POST /api/tenant` again for the existing
tenant, with its name and all roles the admin client needs, gives that client
`clients:manage` and these roles and removes its other EUDIPLO roles (with
Keycloak only those mapped directly to it, see
[Keycloak SSO](keycloak.md#4-give-people-access)); with the built-in server it
also returns a new secret.
`DELETE /api/tenant/:id` removes the tenant with its data and files. Tenants can
also be created from a config folder with an `info.json`
([configuration as code](configuration-as-code.md)).
### API authentication
#### Built-in OAuth2 server
Without `OIDC`, EUDIPLO issues tokens itself with the client credentials grant:
```bash
curl -X POST https://eudiplo.example.com/api/oauth2/token \
-d grant_type=client_credentials \
-d client_id=acme-admin \
-d client_secret="$CLIENT_SECRET"
```
The client can also send its credentials with HTTP Basic authentication. Tokens
are signed with `MASTER_SECRET` and expire after 24 hours. The response has no
refresh token; request a new token with the client credentials. Use tokens as
`Authorization: Bearer `. The Swagger UI of the
management API is at `/api/docs` (its **Authorize** button uses the same
endpoint); the wallet-facing protocol API is documented at `/docs`.
On the first start, EUDIPLO creates the root client from `AUTH_CLIENT_ID` and
`AUTH_CLIENT_SECRET`. It has `tenants:manage` and belongs to no tenant, so it
can create and manage tenants (each new tenant gets a `-admin` client)
and rotate client secrets (except those of
[file-managed](configuration-as-code.md#configuration-model) clients), but cannot call tenant-scoped endpoints such as
clients, issuance or presentation configs. It can also see the cached status lists
and clear the trust list, federation and status list caches of all tenants
([roles](../reference/roles.md)). Changing the two variables later does not
change the stored client; rotate its secret with
`POST /api/client//rotate-secret` instead.
#### API clients with least privilege
Create one client per application, with only the roles it needs. A token with
`clients:manage` creates clients in its own tenant, with the roles it can hand
out, for example the `acme-admin` client above:
```bash
curl -X POST https://eudiplo.example.com/api/client \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"clientId": "shop-backend",
"description": "Issues membership cards and checks age",
"roles": ["issuance:offer", "presentation:request"],
"allowedIssuanceConfigs": ["membership"],
"allowedPresentationConfigs": ["age-check"]
}'
```
The response contains the generated secret once; it is stored as a bcrypt hash
and cannot be read again. Rotate it with `POST /api/client/:id/rotate-secret`;
with the built-in server, tokens issued with the old secret stop working at
once ([revoke access](#revoke-access)).
Client IDs may contain letters, digits, `.`, `_`, `:` and `-`, and are unique
across all tenants: an ID that is already taken answers `409`.
`allowedIssuanceConfigs` limits the credential configuration IDs the client may
put in offers, `allowedPresentationConfigs` the presentation configurations it
may request. Other IDs are rejected with `403`; an empty or missing list allows
all. The web client's client form changes a list only when it can load the
configurations to choose from: listing credential configurations needs
`issuance:manage`, listing presentation configurations `presentation:manage` or
`presentation:request`. Without that role, or when the list fails to load, the
field is locked: editing a client keeps its stored list, and a new client is
created without that limit. Set the list through the API in that case.
The session endpoints (`/api/session`) need `issuance:offer`,
`presentation:request` or `sessions:read`. Without `sessions:read`, a client
sees only the sessions of its side: issuance sessions with `issuance:offer` or
`issuance:manage`, presentation sessions with `presentation:request` or
`presentation:manage`. Other sessions are left out of the list, answer `404`
and are not deleted. `sessions:read` reads the sessions of both sides, with
their logs, events, counts and credential status, including issued claims and
presented credentials, but creates, cancels and deletes none; together with
`issuance:offer` or `presentation:request`, a client still cancels and deletes
only the sessions of that side. Of the session types a client with
`sessions:read` cannot cancel, which also holds for `issuance:manage` or
`presentation:manage` without `issuance:offer` or `presentation:request`, it
sees only the sessions a wallet can no longer use: redeemed, answered or in a
final status. The others are left out of the list and answer `404`,
because the session ID of an ISO 18013-7 request, or of an offer created
before 10.0, alone lets a wallet answer or redeem it; the counts include them.
The sessions it sees come without the values
a wallet redeems or answers them with, such as the offer and request URIs and
the transaction code. Changing credential status
(`POST /api/session/revoke`) needs `credentials:status` or `issuance:manage`.
Typical role sets:
| Caller | Roles |
| ---------------------------------------- | ------------------------------------------------------------- |
| Your application backend | `issuance:offer`, `presentation:request`; also `credentials:status` if it revokes or suspends credentials |
| Support staff who look up sessions and revoke credentials | `sessions:read`, `credentials:status` |
| Auditor | `audit:read`, `sessions:read` |
| Key custodian | `keys:manage` |
| CI pipeline that imports configuration | `tenant:admin` |
| Person who configures a tenant | `issuance:manage`, `presentation:manage`, `clients:manage`, `users:manage`, and the roles they hand out; `tenant:admin` instead also allows key export and KMS settings |
| Platform operator | `tenants:manage`, on a client without a tenant |
`issuance:manage`, `presentation:manage` and `keys:manage` create, import,
rotate and delete key chains, but exporting a key chain with its private key
(`GET /api/key-chain/{id}/export` or its configuration document) and the tenant KMS provider configuration
(`/api/key-chain/providers/config`), which contains provider credentials, need
`tenant:admin` or `tenants:manage`, like configuration bundles.
A caller hands out only roles it holds, or with `tenant:admin` every role
except `tenants:manage` and `tenant:admin`, and cannot change or take over a
client or user with more rights than its own
([granting roles](../reference/roles.md#granting-roles)).
#### Revoke access
With the built-in server, EUDIPLO reads the client on every request: a token is
accepted only while its client exists in the token's tenant, and with the roles,
`allowedIssuanceConfigs` and `allowedPresentationConfigs` the client has now.
Deleting a client (`DELETE /api/client/:id`) ends its access at once; changing
its roles or limits applies to the tokens it already has.
A token is accepted only for the client and secret it was issued for. A client
created again with the same ID, including `-admin` when you create a
deleted tenant again, does not revive the old tokens. A new secret ends the
client's tokens at once, also a token requested while the secret changed:
- `POST /api/client/:id/rotate-secret`;
- `POST /api/tenant` with `roles` for an existing tenant, which gives
`-admin` a new secret;
- a configuration bundle import with another secret, or with `!generate` for
an existing client;
- a startup import with another secret. A client file without `secret` gets a
new random secret on every start in `upsert` or `replace` mode, so set the
secret in the file.
Importing the secret the client already has keeps its tokens, also when the
startup import in `upsert` or `replace` mode re-creates the client. To change a
secret without interrupting an integration, create a second client, switch the
integration to it, then delete the first one.
With Keycloak, EUDIPLO checks tokens without asking Keycloak. Deleting a client
also deletes it in Keycloak, which then issues no new tokens to it. Without
`OIDC_AUDIENCE`, the tokens it already has get `401` at once, as EUDIPLO
accepts only tokens of the clients it manages
([details](keycloak.md#2-configure-eudiplo)); creating a client with the same
ID again makes those that have not expired valid again. Deleting a tenant
leaves its clients in Keycloak, but without `OIDC_AUDIENCE` their tokens get
`401` too; delete them in Keycloak. With `OIDC_AUDIENCE` set, the tokens of a
deleted client stay valid until they expire (the realm's access token
lifespan, 5 minutes by default), without the client's config limits. After a new secret, the tokens
a client already has stay valid until they expire in both cases. Keep that
lifespan short. Changes to the limits apply at once, role changes in Keycloak
with the next token.
### External OIDC provider and human users
To let people sign in with their own accounts, set `OIDC` to a Keycloak realm.
With `OIDC_PROVIDER=keycloak`, the default, EUDIPLO manages clients and people
through Keycloak's admin API. Then:
- EUDIPLO accepts Keycloak access tokens instead of issuing its own; the
built-in `POST /api/oauth2/token` is disabled.
- The web client signs people in with the authorization code flow and PKCE,
from the URLs in `OIDC_UI_URL` or the redirect URIs set in Keycloak.
- Clients created through `/api/client` are Keycloak clients, and people are
managed through `/api/user` (role `users:manage`) or in the web client. Without
`OIDC`, `/api/user` answers `501` and the web client hides **Users**.
- Access tokens must carry the tenant ID in the claim named by `OIDC_SUB`
(default `tenant_id`) and the roles in `roles` or `realm_access.roles`, or in
the claim named by `OIDC_ROLES_CLAIM`.
- Without `OIDC_AUDIENCE`, only access tokens issued to the web client's
client (`OIDC_UI_CLIENT_ID`), the `AUTH_CLIENT_ID` client (with
`AUTH_CLIENT_SECRET` set) or a client EUDIPLO manages are accepted; tokens of other clients in the realm get
`401` ([details](keycloak.md#2-configure-eudiplo)).
Another OpenID Connect provider, such as Authentik, Zitadel, Auth0 or Entra ID,
works with `OIDC_PROVIDER=generic` for signing in only. EUDIPLO then loads the
provider's discovery document at startup, checks the issuer, the signing keys
and the required `OIDC_AUDIENCE`, and accepts only JWT access tokens; ID
tokens with that audience are refused when they carry `at_hash`, `c_hash` or
`s_hash`, and tokens of another `typ` are refused too
([details](oidc-provider.md#1-plan-the-token-claims)). With Authentik, an ID
token still works as an access token
([details](oidc-provider.md#example-authentik)). The
provider manages clients and people: `/api/client`, `/api/user` and creating a
tenant with `roles` answer `501` (the web client creates tenants without an
admin client), and the web client hides **API Clients** and **Users**. Config
folders and bundles carry no clients either
([details](../reference/config-bundle-format.md#clients-with-another-identity-provider)).
The setup, including single sign-on in the web client and machine clients, is
described in [Other OIDC providers](oidc-provider.md).
Tokens get no client limits (`allowedIssuanceConfigs`,
`allowedPresentationConfigs`), except where a client record is left from an
earlier mode: Keycloak clients, the built-in `AUTH_CLIENT_ID` root client and
`-admin` clients alike. A token whose `azp`, `client_id` or, without
those, `sub` names such a record gets the record's limits; if the record
belongs to another tenant than the token's, the token gets `401`.
The web client does not read roles or the tenant from the token itself. It asks
the backend (`GET /api/auth/me`), so its menus follow `OIDC_ROLES_CLAIM` and
`OIDC_SUB` and show what the API allows.
The variables and the setup are described in [Keycloak SSO](keycloak.md) or, for
another provider, in [Other OIDC providers](oidc-provider.md).
`MASTER_SECRET` is optional in OIDC mode, but the default encryption key is
derived from it; set it, or use another
[encryption key source](encryption-keys.md). OpenID Provider clients with a
[`subject`](../presentation/openid-connect.md#stable-subject-and-top-level-claims)
need it too.
---
## TLS and Reverse Proxy
Serve EUDIPLO over HTTPS, either behind a TLS-terminating reverse proxy or with
the backend's built-in TLS. Wallets require HTTPS for every issuer and verifier
URL, so `PUBLIC_URL` must be the `https://` URL wallets reach.
| Option | Use it when |
| --------------- | ----------------------------------------------------------------------------------------------- |
| Reverse proxy | Default. Certificate renewal, rate limits, IP filtering and the web client run in front of EUDIPLO |
| Built-in TLS | No proxy is available, for example a single container on a test host |
### Behind a reverse proxy
The backend listens on plain HTTP (port 3000, or `PORT`). It builds every URL in
offers, metadata and redirects from `PUBLIC_URL` and does not read
`X-Forwarded-*` headers, so set `PUBLIC_URL` to the external URL:
```env
PUBLIC_URL=https://eudiplo.example.com
TLS_ENABLED=false
```
Requirements for the proxy:
- Serve the backend at the root of its host name. Tenant IDs are path segments
of the protocol URLs (`/issuers//…`), so the backend cannot run under
a path prefix. Only the [web client](#serving-the-client-from-a-subpath) can.
- Allow request bodies up to 50 MB if you import configuration ZIP bundles
(`POST /api/config-bundles/import/archive`); other requests stay below 10 MB.
- Do not buffer server-sent events from `/api/session/:id/events`.
- Bind the backend port to `127.0.0.1` (Compose: `EUDIPLO_BIND_ADDRESS=127.0.0.1`)
so it is only reachable through the proxy.
#### Caddy
Caddy obtains and renews certificates automatically:
```text title="Caddyfile"
eudiplo.example.com {
reverse_proxy 127.0.0.1:3000
}
console.example.com {
reverse_proxy 127.0.0.1:4200
}
```
#### nginx
```nginx
server {
listen 443 ssl;
http2 on;
server_name eudiplo.example.com;
ssl_certificate /etc/letsencrypt/live/eudiplo.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/eudiplo.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
client_max_body_size 50m;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off; # session events (SSE)
proxy_read_timeout 1h;
}
}
```
When the web client runs on another origin than the backend, add that origin to
`CORS_ORIGINS` if you restrict browser access to the management API (see the
[production checklist](production-checklist.md#network-and-tls)).
### Built-in TLS
Set the certificate and key files; the backend then serves HTTPS on the same port:
```env
TLS_ENABLED=true
TLS_CERT_PATH=/certs/fullchain.pem
TLS_KEY_PATH=/certs/privkey.pem
PUBLIC_URL=https://eudiplo.example.com:3000
```
```yaml title="Compose override"
services:
eudiplo:
volumes:
- ./certs:/certs:ro
```
Behavior since 9.0:
- **TLS fails closed.** With `TLS_ENABLED=true`, startup fails if `TLS_CERT_PATH`
or `TLS_KEY_PATH` is unset, a file cannot be read, or a file contains no PEM
certificate. The backend never falls back to plain HTTP.
- **`TLS_CA_PATH` adds intermediate certificates.** The certificates in that file
are sent after the server certificate so clients can build the chain;
certificates that `TLS_CERT_PATH` already contains are not added twice. You do
not need it with a full chain such as Let's Encrypt's `fullchain.pem`. It does
not enable client certificate authentication (mTLS).
- **Encrypted keys** need `TLS_KEY_PASSPHRASE`.
- Certificates are read at startup. Restart the backend after renewing them.
The startup log reports `TLS: Enabled`. The variables are listed under
[TLS](../reference/environment-variables.md#tls). For a quick local test, a
self-signed certificate works with `curl -k`; wallets reject it.
```bash
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
-keyout key.pem -out cert.pem -days 30 -subj "/CN=localhost"
```
### Serving the client from a subpath
The web client can run under a path, for example
`https://example.com/eudiplo-client/`. Two settings are needed:
1. Set `CLIENT_BASE_HREF` on the client container. The container rewrites the
`` of the app at start, so routes and assets resolve under the
path. The value is normalized to start and end with `/` and may only contain
letters, digits, `-`, `_` and `/`.
```yaml
services:
eudiplo-client:
image: ghcr.io/eudiplo/eudiplo-client:latest
environment:
API_BASE_URL: https://eudiplo.example.com
CLIENT_BASE_HREF: /eudiplo-client/
```
2. Make the proxy strip the path before forwarding, because the client container
serves its files at `/`:
```text title="Caddyfile"
example.com {
handle_path /eudiplo-client/* {
reverse_proxy 127.0.0.1:4200
}
}
```
```nginx
location /eudiplo-client/ {
proxy_pass http://127.0.0.1:4200/; # trailing slash strips the prefix
}
```
The backend itself cannot be served from a subpath (see above).
---
## Web Application Firewall
Configure a WAF, API gateway or reverse proxy so that wallets reach the protocol
endpoints from anywhere while the management API stays closed to the internet.
EUDIPLO has no built-in rate limiting or IP filtering, so this layer does both.
TLS termination and general proxy settings are on [TLS and reverse proxy](tls.md).
### Two surfaces on one host
| Surface | Paths | Callers | Network access |
| ------------------ | --------------- | ------------------------------------------------------------------------------------------------------------ | ----------------- |
| Management API | `/api/*` | Your backends, the web client in operators' browsers, the CLI, your configuration pipeline | Known networks |
| Protocol endpoints | All other paths | Wallets, users' browsers, your pages that use the DC API, relying parties that read status and trust lists | Internet |
Match the `/api/` prefix case-insensitively: the backend routes `/API/session`
like `/api/session`, so a case-sensitive rule can be bypassed. If your WAF
supports an allow list of paths, allow `/api/`, `/.well-known/`, `/issuers/`,
`/presentations/`, `/verifiers/`, `/storage/`, `/health`, `/docs` and `/`, and
block the rest.
Check the list against the [path prefixes](../reference/api.md#path-prefixes)
after each upgrade.
### Management API
Allow `/api/*` only from the addresses of your backends and operators, for
example with an IP allow list, a VPN or an identity-aware proxy. Except for the
token endpoint and the Swagger UI (`/api/docs`, `/api/docs-json`), every call
also needs a bearer token, so the network rule is a second layer.
The web client sends its token requests to the token endpoint of the
discovery document, `PUBLIC_URL/api/oauth2/token` (with `OIDC` set, the
provider's), even when operators enter another backend address on its login
page. Allow `OPTIONS` (CORS preflight) and `POST` on `/api/oauth2/token` from
operators' browsers on the `PUBLIC_URL` host too
([web client addresses](docker-compose.md#web-client-addresses)).
| Setting | Value |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Methods | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, and `OPTIONS` for the CORS preflight of the web client |
| Content types | `application/json`; `multipart/form-data` for `POST /api/storage`, `/api/config-bundles/plan/archive` and `/api/config-bundles/import/archive`; `application/x-www-form-urlencoded` for `POST /api/oauth2/token` |
| Body size | 50 MB for the two archive routes, 10 MB for JSON |
| Streaming | `GET /api/session/{id}/events` is a server-sent event stream: no buffering, long read timeout ([TLS and reverse proxy](tls.md#behind-a-reverse-proxy)) |
| Rate limits | `POST /api/oauth2/token`, against guessing client secrets |
Management request bodies contain values that injection signatures mistake for
attacks: PEM keys and certificates (`-----BEGIN …`) in key chain imports,
`${VAR}` placeholders, JSON Schemas with regular expressions, DCQL queries, and
the URLs of webhooks, attribute providers and trust lists. Once `/api/*` is
limited to known networks, exclude the rules that fire there (see
[rules that break EUDIPLO](#rules-that-break-eudiplo)) instead of loosening them
for the whole host.
These routes outside `/api` serve operations rather than wallets:
| Route | Caller | Rule |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `POST /issuers/{tenant}/authorize/interactive/complete-web-auth/{authSession}` | Your backend, with a management token ([interactive authorization](../issuance/interactive-authorization.md#3-run-the-steps)) | Allow from your backends, like `/api/*` |
| `GET /.well-known/oauth-authorization-server`, `GET /.well-known/jwks.json` | Web client, CLI and OAuth libraries, to find the token endpoint | Keep open |
| `GET /.well-known/openid-credential-issuer/issuers/{tenant}` | Web client, for **Import from Credential Config** and the type and claim suggestions on a verification config | Keep open |
| `GET /health` | Load balancer, orchestrator, `eudiplo doctor` | May be limited to internal networks |
| `GET /docs`, `GET /docs-json` | People reading the protocol API | Optional; nothing depends on it |
### Protocol endpoints
Wallets call these from phones on mobile networks, so:
- Do not filter by IP address or country beyond what your use case allows.
- Do not use browser challenges such as JavaScript challenges, CAPTCHAs or bot
management interstitials. Wallets are HTTP clients; they cannot solve them,
and the request fails.
- Set per-IP rate limits high enough for many users behind one address; mobile
networks share addresses through carrier-grade NAT.
- Forward the path unchanged. DPoP proofs sign the method and URL, and the
backend compares them with `PUBLIC_URL` plus the request path, so rewriting,
case normalization or an added trailing slash breaks token and credential
requests.
| Route | Methods | Request body | Called by |
| ---------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------ | ----------------------------- |
| `/.well-known/openid-credential-issuer/issuers/{tenant}`, `/.well-known/oauth-authorization-server/issuers/…`, `/.well-known/jwks.json/issuers/…` | GET | – | Wallets; the web client reads the issuer metadata too |
| `/issuers/{tenant}/vci/credential-offers/{offerId}` | GET | – | Wallets |
| `/issuers/{tenant}/vci/nonce` | POST | Empty | Wallets |
| `/issuers/{tenant}/vci/credential` | POST | JSON, or `application/jwt` when the wallet encrypts the request | Wallets |
| `/issuers/{tenant}/vci/deferred_credential` | POST | JSON, or `application/jwt` when the wallet encrypts the request | Wallets |
| `/issuers/{tenant}/vci/notification` | POST | JSON | Wallets |
| `/issuers/{tenant}/authorize/par`, `…/token`, `…/challenge`, and `par`, `token` under `chained-as/` and `authorization-servers/{id}/` | POST | Form; `challenge` has no body | Wallets |
| `/issuers/{tenant}/authorize/interactive` | POST | Form or JSON | Wallets |
| `/issuers/{tenant}/authorize`, `/issuers/{tenant}/chained-as/authorize`, `/issuers/{tenant}/authorization-servers/{id}/authorize` | GET | – | User's browser, opened by the wallet |
| `/issuers/{tenant}/chained-as/callback`, `/issuers/{tenant}/authorization-servers/{id}/vp-callback` | GET | – | User's browser, redirected back by the upstream provider or wallet |
| `/issuers/{tenant}/credentials-metadata/vct/{id}` | GET | – | Wallets, verifiers |
| `/issuers/{tenant}/status-management/status-list/{id}`, `/issuers/{tenant}/status-management/status-list-aggregation` | GET | – | Wallets, verifiers |
| `/issuers/{tenant}/trust-list/{id}` | GET | – | Verifiers, wallets |
| `/issuers/{tenant}/.well-known/openid-federation` | GET | – | Federation verifiers, wallets, trust anchors |
| `/presentations/{walletNonce}/oid4vp/request`, `/presentations/{walletNonce}/oid4vp/request/no-redirect` | GET, POST | POST: form (`wallet_metadata`, `wallet_nonce`) | Wallets |
| `/presentations/{walletNonce}/oid4vp` | POST | Form (`response` or `vp_token`) from wallets; JSON from your page (DC API) | Wallets, your page |
| `/presentations/{walletNonce}/iso-18013-7` | POST | JSON (`data`) | Your page (DC API) |
| `/verifiers/{tenant}/oidc/.well-known/openid-configuration`, `/verifiers/{tenant}/oidc/jwks` | GET | – | Relying parties |
| `/verifiers/{tenant}/oidc/par`, `/verifiers/{tenant}/oidc/token` | POST | Form | Relying parties' backends |
| `/verifiers/{tenant}/oidc/authorize` | GET, POST | POST: form | User's browser |
| `/verifiers/{tenant}/oidc/sign-in/{id}`, `…/status`, `…/complete`, `…/callback` | GET | – | User's browser, redirected back by the wallet |
| `/storage/{key}` | GET | – | Wallets (logos, images) |
| Setting | Value |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Methods | `GET`, `POST`, and `OPTIONS` for the CORS preflight of pages that use the DC API |
| Content types | `application/x-www-form-urlencoded`, `application/json`, `application/jwt` |
| Body size | At least 100 KB. The backend accepts form bodies up to 100 KB and JSON bodies up to 10 MB. Presentations with several credentials and credential requests with several proofs or key attestations can exceed 8 KB. |
| Headers | `DPoP`, `OAuth-Client-Attestation`, `OAuth-Client-Attestation-PoP` and `Authorization: DPoP …` carry JWTs, several KB long with certificate chains (`x5c`). Keep header size limits at their defaults or above. |
| Rate limits | Token, PAR, nonce and credential endpoints |
### Rules that break EUDIPLO
Wallet messages are base64url-encoded: JWTs, encrypted responses (JWE), SD-JWT
presentations with `~`-separated disclosures, and mdoc responses. Base64url
uses `-` and `_` as regular characters, and signatures, keys and ciphertext are
random, so a token of a few kilobytes often contains `--`. Rules that look for
SQL comments (`--`) or count special characters therefore block requests at
random: the same wallet succeeds once and gets a `403` on the next attempt.
Several wallet requests also carry JSON inside a form field, which SQL
injection rules read as an attack.
OWASP CRS 4.30 with its default anomaly threshold blocked these requests
without exclusions:
| Request | Paranoia level 1 (default) | Added at paranoia level 2 |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------ |
| Encrypted credential or deferred credential request (`Content-Type: application/jwt`) | 920420, every request | – |
| Encrypted presentation response (JWE), from the wallet or your DC API page | – | 942440 (`--`) in more than half of the requests; 942430 |
| JSON in a form field: `vp_token`, `wallet_metadata`, `authorization_details`, `openid4vp_response` | – | 942200, 942340, 942370, 942430 |
| ISO 18013-7 response | 942100, rarely (1 of 400) | 942430 |
| URLs of other hosts: `redirect_uri` in PAR and token requests, `iss` in the upstream callback | – | 931130 |
| `PUT`, `PATCH`, `DELETE` on `/api` | 911100 | – |
| Presentation configuration with a DCQL query (the field name `dcql_query.credentials`) | 930120 | – |
| Configuration with `${VAR}` placeholders | 932130, 933135 | – |
| Key chain import with PEM blocks | – | 942120, 942440 |
| Credential configuration with JSON Schema patterns and URLs | – | 931130, 932240, 942430 |
CRS skips values that look like a signed JWT (`eyJ….eyJ….`), so credential
requests with JSON proofs passed. At paranoia level 3, PEM line breaks also
trigger 920272. The managed rule sets of Azure WAF and the Cloudflare OWASP
ruleset are derived from CRS, so expect similar matches there. With the AWS Core rule
set, `SizeRestrictions_BODY` blocks bodies over 8 KB: presentation responses,
credential requests with key attestations and configuration imports.
Whatever the product, run new rules in detection mode first (CRS:
`SecRuleEngine DetectionOnly`, AWS: *Count*), go through issuance and
presentation with your wallets several times, and add exclusions by rule and
path from the WAF log.
#### OWASP CRS (ModSecurity, Coraza)
Add these rules to `REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf`. Adjust the
IDs if they collide with your own rules. With them, all requests of the table
passed CRS 4.30 at paranoia levels 1 to 3, except the `/verifiers/` routes of
the OpenID Provider, which were added later and have not been run against CRS;
their `redirect_uri` parameters trigger 931130 like those of PAR and token
requests, so the rule below covers them too.
```apache
# Management API: allow its methods and skip the injection rules that
# configuration bodies trigger. Restrict /api/ to known networks first.
SecRule REQUEST_FILENAME "@beginsWith /api/" \
"id:10010,phase:1,pass,nolog,t:none,t:lowercase,\
setvar:'tx.allowed_methods=GET HEAD POST PUT PATCH DELETE OPTIONS',\
ctl:ruleRemoveByTag=attack-sqli,\
ctl:ruleRemoveByTag=attack-rce,\
ctl:ruleRemoveByTag=attack-injection-php,\
ctl:ruleRemoveByTag=attack-lfi,\
ctl:ruleRemoveByTag=attack-rfi,\
ctl:ruleRemoveById=920272"
# Encrypted credential and deferred credential requests are sent as application/jwt.
SecRule REQUEST_FILENAME "@rx ^/issuers/[^/]+/vci/(?:credential|deferred_credential)$" \
"id:10020,phase:1,pass,nolog,t:none,\
setvar:'tx.allowed_request_content_type=|application/json| |application/jwt|'"
# Wallet-facing endpoints: base64url tokens, JSON in form fields, redirect URIs.
SecRule REQUEST_FILENAME "@rx ^/(?:issuers|presentations|verifiers)/" \
"id:10030,phase:1,pass,nolog,t:none,\
ctl:ruleRemoveByTag=attack-sqli,\
ctl:ruleRemoveById=931130"
```
On the wallet-facing paths only the SQL injection group and 931130 are removed:
every value there is a token or identifier that the backend verifies, and its
database queries are parameterized. The XSS, command injection, file access and
protocol enforcement rules stay active. On `/api/` the XSS and protocol
enforcement rules stay active; the network restriction and the bearer token
protect the rest.
#### AWS WAF
With `AWSManagedRulesCommonRuleSet`:
1. Override `SizeRestrictions_BODY` to *Count*. The rule then only adds the
label `awswaf:managed:aws:core-rule-set:SizeRestrictions_Body`.
2. Add a rule after the rule group that blocks requests with this label unless
the URI path starts with `/issuers/`, `/presentations/` or `/api/`.
AWS WAF inspects only the first 8 KB of a body behind an Application Load
Balancer (16 KB, configurable up to 64 KB, on CloudFront and API Gateway); the
signature rules continue with the inspected part of larger bodies.
### Check the configuration
From outside your known networks, the management API must be blocked in any
spelling, and the metadata must be reachable:
```bash
curl -s -o /dev/null -w '%{http_code}\n' https://eudiplo.example.com/api/docs
curl -s -o /dev/null -w '%{http_code}\n' https://eudiplo.example.com/API/docs
curl -s -o /dev/null -w '%{http_code}\n' https://eudiplo.example.com/.well-known/openid-credential-issuer/issuers/
```
The first two must not return `200`; the third must. Use a tenant that issues: one without Issuer Settings answers `404`. Then issue and present a
credential several times with each wallet you support, through every flow you
offer (QR code, same device, DC API), and look for blocked requests in the WAF
log. Because the token false positives are random, one successful run is not
enough. The [load tests](load-testing.md) run many token requests,
issuances and presentations against a deployment, which also exercises the WAF.
Run [`eudiplo doctor`](cli.md#check-an-instance-with-doctor) from a network
that may reach `/api/*` and `/health`.
---
## API Reference
## API reference
Every EUDIPLO instance serves its own OpenAPI specification, so the reference always matches the running version. Your backend calls the management API under `/api`; wallets call the protocol endpoints at the root path.
### Specifications
| API | Swagger UI | OpenAPI JSON | Contents |
| -------------- | ----------- | ---------------- | ---------------------------------------------------------------------------------------------- |
| Management API | `/api/docs` | `/api/docs-json` | Everything under `/api`: tenants, clients, configurations, key chains, offers, sessions, lists |
| Protocol API | `/docs` | `/docs-json` | Wallet-facing OID4VCI, OID4VP and ISO 18013-7 endpoints, metadata, status and trust lists |
Both are OpenAPI 3.1 documents. In Swagger UI, choose **Authorize** to call the management API with a client's credentials.
### Path prefixes
Management endpoints carry the `/api` prefix, for example `POST /api/issuer/offer`. Wallet-facing and public endpoints are served without it:
| Path | Purpose |
| --------------------------------------------------- | -------------------------------------------------------------------- |
| `/.well-known/...` | Issuer and authorization server metadata, JWKS |
| `/issuers/{tenant}/vci/...` | Credential offer, credential, deferred, notification and nonce endpoints |
| `/issuers/{tenant}/authorize/...` | Built-in authorization server (PAR, authorize, token, interactive) |
| `/issuers/{tenant}/chained-as/...` | Chained authorization server |
| `/issuers/{tenant}/authorization-servers/{id}/...` | OID4VP-based authorization servers |
| `/issuers/{tenant}/credentials-metadata/...` | SD-JWT VC type metadata |
| `/issuers/{tenant}/status-management/...` | Status lists |
| `/issuers/{tenant}/trust-list/...` | Published trust lists |
| `/issuers/{tenant}/.well-known/openid-federation` | [OpenID Federation entity configuration](../trust/federation.md#publish-your-entity-configuration) |
| `/presentations/{walletNonce}/oid4vp/...` | OID4VP request object and response endpoint |
| `/presentations/{walletNonce}/iso-18013-7` | ISO 18013-7 Annex C response endpoint |
| `/verifiers/{tenant}/oidc/...` | [OpenID Provider](../presentation/openid-connect.md): discovery, JWKS, PAR, authorize, sign-in page, token |
| `/storage/{key}` | Public files such as credential logos |
| `/health` | Health check |
When you restrict network access to the management API, keep the wallet-facing paths reachable from the internet; see [Web application firewall](../operate/waf.md).
### Authentication
Management endpoints require a bearer token of an API client. Which client holds which roles is described in [Tenants and access](../operate/tenants-and-access.md).
With the built-in OAuth 2.0 server (the default), request a token with the client credentials grant:
```bash
curl -X POST https://eudiplo.example.com/api/oauth2/token \
-d grant_type=client_credentials \
-d client_id=membership-backend \
-d client_secret="$CLIENT_SECRET"
```
The endpoint accepts the credentials in the form or JSON body or as HTTP Basic authentication. The response contains an `access_token` that is valid for 24 hours (`expires_in: 86400`) and no refresh token; send it as `Authorization: Bearer `, and request a new one when it expires. `GET /.well-known/oauth-authorization-server` advertises the token endpoint for OAuth client libraries.
When `OIDC` is set, for example to use [Keycloak](../operate/keycloak.md), `/api/oauth2/token` is disabled and tokens come from the external provider.
This includes the session event stream `GET /api/session/{id}/events`, which does not accept tokens in the URL. Browsers cannot set headers on an `EventSource`, so read the stream from your backend.
`GET /api/auth/me` needs no role and returns the subject, tenant and roles the backend grants for the token: with the built-in server the client's current roles, with an external provider those of the token's claims. Use it to check which tenant and roles a token resolves to.
### `@eudiplo/sdk-core`
`@eudiplo/sdk-core` is the TypeScript client for the management API. It works in Node.js 20+ and in browsers.
```bash
npm install @eudiplo/sdk-core
```
`EudiploClient` covers the common flows. It fetches and renews the token from `/api/oauth2/token` itself:
```typescript
import { EudiploClient } from "@eudiplo/sdk-core";
const eudiplo = new EudiploClient({
baseUrl: "https://eudiplo.example.com",
clientId: process.env.EUDIPLO_CLIENT_ID!,
clientSecret: process.env.EUDIPLO_CLIENT_SECRET!,
});
const { crossDeviceUri, sessionId } = await eudiplo.createPresentationRequest({
configId: "membership-check",
});
// Show `crossDeviceUri` as a QR code (on the phone itself, open `uri`),
// then wait for a terminal status.
const session = await eudiplo.waitForSession(sessionId);
```
| Method | Purpose |
| --------------------------------------------------------------- | ------------------------------------------------------------- |
| `createIssuanceOffer()` | `POST /api/issuer/offer` with inline claims |
| `createPresentationRequest()` | `POST /api/verifier/offer` |
| `getSession()`, `waitForSession()` | Read or poll a session until it is `completed`, `failed` or `expired` |
| `subscribeToSession()`, `waitForSessionWithSse()` | Follow a session over Server-Sent Events |
| `createDcApiPresentationRequest()`, `submitDcApiPresentation()`, `verifyWithDcApi()` | Digital Credentials API flow in the browser |
Keep `clientId` and `clientSecret` on your server. Browser code should talk to your backend, which calls EUDIPLO.
For every other endpoint, use the generated functions from `@eudiplo/sdk-core/api`. They are generated from the management OpenAPI specification and named after the controller method, for example `sessionControllerGetSession` or `webhookEndpointControllerCreate`:
```typescript
import { client, sessionControllerGetSession } from "@eudiplo/sdk-core/api";
client.setConfig({
baseUrl: "https://eudiplo.example.com",
headers: { Authorization: `Bearer ${accessToken}` },
});
const { data: session } = await sessionControllerGetSession({
path: { id: sessionId },
});
```
`EudiploClient` authenticates only against the built-in OAuth 2.0 server. With an external OIDC provider, obtain the token yourself and use the generated functions as shown above.
### Related pages
- [Webhooks](webhooks.md): payloads EUDIPLO sends to your backend
- [Attribute provider API](attribute-provider-api.md): the contract for claim sources
- [Environment variables](environment-variables.md)
---
## Attribute provider API
The HTTP contract EUDIPLO uses to fetch claims from your backend during issuance. It applies to attribute providers and to `webhook` claim sources of an offer. For setup, see [Attribute providers](../issuance/attribute-provider.md); for when a provider is called, see [Claims](../issuance/claims.md). An example provider is in [EUDIPLO/examples](https://github.com/EUDIPLO/examples/tree/main/webhook).
### Resource
Attribute providers are tenant resources managed with the `issuance:manage` role:
| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/api/issuer/attribute-providers` | List providers |
| `GET` | `/api/issuer/attribute-providers/{id}` | Get one provider |
| `POST` | `/api/issuer/attribute-providers` | Create a provider |
| `PATCH` | `/api/issuer/attribute-providers/{id}` | Update fields of a provider |
| `DELETE` | `/api/issuer/attribute-providers/{id}` | Delete a provider no credential config uses ([Delete an attribute provider](../issuance/attribute-provider.md#delete-an-attribute-provider)) |
An offer `webhook` source has the shape `{ "url", "auth", "includeRawTokensFor"? }` with the same `auth` options; see [Webhooks](webhooks.md).
### Request
EUDIPLO sends `POST ` with `Content-Type: application/json` and, for `apiKey` authentication, the configured header. It calls the provider when the wallet requests the credential, once per credential request.
```json
{
"session": "a6318799-dff4-4b60-9d1d-58703611bd23",
"reference": "order-4711",
"credential_configuration_id": "membership",
"identity": {
"iss": "https://keycloak.example.com/realms/eudiplo",
"sub": "f3b1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"token_claims": {
"email": "max@example.com",
"preferred_username": "max"
}
},
"credentials": [
{
"id": "pid",
"values": [
{ "given_name": "Max", "family_name": "Mustermann", "birthdate": "1990-01-15" }
]
}
]
}
```
| Field | Present | Description |
| --- | --- | --- |
| `session` | always | Issuance session ID. It equals the `session` returned when the offer was created. |
| `reference` | when set | Your [reference](../issuance/credential-offers.md#your-own-reference) of the offer. |
| `credential_configuration_id` | always | Credential configuration the wallet requested. |
| `identity` | always | `iss`, `sub` and `token_claims` of the authorization behind the wallet's access token. What they contain per flow is listed in [Claims](../issuance/claims.md#identity-passed-to-attribute-providers). |
| `credentials` | after a presentation | Verified claims the wallet presented to an [OID4VP authorization server](../issuance/authorization-servers.md#oid4vp) or in an [interactive authorization](../issuance/interactive-authorization.md) presentation step. One entry per credential query ID of the presentation's DCQL query; `values` holds the disclosed claims of each matching credential (several with `multiple: true`). |
### Response
#### Claims
Answer `200` with the claims under the requested credential configuration ID:
```json
{
"membership": {
"name": "Max",
"member_id": "M-001"
}
}
```
The claims replace the static defaults of the configuration completely and are validated against its `fields` before signing; see [Claims](../issuance/claims.md#validation).
#### Deferred
To issue later, answer `200` with:
```json
{ "deferred": true, "interval": 5 }
```
| Field | Description |
| --- | --- |
| `deferred` | `true` defers the credential. |
| `interval` | Polling interval in seconds suggested to the wallet. Default `5`. |
EUDIPLO answers the wallet with a `transaction_id`. Completing or failing the transaction is described in [Deferred issuance](../issuance/deferred-issuance.md).
### Errors
- Any final non-`2xx` status (after redirects) or network error fails the credential request. The wallet receives HTTP `400` with `invalid_credential_request`; claims that do not match the configuration lead to `credential_request_denied`.
- A `200` answer without a claims object under the requested credential configuration ID, and without `deferred: true`, fails the credential request with `credential_request_denied`. EUDIPLO does not fall back to the static defaults.
- EUDIPLO does not retry. The wallet's credential request waits for your answer, so answer quickly or defer; a request ends after 60 seconds or an answer above 5 MiB ([delivery limits](webhooks.md#delivery)).
- The provider URL must pass the outbound URL policy: HTTPS and public addresses only, unless `OUTBOUND_URL_ALLOW_HTTP` or `OUTBOUND_URL_ALLOW_PRIVATE_NETWORK` is set (both `false` by default since 9.0). See [Webhooks](webhooks.md).
---
## CLI Reference
Every command and option of the `eudiplo` CLI, generated from the CLI's own
command definitions. Installation, instances, drivers, environment variables and
`doctor` are explained in the [CLI guide](../operate/cli.md). Offline, run
`eudiplo commands` for a compact list or `eudiplo --help` for one
command.
### eudiplo
```text
Usage: eudiplo [options] [command]
Deployment-aware command line tools for EUDIPLO
Options:
-v, --version Print the installed CLI version
-h, --help display help for command
Commands:
demo [options] [directory] Start the minimal local demo
init [options] [directory] Configure a local deployment
up [options] [args...] Start the selected Compose deployment
down [options] [args...] Stop the selected Compose deployment
logs [options] [args...] Print the logs of the selected deployment, or
stream them with --follow
ps [options] [args...] List the running containers or pods for the
selected deployment
restart [options] [args...] Restart the workloads of the selected deployment
pull [options] [args...] Download the configured images without changing
configuration
upgrade [options] Upgrade the EUDIPLO application images of a
Compose deployment
open [options] Open the web client of the selected instance in a
browser
instance Manage configured EUDIPLO instances
config Validate and manage local configuration
doctor [options] Run deployment diagnostics
status [options] Print the selected instance status
version Print the installed version and check for updates
completion Generate shell completion scripts
commands [options] List every available CLI command
help [command] display help for command
```
### `eudiplo demo`
Start the minimal local demo
```text
Usage: eudiplo demo [options] [directory]
Start the minimal local demo
Arguments:
directory project directory
Options:
--directory set the project directory
--reset recreate managed demo data and configuration
--force allow replacement of managed demo files
--yes accept the default directory without prompting
--no-interactive disable the directory prompt
--image-tag override the backend and client image tag
-h, --help display help for command
```
### `eudiplo init`
Configure a local deployment
```text
Usage: eudiplo init [options] [directory]
Configure a local deployment
Arguments:
directory project directory
Options:
--directory set the project directory
--target deployment target
--instance instance name (default: "local")
--preset deployment preset
--database database
--storage storage
--kms key management
--public-url public EUDIPLO URL
--auth-client-id authentication client ID
--auth-client-secret authentication client secret
--demo-tenant include the bundled demo tenant
--no-demo-tenant do not include the bundled demo tenant
--client include the web client
--no-client omit the web client
--no-interactive disable the setup wizard
--start start the deployment after initialization
--yes accept defaults without opening the wizard
--image-tag override the backend and client image tag
--demo generate demo-compatible assets without
starting them
--force replace CLI-managed files
--url override the instance API URL
-h, --help display help for command
```
### `eudiplo up`
Start the selected Compose deployment
```text
Usage: eudiplo up [options] [args...]
Start the selected Compose deployment
Arguments:
args additional arguments and options passed to the deployment
runtime
Options:
--instance select a configured instance
-h, --help display help for command
```
### `eudiplo down`
Stop the selected Compose deployment
```text
Usage: eudiplo down [options] [args...]
Stop the selected Compose deployment
Arguments:
args additional arguments and options passed to the deployment
runtime
Options:
--instance select a configured instance
-h, --help display help for command
```
### `eudiplo logs`
Print the logs of the selected deployment, or stream them with --follow
```text
Usage: eudiplo logs [options] [args...]
Print the logs of the selected deployment, or stream them with --follow
Arguments:
args additional arguments and options passed to the deployment
runtime
Options:
--instance select a configured instance
--service select a single service (Compose) or configured workload
(Kubernetes)
--follow stream new output as it arrives
--tail number of recent lines to show
--since