OpenID Federation Node Administration Protocol

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 2 March 2027.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶

Table of Contents

1. Introduction

OpenID Federation 1.1 [OIDF.Federation] defines how Federation Entities publish signed Entity Statements, build Trust Chains, apply metadata policies, and issue Trust Marks. Those mechanisms are the public protocol plane: any relying party on the Internet can fetch /.well-known/openid-federation, call federation_fetch_endpoint, and resolve a Trust Chain.¶

The specification does not define how an operator configures a node so that those public artifacts exist. In practice, Trust Anchors, Intermediate Entities, Leaf Entities, and Trust Mark Issuers are administered through vendor-specific HTTP APIs. Existing implementations [Sphereon.Admin], [GEANT.Admin], [Gateway.Admin], and [SURF.OIDFed] expose dozens of fine-grained endpoints, one for each nested claim. That style is convenient for some user interfaces. It is a poor protocol: it duplicates the OpenID Federation data model, drifts as the federation specification evolves, and forces every control plane to learn a different surface.¶

This document specifies a single, compact administration protocol that is strictly aligned with OpenID Federation 1.1:¶

• The protocol plane remains exactly as defined in [OIDF.Federation]. This document never redefines Entity Statement claims, metadata policy operators, Trust Mark claims, or federation endpoints.¶
• The administration plane writes the inputs from which the node (re)signs and publishes those artifacts.¶
• Resources correspond to independently life-cycled objects: the node itself, Federation Entity Keys, the Entity Configuration document, Immediate Subordinates, and Trust Mark issuance records.¶
• Partial updates use JSON Merge Patch [RFC7396] against those documents. Fine-grained claim URLs are unnecessary.¶

The result is a small, implementable API that Leaf nodes, Intermediates, Trust Anchors, and Trust Mark Issuers can share, advertising which resources they actually support.¶

2. Terminology

This document uses the terms Entity, Entity Identifier, Entity Configuration, Entity Statement, Entity Type, Federation Entity Keys, Immediate Superior, Immediate Subordinate, Intermediate Entity, Leaf Entity, metadata, metadata policy, Subordinate Statement, Trust Anchor, Trust Chain, Trust Mark, Trust Mark Issuer, and Trust Mark Owner as defined in [OIDF.Federation].¶

This document also uses the following terms:¶

Administration API:

The HTTP API specified in this document.¶

Administration Server:

The HTTP origin that serves the Administration API for one Federation Entity (one node).¶

Node:

A deployed Federation Entity that publishes an Entity Configuration and, depending on role, Subordinate Statements and Trust Marks.¶

Admin Document:

A JSON object that an operator reads or writes through the Administration API. An Admin Document contains OpenID Federation claims plus a small set of administration-only members (Section 9.2).¶

Protocol Plane:

The public OpenID Federation endpoints defined in Sections 8 and 9 of [OIDF.Federation], including /.well-known/openid-federation.¶

Status:

An administration-only life-cycle value that controls whether a configured object is currently published on the Protocol Plane.¶

3. Architecture

A node has two HTTP surfaces. The Protocol Plane is defined entirely by [OIDF.Federation]. It serves Entity Configurations, Subordinate Statements, Trust Marks, and related federation endpoints to unauthenticated or private_key_jwt-authenticated federation participants.¶

The Administration Plane is defined by this document. It is a confidential HTTP API used by operators and control-plane clients to create, update, suspend, and revoke the inputs from which the Protocol Plane is generated.¶

 Operator / Control Plane
          |
          |  Administration API (this document)
          |  authenticated, confidential
          v
   +------------+         signs         +----------------+
   | Admin docs | --------------------> | Protocol Plane |
   | Keys       |  Entity Config        | /.well-known/  |
   | Status     |  Subord. Statement    | fetch / list   |
   |            |  Trust Mark JWT       | resolve / TM   |
   +------------+                       +----------------+
          ^                                     |
          |                                     v
   Administration Server             Federation participants

A successful mutating Administration API request MUST leave the Protocol Plane consistent with the resulting Admin Documents before the success response is returned, with the exception of key rollover grace periods described in Section 11. Implementations MAY sign new Entity Statements lazily, provided that the next Protocol Plane response reflects the update.¶

This document does not specify multi-node orchestration, operator identity providers, or a federation-wide registry. Those are deployment concerns (Section 17).¶

4. Node Initialization

A node is initialized when it has an Entity Identifier and at least one signing-capable Federation Entity Key (the server holds the private key or can invoke a KMS to use it).¶

The Entity Identifier is established by local configuration (for example a configuration file or container image) or by the first successful PUT {base}/configuration whose body includes entity_id. After initialization the server MUST reject any write that would change entity_id (400 with problem type invalid_request).¶

GET {base} MUST succeed once the Administration Server is listening, including before initialization. Before the Entity Identifier is set, the Node document omits entity_id and signing_kid.¶

Requests that require a signature — publishing an Entity Configuration or Subordinate Statement, or issuing a Trust Mark — MUST fail with 409 and problem type not_initialized until initialization is complete.¶

5. Node Roles and Capabilities

A node plays one or more of the roles defined by [OIDF.Federation]:¶

• trust_anchor — has Immediate Subordinates and no Superior (or is treated as a Trust Anchor by its federation).¶
• intermediate — has both Immediate Superiors and Immediate Subordinates.¶
• leaf — has Immediate Superiors and no Immediate Subordinates.¶
• trust_mark_issuer — issues Trust Marks.¶
• resolver — publishes federation_resolve_endpoint.¶

The resolver role means the node publishes federation_resolve_endpoint in its Entity Configuration, typically under metadata.federation_entity. This document does not define administration of resolver state such as cached Trust Chains or the set of Trust Anchors a resolver uses. Those remain Protocol Plane behavior and local configuration ([OIDF.Federation], Sections 8.3 and 10.6). A node that is only a resolver MUST implement Node, Keys, and Entity Configuration. It MUST return unsupported_resource for Subordinates and Trust Marks unless it also plays a Superior or issuer role.¶

Roles determine which Administration API resources a node MUST implement. A node that is only a Leaf MUST implement Node, Keys, and Entity Configuration. A node that is a Superior MUST additionally implement Subordinates. A node that issues Trust Marks MUST implement Trust Marks.¶

The node advertises implemented resources in the Node resource (Section 10). Clients MUST query that resource and MUST NOT assume that every node implements every resource.¶

6. Protocol Overview

The Administration API is a set of HTTPS resources under a single base path. The default base path is /admin/v1. Servers MAY use a different base path; clients discover it from the Node resource or from deployment configuration.¶

Five resources constitute the API:¶

Each collection uses the HTTP methods in [RFC9110] with the following uniform meaning:¶

• GET — read a document or list members.¶
• POST — create a member (or invoke a controller such as rotate).¶
• PUT — replace a document.¶
• PATCH — merge-patch a document ([RFC5789], [RFC7396]).¶
• DELETE — remove a member and stop publishing it.¶

Signed protocol artifacts are available as sub-resources that return the JWT the node currently publishes:¶

• GET {base}/configuration/statement¶
• GET {base}/subordinates/{entity_id}/statement¶
• GET {base}/trust-marks/{type}/subjects/{entity_id}/token¶

That is the entire API. Nested claim paths such as /subordinates/{id}/metadata-policies/{entityType}/{claim}/{operator} are deliberately omitted. Operators who need to change one field send a JSON Merge Patch against the document that contains it.¶

7. Identifiers and Paths

A node's Entity Identifier is the iss / sub value of its Entity Configuration. It is immutable for the lifetime of the node after initialization.¶

Immediate Subordinates and Trust Mark subjects are addressed by their Entity Identifier. Trust Mark types are addressed by their trust_mark_type URI.¶

When an Entity Identifier or Trust Mark type appears as a path segment, it MUST be percent-encoded as a single segment per [RFC3986]. Clients MUST encode the entire identifier, including scheme, :, /, and ?. Servers MUST decode exactly one path segment.¶

GET /admin/v1/subordinates/https%3A%2F%2Fop.example.org

Servers MAY also accept an opaque server-assigned id as an alias. If they do, the Admin Document MUST still include the entity_id member, and listing responses MUST include both identifiers.¶

JSON Web Key kid values used as path segments MUST be percent-encoded.¶

8. Authentication and Transport

The Administration API MUST be served over HTTPS [RFC9110]. Servers and clients MUST verify TLS server identity as specified in [RFC9525].¶

Every request except OPTIONS CORS preflight (if offered) MUST be authenticated. This specification does not mandate a single authentication scheme. Servers MUST support at least one of:¶

• OAuth 2.0 Bearer tokens [RFC6749] [RFC6750];¶
• HTTP Message Signatures [RFC9421] using a Federation Entity Key, when the client is itself a Federation Entity.¶

Servers MAY additionally support mutual TLS or HTTP Basic authentication for constrained deployments. Servers MUST NOT accept unauthenticated mutating requests.¶

Authorization — which operators may create subordinates, rotate keys, or issue Trust Marks — is out of scope. Deployments SHOULD apply least-privilege roles and SHOULD record an audit trail of mutating requests.¶

9. Common Conventions

  pending --> active <--> suspended
     |          |            |
     +------> revoked <------+

{
  "items": [
    {
      "entity_id": "https://op.example.org",
      "status": "active"
    }
  ],
  "next": "LjI"
}

10. Node Resource

{
  "entity_id": "https://ta.example.org",
  "roles": ["trust_anchor", "trust_mark_issuer"],
  "base": "/admin/v1",
  "spec": "draft-kodden-oidfed-admin-00",
  "signing_kid": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
  "implementation": {
    "name": "example-node",
    "version": "1.4.2"
  },
  "capabilities": {
    "keys": ["list", "create", "rotate", "delete"],
    "configuration": ["read", "replace", "patch"],
    "subordinates": ["list", "create", "read", "replace",
                     "patch", "delete", "status", "statement"],
    "trust_marks": ["list", "create", "read", "replace",
                    "delete", "grant", "status", "token"]
  }
}

11. Federation Entity Keys

Federation Entity Keys are the keys whose public halves appear in the jwks claim of the node's Entity Configuration as a JSON Web Key Set [RFC7517] and that sign Entity Statements and Trust Marks as JSON Web Signatures [RFC7515] ([OIDF.Federation], Sections 3.1.1 and 7). Entity Statements and Trust Marks are JWTs [RFC7519]. Protocol keys carried under Entity Type metadata are not managed here; they are ordinary members of metadata.¶

{
  "kid": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
  "status": "active",
  "signing": true,
  "alg": "ES256",
  "kty": "EC",
  "public_jwk": {
    "kty": "EC",
    "crv": "P-256",
    "kid": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
    "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
    "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
  },
  "created_at": 1756454400
}

{
  "generate": {
    "kty": "EC",
    "crv": "P-256",
    "alg": "ES256"
  }
}

{
  "import": {
    "kty": "EC",
    "crv": "P-256",
    "x": "...",
    "y": "...",
    "alg": "ES256"
  }
}

{
  "generate": { "kty": "EC", "crv": "P-256", "alg": "ES256" },
  "switch_after": 86400
}

12. Entity Configuration

The Entity Configuration Admin Document is the operator-editable content of the node's self-signed Entity Statement. The server supplies iss, sub, iat, exp, and jwks when it signs. The operator supplies the remaining Entity Configuration claims.¶

{
  "entity_id": "https://ta.example.org",
  "lifetime": 86400,
  "authority_hints": [],
  "metadata": {
    "federation_entity": {
      "organization_name": "Example Trust Anchor",
      "federation_fetch_endpoint": "https://ta.example.org/fetch",
      "federation_list_endpoint": "https://ta.example.org/list",
      "federation_trust_mark_status_endpoint":
        "https://ta.example.org/trust-mark-status"
    }
  },
  "trust_marks": [],
  "trust_mark_issuers": {
    "https://ta.example.org/marks/research": [
      "https://ta.example.org"
    ]
  },
  "trust_mark_owners": {}
}

13. Subordinates

The Subordinates resource is implemented by Trust Anchors and Intermediate Entities. Leaf nodes MUST return 404 with problem type unsupported_resource for every path under {base}/subordinates.¶

A Subordinate Admin Document is the operator-editable content of the Subordinate Statement the node will sign about one Immediate Subordinate.¶

{
  "entity_id": "https://op.example.org",
  "status": "active",
  "lifetime": 86400,
  "jwks": {
    "keys": [
      {
        "kty": "EC",
        "crv": "P-256",
        "kid": "op-fed-1",
        "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
        "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
      }
    ]
  },
  "metadata": {
    "openid_provider": { "organization_name": "Example University" }
  },
  "metadata_policy": {
    "openid_relying_party": {
      "id_token_signed_response_alg": {
        "default": "ES256",
        "one_of": ["ES256", "ES384", "ES512"]
      }
    }
  },
  "constraints": {
    "max_path_length": 1,
    "naming_constraints": { "permitted": [".example.org"] },
    "allowed_entity_types": [
      "openid_provider",
      "openid_relying_party"
    ]
  }
}

14. Trust Marks

The Trust Marks resource is implemented by Trust Mark Issuers. Other nodes MUST return 404 with problem type unsupported_resource for every path under {base}/trust-marks.¶

This resource manages Trust Marks this node issues to subjects. Recognition claims (trust_mark_issuers, trust_mark_owners) and Trust Marks this node holds about itself (trust_marks) are Configuration Document members (Section 12).¶

{
  "trust_mark_type": "https://ta.example.org/marks/research",
  "lifetime": 31536000,
  "logo_uri": "https://ta.example.org/marks/research.png",
  "ref": "https://ta.example.org/marks/research/policy"
}

{
  "entity_id": "https://op.example.org",
  "trust_mark_type": "https://ta.example.org/marks/research",
  "status": "active",
  "iat": 1756458000,
  "exp": 1787994000
}

15. Errors

Error responses MUST use HTTP status codes consistently with [RFC9110] and a [RFC9457] body:¶

{
  "type":
    "urn:ietf:params:oidfed:admin:problem#invalid_federation_claim",
  "title": "Invalid federation claim",
  "status": 400,
  "detail": "authority_hints must not be empty on a leaf node",
  "pointer": "/authority_hints"
}

pointer is an OPTIONAL JSON Pointer to the offending member.¶

The type URI is formed by appending # and the token to urn:ietf:params:oidfed:admin:problem (Section 20).¶

16. Relationship to OpenID Federation 1.1

This section is normative regarding consistency and informative regarding existing products. OpenID Federation 1.1 [OIDF.Federation] is the protocol-independent split of OpenID Federation 1.0. It introduces no new federation mechanisms. OpenID Connect and OAuth metadata types used in examples (openid_provider, openid_relying_party) are defined in [OIDF.Connect].¶

A node that implements this API MUST still implement the Protocol Plane required by its roles. Implementing this API does not satisfy any Protocol Plane requirement.¶

[Sphereon.Admin], [GEANT.Admin], and the OpenAPI contract shipped with [Gateway.Admin] expose a large set of nested resources that map onto the documents in this specification: entity-configuration metadata, authority hints, and published JWKS collapse to Section 12 plus Section 11; per-subordinate metadata, policy, constraints, and JWKS collapse to Section 13; trust-mark types, issuance specs, and subjects collapse to Section 14. Control-plane products such as [SURF.OIDFed] and [Gateway.Admin] sit above this API.¶

17. Deployment Considerations

The Administration API and the Protocol Plane MAY share an origin or MAY use distinct origins. Distinct origins are RECOMMENDED so that operator credentials never appear on the host that federation participants contact.¶

When origins differ, the Entity Identifier remains the Protocol Plane identifier. The Administration API base URL is local configuration. It MUST NOT be published in Entity Configuration metadata.¶

A control plane that manages several nodes MUST address each Administration Server separately. This document does not define a multi-node collection resource.¶

Servers SHOULD emit structured audit records for every mutating request, as specified in Section 18.10. This document does not define an Administration API resource for querying or managing those records.¶

18. Security Considerations

The Administration API can change the trust fabric of a federation. Compromise of Administration API credentials is equivalent to compromise of the node's Federation Entity Keys for the purpose of issuing statements the rest of the federation will accept.¶

19. Privacy Considerations

The Administration API handles identifiers and metadata that often relate to organizations and, in audit logs, to individual operators. This section follows the guidance of [RFC6973].¶

Entity Identifiers, organization_name, logo_uri, and similar metadata members are published on the Protocol Plane once written. Operators MUST treat Admin Document writes as publication. Contact addresses and other optional metadata SHOULD be limited to what the federation policy requires.¶

Trust Marks bind an accreditation statement to an Entity Identifier. Issuing or revoking a mark is visible to any party that can query the issuer's Trust Mark status endpoint.¶

Audit records contain operator identities distinct from the node's Entity Identifier (Section 18.10). Those records MUST be access-controlled independently of the Protocol Plane and SHOULD NOT be written to the same log streams that serve public federation endpoints. Retention of operator identifiers is a local matter. Servers MUST NOT copy operator identities into Entity Statements or Trust Marks.¶

Because the Administration API is confidential, responses MUST NOT be cached by shared caches. Distinct Administration and Protocol Plane origins (Section 17) reduce the risk that a browser or intermediary mixes the two.¶

20. IANA Considerations

This document makes no Well-Known URI registration. The Administration API is not discovered via /.well-known/openid-federation.¶

IANA is requested to register the following value in the "IETF URN Sub-namespace for Registered Protocol Parameter Identifiers" registry established by [RFC3553]:¶

• URI: urn:ietf:params:oidfed:admin¶
• Description: OpenID Federation Node Administration Protocol¶
• Reference: this document¶

Problem-type tokens in Section 15 are relative to urn:ietf:params:oidfed:admin:problem.¶

Complete Message Examples

This appendix shows a Trust Anchor admitting an OpenID Provider and issuing a Trust Mark. Host names and keys are illustrative.¶

POST /admin/v1/subordinates HTTP/1.1
Host: ta.example.org
Authorization: Bearer 6f3c...
Content-Type: application/json

{
  "entity_id": "https://op.example.org",
  "jwks": {
    "keys": [{
      "kty": "EC", "crv": "P-256", "kid": "op-fed-1",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
    }]
  },
  "metadata": {
    "openid_provider": {
      "organization_name": "Example University"
    }
  },
  "constraints": {
    "max_path_length": 0,
    "allowed_entity_types": ["openid_provider"]
  }
}

PATCH /admin/v1/subordinates/https%3A%2F%2Fop.example.org HTTP/1.1
Host: ta.example.org
Authorization: Bearer 6f3c...
Content-Type: application/merge-patch+json
If-Match: "s1"

{
  "metadata_policy": {
    "openid_provider": {
      "id_token_signing_alg_values_supported": {
        "subset_of": ["ES256", "ES384"]
      }
    }
  }
}

Operation Catalog

The following operations are all of the protocol operations. Feature subsets are expressed only by omitting keys from capabilities. A Leaf implements the Node, Keys, and Configuration operations (ten). A Trust Anchor that also issues Trust Marks implements all twenty-eight. Paths in the catalog are relative to {base}.¶

Acknowledgements

This document draws operational experience from the Sphereon OpenID Federation Admin Server, the GÉANT Trust and Identity Incubator Federation Admin API, the Federation Gateway project, and the SURF OpenID Federation control plane and node implementations. The data model is that of OpenID Federation 1.1; any elegance in this API comes from not inventing another one.¶

Author's Address