OpenID Federation

The OpenID Federation capability needs two pieces of deployment configuration: its own PostgreSQL database, and the lifetime of the statements it signs. Both are read by the platform service, which administers and publishes federation entities and serves their public endpoints, and by the tenant authorization server, which registers federation clients and signs Explicit Registration responses with the same Federation Entity Keys. The guides in OpenID Federation describe what tenants do once it is configured.

The federation database

The federation library keeps its accounts, Federation Entity Keys, statements and Trust Marks in a dedicated PostgreSQL database, separate from the tenant workload database. Tenant administration state, such as entities, bindings and superior relationships, stays in the tenant database as usual. Private key material is never stored in either; it stays in key management.

Both the platform service and the tenant authorization server connect to this database with the same three settings:

Property	Environment variable	Meaning
oidf.datasource.url	OIDF_DATASOURCE_URL	JDBC URL, for example jdbc:postgresql://tenant-postgres:5432/oidfed.
oidf.datasource.user	OIDF_DATASOURCE_USER	Database role that owns the federation schema.
oidf.datasource.password	OIDF_DATASOURCE_PASSWORD	Password of that role. Supply it from a secret source.

The library creates and migrates its schema when it connects, so the role needs to own the database. A missing URL or user is reported with an error that names the setting. PostgreSQL is the only supported database for this store.

In the shipped Docker Compose bundle the database is called oidfed and lives on the tenant PostgreSQL server. An initialization script creates the oidfed role and database on first start and on every health check, so existing volumes receive it too. Set the role's password with EDK_OIDFED_DB_PASSWORD; the bundle passes it to both the PostgreSQL container and the two services.

The Helm chart renders the same environment variables into the platform and tenant authorization server deployments from these values:

oidfed:
  database:
    host: ""            # empty uses database.tenant.host
    port: 5432
    name: oidfed
    existingSecret: edk-oidfed-postgres
    usernameKey: username
    passwordKey: password
  statementLifetimeSeconds: 3600

Create the database, its owning role and the Kubernetes Secret before installing. The chart refuses to render without oidfed.database.existingSecret. When host points at a server other than the tenant PostgreSQL server, allow egress from the platform and tenant authorization server pods to it in your network policies.

Statement lifetime

oidf.federation.statement.lifetime.seconds (environment variable OIDF_FEDERATION_STATEMENT_LIFETIME_SECONDS) sets how long signed Entity Configurations and Subordinate Statements stay valid. It has no built-in default: until it is configured, every attempt to prepare or sign a statement fails. The Compose bundle and the Helm chart (oidfed.statementLifetimeSeconds) both ship 3600 seconds, and the chart rejects values below 60.

The lifetime is a trade-off. A shorter one makes key changes, revoked memberships and new metadata policies reach relying parties sooner, because nothing signed stays valid for long. A longer one tolerates longer gaps in renewal. Whatever you choose, renewal has to run well inside it.

Renewal

The EDK enterprise images have no recurring scheduler, so statements are renewed only when something asks for it. Run the tenant renewal operation on a cadence shorter than the statement lifetime, either from an external scheduler that calls POST /api/platform/config/v1/tenants/{tenantId}/openid-federation/publications/refresh with a service credential, or from a workflow that uses the oidfed.refresh-publications step. With the default hour, running every 15 minutes with a 30-minute window leaves room for a missed run. Watch the response for failures, in particular members whose keys changed and need a new review. See Renewal.

Routing the public endpoints

Federation endpoints are addressed by Entity Identifier, so they appear below whatever path the tenant chose for an entity, on the tenant host. The gateway has to forward, on tenant hosts, paths that end in /.well-known/openid-federation, /federation_fetch, /federation_list, /federation_resolve, /federation_trust_mark_status, /federation_trust_mark_list, /federation_trust_mark and /federation_historical_keys to the platform service, and paths that end in /federation_registration to the tenant authorization server. These routes are public and unauthenticated by design, like the other well-known routes in the routing table. The host must be preserved, because the service derives the entity from the host and path.

Service coverage

Federation administration, publication and the public endpoints run in the platform service. OpenID Federation client registration on the hosted authorization server runs in the enterprise tenant authorization server and platform services; the monolith does not include it.

Superior relationships are written only on PostgreSQL, the production database. A tenant workload database on MySQL or SQLite can read federation administration and publish, but refuses changes to superior relationships, which makes joining or operating a federation impossible there.