OpenID Federation Entities

Federation participants, including identity providers, relying parties, intermediate authorities, and trust anchors, are collectively referred to as federation entities. Each federation entity is assigned a globally unique identifier known as an entity ID.

In the above diagram, you can distinguish different types of entities:

• Trust Anchors

• Intermediates

• Leaf Entities

Trust Anchors

Entities that represent a third parties that all other parties agree to trust:

• Superior Trust Anchor (Trust Anchor A): a Trust Anchor that is somewhere above one or more Entities (a Leaf or Intermediate) in the trust hierarchy, possibly with Intermediates between them.

• Intermediate Trust Anchors (Trust Anchors B & C): an Entity that issues an Entity Statement appearing somewhere in between those issued by the Trust Anchor–in this case, the Superior Trust Anchor A–and the subject of a Trust Chain (which is typically a Leaf Entity).

Intermediates

Entities that issue an Entity Statement appearing somewhere in between those issued by the Trust Anchor and the subject of a Trust Chain (which is, typically, a Leaf Entity–its Subordinate Entity)

Leaf Entities

Entities with no Subordinate Entities. Leaf Entities typically play a protocol role, such as:

• OpenID Provider (OP)–Identity Provider / OAuth Authorisation Server

• Resource Server (APIs)

• Relying Party (RP)–applications (client applications)

The entities listed above represent the primary types found in an OpenID Federation. However, the specification also defines several additional, less common entity types. For a complete overview, refer to the OpenID Federation specification.

Entity Statements

An Entity Statement is a signed JWT that contains the information needed for an Entity to participate in federation(s), including metadata about itself and policies that apply to other Entities that it is authoritative for.

Leaf Entity Statements

Leaf Entities (OPs/RPs) issue self-signed JWTs signed by the OPs/RPs private key.

In the example below, note that because the JWT is self-signed, both the issuer and the subject point to the Leaf Entity.

{
    "iss": "https://rp.example.org",
    "sub": "https://rp.example.org",
    "iat": 1649417862,
    "exp": 1649590602,
    "jwks": {
        "keys": [
        {
            "kty": "EC",
            "kid": "NFM1WUViUl",
            "crv": "P-256",
            "x": "…",
            "y": "…"
        }
        ]
    },
    "metadata": {
        "openid_relying_party": {
        "client_id": "https://rp.example.org",
        "redirect_uris": ["https://rp.example.org/cb"],
        "grant_types": ["authorization_code"],
        "response_types": ["code"],
        "token_endpoint_auth_method": "private_key_jwt"
        }
    },
    "authority_hints": [
        "https://ta.example.org"
    ],
    "trust_marks": [
        {
        "id": "https://fw.example.it/tm/1",
        "trust_mark": "eyJh …"
        }
    ]
}

Intermediate Entity Statement

Intermediates issue a self-signed JWT authorizing its subject entity–for example, an RP. Optionally, it can also issue its own entity statement.

{
    "iss": "https://intermediate.example.com",
    "sub": "https://rp.example.com",
    "iat": 1713883000,
    "exp": 1745419000,
    "jwks": {
        "keys": [
        {
            "kty": "EC",
            "kid": "subordinate-key-1",
            "crv": "P-256",
            "x": "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
            "y": "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"
        }
        ]
    },
    "metadata_policy": {
        "openid_relying_party": {
        "grant_types": { 
            "default": ["authorization_code"],
            "superset_of": ["authorization_code"]
        },
        "response_types": {
            "subset_of": ["code"]
        }
        }
    },
    "authority_hints": [
        "https://trust-anchor.example.org"
    ],
    "trust_marks": [
        {
        "id": "https://trust-anchor.example.org/tm/security-audit",
        "trust_mark": "eyJhbGciOiJSUzI1NiIs..."
        }
    ],
    "constraints": {
        "max_path_length": 2,
        "naming_constraints": {
        "permitted": ["example.com"]
        }
    },
    "source_endpoint": "https://intermediate.example.com/fetch"
}

Trust Anchor Entity Statement

Trust Anchor issues a JWT that directly authorizes the Leaf Entity terminating the Trust Chain. The JWT is signed using the Anchor's private key.

{
    "iss": "https://trust-anchor.example.org",
    "sub": "https://trust-anchor.example.org",
    "iat": 1713882000,
    "exp": 1745418000,
    "jwks": {
        "keys": [
        {
            "kty": "RSA",
            "kid": "ta-key-1",
            "n": "sXch...Q",
            "e": "AQAB"
        }
        ]
    },
    "metadata": {
        "federation_entity": {
        "organization_name": "Example Federation Trust Anchor",
        "contacts": ["admin@example.org"],
        "federation_fetch_endpoint": "https://trust-anchor.example.org/fetch",
        "federation_list_endpoint": "https://trust-anchor.example.org/list"
        }
    },
    "metadata_policy": {
        "openid_relying_party": {
        "grant_types": { "subset_of": ["authorization_code"] },
        "id_token_signed_response_alg": { "one_of": ["PS256"] }
        },
        "openid_provider": {
        "id_token_signing_alg_values_supported": { "one_of": ["PS256"] },
        "subject_types_supported": { "value": ["pairwise"] }
        }
    },
    "authority_hints": [],
    "trust_marks_issuers": [
        "https://trust-anchor.example.org/trust-marks"
    ]
}