Security model
This page describes who EUDIPLO trusts, how each boundary is protected and which keys protect which messages. It explains the model only: hardening steps are in the production checklist, and the presentation session binding (OID4VP ยง13.3) is explained on Sessions.
Trust boundariesโ
| Boundary | Callers | Protection |
|---|---|---|
Management API (/api) | Your backend, the web client | OAuth 2.0 bearer token of a client. The token names one tenant and the client's roles; allow lists can further restrict which configurations a client may use. Changes to tenants and to issuance and presentation configuration are written to an audit log. |
| Protocol endpoints | Wallets, and your page for the DC API | Public by design. Each step is protected by the protocol: single-use codes and nonces, PKCE, DPoP, wallet and key attestation, signed requests and encrypted responses. |
| Outbound calls | EUDIPLO to URLs that tenants configure or that credentials and certificates name | Outbound URL policy (below), optional API key header for webhooks and attribute providers. Webhook requests are not signed. |
| Storage and key material | EUDIPLO to database, object storage, KMS | Sensitive columns encrypted at rest; with an external KMS the private keys never leave it. Configuration bundle exports never contain private keys. GET /api/key-chain/{id}/export and the KeyChain document of GET /api/config-bundles/resources/KeyChain/{id}/document return the private keys of a db key chain and, like the tenant KMS provider configuration with its provider credentials, need tenant:admin or tenants:manage. |
Tenants are isolated in the data layer: every entity carries a tenantId, and a client token only reaches its own tenant. A client with the tenants:manage role can manage all tenants, so give it only to platform operators (Tenants and access). Within a tenant, a client or person cannot hand out roles beyond what its own roles allow, or change or take over a client or person with more rights (granting roles).
HTTPS and TLSโ
Wallets expect HTTPS for every issuer and verifier URL, so PUBLIC_URL must be an HTTPS URL. TLS is terminated by a reverse proxy or by EUDIPLO itself (TLS).
For outgoing requests to URLs that tenants configure or that credentials and certificates name (webhooks, attribute providers, issuer metadata, schema metadata, trust lists, status lists, OpenID Federation entity configurations and subordinate statements and the trust engines (FEDERATION_RESOLVER_URL, FEDERATION_ENTITY_PROVIDER_URL), certificate revocation lists, the EUDI Hub API and the issuing CA its access certificates name, and the metadata, keys, token and introspection endpoints of external authorization servers and of the chained server's upstream provider), EUDIPLO applies an outbound URL policy against server-side request forgery: only HTTPS targets that resolve to public addresses are allowed, checked after DNS resolution, and every redirect of a download is checked again. Private, loopback, link-local, carrier-grade NAT, documentation, benchmarking, multicast and reserved ranges are blocked, as are the IETF protocol assignment ranges (192.0.0.0/24, 2001::/23, including Teredo), the IPv4-compatible and local-use NAT64 ranges, and IPv6 addresses that route to a blocked IPv4 address (IPv4-mapped, NAT64 64:ff9b::/96, 6to4 2002::/16). OUTBOUND_URL_ALLOW_HTTP and OUTBOUND_URL_ALLOW_PRIVATE_NETWORK relax this for development or in-cluster services. OUTBOUND_URL_ALLOWED_HOSTS narrows it: when set, only the listed hosts and their subdomains are reachable, and they still need HTTPS and public addresses unless the two flags allow otherwise (environment variables).
Two exceptions keep standard deployments working. Trust lists, status lists, federation entity configurations and subordinate statements, and authorization server keys (JWKS) on EUDIPLO's own PUBLIC_URL or INTERNAL_URL origin skip the policy, because managed trust lists, the status lists of credentials EUDIPLO issued and the keys of its chained and OID4VP-based authorization servers are fetched from there; a redirect to another origin is checked again. CRL distribution points may use plain HTTP regardless of OUTBOUND_URL_ALLOW_HTTP, as is usual for CRLs (RFC 5280); their address is still checked, and a CRL only counts if the CA that issued the certificate signed it (revocation check).
Webhooks and attribute providers check every redirect target against the policy and send their API key only to the origin of the configured URL. Requests to the EUDI Hub send the pasted portal token only to the origin of EUDI_HUB_API_URL, follow at most 3 redirects, time out after 30 seconds and accept at most 1 MiB per answer. Webhook, attribute provider and EUDI Hub requests, the token request to the upstream provider and token introspection use the proxy in HTTPS_PROXY (HTTP_PROXY for http: targets), except for hosts in NO_PROXY. EUDIPLO still resolves and checks the target host before each request, so it must resolve to a public address unless OUTBOUND_URL_ALLOW_PRIVATE_NETWORK is set. The check of the address actually connected to (against DNS rebinding) then applies to the proxy for http: targets and not at all for https: targets, which the proxy connects to itself. The token request to the upstream provider and token introspection requests do not follow redirects. KMS providers, including those in a tenant's KMS configuration, are called without the policy; restrict EUDIPLO's egress at the network level if they must not reach internal services.
Trust decisionsโ
| Decision | Based on |
|---|---|
| Is a presented credential's issuer trusted? | Its certificate chain against the trust lists named in the DCQL query: LoTEs for PID, Pub-EAA and EAA issuers, ETSI TS 119 612 Trusted Lists for the granted qualified services of QTSPs issuing QEAAs (Trusted Lists for QEAAs), or, for an SD-JWT VC under OpenID Federation, its issuer's trust chain and the key kid of its federation metadata (Presentation under the hood) |
| Is an external or upstream authorization server trusted? | With a federation policy in the issuance configuration, the server must have a valid trust chain to a trust anchor before EUDIPLO fetches its metadata |
| Is a wallet trusted? | Wallet and key attestations, checked against wallet-provider trust lists (below) |
| Is EUDIPLO trusted by the wallet? | The access certificate on requests and signed metadata, the registration certificate, and the issuer certificate in credentials |
For OpenID Federation, EUDIPLO verifies the trust chain from the entity to a configured trust anchor; OpenID Federation describes what is and is not checked.
Tokens and codesโ
| Token | Issued by | Accepted at | Lifetime | Bound to |
|---|---|---|---|---|
| Management API token | /api/oauth2/token, or your OIDC provider | /api/... | 24 hours (built-in server) | Client, tenant, roles; with the built-in server only while the client exists and keeps its secret (revoke access) |
| Pre-authorized code | EUDIPLO, in the offer | Token endpoint | Until the session TTL ends; single use | Session; optional tx_code |
| Authorization code | Hosted authorization server | Token endpoint | 60 seconds (built-in), 300 seconds (chained, OID4VP-based); single use | Session, grant, PKCE challenge, DPoP key from PAR |
| OID4VCI access token | Hosted or external authorization server | Credential, deferred and notification endpoints | Built-in: token.lifetimeSeconds, default 300 seconds; chained and OID4VP-based: default 3600 seconds | Session; DPoP key (cnf.jkt) if DPoP is used |
| Refresh token | Hosted authorization server | Token endpoint | 30 days by default; not extended by use | Session, DPoP key, wallet attestation key |
| Credential nonce | POST /issuers/{tenant}/vci/nonce | Key proofs at the credential endpoint | Single use | Tenant |
Refreshing never extends the authorization: the built-in server keeps the refresh token, the chained and OID4VP-based servers replace it, and in both cases its original expiry stays. Presentation-side values (nonce, response_code) are described on Sessions.
PKCEโ
Every authorization code requires PKCE with S256: a PAR request without code_challenge, or with any other method, is rejected, and the token request must send the matching code_verifier. This applies to the built-in, chained and OID4VP-based servers, to interactive authorization and to the OpenID Provider. The chained server also uses S256 towards the upstream provider.
DPoPโ
DPoP (RFC 9449) binds an access token to a key the wallet holds, so a stolen token is useless without that key. EUDIPLO verifies every DPoP proof:
- the signature with the public key in the proof header,
htmandhtuagainst the request method and URL,iatno older than 300 seconds, with 60 seconds of clock skew,jtiused once per key, tracked in the database until the proof leaves the freshness window, so a replay is caught across backend instances,- at the credential, deferred and notification endpoints,
ath(the access token hash) and the key against the token'scnf.jkt.
A key presented at PAR must be used again at the token endpoint and for refreshes. DPoP is required at the credential, deferred and notification endpoints when the issuance configuration sets dPopRequired. At the token endpoint, the built-in server requires it with dPopRequired or its own requireDPoP, the chained and OID4VP-based servers with their requireDPoP. A bad proof is answered with invalid_dpop_proof at PAR and token, and with HTTP 401 invalid_token at the other endpoints. Configuration: Authorization servers.
Wallet and key attestationโ
Both mechanisms are signed by the wallet provider and trusted through wallet-provider trust lists, but they answer different questions:
| Wallet attestation | Key attestation | |
|---|---|---|
| Question | Is this wallet a trusted OAuth client of this authorization server? | Is this holder key, and the way it is stored and unlocked, acceptable for the credential? |
| Sent | OAuth-Client-Attestation and OAuth-Client-Attestation-PoP headers at PAR and token | An attestation proof, or a key_attestation header in a jwt proof, at the credential endpoint |
| Required by | The authorization server entry, with issuance-level defaults | The credential configuration (keyAttestationsRequired, proofTypesSupported) |
| Trust anchor | The authorization server's wallet-provider trust lists, or the issuance-level ones | The issuance configuration's walletProviderTrustLists |
External authorization servers cannot enforce wallet attestation through EUDIPLO. How to configure both: Wallet and key attestation.
Keys and algorithmsโ
Each signing key chain uses one ECDSA algorithm, fixed by its curve: ES256 (P-256, the default), ES384 (P-384) or ES512 (P-521). It is chosen when the key chain is created, kept on rotation, and used for every signature of the key chain, including its certificates; the KMS provider limits which ones new and imported key chains may use (signing algorithms). The issuer metadata names the algorithm of each credential's key chain in credential_signing_alg_values_supported. From wallets and other issuers, EUDIPLO accepts ES256, ES384 and ES512 in proofs, key binding JWTs and presented credentials, and the issuer and verifier metadata list all three. Each operation uses the following key:
| Operation | Key | Algorithm |
|---|---|---|
| Access tokens of hosted authorization servers | authorizationServer key chain (token.signingKeyId of the authorization server, otherwise the tenant's authorization server key chain); never an access or attestation key chain | ES256, ES384 or ES512 (the key chain's) |
| ID tokens of the OpenID Provider | The tenant's authorization server key chain | ES256, ES384 or ES512 (the key chain's) |
| SD-JWT VC credentials, mdoc MSO | attestation key chain (keyChainId of the credential configuration) | ES256, ES384 or ES512 (the key chain's) |
| Status lists | statusList key chain | ES256, ES384 or ES512 (the key chain's) |
| Trust lists hosted by EUDIPLO | trustList key chain | ES256, ES384 or ES512 (the key chain's) |
OID4VP request objects, signed issuer metadata, client_id | access key chain (accessKeyChainId of the presentation configuration, otherwise the tenant's default access key chain) | ES256, ES384 or ES512 (the key chain's) |
| Encrypted credential requests, ISO 18013-7 responses | encrypt key chain, published in the issuer metadata | ECDH-ES (JWE), HPKE (ISO) |
| OID4VP responses | A fresh key pair per session, not a key chain; for openid_federation requests the encrypt key chain | ECDH-ES with A128GCM or A256GCM |
| OpenID Federation entity configuration | federation key chain (federation.entityKeyChainId) | ES256, ES384 or ES512 (the key chain's) |
| Credential responses | The wallet's key from the credential request | ECDH-ES with A128GCM or A256GCM |
Key chains live in a KMS provider. With the db provider, the private key is stored encrypted in the database; with Vault, AWS KMS, PKCS#11, CSC or an HTTP signer, EUDIPLO only sends data to be signed. Usage types and certificates are explained in Keys and certificates, providers in Key management.
Rotationโ
A key chain rotates its signing key automatically by its rotationPolicy (a daily job checks intervalDays) or on demand (POST /api/key-chain/{id}/rotate). Rotation creates a new key in the same KMS provider and a new certificate, issued by the chain's internal root CA if it has one and self-signed otherwise; new signatures use it immediately. The previous key and certificate stay available for a fixed grace period of 30 days, so relying parties can still validate recently signed tokens, credentials and lists.
Encryption at restโ
Sensitive columns are encrypted with AES-256-GCM: the private key material of db key chains, secrets in the configuration (webhook and attribute provider API keys, upstream client secrets of chained authorization servers), session data such as offers, authorization requests, presented credentials and response encryption keys, the state of interactive authorization, and the upstream claims of chained authorization. Refresh tokens, authorization codes and pre-authorized codes are stored only as hashes. The data encryption key comes from ENCRYPTION_KEY_SOURCE: by default it is derived from MASTER_SECRET with HKDF; with vault, aws or azure it is fetched from a secret store at startup and held only in memory. Losing or changing this key makes the encrypted data unreadable, and it also anchors the fingerprints of the single active credential policy. Operating the key: Encryption keys.