
The openid-federation service is configured in two layers
Spring Boot configuration where features such as TLS, management ports, session handling, Redis, logging levels and so on are configured. Read more about this at https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html.
OpenId-Federation service is configuration in modules (resolver, trust-anchor, trust-mark-issuers)
New to this service? Read Demo Mode Configuration first — it walks
through application-demo.yml and the three demo JSON files (entities, trust anchors, policy,
constraints, resolver) property by property, as a worked example of everything documented below. For how
to actually run the demo, see Getting Started (Demo Mode).
Some properties can be configured by object or reference.
See the section about reference configuration later on.
federation.*
Each configured federation component must be referenced an entitiy to function correctly.
| Property | Description | Type | Default |
|---|---|---|---|
allow-http-ec-location |
Accept ec-location values with the http scheme. OpenID Federation Entity Configuration Hosting 1.0 only allows https and data URLs, so only use this for local tests. |
Boolean | false |
federation.keys.*
| Property | Description | Type | Default |
|---|---|---|---|
kid-algorithm |
Key ID algorithm (default or serial), see below |
String | default |
additional-keys |
List of additional public keys that can be referenced | Object | – |
mapping |
Mapping of private keys to determine their usecase (federation/hosted) | Object | - |
With default, a key gets the key ID given in its credential configuration, or else its JWK thumbprint
(RFC 7638). With serial, a key that has a certificate gets the certificate’s serial number, in decimal, as key
ID, and other keys get the default key ID.
federation.keys.additional-keys[*]
| Property | Description | Type |
|---|---|---|
name |
Logical name of the key | String |
base64-encoded-public-jwk |
Base64‑encoded JWK | String |
certificate |
PEM encoded certificate or public key | String |
Keys loaded from federation.keys.additional-keys[*] will be available using the public: prefix.
federation.keys.mapping
| Property | Description | Type | Default |
|---|---|---|---|
federation |
List of federation key names to be mapped to federation: |
List<String> | – |
hosted |
List of hosted key names to be mapped to hosted: At least one key needs to be hosted if you want a default key to be loaded from the registry |
List<String> | – |
federation.service.*
| Property | Description | Type | Default |
|---|---|---|---|
storage |
Storage backend (memory or redis) |
String | memory |
redis.key-name |
Redis namespace / key | String | – |
federation.service.scheduling.*
Background jobs that keep cached state fresh. Useful to disable in tests (see
application-integration-test.yml, which turns both triggers off so tests control reloads explicitly).
| Property | Description | Type | Default |
|---|---|---|---|
registry-trigger-enabled |
Check the registry for changes once a minute (managed mode only) | Boolean | true |
resolver-trigger-enabled |
Periodically rebuild resolver state/cache | Boolean | true |
resolver-reload-rate |
Interval between resolver state rebuilds (ISO‑8601 duration) | Duration | PT10M |
federation.routing.*
| Property | Description | Type | Default |
|---|---|---|---|
enabled |
Enable internal routing support | Boolean | false |
mode |
Routing mode — see below | String | – |
allowed-domains |
Domains accepted when mode is STRICT |
List<URI> | – |
mode must be one of:
| Value | Behavior |
|---|---|
STRICT |
Enforces the host portion of the route; required for hosting entities across multiple domains behind one instance. allowed-domains is mandatory in this mode. |
RELAXED |
Accepts any host, but does not validate it. |
IGNORING |
Ignores the host portion of the route entirely (used by the demo, which only ever runs on localhost). |
Routing dispatches an incoming request path to the correct virtual entity — see Routing for the resolution algorithm.
federation.registry.integration.*
| Property | Description | Type | Default |
|---|---|---|---|
enabled |
Enable registry integration | Boolean | false |
instance-id |
Instance identifier for node groups | UUID | – |
validation-keys |
Keys used to validate registry JWTs | List |
Empty |
transport |
How records are loaded from the registry, legacy or delta |
String | legacy |
With legacy, each load gets all records, and with delta, each load gets only the changes since the last load
(delta needs a registry that supports it).
federation.registry.integration.client.*
| Property | Description | Type | Default |
|---|---|---|---|
base-uri |
Base URI of the registry. | String | – |
trust-store-bundle-name |
Trust store bundle used for TLS. | String | – |
name |
Logical name of the client. | String | – |
timeout.connect |
Maximum time to establish the connection. | Duration | 5s |
timeout.read |
Maximum time to wait for the response. | Duration | 30s |
Every key named by a key reference from the registry, such as hosted:sign-key, must exist on this instance. An
entity with a reference to a missing key is left out and logged as an error. A reference to a missing key in the
module records (Trust Anchors, resolvers and Trust Mark Issuers) makes the whole module load fail, and the previously
loaded modules stay in use. An entity without jwks, or with an empty key reference, is signed with the default
key, which is the first hosted key.
federation.local-registry.*
federation.local-registry.resolvers[*]
| Property | Description | Type |
|---|---|---|
entity-identifier |
Entity ID of the resolver | String |
trusted-keys |
Keys used to validate fetched statements | List |
trust-anchor |
Trust anchor entity ID | String |
resolve-response-duration |
Validity of issued resolve responses, default 7 days. In JSON files and registry records the value is an ISO-8601 duration, for example PT1H |
Duration |
federation.local-registry.trust-anchors[*]
| Property | Description | Type |
|---|---|---|
entity-identifier |
Entity ID of the trust anchor | String |
subordinates |
Subordinate entities and constraints | List |
trust-mark-issuers |
Mapping of trust mark IDs to allowed issuers | Map |
trust-mark-owners |
Trust mark ownership configuration | List |
See Demo Mode Configuration → trust-anchors.json
for the full list of properties a subordinate entry supports, including worked examples of policy and
constraints.
Every subordinate must have entity-types, and is-intermediate may only be set when entity-types contains
federation_entity. A subordinate that does not meet this is rejected when the configuration is loaded. Filtered
subordinate listings are answered from these fields, without fetching the Entity Configurations of the
subordinates. The trust_marked and trust_mark_type filters are only supported when the entity is also a Trust
Mark Issuer, and are then answered from its trust-mark-subjects.
A subordinate gets an ec_location claim in its Subordinate Statement when ec-location is set, or when its
virtual-entity-id differs from its entity-identifier (the well-known location under the virtual entity ID is
then used). See ec-location values for the accepted values. A warning is logged at
startup when ec_location is issued for an Intermediate Entity, since OpenID Federation Entity Configuration
Hosting 1.0 recommends it for Leaf Entities only, and when ec_location is listed in crit, since entities
without support for the claim will then reject the statement.
federation.local-registry.trust-mark-issuers[*]
| Property | Description | Type | Default |
|---|---|---|---|
entity-identifier |
Entity ID of the trust mark issuer | String | – |
trust-mark-validity-duration |
Deprecated, use the validity duration of each trust mark. Only used for trust marks without a duration of their own | Duration | – |
trust-marks |
List of trust marks | List | – |
federation.local-registry.trust-mark-issuers[*].trust-marks[*]
| Property | Description | Type |
|---|---|---|
trust-mark-type |
Unique identifier of the trust mark | String |
trust-mark-validity-duration |
Validity of issued trust marks (ISO‑8601), for example P2D. Without a value the issued trust marks have no exp and never expire, unless the trust mark issuer has a (deprecated) duration |
Duration |
logo-uri |
Logo URI | String |
ref-uri |
Reference URI | String |
delegation |
TrustMarkDelegation JWT | String |
trust-mark-subjects |
Subjects granted this trust mark | List |
A trust mark expires at the earliest of its validity duration and the expires of its subject. A validity duration
shorter than 5 minutes is logged as a warning when the configuration is loaded, and is still used.
federation.local-registry.trust-mark-issuers[*].trust-mark-subjects[*]
| Property | Description | Type |
|---|---|---|
sub |
Subject entity ID | String |
granted |
Grant time (UTC, ISO‑8601) | Instant |
expires |
Expiry time (UTC, ISO‑8601) | Instant |
revoked |
Revocation flag | Boolean |
federation.local-registry.entities[*]
| Property | Description | Type |
|---|---|---|
entity-identifier |
Entity ID | String |
jwks |
Key reference | Object or reference |
metadata |
Federation / OIDC metadata | Object or reference |
trust-mark-source |
External trust mark references | List |
ec-location |
Overrides entity configuration location | String |
Entities define federation metadata, trust mark sources, and may represent trust anchors, resolvers, OPs, RPs, or trust mark issuers.
ec-location valuesThe same rules apply to ec-location of entities and of Trust Anchor subordinates, whether they come from local
configuration or from the registry:
https URL, for example https://hosting.example.com/leaf/ec.data:application/entity-statement+jwt,<jwt>. The ;base64 form
is not accepted./, which is resolved against the virtual entity ID, or the entity identifier if there is
none. The resolved URL must follow the rules above.http URL, only if federation.allow-http-ec-location is true.Other values make startup fail for local configuration. Entities and subordinates from the registry with other
values are left out and logged as errors. The resolver also leaves out subordinates whose Subordinate Statement has
an ec_location that does not follow these rules.
federation.resolver.client.*
The REST client the service’s Resolver module uses to fetch entity configurations and subordinate
statements from other federation participants over HTTPS while walking a trust chain. Same shape as
federation.registry.integration.client:
| Property | Description | Type | Default |
|---|---|---|---|
name |
Logical name of the client. | String | – |
trust-store-bundle-name |
Trust store bundle used to validate TLS server certs. | String | – |
base-uri |
Not used for this client. Startup fails validation if this is set. | String | – |
timeout.connect |
Maximum time to establish the connection. | Duration | 5s |
timeout.read |
Maximum time to wait for the response. | Duration | 10s |
local-requests |
Allows the client to not use HTTP for entities this service controls. | Boolean | true |
A request that exceeds a timeout fails in the same way as other fetch errors.
Configure trust chain source for resolver. Defaults to the pre-calculated tree that rebuilds periodically. Changing this from it’s default value is not recommended and will impact performance.
federation.resolver.*
| Property | Description | Type | Default |
|---|---|---|---|
lazy |
Source of the trust chain. none: pre-calculated tree. local: built at request time for hosted subjects. all: built at request time for all subjects. |
String | none |
Some properties can be configured by reference, this means that we can optionally substitute the object structure with something else. E.g. A file, or another property loaded elsewhere (for keys).
E.g.
federation:
local-registry:
entities:
- entity-identifier: https://myidentifier1.test
policy:
id: my-id
policy: ... policy object ....
- entity-identifier: https://myidentifier2.test
policy: file:/path/to/policy
| Format | Type |
|---|---|
| classpath: | Load file from classpath |
| file: | Load file from system |
| public: | Load key from public keys (JWK,JWKS only) |
| federation: | Load key from federation mapped keys (JWK,JWKS only) |
| hosted: | Load key from hosted mapped keys (JWK,JWKS only) |
Reference keys can be referenced by their prefix + kid or name
E.g.
“public:359433581122628090150675142465804663870388233428” Loads the public key for kid 359433581122628090150675142465804663870388233428
“federation:sign-key-1” Loads the keypair that is mapped for federation use.
These are plain Spring Boot Actuator settings, not openid-federation-specific properties, but a developer starting the service up needs them to know where to look:
| Property | Default (application.yml) |
Purpose |
|---|---|---|
server.port |
8000 (8080 in demo) |
The federation endpoints themselves (/ta, /resolver, …) |
management.server.port |
8081 | A separate port for actuator endpoints, kept off the public traffic port |
management.endpoints.web.exposure.include |
* |
All actuator endpoints are exposed on the management port |
Notable actuator endpoints:
GET http://localhost:8081/actuator/ready — a custom endpoint (not a standard Spring Boot one) that
reports whether the service is ready for traffic. In managed mode,
configuration is fetched from the registry after startup, so the service will not be ready
immediately — orchestration tooling (Kubernetes readiness probes, load balancers) should poll this
instead of assuming readiness at process start. It returns non-200 while any
ReadyStateComponent reports not-ready.GET http://localhost:8081/actuator/health — standard Spring Boot liveness/health check.GET http://localhost:8081/actuator/prometheus — Prometheus-formatted metrics (enabled by default via
management.prometheus.metrics.export.enabled: true), tagged with application_name /
application_version.management.opentelemetry.tracing.export.otlp.endpoint, which
defaults to ${OTEL_EXPORTER_OTLP_ENDPOINT:http://localhost:4318/v1/traces} — point that environment
variable at your collector, or override management.tracing.sampling.probability (default 1.0, i.e.
trace everything) to reduce volume. The demo profile disables tracing and OTLP export entirely, since
there is normally no collector running locally.Since the demo runs both ports on localhost, actuator endpoints are reachable at
http://localhost:8081/actuator/* while the federation service itself answers on
http://localhost:8080/* (see the example requests in the README).