OpenID Federation

OpenID Federation lets parties that have never met establish trust by following signed statements. Every participant publishes an Entity Configuration about itself at its own URL. A superior, such as a federation's Trust Anchor or an intermediate organization, signs a Subordinate Statement about each entity it admits. A relying party that trusts the Trust Anchor can then resolve a Trust Chain from any member up to that anchor and decide whether to accept the member's metadata, keys and Trust Marks.

VDX supports OpenID Federation 1.1, OpenID Federation for OpenID Connect 1.1 for authorization servers and their clients, and the entity types for credential issuers and verifiers defined in OpenID Federation for Wallet Architectures 1.0 (draft 05). Your tenant can take part in federations in two roles, and many organizations use both:

• As a participant, your organization and its hosted services join federations that others operate. Your authorization servers, credential issuers and verifiers become federation entities that wallets and relying parties can resolve. See Join a federation.
• As a federation operator, your organization runs one or more federations as their Trust Anchor. You admit members, set the metadata policies they receive, and issue Trust Marks. See Operate a federation.

Onboard members and clients describes the processes that connect the two roles: admitting an entity into a federation, which both parties take part in, and letting federation relying parties register with your hosted authorization servers.

Where it lives in the admin console

OpenID Federation is a resource of a tenant. Open OpenID Federation from the tenant's resources. The page has two areas:

• Organization is the workspace for your federation administration: the federations you take part in, the entities you publish, which resources back them, their superiors and their participations. Its tabs are Overview, Hierarchy, Resources and Records.
• Hosted federations lists the federations your organization operates as Trust Anchor and opens the operator tools for each of them.

Hosted authorization servers, credential issuers and verifiers also show an OpenID Federation area on their own pages. It lists the federation entity the resource is bound to and that entity's state in each federation, and offers Bind to an entity for that resource. The organization-wide structure stays on the OpenID Federation page.

The first time a tenant opens the page it shows Set up federation administration. Setting it up only creates the empty administration for your tenant. It does not publish, sign or trust anything.

How VDX extends the EDK

The federation model, the administration API and the public protocol endpoints come from the EDK and are the same in both products. VDX adds what a managed platform needs on top:

The admin console gives you the organization workspace and the hosted federation tools described in these guides, so you can run every step without calling the API directly.

Catalog-backed resources mean your entities publish metadata that VDX reads from the resources it already manages. An organization entity publishes the organization record, an authorization server entity publishes the metadata the server serves, a credential issuer entity publishes its served Credential Issuer Metadata, and a verifier entity publishes the verifier metadata configured for it. You do not type metadata into the federation records.

The operator entitlement lets the platform decide which tenants may run federations as Trust Anchor. A tenant can always take part in federations and can always act as an intermediate for its own branches and resources. Publishing a Trust Anchor requires the entitlement.

Recurring renewal runs on the platform scheduler. Signed statements expire, and VDX can renew them for you on a fixed interval. On EDK enterprise images, which have no recurring scheduler, renewal runs on request or from a workflow.

Principles that apply everywhere

Saving is not publishing. Creating or editing a federation, entity, binding, superior or participation only records your intent. Nothing is signed, published, trusted or registered until you run an explicit action such as Publish Entity Configuration, Sign statement or Verify admission. Each of those actions is a separate API operation with its own authorization, so your policies can treat them differently from ordinary edits.

No key appears by itself. Every entity needs a Federation Entity Key before it can publish, and VDX creates one only when you ask for it. You choose the algorithm (ES256, ES384, ES512, PS256, PS384, PS512, RS256, RS384 or RS512) and which key signs.

Trust comes from Trust Domains. Taking part in a federation does not make VDX trust other members. Whether your verifier accepts a credential issuer, or your authorization server accepts a federation client, is decided by a Trust Domain that admits the federation's Trust Anchor as an OpenID Federation entity anchor for that purpose. The federation administration keeps no separate list of trusted parties.

Signed statements expire. Entity Configurations and Subordinate Statements carry a lifetime, which deployments ship as one hour. A published revision stays valid until it expires, even after you change the administration. Plan for renewal, either on a schedule or as part of your operating routine.

Concurrent edits are detected. Every record carries a version. When someone else changed a record while you were editing, the console tells you so and shows the current state, and the API answers with a precondition failure. Review the change and try again.

Limits

Wallet provider entities are not available, because the platform has no wallet provider product that could supply their metadata. The console lists the kind, but publishing such an entity is refused.

Superior relationships can only be changed on deployments that use PostgreSQL.

Accepting federation clients on a hosted authorization server is available on the platform and enterprise tenant authorization server services, not in the single-process monolith.

Reference

The EDK guides explain the model and the protocol at API level: concepts, joining a federation, federation client registration and operating a federation. Database and statement lifetime settings for enterprise deployments are in OpenID Federation deployment.

The administration operations are in the OpenID Federation API reference under /api/platform/config/v1/tenants/{tenantId}/openid-federation. Trust Domains, anchors and attachments are in the Trust Domain API reference. Every operation needs a principal of the tenant in the path and a positive policy decision, and every change to an existing record sends the record's current version in If-Match.