OpenID Federation policy guide

How can metadata policies ensure protocol and API interoperability between federated entities such as applications, services and devices? How can a federation enforce a common security profile? This guide for federation architects explains the purpose, principles and operators of the OpenID Federation metadata policy language.

1. Application protocols rely on entity metadata

Forming a federation establishes a trust framework for its participants. They can then interact using one or more agreed protocols. In a federation for user authentication and single sign-on (SSO), the protocol can be OpenID Connect. In a federation of verifiable credential (VC) issuers, wallets and verifiers, the protocols can be based the OID4VCI and OID4VP specifications.

Protocols often require certain knowledge about the other entity prior to the transaction. For example, in OpenID Connect the identity provider needs to know at a minimum the redirection URI of the relying party in order to handle a login request from it.

To this end, OpenID Federation enables an entity to publish metadata about itself in its configuration, at a /.well-known/openid-federation endpoint. Other federation participants obtain and validate this metadata while resolving a trust chain. Metadata is grouped by entity type; for example, openid_relying_party identifies OpenID Relying Party metadata. An entity can publish metadata for several roles at once, such as both an OpenID Provider and a Relying Party.

Example metadata for an OpenID relying party:

{
  "metadata" : {
    "openid_relying_party" : {
      "redirect_uris" : [ "https://rp.example.com/cb" ],
      "client_name" : "TeamFlow App",
      "logo_uri" : "https://rp.example.com/logo.png",
      "signed_jwks_uri" : "https://rp.example.com/jwks.jwt",
      "token_endpoint_auth_method" : "private_key_jwt",
      "token_endpoint_auth_signing_alg" : "RS256"
    }
  }
}

What are the typical purposes of entity metadata?

• Enable the discovery of protocol endpoints. In OpenID Connect this can be the redirect_uri of the relying party, or the keys, authorisation and token endpoints of the identity provider.

• List supported cryptography algorithms. In OpenID Connect this can include the JWS algorithm for JWT-based client authentication.

• Configure UIs. In OpenID Connect this can be the client name and logo to display on the login screen.

• Identify supported protocol extensions. In OpenID Connect this can be extensions such as Identity Assurance / eKYC.

2. When are metadata policies needed?

Policies for published entity metadata are generally needed for two reasons:

• To ensure interoperability between entities at the protocol level – When the metadata contains optional parameters or must be configured in a certain way to ensure all entities can successfully interop with one another. In OpenID Connect an example of this is that both providers and relying parties must support a compatible client authentication method. Otherwise, a token request can fail because the client uses a method the provider does not support.

• To enforce a security profile – When the protocol and its metadata support varying levels of security and all entities in the federation must comply with a certain profile. In OpenID Connect this could for instance be a requirement to support a FAPI security profile.

Metadata policies are not a substitute for validating metadata syntax and semantics. Each operator accepts specific JSON types and produces a policy error for unsupported types, but the application layer must still validate the resolved metadata according to the specification that defines each parameter.

Metadata policies are not necessary when the following is true:

• The metadata is minimal, has no optional parameters, or otherwise cannot express configurations that are incompatible within the federation.

• The application protocol or layer can itself enforce all interoperability or security requirements of the federation.

Future protocols that are intended for use by entities in OpenID compliant federations may be designed with a strategy to require little or no special metadata policies.

3. Principles of the policy language

The OpenID Federation policy language has a compact, expressive, JSON-based syntax. Trust anchors and intermediate entities place metadata policies in the subordinate statements they issue. A regular JSON parser can parse the data structure, but the implementing software must implement the policy operators, their permitted combinations and merge rules, and the required order in which multiple operators are applied to a metadata parameter.

The policy language in OpenID Federation was designed around 6 principles:

1. Hierarchy

   Trust anchors and intermediate entities can define metadata policies for their subordinate entities. Once a policy is defined, a subordinate intermediate cannot override it, repeal it or make it more permissive.

   The principle of policy hierarchy is preserved in nested federations where a trust anchor in one federation may act as an intermediate entity in another.

2. Equal opportunity

   Intermediate entities are given the opportunity to define their own policies, as long as they do not clash with the policies of superior entities. An intermediate can for instance define a more restrictive policy, or a new policy for a metadata parameter that isn’t already controlled by superior entities.

3. Specificity and granularity

   Policies are expressed at the level of individual metadata parameters, for example token_endpoint_auth_method, and collected into an object for a given entity type, for example openid_relying_party. This ensures the policies for different entity types are independent and isolated from one another. This rule applies also to the individual metadata parameters for an entity type.

   Because each policy is carried in a subordinate statement issued for a particular subject, an authority can issue a common policy for all its immediate subordinates or a different policy for a particular subordinate.

4. Operation

   A policy is a check, a modification, or a combination of both on a given metadata parameter.

   OpenID Federation specifies 7 standard operators. A federation may define and use additional operators, provided they comply with these principles and the rules for additional operators. Unknown custom operators are ignored unless listed in metadata_policy_crit.

5. Integral metadata enforcement

   The resolution and application of metadata policies occur as part of the trust chain resolution.

   • A trust chain which has conflicting policies, for example a policy of an intermediate entity clashing with a trust anchor’s policy, is deemed invalid.

   • A trust chain whose subject metadata does not comply with the resolved metadata policy is also deemed invalid.

6. Determinism

   Policy resolution and application are deterministic, giving trust anchors and intermediates predictable and reproducible outcomes.

4. Policy structure and processing

A metadata policy is carried in the metadata_policy claim of a Subordinate Statement and has three levels: entity type, metadata parameter and operator. For example:

{
  "metadata_policy" : {
    "openid_relying_party" : {
      "id_token_signed_response_alg" : {
        "default" : "ES256",
        "one_of" : [ "ES256", "ES384", "ES512" ]
      }
    }
  }
}

Processing has two distinct stages:

1. Resolve the policy. Starting with the subordinate statement issued by the trust anchor, merge the policies down the trust chain. Each operator defines how two occurrences of that operator are merged. A conflict or a disallowed operator combination is a policy error and invalidates the trust chain.

2. Apply the resolved policy. First apply any metadata supplied by the subject’s immediate superior to the metadata from the subject’s entity configuration. Then apply the resolved policy operators in their defined order. If application produces a policy error or invalid resolved metadata, the trust chain is invalid.

The standard operator order is value, add, default, one_of, subset_of, superset_of, then essential. The order matters when several operators are combined for one parameter.

5. Operators

OpenID Federation defines 7 operators for validating and shaping entity metadata in a trust chain.

Legend:

• The table lists the JSON types that implementations are required to support. Some operators allow implementations to support other JSON types in addition to the mandatory listed above.
• ⁽¹⁾ Implementations may also support array of objects, array of numbers.
• ⁽²⁾ Implementations may also support object, number.

When the same operator occurs in policies at multiple levels of a trust chain, its values are merged as follows:

• value and default: the values must be equal.
• add and superset_of: take the union.
• one_of and subset_of: take the intersection. An empty one_of intersection is a policy error; an empty subset_of intersection is allowed.
• essential: apply logical OR, so an essential parameter cannot become voluntary lower in the hierarchy.

Policy operator: value

The value operator sets or overrides a metadata parameter.

Scenario 1

Example policy to ensure RPs will be registered to receive ID tokens with the auth_time claim, by setting the require_auth_time metadata parameter to true.

{
  "require_auth_time" : {
     "value" : true
  }
}

{}
 
 

{
  "require_auth_time" : true
}

{
  "require_auth_time" : false
}

{
  "require_auth_time" : true
}

Scenario 2

Example policy to ensure RPs cannot register a 3rd party login initiation URL, by removing any initiate_login_uri metadata parameter.

{
  "initiate_login_uri" : {
    "value" : null
  }
}

{}
 

{}
 

{
  "initiate_login_uri" : "https://example.com/login"
}

{}
 
 

Policy operator: add

The add operator adds one or more values to a metadata parameter that is a JSON array. Values already present are not added again. If the parameter is absent, it is initialised with the operator value.

Scenario 1

Example policy by an intermediate federation entity that adds the email address of its administrator to the contacts metadata parameter of subordinate RPs.

{
  "contacts" : {
    "add" : [ "admin@example.com" ]
  }
}

{}
 

{
  "contacts" : [ "admin@example.com" ]
}

{
  "contacts" : [ "support@example.com" ]
}
 

{
  "contacts" : [ "support@example.com",
                 "admin@example.com" ]
}

Scenario 2

Example policy that adds two email addresses to the contacts metadata parameter of subordinate RPs.

{
  "contacts" : {
    "add" : [ "admin@example.com", "webmaster@example.com" ]
  }
}

{}
 
 
 

{
  "contacts" : [ "admin@example.com",
                 "webmaster@example.com" ]
}

{
  "contacts" : [ "alice@example.com" ]
}
 
 

{
  "contacts" : [ "alice@example.com",
                 "admin@example.com",
                 "webmaster@example.com" ]
}

Policy operator: default

The