Environment Variables
All environment variables of the EUDIPLO backend, generated from its validation
schema. The backend refuses to start when a value is invalid or a required
variable is missing. KMS providers are configured in JSON files instead
(KMS config); the variables of the eudiplo CLI are listed in the
CLI guide.
Authentication
| Key | Type | Allowed values | Notes |
|---|---|---|---|
OIDC | string | - | Issuer URL of the identity provider, exactly as its discovery document names it, for example https://keycloak.example.com/realms/eudiplo or https://auth.example.com/application/o/eudiplo/. Setting it switches the management API to OIDC mode; OIDC_PROVIDER selects the provider [optional] |
OIDC_PROVIDER | string | keycloak, generic | Identity provider in OIDC mode. Refused without OIDC. keycloak manages clients and people through the Keycloak admin API. generic accepts access tokens of any OpenID Connect provider and leaves clients and people to that provider: the client and user endpoints answer 501 [optional] [default keycloak when OIDC is set] |
OIDC_AUDIENCE | string | - | Value the aud claim of access tokens must contain. Required with OIDC_PROVIDER=generic, so that tokens the provider issues for other applications are refused; use an audience that only EUDIPLO's access tokens carry, such as an API identifier, not a client ID that ID tokens carry too. With Keycloak it is checked only when set; Keycloak access tokens carry aud: account unless an audience mapper adds this value, also for the clients EUDIPLO creates. With both providers, and whether it is set or not, tokens that carry at_hash, c_hash or s_hash, which only ID tokens carry, and tokens whose JWS header names another typ than at+jwt or JWT (also with the application/ prefix, in any case; a token without typ passes) are refused; with Keycloak also tokens whose typ claim is present and not Bearer, such as its ID tokens (ID) and access tokens bound to a DPoP key (DPoP), whose proof is not checked. Tokens without exp are refused with both providers. Without OIDC_AUDIENCE, Keycloak access tokens are accepted only when their azp (or, without it, client_id) is OIDC_UI_CLIENT_ID, AUTH_CLIENT_ID (when AUTH_CLIENT_SECRET is set too) or a client EUDIPLO manages, so that tokens of other clients in the realm are refused; with it, the audience alone decides, so every client whose tokens carry it is accepted [required when OIDC_PROVIDER is generic] |
OIDC_ROLES_CLAIM | string | - | Claim with the EUDIPLO roles in OIDC mode: a claim name, or a dot path into nested claims such as resource_access.eudiplo.roles. A claim with exactly this name wins over a path, so namespaced names such as https://eudiplo.example.com/roles work. The claim holds an array of role names or an object whose keys are role names (Zitadel; the organizations in its values are ignored, so grant the roles only in the organization that maps to the tenant). Without it, the roles come from roles or realm_access.roles. With Keycloak, the clients EUDIPLO creates carry only these two claims [optional] |
OIDC_JWKS_URI | string | - | URL of the signing keys with OIDC_PROVIDER=generic, instead of jwks_uri of the discovery document, for example when the backend reaches the provider under another host name. Setting it skips the startup check that the key set is HTTPS or at the origin of the discovery document, so use HTTPS, or plain HTTP only inside a private network [optional] |
OIDC_INTERNAL_ISSUER_URL | string | - | With Keycloak, the issuer that access tokens must carry and the base URL of the realm's signing keys. With OIDC_PROVIDER=generic, the URL from which the backend loads the discovery document when it reaches the provider under another address than OIDC, for example http://authentik:9000/application/o/eudiplo/ in Docker Compose; tokens must carry OIDC [optional] [default the value of OIDC when OIDC is set] |
OIDC_CLIENT_ID | string | - | Client ID with which EUDIPLO uses the Keycloak admin API. Required with OIDC_PROVIDER=keycloak, unused with generic [required when OIDC_PROVIDER is keycloak] |
OIDC_CLIENT_SECRET | string | - | Client secret of OIDC_CLIENT_ID. Required with OIDC_PROVIDER=keycloak, unused with generic [required when OIDC_PROVIDER is keycloak] |
OIDC_SUB | string | - | Claim with the tenant ID of access tokens in OIDC mode [optional] [default tenant_id when OIDC is set] |
OIDC_ALGORITHM | string | - | Expected JWT alg [optional] [default RS256 when OIDC is set] |
MASTER_SECRET | string | - | Master secret for JWT signing and encryption key derivation - required, minimum 32 characters [required unless OIDC is set] |
JWT_ISSUER | string | - | Local JWT issuer [optional] [default eudiplo-service unless OIDC is set] |
AUTH_CLIENT_SECRET | string | - | Client secret (local auth). With OIDC_PROVIDER=keycloak, optional bootstrap secret used to create/update a Keycloak admin/root client when AUTH_CLIENT_ID is also set; unused with generic [required unless OIDC is set] |
AUTH_CLIENT_ID | string | - | Client ID (local auth). With OIDC_PROVIDER=keycloak, optional bootstrap client ID used to create/update a Keycloak admin/root client when AUTH_CLIENT_SECRET is also set; unused with generic [required unless OIDC is set] |
OIDC_UI_CLIENT_ID | string | - | Public client ID for the Angular UI in OIDC mode, for Authorization Code + PKCE login. With OIDC_PROVIDER=keycloak (default eudiplo-ui) EUDIPLO registers it in Keycloak. With generic it has no default: the Web Client's login page offers SSO only when it is set. Create it at the provider as a public client with <web client URL>/login and <web client URL>/silent-check-sso.html as redirect URIs and the Web Client's URL as post-logout redirect URI. [optional] [default eudiplo-ui when OIDC_PROVIDER is keycloak] |
OIDC_UI_URL | string | - | Comma-separated URLs the web client is served from with OIDC_PROVIDER=keycloak, e.g. https://console.example.com. EUDIPLO sets the redirect URIs of the UI client (OIDC_UI_CLIENT_ID) to the pages under these URLs and its web origins to their origins. If unset, the redirect URIs set in Keycloak stay, except *, and a web origin * or an empty list of web origins becomes + (the origins of the redirect URIs); without any redirect URI, nobody can sign in to the web client with SSO. Unused with generic [optional] |
Configuration
| Key | Type | Allowed values | Notes |
|---|---|---|---|
CONFIG_IMPORT_MODE | string | disabled, create, upsert, replace | Startup configuration reconciliation mode. [optional] (default: disabled) |
CONFIG_FOLDER | string | - | Path to config import folder [optional] (default: assets/config of the repository; the container image sets /app/config/config) |
CONFIG_VARIABLE_STRICT | alternatives | - | Strict mode for config import. [optional] (default: skip) |
Cryptography
| Key | Type | Allowed values | Notes |
|---|---|---|---|
CRYPTO_TOLERANCE | number | - | Clock tolerance in seconds for JWT verification [optional] (default: 5) |
Database
| Key | Type | Allowed values | Notes |
|---|---|---|---|
DB_TYPE | string | sqlite, postgres | Database type [optional] (default: sqlite) |
DB_HOST | string | - | Database host [required unless DB_TYPE is sqlite] |
DB_PORT | number | - | Database port [required unless DB_TYPE is sqlite] |
DB_USERNAME | string | - | Database username [required unless DB_TYPE is sqlite] |
DB_PASSWORD | string | - | Database password [required unless DB_TYPE is sqlite] |
DB_DATABASE | string | - | Database name [required unless DB_TYPE is sqlite] |
DB_SSL | boolean | - | Enable SSL/TLS for PostgreSQL database connections [optional] (default: false) |
DB_SSL_REJECT_UNAUTHORIZED | boolean | - | Reject PostgreSQL TLS certificates that cannot be validated against trusted CAs [optional] (default: true) |
DB_SSL_CA_PATH | string | - | Path to CA certificate file used to validate PostgreSQL TLS certificates [optional] |
DB_SSL_CERT_PATH | string | - | Path to client certificate file for PostgreSQL TLS [optional] |
DB_SSL_KEY_PATH | string | - | Path to client private key file for PostgreSQL TLS [optional] |
DB_SSL_KEY_PASSPHRASE | string | - | Passphrase for encrypted DB_SSL_KEY_PATH private key [optional] |
DB_SYNCHRONIZE | boolean | - | Enable TypeORM schema synchronization. Intended for development only; fresh installations are created by migrations. [optional] (default: false) |
DB_MIGRATIONS_RUN | boolean | - | Run pending database migrations automatically on startup [optional] (default: true) |
Encryption
| Key | Type | Allowed values | Notes |
|---|---|---|---|
ENCRYPTION_KEY_SOURCE | string | env, vault, aws, azure | Source for the data-at-rest encryption key: env (default, derived from MASTER_SECRET), or optionally vault/aws/azure (key held only in memory) [optional] (default: env) |
VAULT_ADDR | string | - | URL of the HashiCorp Vault server, e.g. http://vault:8200. Required when ENCRYPTION_KEY_SOURCE=vault [optional] |
VAULT_TOKEN | string | - | Token for the HashiCorp Vault server. Required when ENCRYPTION_KEY_SOURCE=vault [optional] 🔒 |
VAULT_ENCRYPTION_KEY_PATH | string | - | Path to encryption key in Vault KV secrets engine [optional] [default secret/data/eudiplo/encryption-key when ENCRYPTION_KEY_SOURCE is vault] |
AWS_REGION | string | - | AWS region, e.g. eu-central-1. Required when ENCRYPTION_KEY_SOURCE=aws [optional] |
AWS_ENCRYPTION_SECRET_NAME | string | - | Name of the encryption key secret in AWS Secrets Manager [required when ENCRYPTION_KEY_SOURCE is aws] |
AWS_ENCRYPTION_SECRET_KEY | string | - | JSON key within the AWS secret (if secret is JSON) [optional] [default key when ENCRYPTION_KEY_SOURCE is aws] |
AZURE_KEYVAULT_URL | string | - | Azure Key Vault URL (e.g., https://myvault.vault.azure.net) [required when ENCRYPTION_KEY_SOURCE is azure] |
AZURE_ENCRYPTION_SECRET_NAME | string | - | Name of the encryption key secret in Azure Key Vault [required when ENCRYPTION_KEY_SOURCE is azure] |
Federation
See OpenID Federation.
| Key | Type | Allowed values | Notes |
|---|---|---|---|
FEDERATION_RESOLVER | string | local, http | How OpenID Federation trust chains are resolved. local: EUDIPLO fetches and validates the entity configurations and subordinate statements itself. http: resolution is delegated to an external trust engine at FEDERATION_RESOLVER_URL. [optional] (default: local) |
FEDERATION_RESOLVER_URL | string | - | HTTPS base URL of the trust engine for FEDERATION_RESOLVER=http. EUDIPLO sends POST {url}/resolve; the request is subject to the outbound URL policy and redirects are not followed. [required when FEDERATION_RESOLVER is http] |
FEDERATION_RESOLVER_TOKEN | string | - | Bearer token EUDIPLO sends to the trust engine for FEDERATION_RESOLVER=http. [optional] 🔒 |
FEDERATION_ENTITY_PROVIDER | string | local, http | Where the entity configuration of a tenant's own federation entity comes from. local: EUDIPLO signs it with the tenant's federation key chain. http: EUDIPLO fetches the signed entity configuration from an external trust engine at FEDERATION_ENTITY_PROVIDER_URL and serves it unchanged. [optional] (default: local) |
FEDERATION_ENTITY_PROVIDER_URL | string | - | HTTPS base URL of the trust engine for FEDERATION_ENTITY_PROVIDER=http. EUDIPLO sends GET {url}/entities/{tenantId}/entity-configuration; the request is subject to the outbound URL policy and redirects are not followed. [required when FEDERATION_ENTITY_PROVIDER is http] |
FEDERATION_ENTITY_PROVIDER_TOKEN | string | - | Bearer token EUDIPLO sends to the trust engine for FEDERATION_ENTITY_PROVIDER=http. [optional] 🔒 |
General
| Key | Type | Allowed values | Notes |
|---|---|---|---|
FOLDER | string | - | Working folder: holds the SQLite database (service.db) and, with local storage, the uploaded files [optional] (default: ../../tmp, relative to the working directory; the container image sets /app/config) |
PUBLIC_URL | string | - | The public URL of the issuer [optional] (default: http://localhost:3000) |
INTERNAL_URL | string | - | URL the backend uses to reach itself: its authorization server keys (JWKS) and managed trust lists. Without it, these requests use PUBLIC_URL [optional] (default: http://127.0.0.1:<PORT>; none with TLS_ENABLED=true or a PORT that is not a number) |
NODE_ENV | string | - | production turns on TLS certificate checks for status list and trust list fetches (federation fetches are always checked), hides internal error messages from API responses and makes warn the default LOG_LEVEL. The container image sets it; set it yourself when you run the backend from source in production. [optional] |
PORT | string | - | Port the HTTP(S) server listens on (default: 3000) [optional] |
CORS_ORIGINS | string | - | Comma-separated list of origins allowed to call the management API (/api/*) from a browser, e.g. https://console.example.com. Protocol and public endpoints stay open to all origins. If unset, all origins are allowed everywhere. [optional] |
Issuer
| Key | Type | Allowed values | Notes |
|---|---|---|---|
ISSUER_MULTI_CONSUMPTION | boolean | - | Enable or disable multi-consumption for the issuer [optional] (default: false) |
Logging
| Key | Type | Allowed values | Notes |
|---|---|---|---|
LOG_LEVEL | string | trace, debug, info, warn, error, fatal | Application log level [optional] (default: warn when NODE_ENV is production (as in the container image), otherwise debug) |
LOG_ENABLE_HTTP_LOGGER | boolean | - | Enable HTTP request logging [optional] (default: false) |
LOG_HTTP_RESPONSE_BODY | boolean | - | Capture and log HTTP response bodies (buffered up to LOG_HTTP_RESPONSE_BODY_MAX_LENGTH bytes). Disabled by default because response bodies may contain access tokens, credentials, or other sensitive data. [optional] (default: false) |
LOG_HTTP_RESPONSE_BODY_MAX_LENGTH | number | - | Maximum number of bytes to capture for HTTP response bodies. Set to 0 to disable truncation. [optional] (default: 4096) |
LOG_REDACT_SENSITIVE_DATA | boolean | - | Redact sensitive request/response fields from logs. Disable only for debugging. [optional] (default: true) |
LOG_OID4VP_DECRYPTED_RESPONSE | boolean | - | Log decrypted OID4VP authorization responses. Disable by default because responses may contain personal data and credentials. [optional] (default: false) |
LOG_ENABLE_SESSION_LOGGER | boolean | - | Enable session flow logging [optional] (default: false) |
LOG_SESSION_STORE | string | off, errors, all, verbose | Controls whether session log entries are persisted to the database. 'off' disables storage, 'errors' stores only warn/error entries, 'all' stores everything, 'verbose' stores everything including full request/response bodies and error stacks. [optional] (default: off) |
LOG_TO_FILE | boolean | - | Enable logging to file in addition to console [optional] (default: false) |
LOG_FILE_PATH | string | - | File path for log output when LOG_TO_FILE is enabled [optional] (default: ./logs/session.log) |
AUDIT_LOG_RETENTION_DAYS | number | - | Delete tenant activity audit log entries older than N days. Set to 0 to disable time-based pruning. [optional] (default: 0) |
OTEL_SDK_DISABLED | boolean | - | Disable OpenTelemetry SDK (and OTel log forwarding) [optional] (default: false) |
AUDIT_LOG_MAX_ENTRIES_PER_TENANT | number | - | Keep only the newest N tenant activity audit log entries per tenant. Set to 0 to disable count-based pruning. [optional] (default: 0) |
Observability
| Key | Type | Allowed values | Notes |
|---|---|---|---|
GRAFANA_URL | string | - | Base URL of the Grafana instance for deep linking from the dashboard UI [optional] |
GRAFANA_DATASOURCE_TEMPO_UID | string | - | UID of the Tempo data source in Grafana [optional] (default: tempo) |
GRAFANA_DATASOURCE_LOKI_UID | string | - | UID of the Loki data source in Grafana [optional] (default: loki) |
OTEL_EXPORTER_OTLP_ENDPOINT | string | - | Base URL of the OTLP/HTTP endpoint (e.g. the OpenTelemetry Collector) that receives traces, metrics and logs (default: http://localhost:4318) [optional] |
OTEL_SERVICE_NAME | string | - | Service name attached to exported traces, metrics and logs (default: eudiplo-backend) [optional] |
Registrar
Connection to the German EUDI Hub (EUDI Hub).
| Key | Type | Allowed values | Notes |
|---|---|---|---|
EUDI_HUB_API_URL | string | - | Base URL of the Organization API of the German EUDI Hub, without the /v1 path. EUDIPLO sends the access token pasted into a EUDI Hub request only to this URL. The outbound URL policy applies to it. [optional] (default: https://api.eudi-hub.gov.de/org-management) |
Session
| Key | Type | Allowed values | Notes |
|---|---|---|---|
SESSION_TIDY_UP_INTERVAL | number | - | Interval in seconds to run session tidy up [optional] (default: 3600) |
SESSION_TTL | number | - | Default time to live for sessions in seconds. Can be overridden per tenant. [optional] (default: 86400) |
SESSION_CLEANUP_MODE | string | full, anonymize | Default cleanup mode when sessions expire. 'full' deletes the entire session, 'anonymize' keeps metadata but removes personal data. Can be overridden per tenant. [optional] (default: full) |
Skip Flags
Every switch that turns off a check of the normal flow is named SKIP_<CHECK>
and defaults to false. On startup, EUDIPLO warns that protection mechanisms
are disabled and lists the active skip flags with the protection each one turns
off. Use them only for development and interoperability tests.
| Key | Type | Allowed values | Notes |
|---|---|---|---|
SKIP_OVERASKING_CHECK | boolean | - | Skip verifying that the registration certificate authorizes every credential in the DCQL query (overasking prevention). Intended for development and interoperability testing only. [optional] (default: false) |
SKIP_TRUST_AUTHORITY | boolean | - | Accept presentation configurations whose DCQL credential queries have no trusted_authorities. Presented credentials of such queries are verified without checking their issuer. Intended for development and interoperability testing only. [optional] (default: false) |
Status
| Key | Type | Allowed values | Notes |
|---|---|---|---|
STATUS_CAPACITY | number | - | The default capacity of the status list. Can be overridden per tenant. [optional] (default: 10000) |
STATUS_BITS | number | 1, 2, 4, 8 | The default number of bits used per status entry. Can be overridden per tenant. [optional] (default: 1) |
STATUS_TTL | number | - | The default TTL in seconds for status list JWTs. Verifiers can cache the JWT until expiration. Can be overridden per tenant. [optional] (default: 3600) |
STATUS_IMMEDIATE_UPDATE | boolean | - | If true, regenerate status list JWT immediately on every status change. If false (default), use lazy regeneration when TTL expires. Can be overridden per tenant. [optional] (default: false) |
STATUS_ENABLE_AGGREGATION | boolean | - | If true (default), include aggregation_uri in status list JWTs. This allows relying parties to pre-fetch all status lists for offline validation per RFC draft-ietf-oauth-status-list Section 9. Can be overridden per tenant. [optional] (default: true) |
WALLET_UNIT_STATUS_CHECK_INTERVAL | number | - | Interval in seconds at which the status lists of wallet unit attestations are checked, for credential configurations with revokeWithWalletUnit. A credential is revoked once its wallet unit is. 0 turns the check off. A fetched status list is reused for its ttl (5 minutes without one), at most one hour and not past its exp. [optional] (default: 3600) |
Storage
| Key | Type | Allowed values | Notes |
|---|---|---|---|
STORAGE_DRIVER | string | local, s3 | The storage driver to use [optional] (default: local) |
LOCAL_STORAGE_DIR | string | - | The directory to store files in when using local storage [optional] [default <FOLDER>/uploads when STORAGE_DRIVER is local] |
S3_REGION | string | - | The AWS region for the S3 bucket [required when STORAGE_DRIVER is s3] |
S3_BUCKET | string | - | The name of the S3 bucket [required when STORAGE_DRIVER is s3] |
S3_ACCESS_KEY_ID | string | - | The access key ID for the S3 bucket. Optional when using IRSA or instance profile credentials. [optional] |
S3_SECRET_ACCESS_KEY | string | - | The secret access key for the S3 bucket. Optional when using IRSA or instance profile credentials. [optional] |
S3_ENDPOINT | string | - | The endpoint URL for the S3 service (for S3-compatible services) [optional] |
S3_FORCE_PATH_STYLE | boolean | - | Whether to force path-style URLs for S3 [optional] [default false when STORAGE_DRIVER is s3] |
TLS
| Key | Type | Allowed values | Notes |
|---|---|---|---|
TLS_ENABLED | boolean | - | Enable built-in TLS termination (serve HTTPS directly). Requires TLS_CERT_PATH and TLS_KEY_PATH; startup fails if they are unset or unreadable [optional] (default: false) |
TLS_CERT_PATH | string | - | Path to the TLS certificate file (PEM format) [optional] |
TLS_KEY_PATH | string | - | Path to the TLS private key file (PEM format) [optional] |
TLS_CA_PATH | string | - | Path to the intermediate CA certificate(s) of the server certificate (PEM format). They are sent to clients after the certificate in TLS_CERT_PATH so clients can build the chain. Not needed if TLS_CERT_PATH already contains the full chain (e.g. Let's Encrypt fullchain.pem). Does not enable client certificate authentication (mTLS) [optional] |
TLS_KEY_PASSPHRASE | string | - | Passphrase for an encrypted TLS_KEY_PATH private key [optional] 🔒 |
Verifier
| Key | Type | Allowed values | Notes |
|---|---|---|---|
VP_REMOVE_TA | boolean | - | If true, strip trusted_authorities from the DCQL query sent to wallets in OID4VP authorization requests. Use this as an escape hatch for wallets that do not yet handle trusted_authorities correctly. [optional] (default: false) |
Webhook
| Key | Type | Allowed values | Notes |
|---|---|---|---|
OUTBOUND_URL_ALLOW_HTTP | boolean | - | Allow HTTP (non-TLS) for outbound calls (webhooks, attribute providers, issuer and schema metadata imports, trust lists, status lists, federation entities and the federation trust engine, the EUDI Hub and the issuing CA of its access certificates, external authorization servers and the upstream provider of a chained authorization server). CRLs may always use HTTP. Also lets the federation entity ID of a tenant (federation.entityId) be an http URL. Enable it for local development against HTTP endpoints. [optional] (default: false) |
OUTBOUND_URL_ALLOW_PRIVATE_NETWORK | boolean | - | Allow outbound calls (webhooks, attribute providers, metadata imports, trust lists, status lists, federation entities and the federation trust engine, CRLs, the EUDI Hub and the issuing CA of its access certificates, external authorization servers and the upstream provider of a chained authorization server) to non-public addresses: private, loopback, link-local, carrier-grade NAT, reserved and the other ranges listed in the security model, e.g. for services inside the same cluster or for local development. The address actually connected to is checked as well (DNS rebinding protection). EUDIPLO's own PUBLIC_URL and INTERNAL_URL are always reachable for trust lists, status lists, federation entity configurations and subordinate statements and authorization server keys. [optional] (default: false) |
OUTBOUND_URL_ALLOWED_HOSTS | string | - | Comma-separated hostname allowlist for outbound calls (webhooks, attribute providers, metadata imports, trust lists, status lists, federation entities and the federation trust engine, CRLs, the EUDI Hub and the issuing CA of its access certificates, external and upstream authorization servers; supports exact host and subdomains). When set, other hosts are rejected. Listed hosts still need HTTPS and public addresses unless OUTBOUND_URL_ALLOW_HTTP or OUTBOUND_URL_ALLOW_PRIVATE_NETWORK is set. [optional] |