Skip to main content

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. The Manage an instance with the CLI 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:

WayUse it forOwnership after the write
Startup importTenant folders in CONFIG_FOLDER, GitOpsfile-managed
Bundle import (API/CLI)Promoting a tenant between instancesfile-managed
Management API, web clientAd-hoc changesunmanaged

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:

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:

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 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:

{
"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:

CONFIG_FOLDER=/app/config
CONFIG_IMPORT_MODE=create
CONFIG_IMPORT_MODEOn every start
disabled (default)Nothing is imported
createCreates missing resources, leaves existing ones untouched
upsertCreates missing and updates existing resources
replaceLike 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.

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).

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:

[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:

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:

.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), then:

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).

To keep a tenant in Git as a tenant folder instead of a bundle, see Keep a tenant in Git.

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 <id>.json, ready for the config folder. The API is GET /api/config-bundles/resources/<kind>/<id>/document (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).

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).

Plan and import​

Always review the server-side plan, then import exactly that plan:

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). 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.

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), deleting a federation trust anchor whose entity ID such a configuration still names (FEDERATION_TRUST_ANCHOR_IN_USE, see Delete a trust anchor), or deleting a key chain that such a configuration names (KEY_CHAIN_IN_USE, see 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:

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). A startup import cannot return the secret; see 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:

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:

eudiplo config operations --instance staging # latest 50 operations
eudiplo config operations <operation-id> --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:

eudiplo config recover <operation-id> --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.