| OpenID Federation | December 2024 | |
| Hedberg, et al. | Standards Track | [Page] |
A federation can be expressed as an agreement between parties that trust each other. In bilateral federations, direct trust can be established between two organizations belonging to the same federation. In a multilateral federation, bilateral agreements might not be practical, in which case, trust can be mediated by a third party. That is the model used in this specification.¶
An Entity in the federation must be able to trust that other Entities it interacts with belong to the same federation. It must also be able to trust that the information the other Entities publish about themselves has not been tampered with during transport and that it adheres to the federation's policies.¶
This specification defines basic components used to build multilateral federations and describes how to apply them when the underlying authentication protocol used is OpenID Connect or the underlying authorization protocol is OAuth 2.0. However, these components can also be used for trust establishment with other application protocols.¶
This specification describes how two Entities that would like to interact can establish trust between them by means of a trusted third party called a Trust Anchor. A Trust Anchor is an Entity whose main purpose is to issue statements about Entities. An identity federation can be realized using this specification using one or more levels of authorities. Examples of authorities are federation operators, organizations, departments within organizations, and individual sites. This specification provides the basic technical trust infrastructure building blocks needed to create a dynamic and distributed trust network, such as a federation.¶
Note that this specification only concerns itself with how Entities in a federation get to know about each other. An organization MAY be represented by more than one Entity in a federation. An Entity MAY also belong to more than one federation. Determining that two Entities belong to the same federation is the basis for establishing trust between them in this specification.¶
Of course, the word "trust" is also used in the vernacular to encompass confidence in the security, reliability, and integrity of entities and their actions. This kind trust is often established through empirical proof, such as past performance, security certifications, or transparent operational practices, which demonstrate a track record of adherence to security standards and ethical conduct. To be clear, this broader meaning of trust, while important, is largely beyond the scope of what this specification accomplishes.¶
Below is an example of two federations rooted at two different Trust Anchors with some members in common. Every Entity is able to establish mutual trust with any other Entity by means of having at least one common Trust Anchor between them.¶
.-----------------. .-----------------.
| Trust Anchor A | | Trust Anchor B |
'------.--.-------' '----.--.--.------'
| | | | |
.--' '---. .-------------------' | |
| | | | |
.---v. .-----v-v------. .-----------' |
| OP | | Intermediate | | |
'----' '--.--.--.-----' | .---------v----.
| | | | | Intermediate |
.-------' | '------. | '---.--.--.----'
| | | | | | |
.--v-. .-v--. .v--v. .---' | '----.
| RP | | RS | | OP | | | |
'----' '----' '----' | .--v-. .-v--.
| | RP | | RP |
| '----' '----'
|
.-------v------.
| Intermediate |
'----.--.--.---'
| | |
.-----' | '----.
| | |
.--v-. .--v-. .-v--.
| OP | | RP | | AS |
'----' '----' '----'
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174].¶
All uses of JSON Web Signature (JWS) [RFC7515] and JSON Web Encryption (JWE) [RFC7516] data structures in this specification utilize the JWS Compact Serialization or the JWE Compact Serialization; the JWS JSON Serialization and the JWE JSON Serialization are not used.¶
This specification uses the terms "Claim", "Claim Name", "Claim Value", "JSON Web Token (JWT)", and "JWT Claims Set" defined by JSON Web Token (JWT) [RFC7519], the terms "OpenID Provider (OP)" and "Relying Party (RP)" defined by OpenID Connect Core 1.0 [OpenID.Core], and the terms "Authorization Endpoint", "Authorization Server", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", and "Token Endpoint" defined by OAuth 2.0 [RFC6749].¶
This specification also defines the following terms:¶
https scheme,
have a host component, and MAY contain port and path components.
It MUST NOT contain query parameter or fragment components.¶
The basic component is the Entity Statement, which is a cryptographically signed JSON Web Token (JWT) [RFC7519]. A set of Entity Statements can form a path from an Entity (typically a Leaf Entity) to a Trust Anchor. Entity Configurations issued by Entities about themselves control the Trust Chain resolution process.¶
The Entity Configuration of a Leaf or Intermediate Entity contains one or more
references to its Immediate Superiors in the
authority_hints parameter
described in Section 3.
These references can be used to download the Entity Configuration of each Immediate Superior.
One or more Entity Configurations are traversed during the Federation Entity Discovery
until the Trust Anchor is reached.¶
The Trust Anchor and its Intermediates issue Entity Statements about their Immediate Subordinate Entities called Subordinate Statements. The sequence of Entity Configurations and Subordinate Statements that validate the relationship between a Superior and a Subordinate, along a path towards the Trust Anchor, forms the proof that the subject of Trust Chain (typically a Leaf Entity) is a member of the federation rooted at the Trust Anchor.¶
The chain that links the statements to one another is verified with the signature of each statement, as described in Section 4.¶
Once there is a verified Trust Chain, the federation policy is applied and the metadata for the Trust Chain subject within the Federation is derived, as described in Section 6.¶
This specification deals with trust operations; it does not cover or touch protocol operations other than metadata derivation and exchange. In OpenID Connect terms, these are the protocol operations specified in OpenID Connect Discovery 1.0 [OpenID.Discovery] and OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration].¶
OpenID Connect is used in many of the examples in this specification, however this does not mean that this specification can only be used with OpenID Connect. On the contrary, it can also be used to build federations for any other protocols.¶
The objects defined by this specification that are used to establish cryptographic trust between participants are secured as signed JWTs using public key cryptography. In particular, the keys used for securing these objects are managed by the Entities controlling those objects, with the public keys securing them being distributed through those objects themselves. This kind of trust mechanism has been utilized by research and academic federations for over a decade.¶
Note that this cryptographic trust mechanism intentionally does not rely on Web PKI / TLS certificates for signing keys. Which TLS certificates are considered trusted can vary considerably between systems depending upon which certificate authorities are considered trusted and there are have been notable examples of ostensibly trusted certificates being compromised. For those reasons, this specification explicitly eschews reliance on Web PKI in favor of self-managed public keys, in this case, keys represented as JSON Web Keys (JWKs) [RFC7517].¶
An Entity Statement contains the information needed for the Entity that is the subject of the Entity Statement to participate in federation(s). An Entity Statement is a signed JWT. The subject of the JWT is the Entity itself. The issuer of the JWT is the party that issued the Entity Statement. All Entities in a federation publish an Entity Statement about themselves called an Entity Configuration. Superior Entities in a federation publish Entity Statements about their Immediate Subordinate Entities called Subordinate Statements.¶
Entity Statement JWTs MUST be explicitly typed, by setting the
typ header parameter to
entity-statement+jwt to prevent
cross-JWT confusion, per Section 3.11 of [RFC8725].
Entity Statements without a typ header parameter
or with a different typ value MUST be rejected.¶
The Entity Statement is signed using one of the private keys of the issuer
Entity in the form of a JSON Web Signature
(JWS) [RFC7515].
Implementations SHOULD support signature verification with
the RSA SHA-256 algorithm because OpenID Connect Core
requires support for it (alg
value of RS256).
Federations MAY also specify different mandatory-to-implement algorithms.¶
Entity Statement JWTs MUST include the
kid (Key ID) header parameter
with its value being the Key ID of the signing key used.¶
The claims in an Entity Statement are:¶
iss and
the sub are identical,
the issuer is making an Entity Statement about itself
called an Entity Configuration.¶
REQUIRED. A JSON Web Key Set (JWKS) [RFC7517]
representing the public part of the subject's Federation Entity
signing keys. The corresponding private key is
used by the Entity to sign the Entity Configuration about itself,
by Trust Anchors and Intermediate Entities
to sign Subordinate Statements about their Immediate Subordinates,
and for other signatures made by Federation Entities,
such as Trust Mark signatures.
This claim is only OPTIONAL for the Entity Statement returned
from an OP when the client is doing Explicit Registration;
in all other cases, it is REQUIRED.
Every JWK in the JWK Set MUST have a unique kid (Key ID) value.
It is RECOMMENDED that the Key ID be the JWK Thumbprint [RFC7638]
using the SHA-256 hash function of the key.¶
These Federation Entity Keys SHOULD NOT be used in other protocols.
(Keys to be used in other protocols, such as OpenID Connect,
are conveyed in the metadata elements
for the protocol's Entity Type Identifiers,
such as the metadata under the
openid_provider and
openid_relying_party
Entity Type Identifiers.)¶
OPTIONAL. JSON object that represents the Entity's Types and the metadata for those Entity Types. Each member name of the JSON object is an Entity Type Identifier, and each value MUST be a JSON object containing metadata parameters according to the metadata schema of the Entity Type.¶
When an Entity participates in a federation or federations with
one or more Entity Types, its Entity Configuration MUST contain a
metadata claim with JSON object values
for each of the corresponding Entity Type Identifiers, even if the
values are the empty JSON object {}
(when the Entity Type has no associated metadata or Immediate
Superiors supply any needed metadata).¶
An Immediate Superior MAY provide selected or all metadata
parameters for an Immediate Subordinate, by using the
metadata claim in a Subordinate
Statement. When metadata is used in a
Subordinate Statement, it applies only to those Entity Types that
are present in the subject's Entity Configuration. Furthermore,
the metadata applies only to the subject of the Subordinate
Statement and has no effect on the subject's Subordinates.
Metadata parameters in a Subordinate Statement have precedence and
override identically named parameters under the same Entity Type
in the subject's Entity Configuration. If both
metadata and
metadata_policy appear in a
Subordinate Statement, then the stated
metadata MUST be applied before the
metadata_policy, as described in
Section 6.1.4.2.¶
metadata_policy
from metadata, which only applies to
the subject itself.¶
crit (critical) claim
defined in Section 13.4 be understood and processed.
Claims in the Entity Statement whose claim names are in the array
that is the value of this claim MUST be understood and processed.
Claims specified for use in Entity Statements by this specification
MUST NOT be included in the list.¶
[]. If any of the listed policy
operators are not understood and supported, then the Subordinate
Statement and thus the Trust Chain that includes it MUST be
considered invalid.¶
OPTIONAL. An array of JSON objects, each representing a Trust Mark. Each JSON object MUST contain the following two claims and MAY contain other claims. All the claims in the JSON object MUST have the same values as those contained in the Trust Mark JWT.¶
trust_mark_id
claim contained in the
Trust Mark JWT.¶
Trust Marks are described in Section 7. This claim SHOULD only be used in Entity Configurations.¶
OPTIONAL. If a Federation Operator knows that a Trust Mark identifier is owned by an Entity different from the Trust Mark Issuer, then that knowledge MUST be expressed in this claim. This claim MUST be ignored if present in an Entity Configuration for an Entity that is not a Trust Anchor. It is a JSON object with member names that are Trust Mark identifiers and each corresponding value being a JSON object with these members:¶
Other members MAY also be defined and used. This claim MUST NOT be present in Subordinate Statements.¶
federation_fetch_endpoint
of the issuing authority.
If an Entity Statement cannot be retrieved from the
source_endpoint,
which can occur if the endpoint URL has changed,
the current federation_fetch_endpoint
location can be determined by retrieving
the Entity Configuration of the issuer.¶
Applications and protocols utilizing Entity Statements MAY specify and use additional claims.¶
The following is a non-normative example of the JWT Claims Set for an Entity Statement.
The example contains
a critical extension jti (JWT ID) to the
Entity Statement and one critical extension to the policy language
regexp
(Regular expression).¶
{
"iss": "https://feide.no",
"sub": "https://ntnu.no",
"iat": 1516239022,
"exp": 1516298022,
"jwks": {
"keys": [
{
"kty": "RSA",
"alg": "RS256",
"use": "sig",
"kid": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
"n": "pnXBOusEANuug6ewezb9J_...",
"e": "AQAB"
}
]
},
"metadata": {
"openid_provider": {
"issuer": "https://ntnu.no",
"organization_name": "NTNU"
},
"oauth_client": {
"organization_name": "NTNU"
}
},
"metadata_policy": {
"openid_provider": {
"id_token_signing_alg_values_supported":
{"subset_of": ["RS256", "RS384", "RS512"]},
"op_policy_uri": {
"regexp":
"^https:\/\/[\\w-]+\\.example\\.com\/[\\w-]+\\.html"}
},
"oauth_client": {
"grant_types": {
"one_of": ["authorization_code", "client_credentials"]
}
}
},
"constraints": {
"max_path_length": 2
},
"crit": ["jti"],
"metadata_policy_crit": ["regexp"],
"source_endpoint": "https://feide.no/federation_api/fetch",
"jti": "7l2lncFdY6SlhNia"
}
The following is a non-normative example of
a trust_mark_owners claim value:¶
{
"https://refeds.org/wp-content/uploads/2016/01/Sirtfi-1.0.pdf":
{
"sub": "https://refeds.org/sirtfi",
"jwks" : {
"keys": [
{
"alg": "RS256",
"e": "AQAB",
"kid": "key1",
"kty": "RSA",
"n": "pnXBOusEANuug6ewezb9J_...",
"use": "sig"
}
]
}
}
}
trust_mark_owners Claim Value
The following is a non-normative example of
a trust_mark_issuers claim value:¶
{
"https://openid.net/certification/op": [],
"https://refeds.org/wp-content/uploads/2016/01/Sirtfi-1.0.pdf":
["https://swamid.se"]
}
trust_mark_issuers Claim Value
Entities whose statements build a Trust Chain are categorized as:¶
A Trust Chain begins with an Entity Configuration that is the subject of the Trust Chain, which is typically a Leaf Entity. The Trust Chain has zero or more Subordinate Statements issued by Intermediates about their Immediate Subordinates, and includes the Subordinate Statement issued by the Trust Anchor about the top-most Intermediate (if there are Intermediates) or the Trust Chain subject (if there are no Intermediates). The Trust Chain logically always ends with the Entity Configuration of the Trust Anchor, even though it MAY be omitted from the JSON array representing the Trust Chain in some cases.¶
The Trust Chain contains the configuration of the federation as it applies to the Trust Chain subject at the time of the evaluation of the chain.¶
A simple example: If we have an RP that belongs to Organization A that is a member of Federation F, the Trust Chain for such a setup will contain the following Entity Statements:¶
an Entity Configuration about the RP published by itself,¶
a Subordinate Statement about the RP published by Organization A,¶
a Subordinate Statement about Organization A published by the Trust Anchor for F,¶
an Entity Configuration about the Trust Anchor for F published by itself.¶
Let us refer to the Entity Statements in the Trust Chain as ES[j], where j = 0,...,i, with 0 being the index of the first Entity Statement and i being the zero-based index of the last. Then:¶
ES[0] (the Entity Configuration of the Trust Chain subject) is signed using a key in ES[0]["jwks"].¶
The iss claim in an Entity Statement
is equal to the sub claim in the next.
Restating this symbolically,
for each j = 0,...,i-1,
ES[j]["iss"] == ES[j+1]["sub"].¶
An Entity Statement is signed using a key from
the jwks claim in the next.
Restating this symbolically,
for each j = 0,...,i-1,
ES[j] is signed by a key in ES[j+1]["jwks"].¶
ES[i] (the Trust Anchor's Entity Configuration in the Trust Chain) is signed using a key in ES[i]["jwks"].¶
The Trust Anchor's public keys are used to verify the signatures on ES[i] (the Trust Anchor's Entity Configuration) and ES[i-1] (the Trust Anchor's Subordinate Statement about its Immediate Subordinate in the Trust Chain). The Trust Anchor's public keys are distributed to Entities that need to verify a Trust Chain in some secure out-of-band way not described in this document.¶
A Trust Chain begins with the Entity Configuration of an Entity for which trust is being established. This is the subject of the Trust Chain. This Entity typically plays a protocol role, such as being an OpenID Provider or OpenID Relying Party.¶
While such Entities are typically Leaf Entities, other topologies are possible. For instance, an Entity might simultaneously be an OpenID Provider and an Intermediate Entity, with OpenID Relying Parties and/or other Intermediates being Subordinate to it. This is a case in which the subject of a Trust Chain would not be a Leaf Entity.¶
A Trust Chain ends with the Entity Configuration of a Trust Anchor. While Trust Anchors typically have no Superiors, a Trust Anchor will have a Superior when the Trust Anchor also acts as an Intermediate Entity in another federation. This will be the case when there is a hierarchy of federations.¶
Thus, while it is typical for a Trust Chain to end with a Trust Anchor with no Superiors, there are situations in which the Trust Chain will end with a Trust Anchor that nonetheless has Superior Entities.¶
The following is an example of a Trust Chain consisting of
a Leaf's Entity Configuration and Subordinate Statements issued
by an Intermediate Entity and a Trust Anchor. It shows
the relationship between the three Entities,
their Entity Configurations, and their Subordinate Statements.
The Subordinate Statements are obtained from the
federation_fetch_endpoint of
the subject's Immediate Superior. The URL of the
federation_fetch_endpoint is
discovered in the Immediate Superior's Entity Configuration.
Note that the first member of the Trust Chain (the Leaf)
is depicted at the bottom of the diagram and that the last
member (the Trust Anchor) is depicted at the top.¶
.----------------. .---------------------------. .---------------------------. | Role | | .well-known/ | | Trust Chain | | | | openid-federation | | | .----------------. .---------------------------. .---------------------------. | .------------. | | .-----------------------. | | .-----------------------. | | | | | | | Entity Configuration | | | | Entity Configuration | | | |Trust Anchor+-+--+-> +-+---------+-> | | | | | | | | Federation Entity Keys| | | | Federation Entity Keys| | | '-----.------' | | | Metadata | | | | Metadata | | | | | | | Trust Mark Issuers | | | | Trust Mark Issuers | | | | | | | Constraints | | | | Constraints | | | | | | | | | | | | | | | | | '-----------------------' | | '-----------------------' | | | | | | | | | | | | |Fetch | .-----------------------. | | | | | |Endpoint | | Subordinate Statement | | | +--------+--+---------------------------+---------+-> | | | | | | | | Federation Entity Keys| | | | | | | | Metadata Policy | | | | | | | | Metadata | | | | | | | | | | | | | | | '-----------.-----------' | | .------------. | | .-----------------------. | | | | | | | | | | Entity Configuration | | | | | | |Intermediate+-+--+-> | | | |sub and key | | | | | | | Federation Entity Keys| | | | binding | | '------.-----' | | | Metadata | | | .-----------v-----------. | | | | | | Trust Marks | | | | Subordinate Statement | | | | | | | | | | | | | | | | | | | | | | Federation Entity Keys| | | | | | '-----------------------' |Fetch | | Metadata Policy | | | | | | |Endpoint | | Metadata | | | +-------+--+---------------------------+---------+-> | | | | | | | '-----------.-----------' | | | | | | |sub and key | | | | | | | binding | | .------------. | | .-----------------------. | | .-----------v-----------. | | | | | | | Entity Configuration | | | | Entity Configuration | | | | Leaf +-+--+-> +-+---------+-> | | | | | | | | Federation Entity Keys| | | | Federation Entity Keys| | | '------------' | | | Metadata | | | | Metadata | | | | | | Trust Marks | | | | Trust Marks | | | | | | | | | | | | | | | | | | | | | | | | | '-----------------------' | | '-----------------------' | '----------------' '---------------------------' '---------------------------'
The trust_chain JWS header parameter is a
JSON array containing the sequence of the statements
that proves the trust relationship between the issuer of the
JWS [RFC7515]
and the selected Trust Anchor, sorted as shown in Section 4.
The Trust Chain contains the public key used to verify the
JWS [RFC7515].
The issuer of the JWS SHOULD select the Trust Anchor that it has in common
with the audience of the JWS.
Otherwise, the issuer is free to select a Trust Anchor.
Most signed JWTs MAY include the
trust_chain JWS header parameter,
with a few exceptions.
Entity Configurations and Subordinate Statements MUST NOT
contain the trust_chain header parameter,
as they are integral components of a Trust Chain. Additionally,
the Authorization Signed Request Object SHOULD NOT contain the
trust_chain header parameter, because
the trust_chain
parameter is intended to be part of its JWS payload, as defined in
Section 12.1.1.1.
Use of this header parameter is OPTIONAL.¶
The following is a non-normative example of a JWS header with
the trust_chain parameter.¶
{
"typ": "...",
"alg": "RS256",
"kid": "SUdtUndEWVY2cUFDeDV5NVlBWDhvOXJodVl2am1mNGNtR0pmd",
"trust_chain": [
"eyJhbGciOiJSUzI1NiIsImtpZCI6ImMzWnlUR1ZTY0RNeFowd3dka1pQVVZZMFMyRkVRMnBYVjE4dFVFd3ROVlZIV21WVVEwTmlTM2xVU1EiLCJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2OTY1ODMzMzQsImlhdCI6MTY5NjI4MzMzNCwiaXNzIjoiaHR0cHM6Ly9jcmVkZW50aWFsX2lzc3Vlci5leGFtcGxlLm9yZyIsInN1YiI6Imh0dHBzOi8vY3JlZGVudGlhbF9pc3N1ZXIuZXhhbXBsZS5vcmciLCJqd2tzIjp7ImtleXMiOlt7Imt0eSI6IlJTQSIsImtpZCI6ImMzWnlUR1ZTY0RNeFowd3dka1pQVVZZMFMyRkVRMnBYVjE4dFVFd3ROVlZIV21WVVEwTmlTM2xVU1EiLCJlIjoiQVFBQiIsIm4iOiIwNmZfWUd0ejhyY29WQWZSUnlNbldYbmNteVRFc3lmUHh6OVlXdlRjT0c1WGtIQ244c1ZCa3hjVENleDFvdWtxZVlVLU0xcUE3ZXE4RmNMRDJHUEVxVHNITDBRNVNMLXVYSUlYd2hSSmx3bWpRNWh1dEdnV3ptMUVOc0g0SENyV3EwNmJGLTRpUFFpUVUxRm1kVXdxVTI5clVqTnlmeUlLTmd1cFJPZ2p1Y3ozcWYtWE1ZdU5SRnFFcld0b3N0dHE1bm4zdFlSNWh5UWpVWnVwNHZPUnFhUUROMUxiVEk5d2cxRzlxRjlxQUxDcGk0WlNmclJyWEphZDUtamwtS1VOdFM1cG5hbGlHRFF2a3AxTnJCaXBJT19haTFvR21BMTlHd1E4VGpNVkNFc3ZXUXpKcTVrd0N1eHVKZTlBODE1RzRuU2I1WFp1RXZ6anhNU1M4b3hpLVEifV19LCJtZXRhZGF0YSI6eyJvcGVuaWRfY3JlZGVudGlhbF9pc3N1ZXIiOnsiandrcyI6eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJraWQiOiJSMlJ6UlhBMFJWQnlkekZPVkcxZmRXUlRNVFozWVRSbU5uRTFWM0ZmTUUxb01VWkxla2xpWTFOWU9BIiwiZSI6IkFRQUIiLCJuIjoiNUhfWGg3eGdEV1R4UVZiSnFtT0d1cm9rRThrcjJlMUtnTVdjWU9BNzRPXzFQWGQydWdqeUlxOXQxbVZQU3V3eC10eVNrMlBLcGpwLS1XckhuM0E0VUtKa3VSMTF6aG1kTEJzVThUT0JCdTVNWjhhdER1amZSd0lMWGRLc0VYa2x2YUI2UExUNHpkWm9kZ0NzMDVLeTJlNXNiNXo2X0NpRHFnVVZuV1BtSkxNa2dwQnRaLWtNZF9sYjlTb29abGxmVUdsVGtzYXVKMl9nVlEtVnBGVU1YWWpvSmpOeDk3ZXVrYVluUkVvQ0MzVGFfLThiY1Jvc2x4MnhySWJ1X1VHVnFpcGVOM05QLW1lZmY5VlRaV1lNM2dtb2x3dXBuTUNYWGlpa2NSNVVTTFZnMGVfZ3o2T2ZvUlZHS0FXSXBSUkxUejJhaXF1a1ZIWmRaWDl0Tm16MG13In1dfX0sImZlZGVyYXRpb25fZW50aXR5Ijp7Im9yZ2FuaXphdGlvbl9uYW1lIjoiT3BlbklEIENyZWRlbnRpYWwgSXNzdWVyIGV4YW1wbGUiLCJob21lcGFnZV91cmkiOiJodHRwczovL2NyZWRlbnRpYWxfaXNzdWVyLmV4YW1wbGUub3JnL2hvbWUiLCJwb2xpY3lfdXJpIjoiaHR0cHM6Ly9jcmVkZW50aWFsX2lzc3Vlci5leGFtcGxlLm9yZy9wb2xpY3kiLCJsb2dvX3VyaSI6Imh0dHBzOi8vY3JlZGVudGlhbF9pc3N1ZXIuZXhhbXBsZS5vcmcvc3RhdGljL2xvZ28uc3ZnIiwiY29udGFjdHMiOlsidGVjaEBjcmVkZW50aWFsX2lzc3Vlci5leGFtcGxlLm9yZyJdfX0sImF1dGhvcml0eV9oaW50cyI6WyJodHRwczovL2ludGVybWVkaWF0ZS5laWRhcy5leGFtcGxlLm9yZyJdfQ.WM0dOdLOhC9UTRi_y6lwwu6PmUWv1wc5f8MhKP2qz6b1haa-eyf4Y60iZ2SDeFeg105wHwPSKN8AfRoNyqubOGZMAFmP-sYBeqZatNsGNWjFEHzI9dJwx1oBab5_TDoULarpKSdvuub4NBOBTKFUSDffBG6jzlaK5JiQzMR30-jqSt9qPPWrJepyLQvyFxmvn94OiNQQwJ0oYB1MecJ7r8gmQMCAH4LixD6amKQoCuN0UeN7iEHTs3z_8ZUDihQ7BHf0dtwDCmG_G7xvaNkLPkG6cP2e2-l5kcYbNaUaK0IsX2yB0BkoQOOHlT-_M2TC2Zzg6Nmmw8WpTeraMrSkIQ",
"eyJhbGciOiJSUzI1NiIsImtpZCI6IlpsSndObTQ1VDJsVWNYbEhUR2cxWldobGJsZGpVV2xsY21RdFNVbFFXWHBIUzFKRVEwOHlUV1Z2TkEiLCJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2OTY1ODMzMzQsImlhdCI6MTY5NjI4MzMzNCwiaXNzIjoiaHR0cHM6Ly9pbnRlcm1lZGlhdGUuZWlkYXMuZXhhbXBsZS5vcmciLCJzdWIiOiJodHRwczovL2NyZWRlbnRpYWxfaXNzdWVyLmV4YW1wbGUub3JnIiwiandrcyI6eyJrZXlzIjpbeyJrdHkiOiJSU0EiLCJraWQiOiJjM1p5VEdWU2NETXhaMHd3ZGtaUFVWWTBTMkZFUTJwWFYxOHRVRXd0TlZWSFdtVlVRME5pUzNsVVNRIiwiZSI6IkFRQUIiLCJuIjoiMDZmX1lHdHo4cmNvVkFmUlJ5TW5XWG5jbXlURXN5ZlB4ejlZV3ZUY09HNVhrSENuOHNWQmt4Y1RDZXgxb3VrcWVZVS1NMXFBN2VxOEZjTEQyR1BFcVRzSEwwUTVTTC11WElJWHdoUkpsd21qUTVodXRHZ1d6bTFFTnNINEhDcldxMDZiRi00aVBRaVFVMUZtZFV3cVUyOXJVak55ZnlJS05ndXBST2dqdWN6M3FmLVhNWXVOUkZxRXJXdG9zdHRxNW5uM3RZUjVoeVFqVVp1cDR2T1JxYVFETjFMYlRJOXdnMUc5cUY5cUFMQ3BpNFpTZnJSclhKYWQ1LWpsLUtVTnRTNXBuYWxpR0RRdmtwMU5yQmlwSU9fYWkxb0dtQTE5R3dROFRqTVZDRXN2V1F6SnE1a3dDdXh1SmU5QTgxNUc0blNiNVhadUV2emp4TVNTOG94aS1RIn1dfX0.GxUAOCfVHTyBvJzq9BIV76fX-bRqIVcL-Y36B8NLO17lE0rkfDQQGUh-Vh1JmF_MF3Q4QhXjW-agXoKST3q9x5nDoYHTleQ-10Lw9qiU9I6K8mn1JMNXahzNaX_MLOA7R3_O0-HhxtARIEKpiGQTjup_f5PyqBLrwcERxhnbg0YrpgsvVQHC1SUgXiMtKxMZDWLUtk7q8YaNNhJ4nuEV2M1ZWcEVFloWYKWBJbJvmZ9jqsop6svMDOqusih3sNGWKZ9XmPqtUeGR8o1vsKsOk0WKVnEMH9ESGu54pUJahX05jd4UmTPOzfRJ61k9-_te6xNZUwJqtU9wJ--IrHz7ig",
"eyJhbGciOiJSUzI1NiIsImtpZCI6IlpXRlRRbWhmVFdaSVRuRlRZM0ZTV2pKdU5HMWZWV05hZWxkNmNtUjFRa0pEYlhaWlRYQm1hM1JWUVEiLCJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2OTY1ODMzMzQsImlhdCI6MTY5NjI4MzMzNCwiaXNzIjoiaHR0cHM6Ly90cnVzdC1hbmNob3IuZXhhbXBsZS5vcmciLCJzdWIiOiJodHRwczovL2ludGVybWVkaWF0ZS5laWRhcy5leGFtcGxlLm9yZyIsImp3a3MiOnsia2V5cyI6W3sia3R5IjoiUlNBIiwia2lkIjoiWmxKd05tNDVUMmxVY1hsSFRHZzFaV2hsYmxkalVXbGxjbVF0U1VsUVdYcEhTMUpFUTA4eVRXVnZOQSIsImUiOiJBUUFCIiwibiI6ImtSQUlzLVRBblF6T29lc195RW9oaDNUeGlaWFlPRC1xekI2T25JalZCaVI0WFNGbkw4djhRQ0IxamJiSlZTQ1hBZmdObTlBZjdVRDNBX0E2T1pQOUtacldSUk00NEp0TVAzZmxVSU5CQ2xzNFBrdVd2RklmWEtaaWVUNGhBMzNYdUlTSndqT2NlNnRrbUZTUl9wQmI3S0JHbnB4d3dnRlJjeUM2RU1VQWtWUGdQRl9mbXM3NEEyTF83TGVaNzh2X053VUhsY2VxVHB1OUx6VTRuTTd1RTZQY0JPSmJweXI2SFFuUTR1VHN6WThsWHVmT3pHZ2IzVXNDNmRnQWVVVERIZlFROE4xYXV2bkJUNmR0SHNHNWMxS2NCT2QzLVp6ZTZ5WVE5c2JLUlUtWVoydDZKdUJIbS1xLTVOamxiRWVwNDAwbFgxSXlKdG9Tc3F0d3lCX1djdyJ9XX19.CvBvN0aG-r13UG4uITH72tC5CbAG0rT4qYQ5wwHOtGE021etZFQd40RFnQT5e-Gy_Y8Wiin-Zmc1hWW2rVyZ1RRInjYGUt26QI6ujR-5w9Y_LHVp-6RzYEF0lg9otpAyszQE4hf5qBZYAj8t39FvCYWTYVci6mtpovJQ380ha8I4QL__fZtEgDLQ-7VKS58nN1DOVdcIICMMfxpDR81bkY5i5Qxcy7AaZTN6xxE2SlCO-pKKub0jBUtnug20-BL2YgcPhLFOYWfj2cuyapOA9Omwu6CPhmZHgsL1P2oK_f4jA9JxNDYcV0losDbD86r8Wg3anM2lVM5BTHkiUr2grg",
"eyJhbGciOiJSUzI1NiIsImtpZCI6IlpXRlRRbWhmVFdaSVRuRlRZM0ZTV2pKdU5HMWZWV05hZWxkNmNtUjFRa0pEYlhaWlRYQm1hM1JWUVEiLCJ0eXAiOiJlbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2OTY1ODMzMzQsImlhdCI6MTY5NjI4MzMzNCwiaXNzIjoiaHR0cHM6Ly90cnVzdC1hbmNob3IuZXhhbXBsZS5vcmciLCJzdWIiOiJodHRwczovL3RydXN0LWFuY2hvci5leGFtcGxlLm9yZyIsImp3a3MiOnsia2V5cyI6W3sia3R5IjoiUlNBIiwia2lkIjoiWldGVFFtaGZUV1pJVG5GVFkzRlNXakp1TkcxZlZXTmFlbGQ2Y21SMVFrSkRiWFpaVFhCbWEzUlZRUSIsImUiOiJBUUFCIiwibiI6InhPQnN0YnJUUE9SQ3JnTXowQ254Skk4cjd4TkwwYjZITExKY05NSkNQbGl0SmUzNUZUdGw1bVdMVXFoeFdiRXFYYnpVLW80VHd1ZHA5NHFrckI3Zks5cEk0bDBldEoxMFZTbTQ0dXNiakxoMTUwVXFlSnlmQmdyMzRWbWhINWo3ZFMzS3V5bjNvOEdER2ZjNDVjcmdsR3lNOUgzbFp6SGl6SXdncDVzSUhCeGFPRWQ1eXlOdXhBLXFFQU4zaFIxQi1LQ2JYaWVDRVRrcWNMWU1zX2psRHVsTVE0MzI5TEgwNkhaclhINElfUHVnWXd0WldUN0VqZUR6c3Y2Ny14TFFhOEg3cnV1N3JVME1FREl0TkVpS3ljdVk5b0pLWWtrX2hBQzFMNkt2VkNmeXpVOGVvem9KQzM4eGhXUklNTXJZd2hiSmFaa3dUdDZCRDByalNNRUp6USJ9XX0sIm1ldGFkYXRhIjp7ImZlZGVyYXRpb25fZW50aXR5Ijp7ImZlZGVyYXRpb25fZmV0Y2hfZW5kcG9pbnQiOiJodHRwczovL3RydXN0LWFuY2hvci5leGFtcGxlLm9yZy9mZXRjaCIsImZlZGVyYXRpb25fcmVzb2x2ZV9lbmRwb2ludCI6Imh0dHBzOi8vdHJ1c3QtYW5jaG9yLmV4YW1wbGUub3JnL3Jlc29sdmUiLCJmZWRlcmF0aW9uX2xpc3RfZW5kcG9pbnQiOiJodHRwczovL3RydXN0LWFuY2hvci5leGFtcGxlLm9yZy9saXN0Iiwib3JnYW5pemF0aW9uX25hbWUiOiJUQSBleGFtcGxlIiwiaG9tZXBhZ2VfdXJpIjoiaHR0cHM6Ly90cnVzdC1hbmNob3IuZXhhbXBsZS5vcmcvaG9tZSIsInBvbGljeV91cmkiOiJodHRwczovL3RydXN0LWFuY2hvci5leGFtcGxlLm9yZy9wb2xpY3kiLCJsb2dvX3VyaSI6Imh0dHBzOi8vdHJ1c3QtYW5jaG9yLmV4YW1wbGUub3JnL3N0YXRpYy9sb2dvLnN2ZyIsImNvbnRhY3RzIjpbInRlY2hAdHJ1c3QtYW5jaG9yLmV4YW1wbGUub3JnIl19fSwiY29uc3RyYWludHMiOnsibWF4X3BhdGhfbGVuZ3RoIjoxfX0.ZenICRAm4zrd65A3tsSN77VLjheJAK09s8sBXQVo2l3r7RrN8pXFKqulZebxfSALF4am58Ry8GeK2N1ZK7B1GlfskAnnIINfi-IpjqquvPW_MXrSo0bLoXnnmruHJ1D0KbONbwdZaOZg4oJRo2PBU009pojheUwcRcNDujCRiQimsvEYlL4YLwpPHjEmt46WviPESnZCgez_oEdoXkNjN3PsOta9de_abjkASYdGgAlBTIbUjAutmErbubjKptxpvycibBLuJ58nkiQZ_KesLRPnDY9hbPf0ZMbtCB_gx8yLlQ9-8nE5_fuxICz1uKR4536txsQFmrCvireBchaZ1A"
]
}
trust_chain Parameter
This section defines how to represent and use metadata about Entities. It uses existing OpenID Connect and OAuth 2.0 metadata standards that are applicable to each Entity Type.¶
As described in Section 3,
Entity metadata is located in the metadata
claim of an Entity Statement, whose value is a JSON object.
The member names of this object are Entity Type Identifiers,
as specified in Section 5.1.
The metadata data structure following each Entity Type Identifier is a JSON object;
it MAY be the empty JSON object {},
which may be the case when Superiors supply any needed metadata values.¶
Top-level JSON object members in the metadata data structures MAY use
any JSON value other than null;
the use of null is prohibited to prevent likely
implementation errors caused by confusing members having
null values with omitted members.¶
The Entity Type Identifier uniquely identifies the Entity Type of a
federation participant and the metadata format for that Entity Type. This
section defines a federation_entity Entity
Type Identifier as well as identifiers for OpenID Connect and OAuth 2.0
Federation Entities.¶
Additional Entity Type Identifiers MAY be defined to support use cases outside OpenID Connect and OAuth 2.0 federations.¶
The Entity Type Identifier is
federation_entity.¶
All Entities in a federation MAY use this Entity Type. The Entities that provide federation API endpoints MUST use this Entity Type.¶
The following Federation Entity properties are defined:¶
https
scheme and MAY contain port,
path, and query parameter components;
it MUST NOT contain a fragment component.
Intermediate Entities and
Trust Anchors MUST publish a
federation_fetch_endpoint.
Leaf Entities MUST NOT.¶
https
scheme and MAY contain port,
path, and query parameter components;
it MUST NOT contain a fragment component.
Intermediate Entities and
Trust Anchors MUST publish a
federation_list_endpoint.
Leaf Entities MUST NOT.¶
https
scheme and MAY contain port,
path, and query parameter components;
it MUST NOT contain a fragment component.
Any federation Entity MAY publish a
federation_resolve_endpoint.¶
federation_trust_mark_status_endpoint.
This URL MUST use the https
scheme and MAY contain port,
path, and query parameter components;
it MUST NOT contain a fragment component.¶
https
scheme and MAY contain port,
path, and query parameter components;
it MUST NOT contain a fragment component.
Trust Mark Issuers MAY publish a
federation_trust_mark_list_endpoint.¶
https
scheme and MAY contain port,
path, and query parameter components;
it MUST NOT contain a fragment component.
Trust Mark Issuers MAY publish a
federation_trust_mark_endpoint.¶
https
scheme and MAY contain port,
path, and query parameter components;
it MUST NOT contain a fragment component.
All Federation Entities MAY publish a
federation_historical_keys_endpoint.¶
alg values)
for signing the JWT [RFC7519]
used for private_key_jwt
when authenticating to federation endpoints,
as described in Section 8.8.
No default algorithms are implied if this entry is omitted.
Servers SHOULD support RS256.
The value none MUST NOT be used.¶
It is RECOMMENDED that each Federation Entity contain
an organization_name claim,
as defined in Section 5.2.2.¶
The following is a non-normative example of the federation_entity Entity Type:¶
"federation_entity": {
"federation_fetch_endpoint":
"https://amanita.caesarea.example.com/federation_fetch",
"federation_list_endpoint":
"https://amanita.caesarea.example.com/federation_list",
"federation_trust_mark_status_endpoint": "https://amanita.caesarea.example.com/status",
"federation_trust_mark_list_endpoint": "https://amanita.caesarea.example.com/trust_marked_list",
"organization_name": "Ovulo Mushroom",
"homepage_uri": "https://amanita.caesarea.example.com"
}
federation_entity Entity Type
The Entity Type Identifier is
openid_relying_party.¶
All parameters defined in Section 2 of OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration], in [OpenID.RP.Choices], and in Section 5.2 are applicable, as well as additional parameters registered in the IANA "OAuth Dynamic Client Registration Metadata" registry [IANA.OAuth.Parameters].¶
In addition, the following RP metadata parameter is defined:¶
automatic
and explicit.
Additional values MAY be defined and used, without restriction by this specification.¶
The following is a non-normative example of the JWT Claims Set for an RP's Entity Configuration:¶
{
"iss": "https://openid.sunet.se",
"sub": "https://openid.sunet.se",
"iat": 1516239022,
"exp": 1516298022,
"metadata": {
"openid_relying_party": {
"application_type": "web",
"redirect_uris": [
"https://openid.sunet.se/rp/callback"
],
"organization_name": "SUNET",
"logo_uri": "https://www.sunet.se/sunet/images/32x32.png",
"grant_types": [
"authorization_code",
"implicit"
],
"signed_jwks_uri":"https://openid.sunet.se/rp/signed_jwks.jose",
"jwks_uri": "https://openid.sunet.se/rp/jwks.json",
"client_registration_types": ["automatic"]
}
},
"jwks": {
"keys": [
{
"alg": "RS256",
"e": "AQAB",
"kid": "key1",
"kty": "RSA",
"n": "pnXBOusEANuug6ewezb9J_...",
"use": "sig"
}
]
},
"authority_hints": [
"https://edugain.org/federation"
]
}
The Entity Type Identifier is
openid_provider.¶
All parameters defined in Section 3 of
OpenID Connect Discovery 1.0 [OpenID.Discovery]
and Section 5.2 are applicable,
as well as additional parameters registered in the
IANA "OAuth Authorization Server Metadata" registry
[IANA.OAuth.Parameters].
For instance, the require_signed_request_object
and require_pushed_authorization_requests
metadata parameters can be used.¶
The issuer parameter value
in the openid_provider metadata MUST
match the Federation Entity identifier
(the iss parameter within the Entity Configuration).¶
In addition, the following OP metadata parameters are defined:¶
automatic
and explicit.
Additional values MAY be defined and used, without restriction by this specification.¶
https
scheme and MAY contain port,
path, and query parameter components;
it MUST NOT contain a fragment component.
If the OP supports Explicit Client
Registration as described in Section 12.2,
then this claim is REQUIRED.¶
The following is a non-normative example of the JWT Claims Set for an OP's Entity Configuration:¶
{
"iss":"https://op.umu.se",
"sub":"https://op.umu.se",
"exp":1568397247,
"iat":1568310847,
"metadata":{
"openid_provider":{
"issuer":"https://op.umu.se",
"signed_jwks_uri":"https://op.umu.se/openid/signed_jwks.jose",
"authorization_endpoint":"https://op.umu.se/openid/authorization",
"client_registration_types_supported":[
"automatic",
"explicit"
],
"grant_types_supported":[
"authorization_code",
"implicit",
"urn:ietf:params:oauth:grant-type:jwt-bearer"
],
"id_token_signing_alg_values_supported":[
"ES256",
"RS256"
],
"logo_uri":"https://www.umu.se/img/umu-logo-left-neg-SE.svg",
"op_policy_uri":"https://www.umu.se/en/legal-information/",
"response_types_supported":[
"code",
"code id_token",
"token"
],
"subject_types_supported":[
"pairwise",
"public"
],
"token_endpoint":"https://op.umu.se/openid/token",
"federation_registration_endpoint":"https://op.umu.se/openid/fedreg",
"token_endpoint_auth_methods_supported":[
"client_secret_post",
"client_secret_basic",
"client_secret_jwt",
"private_key_jwt"
],
"pushed_authorization_request_endpoint":"https://op.umu.se/openid/par",
"request_object_signing_alg_values_supported": [
"ES256",
"RS256"
],
"token_endpoint_auth_signing_alg_values_supported": [
"ES256",
"RS256"
]
}
},
"authority_hints":[
"https://umu.se"
],
"jwks":{
"keys":[
{
"e":"AQAB",
"kid":"dEEtRjlzY3djcENuT01wOGxrZlkxb3RIQVJlMTY0...",
"kty":"RSA",
"n":"x97YKqc9Cs-DNtFrQ7_vhXoH9bwkDWW6En2jJ044yH..."
}
]
}
}
The Entity Type Identifier is
oauth_authorization_server.¶
All parameters defined in Section 2 of [RFC8414] and Section 5.2 are applicable, as well as additional parameters registered in the IANA "OAuth Authorization Server Metadata" registry [IANA.OAuth.Parameters].¶
The issuer parameter value
in the oauth_authorization_server metadata MUST
match the Federation Entity identifier
(the iss claim in the Entity Configuration).¶
The Entity Type Identifier is
oauth_client.¶
All parameters defined in Section 2 of OAuth 2.0 Dynamic Client Registration Protocol [RFC7591] and Section 5.2 are applicable, as well as additional parameters registered in the IANA "OAuth Dynamic Client Registration Metadata" registry [IANA.OAuth.Parameters].¶
The Entity Type Identifier is
oauth_resource.
The parameters defined in Section 5.2 are applicable.
In addition, while it is not yet a standard,
deployments MAY use the protected resource metadata parameters
defined in [I-D.ietf-oauth-resource-metadata].¶
This section defines additional metadata parameters that MAY be used with all the Entity Types above, with the exception for JWK Sets noted below.¶
The following metadata parameters define ways of obtaining
JWK Sets for an Entity Type of the Entity.
Note that these keys are distinct from the Federation Entity Keys
used to sign Entity Statements, which are in
the jwks claim of the Entity Statement,
and not within the metadata claim.
These extensions for JWK Sets MUST NOT be used in
federation_entity Entity Type metadata.¶
https scheme.
The JWT MUST be signed using a Federation Entity Key.
A successful response from the URL MUST use the HTTP status code 200
with the content type
application/jwk-set+jwt.
When both signing and encryption keys are present,
a use (public key use) parameter
value is REQUIRED for all keys in the referenced JWK Set
to indicate each key's intended usage.¶
typ header parameter to
jwk-set+jwt to prevent
cross-JWT confusion, per Section 3.11 of [RFC8725].
Signed JWK Set JWTs without a typ header parameter
or with a different typ value MUST be rejected.¶
kid (Key ID) header parameter
with its value being the Key ID of the signing key used.¶
The following claims are specified for use in the payload,
all of which except keys
are defined in [RFC7519]:¶
More claims are defined in [RFC7519]; of
these, aud SHOULD NOT be used since
the issuer cannot know who the audience is.
nbf and jti
are not particularly useful in this context and SHOULD be omitted.¶
Additional claims MAY be defined and used in conjunction with the claims above.¶
The following is a non-normative example of the JWT Claims Set for a signed JWK Set.¶
{
"keys": [
{
"kty": "RSA",
"kid": "SUdtUndEWVY2cUFDeDV5NVlBWDhvOXJodVl2am1mNGNtR0pmd",
"n": "y_Zc8rByfeRIC9fFZrDZ2MGH2ZnxLrc0ZNNwkNet5rwCPYeRF3Sv
5nihZA9NHkDTEX97dN8hG6ACfeSo6JB2P7heJtmzM8oOBZbmQ90n
EA_JCHszkejHaOtDDfxPH6bQLrMlItF4JSUKua301uLB7C8nzTxm
tF3eAhGCKn8LotEseccxsmzApKRNWhfKDLpKPe9i9PZQhhJaurwD
kMwbWTAeZbqCScU1o09piuK1JDf2PaDFevioHncZcQO74Obe4nN3
oNPNAxrMClkZ9s9GMEd5vMqOD4huXlRpHwm9V3oJ3LRutOTxqQLV
yPucu7eHA7her4FOFAiUk-5SieXL9Q",
"e": "AQAB"
},
{
"kty": "EC",
"kid": "MFYycG1raTI4SkZvVDBIMF9CNGw3VEZYUmxQLVN2T21nSWlkd3",
"crv": "P-256",
"x": "qAOdPQROkHfZY1daGofOmSNQWpYK8c9G2m2Rbkpbd4c",
"y": "G_7fF-T8n2vONKM15Mzj4KR_shvHBxKGjMosF6FdoPY"
}
],
"iss": "https://example.org/op",
"sub": "https://example.org/op",
"iat": 1618410883
}
https scheme.
When both signing and encryption keys are present,
a use (public key use) parameter
value is REQUIRED for all keys in the referenced JWK Set
to indicate each key's intended usage.¶
use (public key use) parameter
value is REQUIRED for all keys in the JWK Set
to indicate each key's intended usage.
This parameter is intended
to be used by participants that, for some reason,
cannot use the signed_jwks_uri
parameter.
An upside of using jwks is that
the Entity's keys for the Entity Type are recorded in Trust Chains.¶
It is RECOMMENDED that an Entity Configuration
use only one of
jwks,
jwks_uri, and
signed_jwks_uri in its OpenID Connect or OAuth 2.0 metadata.
However, there may be circumstances in which is it desirable to use multiple
JWK Set representations, such as when an Entity is in multiple federations and the
federations have different policies about the JWK Set representation to be used.
When multiple JWK Set representations are used, the keys present in each
representation SHOULD be the same. Even if they are not completely the
same at a given instant in time (which may be the case during key rollover operations),
implementations MUST make them consistent in a timely manner.¶
The following metadata parameters define ways of obtaining information about the Entity for an Entity Type.¶
It is RECOMMENDED that, when present, these metadata parameters occur in
an Entity's federation_entity metadata.
They MAY also be present in the Entity's metadata for other Entity Types,
particularly when the values for those Entity Types differ from
those for the federation_entity metadata.¶
Trust Anchors and Intermediate Entities MAY define policies that apply to the metadata of their Subordinates.¶
A federation may utilize metadata policies to achieve specific objectives. For example, in a federation of OpenID Connect [OpenID.Core] Entities, one objective may be to ensure the metadata published by OpenID Providers and Relying Parties are interoperable with one another. Another objective may be to ensure the Entity metadata complies with a security profile, for example, FAPI [FAPI].¶
Note that the metadata_policy is not
intended to check and validate the JSON value types of metadata
parameters. Such checks SHOULD be performed at the application
layer, after obtaining the Entity metadata from a successfully
resolved Trust Chain.¶
OpenID Federation enables the definition of metadata policies with the following properties:¶
Once applied to a metadata parameter, a metadata policy cannot be repealed or made more permissive by Intermediate Entities that are subordinate in the Trust Chain.¶
The hierarchy of policies is preserved in nested federations where a Trust Anchor in one federation acts as an Intermediate Entity in another federation.¶
Just like metadata, a metadata policy is bound to a specific Entity Type. This ensures policies for different Entity Types are independent and isolated from one another.¶
Policies are expressed at the level of individual metadata parameters. The policies for a given Entity Type metadata parameter are thus independent and isolated from those for other parameters.¶
When a Trust Anchor or an Intermediate Entity defines a metadata policy for an Entity Type, it applies to the metadata of all Subordinate Entities of that type in the Trust Chain.¶
Because the place to define a policy is the Subordinate Statement and every Entity Statement is issued for a specific subject, a federation authority can choose to define a common Entity Type metadata policy for all its Subordinates, or specific Entity Type metadata policies for specific Subordinates.¶
The resolution and application of metadata policies is an integral part of the Trust Chain resolution process, as described in Section 10.¶
This means:¶
Metadata policies are expressed in the
metadata_policy claim of a Subordinate
Statement, as described in Section 3. The
claim value is a JSON object that has a data structure consisting of
three levels:¶
Metadata policies for Entity Types.¶
The top level contains one or more members, each representing
the metadata policy for an Entity Type. Each member name is an
Entity Type Identifier, as specified in
Section 5.1, for example,
openid_relying_party. The member
value is a JSON object that contains metadata parameter
policies.¶
Metadata parameter policies for the Entity Type.¶
The second level contains one or more members, each representing
a policy for a metadata parameter for the Entity Type. Each
member name is a metadata parameter name, for example
id_token_signed_response_alg. The
name MAY include a language tag, as described in
Section 14, in which case the
metadata parameter policy applies only to the metadata parameter
with the specified language tag. The member value is a JSON
object that contains policy operators.¶
Operators for the metadata parameter policy for the Entity Type.¶
The third level contains one or more members, each representing an operator that checks or modifies the metadata parameter, as described in Section 6.1.3. Only operators that are allowed to be combined with one another MUST be included, as described in the specification for each operator.¶
Duplicate JSON object member names MUST NOT be present at any of
the three levels of the metadata_policy
claim data structure.¶
The following is a non-normative example of a metadata policy
for an OpenID Relying Party that consists of a single policy for
the id_token_signed_response_alg
metadata parameter and uses two operators,
default and
one_of:¶
"metadata_policy" : {
"openid_relying_party": {
"id_token_signed_response_alg": {
"default": "ES256",
"one_of": ["ES256", "ES384", "ES512"]
}
}
}
metadata_policy Claim
A metadata policy operator:¶
Is identified by a unique case-sensitive name.¶
Acts on a single metadata parameter. The operator definition MUST specify the metadata parameter JSON value types that are mandatory to support and MAY also specify JSON value types that are optional to support. When the metadata parameter has a JSON value type that is not supported, the operator MUST produce a policy error.¶
The action on the metadata parameter can be a value check, a value modification, or both. When the operator’s action is a value modification, it MAY remove the metadata parameter.¶
The action of the operator is configured by a JSON value. The operator definition MUST specify the JSON value types that are mandatory to support and MAY also specify JSON value types that are optional to support. When the operator is configured with a JSON value type that isn’t supported, the operator MUST produce a policy error.¶
MUST declare what other operators it may be combined within a metadata parameter policy. Combinations that are not allowed MUST result in a policy error.¶
MUST declare in what order it is to be applied to a metadata parameter, absolute or relative to other operators in the metadata parameter policy. Value check operators SHOULD generally be applied after operators that perform value modifications.¶
MUST specify, when more than one Subordinate Statement in a Trust Chain has a policy for an Entity Type metadata parameter that uses the same operator, whether the operator values are allowed to be merged to produce an identical or more restrictive policy, and if so, under what conditions. If the operator does not allow such a merge, it MUST produce a policy error.¶
An operator MUST NOT output a metadata parameter with the
null value.¶
Metadata parameters and policies that conform to the JSON grammar but do not represent interoperable uses of JSON, as per Sections 4 and 8 of [RFC8259], can cause unpredictable behavior.¶
This specification defines the following metadata policy operators:¶
Name: value¶
Action: The metadata parameter MUST be assigned the value of the
operator. When the value of the operator is
null, the metadata parameter MUST be
removed.¶
Metadata parameter JSON values:¶
Mandatory to support: string, number, boolean, object, array¶
Operator JSON values:¶
Mandatory to support: string, number, boolean, object, array, null¶
Combination with other operators in a metadata parameter policy:¶
MAY be combined with essential.¶
Order of application: First¶
Operator value merge: Allowed only when the operator values are equal. If not, this MUST result in a policy error.¶
Name: add¶
Action: The value or values of this operator MUST be added to the metadata parameter. Values that are already present in the metadata parameter MUST NOT be added another time. If the metadata parameter is absent, it MUST be initialized with the value of this operator.¶
Metadata parameter JSON values:¶
Operator JSON values:¶
Combination with other operators in a metadata parameter policy:¶
MAY be combined with default.¶
MAY be combined with subset_of,
in which case the values of add
MUST be a subset of the values of
subset_of.¶
MAY be combined with superset_of,
in which case the values of add
MUST be a superset of the values of
superset_of.¶
MAY be combined with essential.¶
Order of application: After value.¶
Operator value merge: The result of merging the values of two
add operators is the union of the
values.¶
Name: default¶
Action: If the metadata parameter is absent, it MUST be set to the value of the operator. If the metadata parameter is present, this operator has no effect.¶
Metadata parameter JSON values:¶
Mandatory to support: string, number, boolean, object, array¶
Operator JSON values:¶
Mandatory to support: string, number, boolean, object, array¶
Combination with other operators in a metadata parameter policy:¶
MAY be combined with add.¶
MAY be combined with one_of, in
which case the default value
MUST be among the one_of values.¶
MAY be combined with subset_of,
in which case the default values
MUST be a subset of the subset_of
values.¶
MAY be combined with superset_of,
in which case the default values
MUST be a superset of the
superset_of values.¶
MAY be combined with essential.¶
Order of application: After add.¶
Operator value merge: The operator values MUST be equal. If the values are not equal this MUST result in a policy error.¶
Name: one_of¶
Action: If the metadata parameter is present, its value MUST be one of those listed in the operator value.¶
Metadata parameter JSON values:¶
Operator JSON values:¶
Combination with other operators in a metadata parameter policy:¶
MAY be combined with default,
in which case the value of default MUST be among the
one_of values.¶
MAY be combined with essential.¶
Order of application: After default.¶
Operator value merge: The result of merging the values of two
one_of operators is the intersection
of the operator values. If the intersection is empty, this MUST
result in a policy error.¶
Name: subset_of¶
Action: If the metadata parameter is present, this operator
computes the intersection between the values of the operator and
the metadata parameter. If the intersection is non-empty, the
metadata parameter is set to the values in the intersection. If
the intersection is empty, the metadata parameter MUST be
removed. Note that this behavior makes
subset_of a potential value modifier
in addition to it being a value check.¶
Metadata parameter JSON values:¶
Operator JSON values:¶
Combination with other operators in a metadata parameter policy:¶
MAY be combined with add, in
which case the values of add
MUST be a subset of the values of
subset_of.¶
MAY be combined with default, in
which case the values of default
MUST be a subset of the values of
subset_of.¶
MAY be combined with superset_of,
in which case the values of
subset_of MUST be a superset of
the values of superset_of.¶
MAY be combined with essential.¶
Order of application: After one_of.¶
Operator value merge: The result of merging the values of two
subset_of operators is the
intersection of the operator values. If the intersection is
empty, this MUST result in a policy error.¶
Name: superset_of¶
Action: If the metadata parameter is present, its values MUST contain those specified in the operator value. By mathematically defining supersets, equality is included.¶
Metadata parameter JSON values:¶
Operator JSON values:¶
Combination with other operators in a metadata parameter policy:¶
MAY be combined with add, in
which case the values of add
MUST be a superset of the values of
superset_of.¶
MAY be combined with default, in
which case the values of default
MUST be a superset of the values of
superset_of.¶
MAY be combined with subset_of,
in which case the values of
subset_of MUST be a superset of
the values of superset_of.¶
MAY be combined with essential.¶
Order of application: After subset_of.¶
Operator value merge: The result of merging the values of two
superset_of operators is the union
of the operator values.¶
Name: essential¶
Action: If the value of this operator is
true, then the metadata parameter
MUST be present. If false, the
metadata parameter is voluntary and may be absent. If the
essential operator is omitted, this
is equivalent to including it with a value of
false.¶
Metadata parameter JSON values:¶
Mandatory to support: string, number, boolean, object, array¶
Operator JSON values:¶
Mandatory to support: boolean¶
Combination with other operators in a metadata parameter policy:¶
MAY be combined with any other operator.¶
Order of application: Last¶
Operator value merge: The result of merging the values of two
essential operators is the logical
disjunction (OR) of the operator values.¶
A "set equals" metadata parameter policy can be expressed by
combining the operators subset_of and
superset_of with identical array
values.¶
The scope OAuth 2.0 client metadata
parameter, defined in [RFC7591] and represented by
a string of space-separated string values, is to be regarded and
processed as a string array by policy operators, such as the
operators default,
subset_of and
superset_of. The resulting
scope metadata parameter is a
space-separated string of individual scope values, where the
scope values present are taken from the array of values produced
by applying the metadata operators to the
scope parameter.¶
The following table is a map of the outputs produced by
combinations of the essential and
subset_of policy operators with
different input metadata parameter values.
Note, the subset_of check is skipped
when the metadata parameter is absent and designated as
voluntary, as shown in the last row.¶
| Policy | Metadata Parameter | ||
| essential | subset_of | input | output |
| true | [a,b,c] | [a,e] | [a] |
| false | [a,b,c] | [a,e] | [a] |
| true | [a,b,c] | [d,e] | error |
| false | [a,b,c] | [d,e] | no parameter |
| true | [a,b,c] | no parameter | error |
| false | [a,b,c] | no parameter | no parameter |
Federations MAY specify and use additional metadata policy operators that conform with the principles in Section 6.1.1 and in Section 6.1.3.¶
Additional operators MUST observe the following rules in regard to the order of their application relative to the standard operators defined in Section 6.1.3.1:¶
Additional operators that modify metadata parameters MUST be
applied after the value operator
that is specified in Section 6.1.3.1.1.¶
Additional operators that check metadata parameters MUST be
applied before the essential
operator that is specified in
Section 6.1.3.1.7.¶
Implementations MUST ignore additional operators that are not
understood, unless the operator name is included in the
metadata_policy_crit Subordinate
Statement claim, in which case the operator MUST be understood
and processed. If an additional operator listed in
metadata_policy_crit is not understood
or cannot be processed, then this MUST result in a policy error
and the Trust Chain MUST be considered invalid.¶
This section describes the resolution of the metadata policy for a Trust Chain and its application to the metadata of the Federation Entity that is the Trust Chain subject.¶
If a policy error or another error is encountered during the metadata policy resolution or its application, the Trust Chain MUST be considered invalid.¶
The metadata policy for a Trust Chain is determined by the
sequence of the present metadata_policy
claims of the Subordinate Statements that make up the chain.¶
The resolution process MUST first gather the names of all policy
operators other than the standard ones defined in
Section 6.1.3.1 that are
declared as critical. This is done by checking each Subordinate
Statement in the Trust Chain for the optional
metadata_policy_crit claim,
described in Section 3, and collecting
any operator names that are found in it.¶
The resolution process proceeds by iterating through the Subordinate Statements. The sequence of this iteration is crucial - it MUST begin with the Subordinate Statement issued by the most Superior Entity and end with the Subordinate Statement issued by the Immediate Superior of the Trust Chain subject.¶
An important procedure during the iteration is the
metadata_policy validation. It MUST
ensure the data structure is compliant and that every metadata
parameter policy contains only allowed operator combinations, as
described in Section 6.1.3, and in
accordance with the specifications of the operators. It MUST be
also ensured the metadata_policy
contains no operators that cannot be understood and processed
whose names are among the collected
metadata_policy_crit values. An
unsuccessful validation MUST result in a policy error.¶
At each iteration step, the Subordinate Statement MUST be checked
for the presence of a metadata_policy
claim. The first encountered
metadata_policy MUST be validated as
described above, after which it becomes the current metadata
policy.¶
If the iteration yields a next subordinate
metadata_policy claim, it MUST be
validated as described above, then merged into the current
metadata policy.¶
The merge is performed at all three levels of the
metadata_policy data structure
described in Section 6.1.2, by
starting from the top level:¶
The metadata policies for Entity Types.¶
The metadata parameter policies for an Entity Type.¶
The operators for a metadata parameter policy for an Entity Type.¶
At the level of metadata policies for Entity Types, the merge proceeds as follows:¶
If the next subordinate
metadata_policy claim contains
a metadata policy for an Entity Type that is already
present in the current metadata policy, it MUST be merged
according to the rules of the next lower level (the
metadata parameter policies).¶
Entity Type metadata policies in the next subordinate
metadata_policy claim that are
not present in the current metadata policy MUST be copied
to it.¶
At the level of metadata parameter policies, the merge proceeds as follows:¶
If a metadata parameter policy is already present in the current Entity Type metadata policy, it MUST be merged according to the rules of the next lower level (the operators for the metadata parameter policy). If the resulting metadata parameter policy contains combinations that are not allowed, as described in Section 6.1.3 and in accordance with the specifications of the operators, this MUST result in a policy error.¶
Subordinate metadata parameter policies that are not present in the current Entity Type metadata policy MUST be copied to it.¶
At the level of operators, the merge proceeds as follows:¶
If an operator is already present in the current metadata parameter policy, the values of the subordinate operator MUST be merged, as described in Section 6.1.3 and in accordance with the operator specification. If an operator value merge is not allowed or otherwise unsuccessful this MUST result in a policy error.¶
Subordinate operators that are not present in the current metadata parameter policy MUST be copied to it.¶
If no further Subordinate Statements with a
metadata_policy claim are found, the
current metadata policy becomes the resolved one for the Trust Chain.¶
If the Subordinate Statement about the Trust Chain subject
contains a metadata claim, this MUST
first be applied, as described in the claim definition in
Section 3, and only then it can be
proceeded with applying the resolved metadata policy.¶
If the process described in
Section 6.1.4.1 found no Subordinate
Statements in the Trust Chain with a
metadata_policy claim, the metadata
of the Trust Chain subject resolves simply to the
metadata found in its Entity
Configuration, with any metadata
parameters provided by the Immediate Superior applied to it.¶
If a metadata policy was resolved for the Trust Chain, for every Entity Type metadata and metadata parameter for which a corresponding metadata parameter policy is present, the included policy operators MUST be applied as described in Section 6.1.3 and in accordance with the specifications of the operators. The operators MUST be applied to the metadata parameter in a sequence that is determined by the absolute or relative order specified for each operator.¶
If the application of metadata policies results in illegal or otherwise incorrect resolved metadata, then the metadata MUST be regarded as broken and MUST NOT be used.¶
The Trust Chain subject is responsible to verify that it is able to support and comply with the resolved metadata that results from the application of federation metadata policies. For instance, this may involve a check that cryptographic algorithms required by the resulting resolved metadata are supported. Likewise, the Trust Chain subject MUST verify that all the required metadata parameters for its Entity Types are present and all the metadata values in the resolved metadata are valid. When metadata policies change, Trust Chain subjects may need to reevaluate their support and compliance.¶
The following is a non-normative example of resolving and applying Trust Chain metadata policies for an OpenID relying party.¶
We start with a federation Trust Anchor's
metadata_policy for RPs:¶
"metadata_policy": {
"openid_relying_party": {
"grant_types": {
"default": [
"authorization_code"
],
"subset_of": [
"authorization_code",
"refresh_token"
],
"superset_of": [
"authorization_code"
]
},
"token_endpoint_auth_method": {
"one_of": [
"private_key_jwt",
"self_signed_tls_client_auth"
],
"essential": true
},
"token_endpoint_auth_signing_alg" : {
"one_of": [
"PS256",
"ES256"
]
},
"subject_type": {
"value": "pairwise"
},
"contacts": {
"add": [
"helpdesk@federation.example.org"
]
}
}
}
Next, we have an Intermediate organization's
metadata_policy for Subordinate RPs
together with metadata values for its
Immediate Subordinate RPs:¶
{
"metadata_policy": {
"openid_relying_party": {
"grant_types": {
"subset_of": [
"authorization_code"
]
},
"token_endpoint_auth_method": {
"one_of": [
"self_signed_tls_client_auth"
]
},
"contacts": {
"add": [
"helpdesk@org.example.org"
]
}
}
},
"metadata": {
"openid_relying_party": {
"sector_identifier_uri": "https://org.example.org/sector-ids.json",
"policy_uri": "https://org.example.org/policy.html"
}
}
}
Merging the example RP metadata policy of the Intermediate Entity into the RP metadata policy of the Trust Anchor produces the following policy for the Trust Chain:¶
{
"grant_types": {
"default": [
"authorization_code"
],
"superset_of": [
"authorization_code"
],
"subset_of": [
"authorization_code"
]
},
"token_endpoint_auth_method": {
"one_of": [
"self_signed_tls_client_auth"
],
"essential": true
},
"token_endpoint_auth_signing_alg": {
"one_of": [
"PS256",
"ES256"
]
},
"subject_type": {
"value": "pairwise"
},
"contacts": {
"add": [
"helpdesk@federation.example.org",
"helpdesk@org.example.org"
]
}
}
The Trust Chain subject is a Leaf Entity, which publishes the following RP metadata in its Entity Configuration:¶
"metadata": {
"openid_relying_party": {
"redirect_uris": [
"https://rp.example.org/callback"
],
"response_types": [
"code"
],
"token_endpoint_auth_method": "self_signed_tls_client_auth",
"contacts": [
"rp_admins@rp.example.org"
]
}
}
The metadata values specified by the
Intermediate Entity for its Immediate Subordinates are applied to
the Trust Chain subject metadata.
After that, the merged metadata policy is applied, to produce the
following resulting resolved RP metadata:¶
{
"redirect_uris": [
"https://rp.example.org/callback"
],
"grant_types": [
"authorization_code"
],
"response_types": [
"code"
],
"token_endpoint_auth_method": "self_signed_tls_client_auth",
"subject_type": "pairwise",
"sector_identifier_uri": "https://org.example.org/sector-ids.json",
"policy_uri": "https://org.example.org/policy.html",
"contacts": [
"rp_admins@rp.example.org",
"helpdesk@federation.example.org",
"helpdesk@org.example.org"
]
}
Trust Anchors and Intermediate Entities MAY define constraining criteria
that apply to their Subordinates. They are expressed in the
constraints claim of a Subordinate Statement,
as described in Section 3.¶
The following constraint parameters are defined:¶
Additional constraint parameters MAY be defined and used. If they are not understood, they MUST be ignored.¶
The following is a non-normative example of a set of constraints:¶
{
"max_path_length": 2,
"naming_constraints": {
"permitted": [
"https://.example.com"
],
"excluded": [
"https://east.example.com"
]
},
"allowed_entity_types": [
"openid_provider",
"openid_relying_party"
]
}
When resolving the Trust Chain for an Entity the
constraints claim in each Subordinate
Statement MUST be independently applied, if present. If any of the
constraints checks fails, the Trust Chain
MUST be considered invalid.¶
The max_path_length constraint specifies
the maximum allowed number of Intermediate Entities in a Trust Chain
between a Trust Anchor or Intermediate that sets the constraint and
the Trust Chain subject.¶
A max_path_length constraint of zero
indicates that no Intermediates MAY appear between this Entity and
the Trust Chain subject. The
max_path_length constraint MUST have a
value greater than or equal to zero.¶
Omitting the max_path_length constraint
means that there are no additional constraints apart from those
already in effect.¶
Assuming that we have a Trust Chain with four Entity Statements:¶
Entity Configuration of a Leaf Entity (LE)¶
Subordinate Statement by an Intermediate 1 (I1) about LE¶
Subordinate Statement by an Intermediate 2 (I2) about I1¶
Subordinate Statement by a Trust Anchor (TA) about I2¶
Then the Trust Chain fulfills the constraints if, for instance:¶
The TA specifies a max_path_length
that is greater than or equal to 2.¶
TA specifies a max_path_length of 2,
I2 specifies a max_path_length of 1,
and I1 omits the max_path_length
constraint.¶
Neither TA nor I2 specifies any
max_path_length constraint while I1
sets max_path_length to 0.¶
The Trust Chain does not fulfill the constraints if, for instance, the:¶
The TA sets the max_path_length to 1.¶
The naming_constraints member specifies
a URI namespace within which the Entity Identifiers of Subordinate
Entities in a Trust Chain MUST be located.¶
Restrictions are defined in terms of URI name subtrees,
using permitted and/or
excluded members within the
naming_constraints member,
each of which contains an array of names to be permitted or excluded.
Any name matching a restriction in the excluded list is invalid,
regardless of the information appearing in the permitted list.¶
This specification uses the syntax of domain name constraints specified in Section 4.2.1.10 of [RFC5280]. As stated there, a domain name constraint MUST be specified as a fully qualified domain name and MAY specify a host or a domain. Examples are "host.example.com" and ".example.com". When the domain name constraint begins with a period, it MAY be expanded with one or more labels. That is, the domain name constraint ".example.com" is satisfied by both host.example.com and my.host.example.com. However, the domain name constraint ".example.com" is not satisfied by "example.com". When the domain name constraint does not begin with a period, it specifies a host. As in RFC 5280, domain name constraints apply to the host part of the URI.¶
The allowed_entity_types constraint
specifies the acceptable Entity Types of Subordinate Entities in a
Trust Chain. If there is no
allowed_entity_types constraint, it
means that any Entity Type is allowed. The
federation_entity Entity Type
Identifier, specified in Section 5.1.1, is
always allowed and MUST NOT be included in the constraint. If the
constraint is the empty array [], it
means that only the federation_entity
Entity Type is allowed.¶
Per the definition in Section 1.2,
Trust Marks are statements of conformance to sets of criteria
determined by an accreditation authority.
Trust Marks used by this specification are signed JWTs.
Entity Statements MAY include Trust Marks,
as described in the trust_marks
claim definition in Section 3.¶
Trust Marks are signed by a federation-accredited
authority called a Trust Mark Issuer.
All Trust Mark Issuers MUST be represented in the
federation by an Entity. The fact that a Trust Mark Issuer is
accepted by the federation is expressed in the
trust_mark_issuers claim of the
Trust Anchor's Entity Configuration.¶
The key used by the Trust Mark issuer to sign its Trust Marks MUST be one of the private keys in its set of Federation Entity Keys.¶
Trust Mark JWTs MUST include the
kid (Key ID) header parameter
with its value being the Key ID of the signing key used.¶
Note that a federation MAY allow an Entity to self-sign Trust Marks.¶
Trust Mark JWTs MUST be explicitly typed by using the
typ header parameter to prevent
cross-JWT confusion, per Section 3.11 of [RFC8725].
The typ header parameter value MUST be
trust-mark+jwt
unless the trust framework in use defines a more specific
media type value for the particular kind of Trust Mark.
Trust Marks without a typ header parameter
or an unrecognized typ value MUST be rejected.¶
The claims in a Trust Mark are:¶
trust_mark_id (identifier) claim
defined in Section 7.1 is used in Trust Marks
to provide the identifier of the Trust Mark.
The Trust Mark identifier
MUST be collision-resistant
across multiple federations.
It is RECOMMENDED that the
identifier
value is built
using a URL that uniquely identifies the federation
or the trust framework
within which it was issued. This is required to prevent
Trust Marks issued in different federations
from having colliding identifiers.¶
ref (reference) claim
defined in Section 13.5 is used in Trust Marks
to provide a URL referring to human-readable information
about the issuance of the Trust Mark.¶
delegation claim
defined in Section 13.6 is used in Trust Marks
to delegate the right to issue Trust Marks
with a particular identifier.
Its value is a Trust Mark delegation JWT,
as defined in Section 7.2.1.¶
Additional claims MAY be defined and used in conjunction with the claims above.¶
There will be cases where the owner of a Trust Mark for some reason does not match the Trust Mark Issuer due to administrative or technical requirements. Take as an example vehicle inspection. Vehicle inspection is a procedure mandated by national or subnational governments in many countries, in which a vehicle is inspected to ensure that it conforms to regulations governing safety, emissions, or both. The body that mandates the inspections does not perform them; instead, there may be commercial companies performing the inspections, after which they issue the Trust Mark.¶
The fact that a Trust Mark is issued by a Trust Mark Issuer that is
not the owner of the Trust Mark is expressed by including
a delegation claim in the Trust Mark,
whose value is a Trust Mark delegation JWT,
as defined in Section 7.2.1.¶
If the Federation Operator knows that Trust Marks with a
certain Trust Mark identifier may legitimately be issued by Trust Mark Issuers
that are not the owner of the Trust Mark identifier, then information
about the owner and the Trust Mark identifier MUST be included in the
trust_mark_owners claim in
the Trust Anchor's Entity Configuration.¶
A Trust Mark Delegation JWT is a signed JWT issued by a Trust Mark Owner that identifies a legitimate delegated issuer of Trust Marks with a particular identifier.¶
A Trust Mark delegation JWT MUST be explicitly typed, by setting the
typ header parameter to
trust-mark-delegation+jwt to prevent
cross-JWT confusion, per Section 3.11 of [RFC8725].
Trust Mark delegation JWTs without a typ header parameter
or with a different typ value MUST be rejected.
It is signed with a Federation Entity Key.¶
Trust Mark delegation JWTs MUST include the
kid (Key ID) header parameter
with its value being the Key ID of the signing key used.¶
The claims in a Trust Mark delegation JWT are:¶
Additional claims MAY be defined and used in conjunction with the claims above.¶
An Entity SHOULD NOT try to validate a Trust Mark until it knows which Trust Anchor it is using. To validate a Trust Mark Issuer, follow the procedure defined in Section 10. To validate a Trust Mark, either:¶
Validate the signature of the Trust Mark JWT and verify that it has not expired.¶
If the Trust Mark identifier appears in the
trust_mark_owners claim
of the Trust Anchor's Entity Configuration,
verify that the Trust Mark contains
a delegation
claim.
The claims for the Trust Mark identifier
in the trust_mark_owners value
are used in the following way:¶
or:¶
Use the Trust Mark Issuer status endpoint to verify that the Trust Mark is still active as described in Section 8.4.¶
Note that the Entity representing the accreditation authority
SHOULD be well known and trusted for a given Trust Mark identifier.
A Trust Anchor MAY publish a list of accreditation authorities
of Trust Marks that SHOULD be trusted by other Entities.
A Trust Anchor uses the trust_mark_issuers claim
in its Entity Configuration to publish this information.¶
If a Trust Mark Issuer is issuing Trust Marks on behalf of a
Trust Mark Owner, then the Trust Anchor MUST publish the
connection between the Trust Mark identifier
and the corresponding Trust Mark Issuer in the
trust_mark_issuers claim. This
signifies that the Trust Anchor has validated
the Trust Mark Owner and that the
Trust Mark Owner has delegated the right to issue Trust Marks
with a designated Trust Mark identifier to a specified Trust Mark Issuer.¶
Trust Marks that are not recognized within a federation SHOULD be ignored when evaluating trust in the Entity that presented them. Such Trust Marks can appear for various reasons, such as the Entity Configuration including Trust Marks associated with another federation, or Trust Marks intended for specific purposes or Entity audiences.¶
An Entity MAY choose, at its own discretion, to utilize Trust Marks presented to it that are not recognized within the federation, and where the accreditation authority is established by some out-of-band mechanism.¶
A non-normative example of a trust_marks
claim in the JWT Claims Set for an Entity Configuration is:¶
{
"iss": "https://rp.example.it/spid/",
"sub": "https://rp.example.it/spid/",
"iat": 1516239022,
"exp": 1516298022,
"trust_marks": [
{
"trust_mark_id": "https://www.spid.gov.it/certification/rp",
"trust_mark":
"eyJ0eXAiOiJ0cnVzdC1tYXJrK2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoia29
zR20yd3VaaDlER21OeEF0a3VPNDBwUGpwTDMtakNmMU4tcVBPLVllVSJ9.eyJpc
3MiOiJodHRwczovL3d3dy5hZ2lkLmdvdi5pdCIsInN1YiI6Imh0dHBzOi8vcnAu
ZXhhbXBsZS5pdC9zcGlkIiwiaWF0IjoxNTc5NjIxMTYwLCJ0cnVzdF9tYXJrX2l
kIjoiaHR0cHM6Ly93d3cuc3BpZC5nb3YuaXQvY2VydGlmaWNhdGlvbi9ycCIsIm
xvZ29fdXJpIjoiaHR0cHM6Ly93d3cuYWdpZC5nb3YuaXQvdGhlbWVzL2N1c3Rvb
S9hZ2lkL2xvZ28uc3ZnIiwicmVmIjoiaHR0cHM6Ly9kb2NzLml0YWxpYS5pdC9k
b2NzL3NwaWQtY2llLW9pZGMtZG9jcy9pdC92ZXJzaW9uZS1jb3JyZW50ZS8ifQ.
L_pSh1InEiFAcs3E-1HBM7fNZYwF5ru3UGA_8yc80dGS3sszfA_sbj4AoW_zAJW
QBdZpjxnHBBmybYXFrfZBcqxcedsrvUYrmbt1nPYxbUE54fRRoZK-sJmVqh1GzS
an5nOmkxuAtMinU8k_-aWnPWj83sYe2AzT2mMgkXiz8zhda3jZm8hoxZ4jR6B0Y
AvbMlq2pPWO5OWKdZhiFRMSprwh0GYluQkK0j1aLNMGXD3keMJd2zEoWX9D7w2f
XShAA48W3cNhuXyBVnCoum1K4IWK3s_fx4nIkp6W-V4jCBOpxp7Yo8LZ30o_xpE
OzGTIECGWVR86azOAlwVC8XSiAA"
}
],
"metadata": {
"openid_relying_party": {
"application_type": "web",
"client_registration_types": ["automatic"],
"client_name": "https://rp.example.it/spid/",
"contacts": [
"ops@rp.example.it"
]
}
}
}
An example of a decoded Trust Mark payload issued to an RP, attesting to conformance to a national public service profile:¶
{
"trust_mark_id":"https://mushrooms.federation.example.com/openid_relying_party/public/",
"iss": "https://epigeo.tm-issuer.example.it",
"sub": "https://porcino.example.com/rp",
"iat": 1579621160,
"organization_name": "Porcino Mushrooms & Co.",
"policy_uri": "https://porcino.example.com/privacy_policy",
"tos_uri": "https://porcino.example.com/info_policy",
"service_documentation": "https://porcino.example.com/api/v1/get/services",
"ref": "https://porcino.example.com/documentation/manuale_operativo.pdf"
}
An example of a decoded Trust Mark payload issued to an RP, attesting to its conformance to the rules for data management of underage users:¶
{
"trust_mark_id":"https://mushrooms.federation.example.com/openid_relying_party/private/under-age",
"iss": "https://trustissuer.pinarolo.example.it",
"sub": "https://vavuso.example.com/rp",
"iat": 1579621160,
"organization_name": "Pinarolo Suillus luteus",
"policy_uri": "https://vavuso.example.com/policy",
"tos_uri": "https://vavuso.example.com/tos"
}
An example of a decoded Trust Mark payload attesting a stipulation of an agreement between two organization's Entities:¶
{
"trust_mark_id": "https://mushrooms.federation.example.com/arrosto/agreements",
"iss": "https://agaricaceae.example.it",
"sub": "https://coppolino.example.com",
"iat": 1579621160,
"logo_uri": "https://coppolino.example.com/sgd-cmyk-150dpi-90mm.svg",
"organization_type": "public",
"id_code": "123456",
"email": "info@coppolino.example.com",
"organization_name#it": "Mazza di Tamburo",
"policy_uri#it": "https://coppolino.example.com/privacy_policy",
"tos_uri#it": "https://coppolino.example.com/info_policy",
"service_documentation": "https://coppolino.example.com/api/v1/get/services",
"ref": "https://agaricaceae.example.it/documentation/agaricaceae.pdf"
}
An example of a decoded Trust Mark payload asserting conformance to a security profile:¶
{
"trust_mark_id": "https://mushrooms.federation.example.com/ottimo/commestibile",
"iss": "https://cantharellus.cibarius.example.org",
"sub": "https://gallinaccio.example.com/op",
"iat": 1579621160,
"logo_uri": "https://cantharellus.cibarius/static/images/cantharellus-cibarius.svg",
"ref": "https://cantharellus.cibarius/cantharellus/cibarius"
}
An example of a decoded self-signed Trust Mark:¶
{
"trust_mark_id": "https://mushrooms.federation.example.com/trust-marks/self-signed",
"iss": "https://amanita.muscaria.example.com",
"sub": "https://amanita.muscaria.example.com",
"iat": 1579621160,
"logo_uri": "https://amanita.muscaria.example.com/img/amanita-mus.svg",
"ref": "https://amanita.muscaria.example.com/uploads/cookbook.zip"
}
An example of a third-party accreditation authority for Trust Marks:¶
{
"iss": "https://swamid.se",
"sub": "https://umu.se/op",
"iat": 1577833200,
"exp": 1609369200,
"trust_mark_id": "https://refeds.org/wp-content/uploads/2016/01/Sirtfi-1.0.pdf"
}
A non-normative example of a trust_marks
claim in the JWT Claims Set for an Entity Configuration in which the
Trust Mark is issued by an Entity that issues Trust Marks on behalf of
another Entity.
The fact that a Trust Mark is issued by a Trust Mark Issuer that is not
the owner of the Trust Mark is expressed by including a
delegation claim
in the Trust Mark, whose value is a signed JWT.¶
{
"delegation":
"eyJ0eXAiOiJ0cnVzdC1tYXJrLWRlbGVnYXRpb24rand0IiwiYWxnIjoiUl
MyNTYiLCJraWQiOiJrb3NHbTJ3dVpoOURHbU54QXRrdU80MHBQanBMMy1qQ
2YxTi1xUE8tWWVVIn0.eyJzdWIiOiJodHRwczovL3RtaS5leGFtcGxlLm9y
ZyIsInRydXN0X21hcmtfaWQiOiJodHRwczovL3JlZmVkcy5vcmcvc2lydGZ
pIiwiaXNzIjoiaHR0cHM6Ly90bV9vd25lci5leGFtcGxlLm9yZyIsImlhdC
I6MTcyNTE3NjMwMn0.ao0rWGpVjEgpNyFxsKawps8q71eYnp78TzRdY4P52
CT8QX6etXt-2L2Z1Vw5A6jx2mhjpPwWi_sOxfiOSA5TugJfN0Gbwj7teTzM
0IMciuasCWgnLrKyLZjS147ZE50I9e9P8Ot8UQwhmXcLiuwsbDxSdqM4pVp
75lfWnmzPH0L2pDZG5COFgIgSOAlK3TVMBOR8fziF-VmWNPzAfB0lSc-hjH
-7q66GyT43o3Exnm6DsoLxyB8bxG99BQltLxURDT90CzM6szGcF3OG64Rbe
0I4lT_LAOfvhlrRbT56eK4sJNCsbVbGnDBfFmyfB_HIeBMGP0L7T5JPMOUU
9bjIlA",
"iat": 1725176302,
"trust_mark_id": "https://refeds.org/sirtfi",
"sub": "https://entity.example.org",
"exp": 1727768302,
"iss": "https://tmi.example.org"
}
JWS Header Parameters for the Trust Mark delegation JWT in the "delegation" claim above¶
{
"typ": "trust-mark-delegation+jwt",
"alg": "RS256",
"kid": "kosGm2wuZh9DGmNxAtkuO40pPjpL3-jCf1N-qPO-YeU"
}
JWT Claims Set of the Trust Mark delegation JWT in the "delegation" claim above¶
{
"sub": "https://tmi.example.org",
"trust_mark_id": "https://refeds.org/sirtfi",
"iss": "https://tm_owner.example.org",
"iat": 1725176302
}
The federation endpoints of an Entity can be found in the configuration response as described in Section 9 or by other means.¶
For all federation endpoints, additional request parameters beyond those initially specified MAY be defined and used. If they are not understood, they MUST be ignored.¶
The fetch endpoint is used to collect Subordinate Statements one-by-one when assembling Trust Chains. An Entity with Subordinates MUST expose a fetch endpoint. An Entity MUST publish Subordinate Statements about its Immediate Subordinates via its fetch endpoint.¶
The fetch endpoint location is published in
the Entity's federation_entity metadata
in the federation_fetch_endpoint parameter
defined in Section 5.1.1.
Since this endpoint is used when building and validating Trust Chains,
its location MUST be available before metadata and metadata policies
from Superiors can be applied.
Therefore, this endpoint MUST be published directly in Entity Configuration
metadata and not in Subordinate Statements.¶
To fetch a Subordinate Statement, one needs to know the identifier of the Entity to ask (the issuer), the fetch endpoint of that Entity, and the Entity Identifier of the subject of the Subordinate Statement. The issuer is normally the Immediate Superior of the subject of the Subordinate Statement.¶
When client authentication is not used,
the request MUST be an HTTP request using the GET method
to a fetch endpoint with the
following query parameter, encoded in
application/x-www-form-urlencoded format.
The request is made to the fetch endpoint of the specified issuer.¶
When client authentication is used, the request MUST be an HTTP request using the POST method, with the parameters passed in the POST body.¶
The following is a non-normative example of an HTTP GET request for a Subordinate Statement from edugain.org about https://openid.sunet.se:¶
GET /federation_fetch_endpoint? sub=https%3A%2F%2Fopenid%2Esunet%2Ese HTTP/1.1 Host: edugain.org
A successful response MUST use the HTTP status code 200
with the content type
application/entity-statement+jwt,
to make it clear that the response contains an Entity Statement.
If it is a negative response, it will be a JSON object and the
content type MUST be
application/json.
If the fetch endpoint cannot provide data for the requested
sub parameter, returning the
not_found error code is RECOMMENDED.
If the sub parameter references the Entity
Identifier of the Issuing Entity, returning the
invalid_request error code is RECOMMENDED.
See more about error responses in Section 8.9.¶
The following is a non-normative example of the JWT Claims Set for a fetch response:¶
{
"iss": "https://edugain.org",
"sub": "https://openid.sunet.se",
"exp": 1568397247,
"iat": 1568310847,
"source_endpoint": "https://edugain.org/federation_fetch_endpoint",
"jwks": {
"keys": [
{
"e": "AQAB",
"kid": "dEEtRjlzY3djcENuT01wOGxrZlkxb3RIQVJlMTY0...",
"kty": "RSA",
"n": "x97YKqc9Cs-DNtFrQ7_vhXoH9bwkDWW6En2jJ044yH..."
}
]
},
"metadata":{
"federation_entity": {
"organization_name":"SUNET"
}
}
"metadata_policy": {
"openid_provider": {
"subject_types_supported": {
"value": [
"pairwise"
]
},
"token_endpoint_auth_methods_supported": {
"default": [
"private_key_jwt"
],
"subset_of": [
"private_key_jwt",
"client_secret_jwt"
],
"superset_of": [
"private_key_jwt"
]
}
}
}
}
The listing endpoint is exposed by Federation Entities acting as a Trust Anchor, Intermediate, or Trust Mark Issuer. The endpoint lists the Immediate Subordinates about which the Trust Anchor, Intermediate, or Trust Mark Issuer issues Entity Statements.¶
As a Trust Mark Issuer, the endpoint MAY list the Immediate Subordinates for which Trust Marks have been issued and are still valid, if the issuer exposing this endpoint supports Trust Mark filtering, as defined below.¶
In both cases, the list contained in the result MAY be a very large list.¶
The list endpoint location is published in
the Entity's federation_entity metadata
in the federation_list_endpoint parameter
defined in Section 5.1.1.
This endpoint MUST be published directly in Entity Configuration
metadata and not in Subordinate Statements.¶
The following example shows a tree of Entities belonging to the same federation including the Trust Anchor, Intermediate Entities, and Leaf Entities, discovered and collected through the Subordinate listing endpoints:¶
+----------------------+
| Trust Anchor |
+----------------------+
+---------------+ Subordinate Listing +--------------+
| +----------+-----------+ |
| | |
| | |
| | |
| | |
| | |
+------v-------+ +----------v-----------+ +------v-------+
| Leaf | | Intermediate | | Leaf |
+--------------+ +----------------------+ +--------------+
+----+ Subordinate Listing |
| +------------+---------+
| |
| |
| |
+----------v-----------+ |
| Intermediate | |
+----------------------+ |
| Subordinate Listing | |
+-+---------+----------+ |
| | |
| | |
+-------v--+ +v--------+ +--v------+
| Leaf | | Leaf | | Leaf |
+----------+ +---------+ +---------+
When client authentication is not used,
the request MUST be an HTTP request using the GET method
to a list endpoint with the
following query parameters, encoded in
application/x-www-form-urlencoded format.¶
entity_type
parameters are present, for example
entity_type=openid_provider&entity_type=openid_relying_party
,
the result MUST be filtered to include all specified Entity Types.
If the responder does not support this feature, it MUST
use the HTTP status code 400 and the content type
application/json, with
the error code
unsupported_parameter.¶
trust_marked is present and
set to true,
the result contains only the Immediate Subordinates for which
at least one Trust Mark have been issued and is still valid.
If the responder does not support this feature, it MUST
use the HTTP status code 400 and set the content type to
application/json, with
the error code
unsupported_parameter.¶
application/json, with
the error code
unsupported_parameter.¶
intermediate is present and set to
true, then if the responder knows
whether its Immediate Subordinates are Intermediates or not,
the result MUST be filtered accordingly.
If the responder does not support this feature, it MUST
use the HTTP status code 400 and the content type
application/json, with
the error code
unsupported_parameter.¶
When client authentication is used, the request MUST be an HTTP request using the POST method, with the parameters passed in the POST body.¶
The following is a non-normative example of an HTTP GET request for a list of Immediate Subordinates:¶
GET /list HTTP/1.1 Host: openid.sunet.se
A successful response MUST use the HTTP status code 200
with the content type application/json,
containing a JSON array with the known Entity Identifiers.¶
If the response is negative, the response is as defined in Section 8.9.¶
The following is a non-normative example of a response containing the Immediate Subordinate Entities:¶
200 OK Content-Type: application/json [ "https://ntnu.andreas.labs.uninett.no/", "https://blackboard.ntnu.no/openid/callback", "https://serviceprovider.andreas.labs.uninett.no/application17" ]
An Entity MAY use a resolve endpoint to fetch resolved metadata and Trust Marks for an Entity. The resolver fetches the subject's Entity Configuration, assembles a Trust Chain that starts with the subject's Entity Configuration and ends with the specified Trust Anchor's Entity Configuration, verifies the Trust Chain, and then applies all the policies present in the Trust Chain to the subject's metadata.¶
The resolver MUST verify that all present Trust Marks with identifiers recognized within the Federation are active. The response set MUST include only verified Trust Marks.¶
The resolve endpoint location is published in
the Entity's federation_entity metadata
in the federation_resolve_endpoint parameter
defined in Section 5.1.1.¶
When client authentication is not used,
the request MUST be an HTTP request using the GET method
to a resolve endpoint with the
following query parameters, encoded in
application/x-www-form-urlencoded format.¶
REQUIRED. The Trust Anchor that the resolve endpoint MUST use when resolving the metadata. The value is an Entity identifier.¶
The trust_anchor request parameter
MAY occur multiple times, in which case,
the resolver MAY return a successful resolve response
using any of the Trust Anchor values provided.¶
OPTIONAL. A specific Entity Type to resolve. Its value is an Entity Type Identifier, as specified in Section 5.1. If this parameter is not present, then all Entity Types are returned.¶
The entity_type request parameter
MAY occur multiple times, in which case, data for each Entity Type
whose Entity Type Identifier is in an entity_type
parameter value is returned.¶
When client authentication is used, the request MUST be an HTTP request using the POST method, with the parameters passed in the POST body.¶
The following is a non-normative example of a resolve request:¶
GET /resolve? sub=https%3A%2F%2Fop.example.it%2Fspid& entity_type=openid_provider& trust_anchor=https%3A%2F%2Fswamid.se HTTP/1.1 Host: openid.sunet.se
A successful response MUST use the HTTP status code 200
with the content type
application/resolve-response+jwt,
containing resolved metadata and
verified Trust Marks.¶
The response is a signed JWT that is explicitly typed by setting the
typ header parameter to
resolve-response+jwt to prevent
cross-JWT confusion, per Section 3.11 of [RFC8725].
Resolve responses without a typ header parameter
or with a different typ value MUST be rejected.
It is signed with a Federation Entity Key.¶
The resolve response JWT MUST include the
kid (Key ID) header parameter
with its value being the Key ID of the signing key used.¶
The resolve response JWT MUST return the Trust Chain
from the subject to the Trust Anchor
in its trust_chain parameter,
sorted as shown in Section 4.¶
The resolve response MAY also return the Trust Chain
from its issuer to the Trust Anchor
in the trust_chain JWS header parameter,
as specified in Section 4.3.
When this is present, the Trust Anchor in the Trust Chain
MUST match the Trust Anchor requested in the
related request in the trust_anchor parameter.¶
An issuer that provides its Trust Chain within the resolve response makes it evident that it is part of the same federation as the subject of the response. Thus, when the Trust Chains of both the issuer and the subject are available and the Federation Historical Keys endpoint is provided by the Trust Anchor, the resolve response becomes a long-lived attestation; it can be always verified, even when the Federation Keys change in the future.¶
The response SHOULD contain the
aud claim only
if the requesting party is authenticated,
in which case, the value MUST be the Entity Identifier
of the requesting party
and MUST NOT include any other values.¶
The claims in a resolve response are:¶
exp value of
the Trust Chain from which the resolve response was derived.¶
type
and expressed in the metadata format
defined in Section 3.¶
Additional claims MAY be defined and used in conjunction with the claims above.¶
If the response is negative, the response is as defined in Section 8.9.¶
The following is a non-normative example of the JWT Claims Set for a resolve response:¶
{
"iss": "https://resolver.spid.gov.it/",
"sub": "https://op.example.it/spid/",
"iat": 1516239022,
"exp": 1516298022,
"metadata": {
"openid_provider": {
"contacts": ["legal@example.it", "technical@example.it"],
"logo_uri":
"https://op.example.it/static/img/op-logo.svg",
"op_policy_uri":
"https://op.example.it/en/about-the-website/legal-information",
"federation_registration_endpoint":"https://op.example.it/spid/fedreg",
"authorization_endpoint":
"https://op.example.it/spid/authorization",
"token_endpoint": "https://op.example.it/spid/token",
"response_types_supported": [
"code",
"code id_token",
"token"
],
"grant_types_supported": [
"authorization_code",
"urn:ietf:params:oauth:grant-type:jwt-bearer"
],
"subject_types_supported": ["pairwise"],
"id_token_signing_alg_values_supported": ["RS256"],
"issuer": "https://op.example.it/spid",
"jwks": {
"keys": [
{
"kty": "RSA",
"use": "sig",
"n": "1Ta-sE ...",
"e": "AQAB",
"kid": "FANFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs"
}
]
}
}
},
"trust_marks": [
{"trust_mark_id": "https://www.spid.gov.it/certification/op/",
"trust_mark":
"eyJ0eXAiOiJ0cnVzdC1tYXJrK2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiOH
hzdUtXaVZmd1NnSG9mMVRlNE9VZGN5NHE3ZEpyS2ZGUmxPNXhoSElhMCJ9.
eyJpc3MiOiJodHRwczovL3d3dy5hZ2lkLmdvdi5pdCIsInN1YiI6Imh0dHBzOi
8vb3AuZXhhbXBsZS5pdC9zcGlkLyIsImlhdCI6MTU3OTYyMTE2MCwidHJ1c3Rf
bWFya19pZCI6Imh0dHBzOi8vd3d3LnNwaWQuZ292Lml0L2NlcnRpZmljYXRpb2
4vb3AvIiwibG9nb191cmkiOiJodHRwczovL3d3dy5hZ2lkLmdvdi5pdC90aGVt
ZXMvY3VzdG9tL2FnaWQvbG9nby5zdmciLCJyZWYiOiJodHRwczovL2RvY3MuaX
RhbGlhLml0L2l0YWxpYS9zcGlkL3NwaWQtcmVnb2xlLXRlY25pY2hlLW9pZGMv
aXQvc3RhYmlsZS9pbmRleC5odG1sIn0.
xyz-PDQ_..."
}
],
"trust_chain" : [
"eyJhbGciOiJSUzI1NiIsImtpZCI6Ims1NEhRdERpYnlHY3M5WldWTWZ2aUhm ...",
"eyJhbGciOiJSUzI1NiIsImtpZCI6IkJYdmZybG5oQU11SFIwN2FqVW1BY0JS ...",
"eyJhbGciOiJSUzI1NiIsImtpZCI6IkJYdmZybG5oQU11SFIwN2FqVW1BY0JS ..."
]
}
The basic assumption of this specification is that an Entity should have direct trust in no one except the Trust Anchor and its own capabilities. However, Entities may establish a kind of transitive trust in other Entities. For example, the Trust Anchor states who its Immediate Subordinates are and Entities may choose to trust them. If a party uses the resolve service of another Entity to obtain federation data, it is trusting the resolver to perform validation of the cryptographically protected metadata correctly and to provide it with authentic results.¶
This enables an Entity to check whether a Trust Mark has been issued to an Entity and is still active. The query MUST be sent to the Trust Mark Issuer.¶
The Trust Mark status endpoint location is published in
the Entity's federation_entity metadata
in the federation_trust_mark_status_endpoint parameter
defined in Section 5.1.1.
This endpoint MUST be published directly in Entity Configuration
metadata and not in Subordinate Statements.¶
The request MUST be an HTTP request using the GET method
to a Trust Mark status endpoint
with the following query parameters, encoded in
application/x-www-form-urlencoded format.¶
iat is not specified and the
Trust Mark Issuer has issued several Trust Marks with the
identifier specified in the request to the
Entity identified by sub, the
most recent one is assumed.¶
When client authentication is used, the request MUST be an HTTP request using the POST method, with the parameters passed in the POST body.¶
The following is a non-normative example of a Trust Mark status request:¶
GET /federation_trust_mark_status_endpoint? sub=https%3A%2F%2Fopenid.sunet.se%2FRP& trust_mark_id=https%3A%2F%2Frefeds.org%2Fsirtfi HTTP/1.1 Host: op.example.org
A successful response MUST use the HTTP status code 200
with the content type
application/json.
The response body is a JSON object containing the data below:¶
If the response is negative, the response is as defined in Section 8.9.¶
The following is a non-normative example of a Trust Mark status response:¶
200 OK
Content-Type: application/json
{
"active": true
}
The Trust Marked Entities listing endpoint is exposed by Trust Mark Issuers and lists all the Entities for which Trust Marks have been issued and are still valid.¶
The Trust Marked Entities listing endpoint location is published in
the Entity's federation_entity metadata
in the federation_trust_mark_list_endpoint parameter
defined in Section 5.1.1.¶
When client authentication is not used,
the request MUST be an HTTP request using the GET method
to a list endpoint with the
following query parameters, encoded in
application/x-www-form-urlencoded format.¶
When client authentication is used, the request MUST be an HTTP request using the POST method, with the parameters passed in the POST body.¶
The following is a non-normative example of an HTTP GET request for a list of Trust Marked Entities:¶
GET /trust_marked_list?trust_mark_id=https%3A%2F%2Ffederation.example.org%2Fopenid_relying_party%2Fprivate%2Funder-age HTTP/1.1 Host: trust-mark-issuer.example.org
A successful response MUST use the HTTP status code 200
with the content type application/json,
containing a JSON array with Entity Identifiers.¶
If the response is negative, the response is as defined in Section 8.9.¶
The following is a non-normative example of a response, containing the Trust Marked Entities:¶
200 OK Content-Type: application/json [ "https://blackboard.ntnu.no/openid/rp", "https://that-rp.example.org" ]
The Trust Mark endpoint is exposed by a Trust Mark Issuer to provide Trust Marks to subjects.¶
The Trust Mark endpoint location is published in
the Entity's federation_entity metadata
in the federation_trust_mark_endpoint parameter
defined in Section 5.1.1.¶
When client authentication is not used,
the request MUST be an HTTP request using the GET method
with the following query parameters, encoded in
application/x-www-form-urlencoded format.¶
When client authentication is used,
the request MUST be an HTTP request using the POST method,
with the parameters passed in the POST body.
The Trust Mark endpoint MAY choose to allow authenticated requests from
clients that are not the Trust Mark subject, as indicated by the
sub parameter. An example use case is to
let a Federation Entity retrieve the Trust Mark for another Entity.¶
The following is a non-normative example of an HTTP request for a Trust Mark with a specific Trust Mark ID and subject:¶
GET /trust_mark?trust_mark_id=https%3A%2F%2Fwww.spid.gov.it%2Fcertification%2Frp&sub=https%3A%2F%2Frp.example.it%2Fspid HTTP/1.1 Host: tuber.cert.example.org
A successful response MUST use the HTTP status code 200
with the content type
application/trust-mark+jwt,
containing the Trust Mark.¶
If the specified Entity doesn't have the specified Trust Mark, the response is negative and MUST use the HTTP status code 404.¶
The following is a non-normative example of a response, containing the Trust Mark for the specified Entity (with line wraps within values for display purposes only):¶
200 OK Content-Type: application/trust-mark+jwt eyJ0eXAiOiJ0cnVzdC1tYXJrK2p3dCIsImFsZyI6IlJTMjU2Iiwia2lkIjoia29zR20yd3Va aDlER21OeEF0a3VPNDBwUGpwTDMtakNmMU4tcVBPLVllVSJ9.eyJpc3MiOiJodHRwczovL3d 3dy5hZ2lkLmdvdi5pdCIsInN1YiI6Imh0dHBzOi8vcnAuZXhhbXBsZS5pdC9zcGlkIiwiaWF 0IjoxNTc5NjIxMTYwLCJ0cnVzdF9tYXJrX2lkIjoiaHR0cHM6Ly93d3cuc3BpZC5nb3YuaXQ vY2VydGlmaWNhdGlvbi9ycCIsImxvZ29fdXJpIjoiaHR0cHM6Ly93d3cuYWdpZC5nb3YuaXQ vdGhlbWVzL2N1c3RvbS9hZ2lkL2xvZ28uc3ZnIiwicmVmIjoiaHR0cHM6Ly9kb2NzLml0YWx pYS5pdC9kb2NzL3NwaWQtY2llLW9pZGMtZG9jcy9pdC92ZXJzaW9uZS1jb3JyZW50ZS8ifQ. L_pSh1InEiFAcs3E-1HBM7fNZYwF5ru3UGA_8yc80dGS3sszfA_sbj4AoW_zAJWQBdZpjxnH BBmybYXFrfZBcqxcedsrvUYrmbt1nPYxbUE54fRRoZK-sJmVqh1GzSan5nOmkxuAtMinU8k_ -aWnPWj83sYe2AzT2mMgkXiz8zhda3jZm8hoxZ4jR6B0YAvbMlq2pPWO5OWKdZhiFRMSprwh 0GYluQkK0j1aLNMGXD3keMJd2zEoWX9D7w2fXShAA48W3cNhuXyBVnCoum1K4IWK3s_fx4nI kp6W-V4jCBOpxp7Yo8LZ30o_xpEOzGTIECGWVR86azOAlwVC8XSiAA
Each Federation Entity MAY publish its previously used Federation Entity Keys at the historical keys endpoint defined in Section 5.1.1. The purpose of this endpoint is to provide the list of keys previously used by the Federation Entity to provide non-repudiation of statements signed by it after key rotation. This endpoint also discloses the reason for the retraction of the keys and whether they were expired or revoked, including the reason for the revocation.¶
Note that an expired key can be later additionally marked as revoked, to indicate a key compromise event discovered after the expiration of the key.¶
The publishing of the historical keys guarantees that Trust Chains will remain verifiable and usable as inputs to trust decisions after the key expiration, unless the key becomes revoked for a security reason.¶
When client authentication is not used, the request MUST be an HTTP request using the GET method to the federation historical keys endpoint.¶
When client authentication is used, the request MUST be an HTTP request using the POST method, with the client authentication parameters passed in the POST body.¶
The following is a non-normative example of a historical keys request:¶
GET /federation_historical_keys HTTP/1.1 Host: trust-anchor.example.com
The response is a signed JWK Set containing the historical keys.
It is signed with a Federation Entity Key.
A signed JWK Set is a signed JWT with a
JWK Set [RFC7517] as its payload.
A successful response MUST use the HTTP status code 200
with the content type
application/jwk-set+jwt.¶
Historical keys JWTs are explicitly typed by setting the
typ header parameter to
jwk-set+jwt to prevent
cross-JWT confusion, per Section 3.11 of [RFC8725].
Historical keys JWTs without a typ header parameter
or with a different typ value MUST be rejected.¶
Historical keys JWTs MUST include the
kid (Key ID) header parameter
with its value being the Key ID of the signing key used.¶
The claims in a historical keys JWT are:¶
REQUIRED. Array of JSON objects containing the signing keys for the Entity in JWK format.¶
JWKs in the keys
claim use the following parameters:¶
OPTIONAL. JSON object that contains the properties of the revocation, as defined below:¶
iat claim in
[RFC7519].¶
Additional members of the revoked
object MAY be defined and used.¶
Additional claims MAY be defined and used in conjunction with the claims above.¶
JWKs in the keys claim MAY also contain the
nbf parameter. For use in Historical Keys,
iat and exp
are sufficient to establish the key lifetime,
making nbf typically superfluous;
however, it is registered for use by profiles that may choose to
issue keys that do not immediately become valid at the time of issuance.
Its definition is:¶
nbf claim in
[RFC7519].¶
The following is a non-normative example of the JWT Claims Set for a historical keys response:¶
{
"iss": "https://trust-anchor.federation.example.com",
"iat": 123972394272,
"keys":
[
{
"kty":"RSA",
"n":"5s4qi …",
"e":"AQAB",
"kid":"2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs",
"iat": 123972394872,
"exp": 123974395972
},
{
"kty":"RSA",
"n":"ng5jr …",
"e":"AQAB",
"kid":"8KnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMJJr",
"iat": 123972394872,
"exp": 123974394972,
"revoked": {
"revoked_at": 123972495172,
"reason": "compromised",
}
}
]
}
Federation Entities are strongly encouraged to use a meaningful
reason value when indicating the revocation reason
for a Federation Entity Key. The reason
MAY be omitted
instead of using the unspecified value.¶
Below is the definition of the reason values.¶
The following table defines Federation Entity Keys revocation reasons. These reasons are inspired by Section 5.3.1 of [RFC5280].¶
| Reason | Description |
| unspecified | General or unspecified reason for the JWK status change. |
| compromised | The private key is believed to have been compromised. |
| superseded | The JWK is no longer active. |
A federation MAY specify and utilize additional reasons depending on the trust or security framework in use.¶
The Federation Historical Keys endpoint solves the problem of verifying historical Trust Chains when the Federation Entity Keys have changed, either due to expiration or revocation.¶
The Federation Historical Keys endpoint publishes the list of public keys used in the past by the Entity. These keys are needed to verify Trust Chains created in the past with Entity keys no longer published in the Entity's Entity Configuration.¶
The Federation Historical Keys endpoint response contains a signed JWT that attests to all the expired and revoked Entity keys.¶
Based on the attributes contained in the Entity Statements
that form a Trust Chain, it MAY be also possible to verify
the non-federation public keys used in the past by Leaf Entities for
signature operations for OpenID Connect
requests and responses.
For example, an Entity Statement issued for a Leaf
MAY also include the
jwks claim for the Leaf's Entity Types,
in its
metadata or
metadata_policy claims.¶
A simple example: In the following Trust Chain, the
Federation Intermediate attests to the Leaf's OpenID Connect RP
jwks
in the Subordinate Statement issued about the Leaf. The result is
a Trust Chain that contains the Leaf's OpenID Connect RP JWK Set,
needed to verify historical signature on
Request Objects and any other signed JWT issued by the Leaf as an RP.
This example Trust Chain contains:¶
an Entity Configuration about the RP published by the RP,¶
a Subordinate Statement about the RP published by Organization A,
with the claim jwks contained in
metadata or
metadata_policy attesting the
Leaf's OpenID Connect RP jwks, and¶
a Subordinate Statement about Organization A published by Federation F.¶
Client authentication is not used at any of the federation endpoints, by default. Federations can choose to make client authentication OPTIONAL, REQUIRED, and/or not allowed at particular federation endpoints.¶
Client authentication with private_key_jwt
is the default client authentication method to federation endpoints
when client authentication is supported.
This client authentication method is described in Section 9 of
OpenID Connect Core 1.0 [OpenID.Core].
The client authentication JWT MUST be signed with a Federation Entity Key.
The audience of the JWT MUST be the Entity Identifier
of the Entity whose federation endpoint is being authenticated to.
The endpoint MUST NOT accept JWTs containing audience values
other than its Entity Identifier.
When client authentication is used,
the request MUST be an HTTP request using the POST method,
with the client authentication and endpoint request parameters passed in the POST body.
Federations can choose to also use other client authentication methods.¶
Like other OAuth and OpenID endpoints supporting client authentication,
this specification defines metadata parameters saying which
client authentication methods are supported for each endpoint.
These largely parallel the
token_endpoint_auth_methods_supported
metadata value defined in Section 3 of
OpenID Connect Discovery 1.0 [OpenID.Discovery].¶
Specifically, for each of the federation endpoints defined in
Section 5.1.1, parameters named
*_auth_methods
are defined, where the * represents the
federation endpoint names
federation_fetch_endpoint,
federation_list_endpoint, ...,
federation_historical_keys_endpoint.¶
The *_auth_methods
metadata parameters list supported client authentication methods
for these endpoints, just as
token_endpoint_auth_methods_supported
does for the Token Endpoint.
In addition, the value none MAY be used
to indicate that client authentication is not required at the endpoint.¶
So, for instance, this metadata declaration states that
requests authenticated with
private_key_jwt
are REQUIRED at the
federation_trust_mark_endpoint:¶
"federation_trust_mark_endpoint_auth_methods": ["private_key_jwt"]
If omitted, the default value for these methods is
["none"],
indicating that only unauthenticated requests are accepted.¶
The endpoint_auth_signing_alg_values_supported
metadata parameter lists supported client authentication
signing algorithms supported for these endpoints, just as
token_endpoint_auth_signing_alg_values_supported
does for the Token Endpoint.¶
If the request was malformed or an error occurred during
the processing of the request,
the response body SHOULD be a JSON object with the content type
application/json.
In compliance with
[RFC6749], the following
standardized error format SHOULD be used:¶
REQUIRED. Error codes in the IANA "OAuth Extensions Error Registry" [IANA.OAuth.Parameters] MAY be used. This specification also defines the following error codes:¶
The following is a non-normative example of an error response:¶
400 Bad request
Content-Type: application/json
{
"error": "invalid_request",
"error_description":
"Required request parameter [sub] was missing."
}
The Entity Configuration of every Federation Entity is published
at its configuration endpoint.
Its location is determined by concatenating the string
/.well-known/openid-federation
to the Entity Identifier
(which MUST contain scheme and host components
and MAY also contain port and path components).
For instance, the configuration endpoint for the Entity Identifier
https://entity.example is the URL
https://entity.example/.well-known/openid-federation.¶
Federation Entities MUST make an Entity Configuration document available at their configuration endpoint. The sole exception to this rule is for an RP that only does Explicit Registration. Since it posts the Entity Configuration to the OP during client registration, the OP has everything it needs from the RP.¶
An Entity Configuration document MUST be queried using an HTTP GET request at the previously specified path.¶
In this example, the requesting party would make the following request to the Entity
https://openid.sunet.se
to obtain its Entity Configuration:¶
GET /.well-known/openid-federation HTTP/1.1 Host: openid.sunet.se
The response is an Entity Configuration, as described in
Section 3.
If the Entity is an Intermediate Entity or a Trust Anchor, the
response MUST contain metadata for a federation Entity
(federation_entity).¶
A successful response MUST use the HTTP status code 200
with the content type
application/entity-statement+jwt,
to make it clear that the response contains an Entity Statement.
In case of an error, the response
is as defined in
Section 8.9.¶
The following is a non-normative example JWT Claims Set for a response from an Intermediate Entity:¶
{
"iss": "https://openid.sunet.se",
"sub": "https://openid.sunet.se",
"iat": 1516239022,
"exp": 1516298022,
"metadata": {
"federation_entity": {
"contacts": ["ops@sunet.se"],
"federation_fetch_endpoint": "https://sunet.se/openid/fedapi",
"homepage_uri": "https://www.sunet.se",
"organization_name": "SUNET"
},
"openid_provider": {
"issuer": "https://openid.sunet.se",
"signed_jwks_uri": "https://openid.sunet.se/jwks.jose",
"authorization_endpoint":
"https://openid.sunet.se/authorization",
"client_registration_types_supported": [
"automatic",
"explicit"
],
"grant_types_supported": [
"authorization_code"
],
"id_token_signing_alg_values_supported": [
"ES256", "RS256"
],
"logo_uri":
"https://www.umu.se/img/umu-logo-left-neg-SE.svg",
"op_policy_uri":
"https://www.umu.se/en/website/legal-information/",
"response_types_supported": [
"code"
],
"subject_types_supported": [
"pairwise",
"public"
],
"token_endpoint": "https://openid.sunet.se/token",
"federation_registration_endpoint":
"https://op.umu.se/openid/fedreg",
"token_endpoint_auth_methods_supported": [
"private_key_jwt"
]
}
},
"jwks": {
"keys": [
{
"alg": "RS256",
"e": "AQAB",
"kid": "key1",
"kty": "RSA",
"n": "pnXBOusEANuug6ewezb9J_...",
"use": "sig"
}
]
},
"authority_hints": [
"https://edugain.org/federation"
]
}
An Entity (Party A) that wants to establish trust with another Entity (Party B) MUST have Party B's Entity Identifier and a list of Entity Identifiers of Trust Anchors and their public signing keys. Party A will first have to fetch sufficient Entity Statements to establish at least one chain of trust from Party B to one or more of the Trust Anchors. After that, Party A MUST validate the Trust Chains independently, and if there are multiple valid Trust Chains and if the application demands it, choose one to use.¶
To delegate the Trust Chain evaluation to a trusted third party, the Entity (Party A) that wants to establish trust with another Entity (Party B) MAY use a resolve endpoint, as defined in Section 8.3.¶
Depending on the circumstances, Party A MAY be handed Party B's Entity Configuration, or it may have to fetch it by itself. If it needs to fetch it, it will use the process described in Section 9 based on the Entity Identifier of Party B.¶
The next step is to iterate through the list of
Intermediates listed in
authority_hints, ignoring the authority
hints that end in an unknown Trust Anchor,
requesting an Entity Configuration from each of the Intermediates.
If the received Entity Configuration contains an authority hint, this
process is repeated.¶
With the list of all Intermediates and the Trust Anchor, the respective fetch endpoints, as defined in Section 8.1, are used to fetch Entity Statements about the Intermediates and Party B.¶
Federation participants MUST NOT attempt to fetch
Entity Statements they already have obtained during this
process to prevent loops.
An invalid_trust_chain error
SHOULD be returned if a loop is encountered.¶
A successful operation will return one or more lists of Entity Statements. Each of the lists terminating in a self-signed Entity Statement is issued by a Trust Anchor.¶
If there is no path from Party B to at least one of the trusted Trust Anchors, then the list will be empty and there is no way of establishing trust in Party B's information. How Party A deals with this is out of scope for this specification.¶
The following sequence diagram represents the interactions between the RP, the OP, and the Trust Anchor during a trust evaluation made by the OP about the RP. Relating this to the preceding description, in this diagram, Party A is the OP and Party B is the RP.¶
+-----+ +-----+ +--------------+ | RP | | OP | | Trust Anchor | +-----+ +-----+ +--------------+ | | | | Entity Configuration Request | | |<------------------------------| | | | | | Entity Configuration Response | | |------------------------------>| | | | | | | Evaluates authority_hints | | |-------------------------- | | | | | | |<------------------------- | | | | | | Entity Configuration Request | | |--------------------------------------->| | | | | | Entity Configuration Response | | |<---------------------------------------| | | | | | Obtains Fetch Endpoint | | |----------------------- | | | | | | |<---------------------- | | | | | | Request Subordinate Statement about RP | | |--------------------------------------->| | | | | | Subordinate Statement about RP | | |<---------------------------------------| | | | | | Evaluates the Trust Chain | | |-------------------------- | | | | | | |<------------------------- | | | | | | Applies Metadata Policies | | |-------------------------- | | | | | | |<------------------------- | | | | | | Derives the RP's Resolved Metadata | | |----------------------------------- | | | | | | |<---------------------------------- |
As described in Section 4, a Trust Chain consists of an ordered list of Entity Statements. So however Party A has acquired the set of Entity Statements, it MUST now verify that it is a proper Trust Chain using the rules laid out in that section.¶
Let us refer to the Entity Statements in the Trust Chain as ES[j], where j = 0,...,i, with 0 being the index of the first Entity Statement and i being the zero-based index of the last. To validate the Trust Chain, the following MUST be done:¶
For each Entity Statement ES[j], where j = 0,..,i:¶
For ES[0] (the Entity Configuration of the Trust Chain subject), verify that
iss == sub.¶
For ES[0], verify that its signature validates with a public key in ES[0]["jwks"].¶
For each j = 0,...,i-1, verify that ES[j]["iss"] == ES[j+1]["sub"].¶
For each j = 0,...,i-1, verify that the signature of ES[j] validates with a public key in ES[j+1]["jwks"].¶
For ES[i] (the Trust Anchor's Entity Configuration), verify that the issuer matches the Entity Identifier of the Trust Anchor.¶
For ES[i], verify that its signature validates with a public key of the Trust Anchor.¶
Verifying the signature is a much more expensive operation than verifying the correctness of the statement and the timestamps. An implementer MAY therefore choose not to verify the signatures until all the other checks have been done.¶
Federation participants MAY cache Entity Statements and signature verification results until they expire, per Section 10.4.¶
If multiple valid Trust Chains are found, Party A will need to decide on which one to use. One simple rule would be to prefer a shorter chain over a longer one. Federation participants MAY follow other rules according to local policy.¶
Each Entity Statement in a Trust Chain is signed and MUST have an
expiration time (exp).
The expiration time of the whole Trust Chain is the minimum
(exp) value within the Trust Chain.¶
If the federation topology is being updated, for example when a set of Leaf Entities is moved to a new Intermediate Entity, the Trust Chain validation may fail in a transient manner. Retrying after a period of time may resolve the situation.¶
Note that an alternative method for resolving a Trust Chain for an Entity (Party B) using the methods described above is to use a resolve endpoint, as described in Section 8.3. This lets the resolver do the work that otherwise the Entity (Party A) wanting to establish trust would have to do for itself.¶
This specification facilitates smoothly updating metadata and public keys.¶
As described in Section 10.4, each Trust Chain has an expiration time. Federation participants MUST support refreshing a Trust Chain when it expires. How often a participant reevaluates the Trust Chain depends on how quickly it wants to find out that something has changed.¶
If a Leaf Entity publishes its public keys in its metadata
using jwks, the expiration time of
its Entity Configuration
can be used to control how often the receiving Entity
needs to fetch an updated set of public keys.¶
A Trust Anchor MUST publish an Entity Configuration about itself. The Trust Anchor SHOULD set an expiration time on its Entity Configuration, such that federation participants will re-fetch it at reasonable intervals. When a Trust Anchor rolls over its signing keys, it needs to:¶
Add the new keys to the jwks representing
the Trust Anchor's signing keys in its Entity Configuration.¶
Keep signing the Entity Configuration and the Entity Statements using the old keys for a long enough time period to allow all Subordinates to have obtained the new keys.¶
Switch to signing with the new keys.¶
After a reasonable time period, remove the old keys. What is regarded as a reasonable time is dependent on the security profile and risk assessment of the Trust Anchor.¶
It is RECOMMENDED that Federation Operators provide a means of retrieving the public keys for the Trust Anchors it administers that is independent of those Trust Anchors' Entity Configurations. This is intended to provide redundancy in the eventuality of the compromise of the Web PKI infrastructure underlying retrieval of public keys from Entity Configurations.¶
The keys retrieved via the independent mechanism specified by the Federation Operator SHOULD be compared to those retrieved via the Trust Anchor's Entity Configuration. If they do not match, both SHOULD be retrieved again. If they still do not match, it is indicative of a security or configuration problem. The appropriate remediation steps in that eventuality SHOULD be specified by the Federation Operator.¶
Since the participants in federations are expected to check the Trust Chain on a regular frequent basis, this specification does not define a revocation process. Specific federations MAY make a different choice and will then have to define their own revocation process.¶
This section describes how the mechanisms defined in this specification are used to establish trust between an RP and an OP that have no explicit configuration or registration between them in advance.¶
There are two alternative approaches to establish trust between an RP and an OP: Automatic Registration and Explicit Registration. Members of a federation or a community SHOULD agree upon which one to use. While implementations should support both methods, deployments MAY choose to use one or the other of them.¶
Independent of whether the RP uses Automatic or Explicit Registration, the way that the RP establishes trust with the OP is the same: it uses Trust Chains, as described in Section 10.¶
Note that both Automatic Registration and Explicit Registration
can also be used for OAuth 2.0 profiles other than OpenID Connect.
To do so, rather than using the Entity Type Identifiers
openid_relying_party and
openid_provider,
one would instead use the Entity Type Identifiers
oauth_client and
oauth_authorization_server,
or possibly other Entity Type Identifiers defined for the specific
OAuth 2.0 profile being used.¶
Automatic Registration enables an RP to make Authentication Requests without a prior registration step with the OP. The OP resolves the RP's Entity Configuration from the Client ID in the Authentication Request, following the process defined in Section 10.¶
Automatic Registration has the following characteristics:¶
In all interactions with the OP, the RP employs its Entity Identifier as the Client ID. The OP retrieves the RP's Entity Configuration from the URL derived from the Entity Identifier, as described in Section 9.¶
Since there is no registration step prior to the Authentication Request, asymmetric cryptography MUST be used to authenticate requests when using Automatic Registration. Asymmetric cryptography is used to authenticate requests; therefore, the OP neither assigns a Client Secret to the RP nor returns it as a result of the registration process.¶
An OP that supports Automatic Registration MUST include the
automatic keyword in its
client_registration_types_supported
metadata parameter.¶
The Authentication Request is performed by passing a signed Request Object by value as described in Section 6.1 of OpenID Connect Core 1.0 [OpenID.Core] and The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR) [RFC9101] or using a pushed authorization request, as described in Pushed Authorization Requests [RFC9126].¶
Authentication requests MUST demonstrate that the requesting Entity controls the Entity's RP keys, using one of the methods described below. Attempted authentication requests that do not do so MUST be rejected.¶
Deployments MAY choose to not support passing the request object
by reference
(using the request_uri request parameter)
because allowing this would make it easier for attackers
to mount denial of service attacks against
OAuth 2.0 Authorization Servers or OpenID Providers.
They can do this by using the
request_uri_parameter_supported
OP metadata parameter with the value false.
If the request parameters are too large to practically
be passed by value as query parameters,
the request parameters can instead be sent via HTTP POST or
a Pushed Authorization Request [RFC9126],
as described in Section 12.1.1.2.¶
When a Request Object is used at the Authorization Endpoint
or the Pushed Authorization Request Endpoint,
the value of the request
parameter is a JWT whose Claims are the request parameters
specified in Section 3.1.2 in
OpenID Connect Core 1.0 [OpenID.Core].
The JWT MUST be signed and MAY be encrypted.
The following parameters are used in the Request Object:¶
client_id
value MUST be the RP's Entity Identifier.¶
iss
value MUST be the RP's Entity Identifier.¶
private_key_jwt
client authentication.¶
When the trust_chain
request parameter
is used in the authentication request, the Relying Party
informs the OP of the sequence of Entity Statements
that proves the trust relationship between it
and the selected Trust Anchor.¶
Due to the large size of a Trust Chain, it may be necessary
to use the HTTP POST method,
a request_uri, or
a Pushed Authorization Request [RFC9126]
for the request.¶
The following is a non-normative example of the JWT Claims Set in a Request Object:¶
{
"typ": "oauth-authz-req+jwt",
"alg": "RS256",
"kid": "that-kid-which-points-to-a-jwk-contained-in-the-trust-chain",
}
.
{
"aud": "https://op.example.org",
"client_id": "https://rp.example.com",
"exp": 1589699162,
"iat": 1589699102,
"iss": "https://rp.example.com",
"jti": "4d3ec0f81f134ee9a97e0449be6d32be",
"nonce": "4LX0mFMxdBjkGmtx7a8WIOnB",
"redirect_uri": "https://rp.example.com/authz_cb",
"response_type": "code",
"scope": "openid profile email address phone",
"state": "YmX8PM9I7WbNoMnnieKKBiptVW0sP2OZ",
"trust_chain" : [
"eyJhbGciOiJSUzI1NiIsImtpZCI6Ims1NEhRdERpYnlHY3M5WldWTWZ2aUhm ...",
"eyJhbGciOiJSUzI1NiIsImtpZCI6IkJYdmZybG5oQU11SFIwN2FqVW1BY0JS ...",
"eyJhbGciOiJSUzI1NiIsImtpZCI6IkJYdmZybG5oQU11SFIwN2FqVW1BY0JS ..."
]
}
The following is a non-normative example of an Authentication
Request using the request parameter
(with line wraps within values for display purposes only):¶
Host: server.example.com
GET /authorize?
redirect_uri=https%3A%2F%2Frp.example.com%2Fauthz_cb
&scope=openid+profile+email+address+phone
&response_type=code
&client_id=https%3A%2F%2Frp.example.com
&request=eyJ0eXAiOiJvYXV0aC1hdXRoei1yZXErand0IiwiYWxnIjoiUlMyNTYiLCJ
raWQiOiJOX19EOThJdkI4TmFlLWt3QTZuck90LWlwVGhqSGtEeDM3bmljRE1IM04
0In0.
eyJhdWQiOiJodHRwczovL29wLmV4YW1wbGUub3JnIiwiY2xpZW50X2lkIjoiaHR0
cHM6Ly9ycC5leGFtcGxlLmNvbSIsImV4cCI6MTU4OTY5OTE2MiwiaWF0IjoxNTg5
Njk5MTAyLCJpc3MiOiJodHRwczovL3JwLmV4YW1wbGUuY29tIiwianRpIjoiNGQz
ZWMwZjgxZjEzNGVlOWE5N2UwNDQ5YmU2ZDMyYmUiLCJub25jZSI6IjRMWDBtRk14
ZEJqa0dtdHg3YThXSU9uQiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vcnAuZXhh
bXBsZS5jb20vYXV0aHpfY2IiLCJyZXNwb25zZV90eXBlIjoiY29kZSIsInNjb3Bl
Ijoib3BlbmlkIHByb2ZpbGUgZW1haWwgYWRkcmVzcyBwaG9uZSIsInN0YXRlIjoi
WW1YOFBNOUk3V2JOb01ubmllS0tCaXB0Vlcwc1AyT1oiLCJ0cnVzdF9jaGFpbiI6
WyJleUpoYkdjaU9pSlNVekkxTmlJc0ltdHBaQ0k2SW1zMU5FaFJkRVJwWW5sSFkz
TTVXbGRXVFdaMmFVaG0gLi4uIiwiZXlKaGJHY2lPaUpTVXpJMU5pSXNJbXRwWkNJ
NklrSllkbVp5Ykc1b1FVMTFTRkl3TjJGcVZXMUJZMEpTIC4uLiIsImV5SmhiR2Np
T2lKU1V6STFOaUlzSW10cFpDSTZJa0pZZG1aeWJHNW9RVTExU0ZJd04yRnFWVzFC
WTBKUyAuLi4iXX0.
Rv0isfuku0FcRFintgxgKDk7EnhFkpQRg3Tm6N6fCHAHEKFxVVdjy4
9JboJtxKcQVZKN9TKn3lEYM1wtF1e9PQrNt4HZ21ICfnzxXuNx1F5SY1GXCU2n2y
FVKtz3N0YkAFbTStzy-sPRTXB0stLBJH74RoPiLs2c6dDvrwEv__GA7oGkg2gWt6
VDvnfDpnvFi3ZEUR1J8MOeW_VFsayrT9sNjyjsz62Po4LzvQKQMKxq0dNwPNYuuS
fUmb-YvmFguxDb3weYl8WS-
48EIkP1h4b_KGU9x9n7a1fUOHrS02ATQZmaL8jUil7yLJqx5MiCsPr4pCAXV0doA
4pwhs_FIw HTTP/1.1
When the OP receives an incoming Authentication Request, the OP supports OpenID Federation, the incoming Client ID is a valid URL, and the OP does not have the Client ID registered as a known client, then the OP SHOULD resolve the Trust Chains related to the requestor.¶
An RP MAY present a Trust Chain related to itself to the OP in the Request Object using the
trust_chain request parameter
defined in Section 12.1.1.1.
If the OP does not have a valid registration for the RP or
its registration has expired, the OP MAY use the received
Trust Chain as a hint for which path to take from the
RP's Entity to the Trust Anchor.
The OP MAY evaluate the statements in the
provided Trust Chain
to make its Federation Entity Discovery procedure more efficient,
especially if the RP contains multiple authority hints in
its Entity Configuration.
If the OP already has a valid registration for the RP, it MAY
use the received Trust Chain to update the RP's registration.¶
A Trust Chain may be relied upon by the OP because it has validated
all of its statements. This is true whether these statements
are retrieved from their URLs or whether they
are provided via the trust_chain
request parameter in the Request Object.
In both cases, the OP MUST fully verify the Trust Chain
including every Entity Statement contained in it.¶
If the RP does not include the
trust_chain
request parameter in the Request Object,
the OP for some reason decides not to use the provided Trust Chain,
or the OP does not support this feature, it then MUST
validate the possible Trust Chains, starting with the RP's Entity Configuration,
as described in Section 10.1,
and resolve the RP metadata with Entity Type
openid_relying_party.¶
The OP SHOULD furthermore verify that the resolved metadata of the RP complies with the client metadata specification OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration].¶
Once the OP has the RP's metadata, it MUST verify that the client
was actually the one sending the Authentication Request by
verifying the signature of the Request Object using the key
material the client published in its metadata for the
openid_relying_party Entity Type.
If the signature does not verify, the OP MUST reject the request.¶
Pushed Authorization Requests [RFC9126]
provide an
interoperable way to push authentication request parameters
directly to the AS in exchange for a one-time-use
request_uri.
The standard PAR metadata parameters are used in the
RP and OP metadata to indicate its use.¶
When using PAR with Automatic Registration, either a Request Object MUST be used as a PAR parameter, with the Request Object being as described in Section 12.1.1.1, or a client authentication method for the PAR endpoint MUST be used that proves possession of one of the RP's private keys. Furthermore, the corresponding public key MUST be in the Entity's RP JWK Set.¶
The two applicable PAR client authentication methods are:¶
JWT Client authentication, as described
for private_key_jwt in Section 9 of
OpenID Connect Core 1.0 [OpenID.Core].
In this case, the audience of the client authentication JWT
MUST be the OP's Entity Identifier
and MUST NOT include any other values.¶
mTLS using self-signed certificates,
as described in Section 2.2 of [RFC8705].
In this case, the self-signed certificate MUST be present as
the value of an x5c
claim for a key in the Entity's RP JWK Set.
In this case, the server MUST omit certificate chain validation.¶
A Pushed Authorization Request to the OP could look like this:¶
POST /par HTTP/1.1 Host: op.example.org Content-Type: application/x-www-form-urlencoded redirect_uri=https%3A%2F%2Frp.example.com%2Fauthz_cb &scope=openid+profile+email+address+phone &response_type=code &nonce=4LX0mFMxdBjkGmtx7a8WIOnB &state=YmX8PM9I7WbNoMnnieKKBiptVW0sP2OZ &client_id=https%3A%2F%2Frp.example.com &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A client-assertion-type%3Ajwt-bearer &client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6ImRVTjJ hMDF3Umtoa1NXcGxRVGh2Y1ZCSU5VSXdUVWRPVUZVMlRtVnJTbW hFUVhnelpYbHBUemRRTkEifQ. eyJzdWIiOiAiaHR0cHM6Ly9ycC5leGFtcGxlLmNvbSIsICJpc3M iOiAiaHR0cHM6Ly9ycC5leGFtcGxlLmNvbSIsICJpYXQiOiAxNT g5NzA0NzAxLCAiZXhwIjogMTU4OTcwNDc2MSwgImF1ZCI6ICJod HRwczovL29wLmV4YW1wbGUub3JnIiwgImp0aSI6ICIzOWQ1YWU1 NTJkOWM0OGYwYjkxMmRjNTU2OGVkNTBkNiJ9. oUt9Knx_lxb4V2S0tyNFH CNZeP7sImBy5XDsFxv1cUpGkAojNXSy2dnU5HEzscMgNW4wguz6 KDkC01aq5OfN04SuVItS66bsx0h4Gs7grKAp_51bClzreBVzU4g _-dFTgF15T9VLIgM_juFNPA_g4Lx7Eb5r37rWTUrzXdmfxeou0X FC2p9BIqItU3m9gmH0ojdBCUX5Up0iDsys6_npYomqitAcvaBRD PiuUBa5Iar9HVR-H7FMAr7aq7s-dH5gx2CHIfM3-qlc2-_Apsy0 BrQl6VePR6j-3q6JCWvNw7l4_F2UpHeanHb31fLKQbK-1yoXDNz DwA7B0ZqmuSmMFQ
The requirements specified in Section 12.1.1.1.2 also apply to Pushed Authorization Requests [RFC9126].¶
Once the OP has the RP's metadata, it MUST verify the client
is using the keys published for the
openid_relying_party
Entity Type Identifier.
If the RP does not verify, the OP MUST reject the request.¶
The means of verification depends on the client authentication method used:¶
x5c
claim for a key in the JWK Set containing the RP's keys.¶
The response to a successful authentication request when using Automatic Registration is the same as the successful authentication responses defined in [OpenID.Core]. In particular, it is a successful OAuth 2.0 authorization response sent to the Client's redirection URI.¶
The error response to an unsuccessful authentication request when using Automatic Registration is the same as the error authentication responses defined in [OpenID.Core]. In particular, it is an OAuth 2.0 authorization error response sent to the Client's redirection URI, unless a Pushed Authorization Request [RFC9126] was used for the request.¶
However, as in both [OpenID.Core] and [RFC6749], if the redirection URI is invalid, redirection MUST NOT be performed, and instead the Authorization Server SHOULD inform the End-User of the error in the user interface. The Authorization Server MAY also choose to do this if it has reason to believe that the redirection URI might be being used as a component of an open redirector.¶
If the OP fails to establish trust with the RP or
finds the RP metadata to be invalid or in conflict with metadata policy,
it MUST treat the redirection URI as invalid
and not perform redirection.
This means that the error codes
invalid_trust_anchor,
invalid_trust_chain, and
invalid_metadata,
which are about reasons trust failed to be established,
SHOULD only be returned in
Pushed Authorization Request [RFC9126]
error responses, and not to the Client's redirection URI.¶
In addition to the error codes contained in the IANA "OAuth Extensions Error Registry" registry [IANA.OAuth.Parameters], this specification also defines the error codes in Section 8.9, which MAY also be used.¶
The following is a non-normative example authentication error response:¶
HTTP/1.1 302 Found
Location: https://client.example.org/cb?
error=consent_required
&error_description=
Consent%20by%20the%20End-User%20required
&state=af0ifjsldkj
Automatic Registration is designed to be able to be employed for OAuth 2.0 use cases beyond OpenID Connect, as noted in Section 12. For instance, ecosystems using bare OAuth 2.0 [RFC6749] or FAPI [FAPI] can utilize Automatic Registration.¶
Using this method, the RP establishes its client registration with the OP by means of a dedicated registration request, similar to [OpenID.Registration], but instead of its metadata, the RP submits its Entity Configuration or an entire Trust Chain. When the Explicit Registration is completed, the RP can proceed to make regular OpenID authentication requests to the OP.¶
An OP that supports Explicit Registration MUST include the
explicit keyword in its
client_registration_types_supported
metadata parameter and set the
federation_registration_endpoint metadata
parameter to the URL at which it receives Explicit Registration requests.¶
Explicit Registration is suitable for implementation on top of the OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration] endpoint of an OP deployment. In contrast to Automatic Registration, it enables an OP to provision a Client ID, potentially a Client Secret, and other metadata parameters.¶
An example of an Explicit Registration is provided in Appendix A.3.2.¶
The RP performs Explicit Client Registration as follows:¶
Once the RP has determined a set of Trust Anchors it has in common with the OP, it chooses the subset it wants to proceed with. This may be a single Trust Anchor, or it can also be more than one. The RP MUST perform Trust Chain and metadata resolution for the OP, as specified in Section 10. If the resolution is not successful, the RP MUST abort the request.¶
Using this subset of Trust Anchors, the RP chooses a set of
authority_hints
from the hints that are available to it. Each hint MUST,
when used as a starting point for Trust Chain collection,
lead to at least one of the Trust Anchors in the subset.
If the RP has more than one Trust Anchor in common with the
OP it MUST select a subset of Trust Anchors to proceed with.
The subset may be as small as a single Trust Anchor, or
include multiple ones.¶
The RP will then construct its Entity Configuration,
where the metadata statement chosen is influenced by the OP's
metadata and where the
authority_hints
included are picked by the process described above.
From its Immediate Superiors, the RP MUST select
one or more authority_hints so
that every hint, when used as the starting point for a Trust Chain
collection, leads to at least one of the Trust Anchors
in the subset selected above.¶
The RP MAY include its Entity Configuration
in a Trust Chain regarding itself.
In that case, the Registration Request will contain an
array with the sequence of
Entity Statements that compose the Trust Chain
between the RP that is making the request and the
selected Trust Anchor.
The RP MUST include its
metadata in its Entity Configuration and use the
authority_hints selected above.¶
The RP SHOULD select its metadata parameters to comply with the resolved OP metadata and thus ensure a successful registration with the OP. Note that if the submitted RP metadata is not compliant with the metadata of the OP, the OP may choose to modify it to make it compliant rather than reject the request with an error response.¶
The Entity Configuration, or the entire Trust Chain,
is sent, using HTTP POST, to the
federation_registration_endpoint.
The Entity Configuration or Trust Chain is the entire POST body.
The RP MUST sign its Entity Configuration with a current
Federation Entity Key in its possession.¶
The content type of the Registration Request MUST be
application/entity-statement+jwt
when it contains only the Entity Configuration of the
requestor. Otherwise, when it contains the Trust Chain, the
content type of the Registration Request MUST be
application/trust-chain+json.
The RP MAY include its Entity Configuration in a Trust Chain
that leads to the RP. In this case, the registration request
will contain an array consisting of the sequence of
statements that make up the Trust Chain between the RP and
the Trust Anchor the RP selected.¶
The following Entity Configuration claims are specified for use in Explicit Registration requests. Their full descriptions are in Section 3.¶
openid_relying_party
Entity Type Identifier.¶
The request MUST be an HTTP request to the
federation_registration_endpoint of
the OP, using the POST method.¶
When the RP submits an Entity Configuration the content type of
the request MUST be
application/entity-statement+jwt.
When the RP submits a Trust Chain, the content type MUST be
application/trust-chain+json.¶
The OP processes the request as follows:¶
Upon receiving a registration request, the OP MUST inspect the content type to determine whether it contains an Entity Configuration or an entire Trust Chain.¶
The OP MUST validate the RP's explicit registration request JWT.
All the normal Entity Statement validation rules apply.
In addition, if the aud (audience)
claim value is not the Entity Identifier of the OP,
then the request MUST be rejected.¶
If the request contains an Entity Configuration the OP
MUST use it to complete the Federation Entity Discovery by
collecting and evaluating the Trust Chains that start with
the authority_hints in the
Entity Configuration of the RP. After validating at least
one Trust Chain, the OP MUST verify the signature of the
received Entity Configuration. If the OP finds more than
one acceptable Trust Chain, it MUST choose one Trust Chain
from among them as the one to proceed with.¶
If the request contains a Trust Chain, the OP MAY evaluate the statements in the Trust Chain to save the HTTP calls that are necessary to perform the Federation Entity Discovery, especially if the RP included more than one authority hint in its Entity Configuration. Otherwise, the OP MUST extract the RP Entity Configuration from the Trust Chain and proceed according to Step 2, as if only an Entity Configuration was received.¶
At this point, if the OP finds that it already has an existing client registration for the requesting RP, then that registration MUST be invalidated. The precise time of the invalidation is at the OP's discretion, as the OP may want to ensure the completion of concurrent OpenID authentication requests initiated by the RP while the registration request is being processed.¶
The OP MAY retain client credentials and key material from the invalidated registration in order to verify past RP signatures and perform other cryptographic operations on past RP data.¶
The OP will now use the RP metadata to create a client registration compliant with its own OP metadata and other applicable policies.¶
The OP MAY provision the RP with a
client_id other than the RP's
Entity Identifier. This enables Explicit Registration to be
implemented on top of the
OpenID Connect Dynamic
Client Registration 1.0 [OpenID.Registration] endpoint of an OP.¶
If the RP is provisioned with a
client_secret it MUST NOT
expire before the expiration of the registration Entity Statement
that will be returned to the RP.¶
The OP SHOULD NOT provision the RP with a
registration_access_token and a
registration_client_uri
because the expected way for the RP to update its
registration is to make a new Explicit Registration
request. If the RP is provisioned with a
registration_access_token for
some purpose, for example to let it independently check its
registered metadata, the token MUST NOT allow modification
of the registration.¶
The OP MAY modify the received RP metadata, for example by
substituting an invalid or unsupported parameter,
to make it compliant with its own OP metadata and other
policies. If the OP does not accept the RP metadata or is
unwilling to modify it to make it compliant, it
MUST return a client registration error response, with an
appropriate error, such as
invalid_client_metadata or
invalid_redirect_uri, as
specified in Section 3.3 of
[OpenID.Registration].¶
The OP MUST assign an expiration time to the created registration. This time MUST NOT exceed the expiration time of the Trust Chain that the OP selected to process the request.¶
If the OP created a client registration for the RP, it MUST then construct a success response in the form of an Entity Statement.¶
The OP MUST set the trust_anchor
claim of the Entity Statement to the Trust Anchor it
selected to process the request. The
authority_hints claim MUST be
set to the RP's Immediate Superior in the
selected Trust Chain.¶
The OP MUST set the exp claim
to the expiration time of the created registration. The OP
MAY choose to invalidate the registration before that, as
explained in Section 12.2.6.¶
The OP MUST express the client registration it created for
the RP by means of the metadata
claim, by placing the metadata parameters under the
openid_relying_party
Entity Type Identifier.
The parameters MUST include the
client_id that was provisioned
for the RP. If the RP was provisioned with credentials,
for example a client_secret,
these MUST be included as well.¶
The OP SHOULD include metadata parameters that have a
default value, for example
token_endpoint_auth_method
which has a default value of
client_secret_basic,
to simplify the processing of the response by the RP.¶
The OP MUST sign the registration Entity Statement with a current Federation Entity Key in its possession.¶
The following Entity Statement claims are used in Explicit Registration responses, as specified in Section 3:¶
jwks Entity Statement claim
from the received Entity Configuration of the RP.
Note that this is distinct from the identically named RP metadata parameter.¶
openid_relying_party
Entity Type Identifier.¶
A successful response MUST have an HTTP status code 200 and
the content type
application/explicit-registration-response+jwt.
Furthermore, the typ header parameter
value in the response MUST be
explicit-registration-response+jwt
(and not entity-statement+jwt)
to prevent confusion between the Explicit Registration response
and normal Entity Statements.¶
For a client registration error, the response is as defined in Section 8.9 and MAY use errors defined there and in Section 3.3 of [OpenID.Registration] and Section 3.2.2 of [RFC7591].¶
If the response indicates success, the RP MUST verify that its content is a valid Entity Statement and issued by the OP.¶
The RP MUST ensure the signing Federation Entity Key used
by the OP is present in the
jwks claim of the Subordinate Statement
issued by the OP's Immediate Superior
in a Trust Chain that the RP successfully resolved for the
OP when it prepared the Explicit Registration request.¶
The RP MUST verify that the aud (audience)
claim value is its Entity Identifier.¶
The RP MUST verify that the
trust_anchor represents one
of its own Trust Anchors.¶
The RP MUST verify that at least one of the
authority_hints it specified in
the Explicit Registration request leads to the Trust Anchor
that the OP set in the
trust_anchor claim.¶
The RP MUST ensure that the metadata it was registered with
at the OP complies with the Trust Chain
openid_relying_party policies,
which Trust Chain is resolved using the
trust_anchor and
authority_hints claims of the
received registration Entity Statement. The RP SHOULD perform this check
by applying the resolved policies to the metadata as
specified in Section 6.1.4.1, or
utilize another equivalent method.¶
If the received registration Entity Statement does not pass the above checks, the RP MUST reject it. The RP MAY choose to retry the Explicit Registration request to work around a transient exception, for example due to a recent change of Entity metadata or metadata policy causing temporary misalignment of metadata.¶
An RP can utilize the exp claim of the
registration Entity Statement to devise a suitable strategy for
renewing its client registration. RP implementers should note that
if the OP expiration of the client_id
coincides with an OAuth 2.0 flow that was just initiated by the RP, this
may cause OpenID Connect authentication requests, token requests, or
UserInfo requests to suddenly fail. Renewing the RP registration
prior to its expiration can prevent such errors from
occurring and ensure the end-user experience is not disrupted.¶
An OP MAY invalidate a client registration before the expiration that is indicated in the registration Entity Statement for the RP. An example reason could be the OP leaving the federation that was used to register the RP.¶
The validity of an Automatic or Explicit Registration at an OP MUST NOT exceed the lifetime of the Trust Chain the OP used to create the registration. An OP MAY choose to expire the registration at some earlier time, or choose to perform additional periodic reevaluations of the Trust Chain for the registered RP before the Trust Chain reaches its expiration time.¶
Similarly, an RP that obtained an Automatic or Explicit Registration MUST NOT use it past the expiration of the Trust Chain the RP used to establish trust in the OP. For an RP using Automatic Registration, the trust in the OP MUST be successfully reevaluated before continuing to make requests to the OP. For an RP using Explicit Registration, the RP MUST successfully renew its registration. An RP MAY choose to perform additional periodic reevaluations of the Trust Chain for the OP before the Trust Chain reaches its expiration time.¶
The primary differences between Automatic Registration and Explicit Registration are:¶
With Automatic Registration, there is no registration step prior to the Authentication Request, whereas with Explicit Registration, there is. (OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration] and OAuth 2.0 Dynamic Client Registration [RFC7591] also employ a prior registration step.)¶
With Automatic Registration, the Client ID value is the RP's Entity Identifier and is supplied to the OP by the RP, whereas with Explicit Registration, a Client ID is assigned by the OP and supplied to the RP.¶
With Automatic Registration, the Client is authenticated by means of the RP proving that it controls a private key corresponding to one of its Entity Configuration's public keys. Whereas with Explicit Registration, a broader set of options is available for authenticating the Client, including the use of a Client Secret.¶
Both Automatic and Explicit Client Registration support the submission of the Trust Chain embedded in the Request, calculated by the requestor, and related to itself. This provides the following benefits:¶
It solves the problem of OPs using RP metadata that has become stale.
This stale data may occur when the OP uses cached RP metadata from a Trust Chain
that has not reached its expiration time yet.
The RP MAY notify the OP that a change has taken place by including
the trust_chain header parameter
or the trust_chain request parameter
in the request,
thus letting the OP update its Client Registration
and preventing potential temporary faults due to stale metadata.¶
It enables the RP to pass a verifiable hint for which trust path to take to build the Trust Chain. This can reduce the costs of RP Federation Entity Discovery for OPs in complex federations where the RP has multiple Trust Anchors or the Trust Chain resolution may result in dead-ends.¶
It enables direct passing of the Entity Configuration, including
any present Trust Marks, thus saving the OP from having to make
an HTTP request to the RP
/.well-known/openid-federation
endpoint.¶
This section defines general-purpose JWT claims designed to be used by many different JWT profiles. They are also used in specific kinds of JWTs defined by this specification.¶
The jwks (JSON Web Key Set) claim
value is a JWK Set, as defined in [RFC7517].
It is used to convey a set of cryptographic keys.
Use of this claim is OPTIONAL.¶
For instance, the jwks (JSON Web Key Set) claim
might be used to represent a set of signing keys for an application.
This claim is used in this specification in Section 3
to represent the public keys used to sign the Entity Statement.¶
The metadata claim
is used for conveying metadata pertaining to the JWT.
Its value is a JSON object.
The details of the metadata contained are application-specific.
Use of this claim is OPTIONAL.¶
For instance, the metadata claim
might be used to represent a set of endpoint URLs
and algorithm identifiers in an API description.
This claim is used in this specification in Section 3
to represent metadata about the Entity.¶
The constraints claim
is used for conveying constraints pertaining to the JWT.
Its value is a JSON object.
The details of the constraints contained are application-specific.
Use of this claim is OPTIONAL.¶
For instance, the constraints claim
might be used to impose material thickness limits for a physical object.
This claim is used in this specification in Section 3
to represent constraints on the Trust Chain for the Entity.¶
The crit (critical) claim
indicates that extensions to the set of claims
specified for use in this type of JWT are being used
that MUST be understood and processed.
It is used in the same way that
the crit header parameter
is used for extension JOSE header parameters
that MUST be understood and processed.
Its value is an array listing the claim names
present in the JWT that use those extensions.
If any of the listed claims are not
understood and supported by the recipient, then the JWT is invalid.
Producers MUST NOT include claim names already
specified for use in this type of JWT,
duplicate names, or
names that do not occur as claim names in the JWT
in the crit list.
Producers MUST NOT use the empty array
[]
as the crit value.
Use of this claim is OPTIONAL.¶
This claim is used in this specification in Section 3 to identify claims not defined by this specification that MUST be understood and processed when used in Entity Statements.¶
The ref (reference) claim
is used for conveying the URI for a resource pertaining to the JWT.
It plays a similar role in a JWT as
the href property does in HTML.
The nature of the content at the referenced resource
is generally application specific.
The ref value is a case-sensitive string
containing a URI value.
Use of this claim is OPTIONAL.¶
For instance, a JWT referring to a contract between two parties might use
the ref (reference) claim
to refer to a resource at which the contract terms can be read.
This claim is used in this specification in Section 7.1
to provide a URL referring to human-readable information
about the issuance of the Trust Mark.¶
The delegation claim expresses that
authority is being delegated to the party referenced in the claim value.
The delegation value is a case-sensitive string
containing a StringOrURI value.
Use of this claim is OPTIONAL.¶
For instance, the delegation claim
might be used to express that the referenced party may sign
a legal document on behalf of the subject.
This claim is used in this specification in Section 7.1
to represent delegation of the right to issue Trust Marks
with a particular identifier.¶
The logo_uri claim
value is a URI that references a logo pertaining to the JWT.
Use of this claim is OPTIONAL.¶
For instance, the logo_uri claim
might be used to represent the location from which to retrieve
the logo of an organization to display in a user interface.
This claim is used in this specification in Section 7.1
to convey a URL that references a logo for the Entity.¶
Human-readable claim values and claim values that reference human-readable values MAY be represented in multiple languages and scripts. This specification enables such representations in the same manner as defined in Section 5.2 of OpenID Connect Core 1.0 [OpenID.Core].¶
As described in OpenID Connect Core,
to specify the languages and scripts, BCP47 [RFC5646] language tags are added to member names,
delimited by a # character. For example,
family_name#ja-Kana-JP expresses the
Family Name in Katakana in Japanese, which is commonly used to index
and represent the phonetics of the Kanji representation of the same name
represented as family_name#ja-Hani-JP.¶
Language tags can be used in any data structures
containing or referencing human-readable values,
including metadata parameters and Trust Mark parameters.
For instance, both organization_name and
organization_name#de might occur together in metadata.¶
These media types [RFC2046] are defined by this specification.¶
The application/entity-statement+jwt
media type is used to specify that the associated content is
an Entity Statement, as defined in Section 3.
No parameters are used with this media type.¶
The application/trust-mark+jwt
media type is used to specify that the associated content is
a Trust Mark, as defined in Section 7.
No parameters are used with this media type.¶
The application/resolve-response+jwt
media type is used to specify that the associated content is
a Resolve Response, as defined in Section 8.3.2.
No parameters are used with this media type.¶
The application/trust-chain+json
media type is used to specify that the associated content is
a JSON array representing a Trust Chain, as defined in Section 4.
No parameters are used with this media type.¶
The application/trust-mark-delegation+jwt
media type is used to specify that the associated content is
a Trust Mark delegation, as defined in Section 7.2.1.
No parameters are used with this media type.¶
The application/jwk-set+jwt
media type is used to specify that the associated content is
a signed JWK Set, as defined in Section 8.7.2.
No parameters are used with this media type.¶
The application/explicit-registration-response+jwt
media type is used to specify that the associated content is
an Explicit Registration response, as defined in Section 12.2.3.
No parameters are used with this media type.¶
This section provides guidance to implementers and deployers of Federations on situations and properties that they should consider for their Federations.¶
It is possible to construct Federation topologies that have multiple trust paths between Entities. The specification does not disallow this, but it can create ambiguities that deployers need to be aware of.¶
Consider the following Federation topology:¶
.--------------.
| Trust Anchor |
'--.---.-----.-'
| | |
.--' '--. '---------------.
| | |
.-------------v--. .--v-------------. |
| Intermediate 1 | | Intermediate 2 | |
'-------------.--' '--.-------------' |
| | .-v--.
| | | OP |
.--v---------v---. '----'
| Intermediate 3 |
'-------.--------'
|
|
.-v--.
| RP |
'----'
In this topology, there are multiple trust paths between the RP and the Trust Anchor, meaning that multiple different Trust Chains could be built between them. If the metadata policies of Intermediate 1 and Intermediate 2 are different, this could result in the resolved metadata for the RP differing, depending upon which Intermediate is used when building the Trust Chain. Some such differences will be innocuous and some can cause failures.¶
It is the job of the Federation architects to deploy topologies and metadata policies that work as intended, no matter which trust path is chosen when building a Trust Chain. Of course, one way to avoid potential ambiguities is to only use topologies that are trees, without multiple paths between two Entities. Topologies that are not trees are permitted, but should be used consciously and with care.¶
Also, as described in Section 10.1 Federation topologies MUST NOT contain loops.¶
Some of the interfaces defined in this specification could be used for Denial-of-Service attacks (DoS), most notably, the resolve endpoint (Section 8.2), Explicit Client Registration (Section 12.2), and Automatic Client Registration (Section 12.1) can be exploited as vectors of HTTP propagation attacks. Below is an explanation of how such an attack can occur and the countermeasures to prevent it.¶
An adversary, providing hundreds of fake
authority_hints
in its Entity Configuration,
could exploit the Federation Entity Discovery mechanism
to propagate many HTTP requests.
Imagine an adversary controlling an RP that sends an authorization
request to an OP. For each request crafted
by the adversary, the OP produces one request for
the adversary's Entity Configuration and another one
for each URL found in the authority_hints.¶
If these endpoints are provided, some adequate defense methods are required, such as those described below and in [RFC4732].¶
Implementations should set a limit on the number of
authority_hints
they are willing to inspect. This is to protect against attacks
where an adversary might define a large count of false
authority_hints
in their Entity Configuration.¶
Entities may be required to include a Trust Chain (Section 4.3) in their requests, as explained in Section 12.1.1.1. The static Trust Chain gives a predefined trust path, meaning that Federation Entity Discovery need not be performed. In this case, the propagation attacks will be prevented since the Trust Chain can be statically validated with a public key of the Trust Anchor.¶
A Trust Mark can be statically validated using the public key of its issuer. The static validation of the Trust Marks represents a filter against propagation attacks. If the OpenID Provider (OP) discovers at least one valid Trust Mark within an Entity Configuration, this may serve as evidence of the reliability of the Relying Party that initiated the request. Given that the Trust Mark is optional, the decision to require one is at the discretion of the federation implementation, where a federation may define and require Trust Marks according to specific needs.¶
If Client authentication is not required at the resolve endpoint, then incoming requests should not automatically trigger the collection (Federation Entity Discovery process) and assessment of Trust Chains. Instead, the resolve endpoint should only respond to unauthenticated Client requests with cached information about Entities that have already been evaluated and deemed trustworthy. The initiation of the Federation Entity Discovery process should not be the default action for the resolve endpoint in this case.¶
Passing request objects by reference (using the
request_uri request parameter)
may not be supported by some deployments,
as described in Section 12.1.1, to eliminate a mechanism
by which an attacker could otherwise require OPs
to retrieve arbitrary content under the control of the attacker.¶
One of the fundamental design goals of this protocol is to protect messages end-to-end. This cannot be accomplished by demanding TLS since TLS, in lots of cases, is not end-to-end but ends in a HTTPS to HTTP Reverse Proxy. Allowing unsigned error messages therefore opens an attack vector for someone who wants to run a Denial-of-Service attack. This is not specific to OpenID Federation but equally valid for other protocols when HTTPS to HTTP reverse proxies are used.¶
This specification registers the following metadata entries in the IANA "OAuth Authorization Server Metadata" registry [IANA.OAuth.Parameters] established by [RFC8414].¶
Metadata Name:
client_registration_types_supported¶
Metadata Description: Client Registration Types Supported¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.1.3 of this specification¶
Metadata Name: federation_registration_endpoint¶
Metadata Description: Federation Registration Endpoint¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.1.3 of this specification¶
Metadata Name: signed_jwks_uri¶
Metadata Description: URL referencing a signed JWT having this authorization server's JWK Set document as its payload¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.2.1 of this specification¶
Metadata Name: jwks¶
Metadata Description: JSON Web Key Set document, passed by value¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.2.1 of this specification¶
Metadata Name: organization_name¶
Metadata Description: Human-readable name representing the organization owning this authorization server¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.2.2 of this specification¶
Metadata Name: contacts¶
Metadata Description: Array of strings representing ways to contact people responsible for this authorization server, typically email addresses¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.2.2 of this specification¶
Metadata Name: logo_uri¶
Metadata Description: URL that references a logo for the organization owning this authorization server¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.2.2 of this specification¶
Metadata Name: homepage_uri¶
Metadata Description: URL of a Web page for the organization owning this authorization server¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.2.2 of this specification¶
This specification registers the following client metadata entries in the IANA "OAuth Dynamic Client Registration Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591].¶
Client Metadata Name: client_registration_types¶
Client Metadata Description: An array of strings specifying the client registration types the RP wants to use¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.1.2 of this specification¶
Client Metadata Name: signed_jwks_uri¶
Client Metadata Description: URL referencing a signed JWT having the client's JWK Set document as its payload¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.2.1 of this specification¶
Client Metadata Name: organization_name¶
Client Metadata Description: Human-readable name representing the organization owning this client¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.2.2 of this specification¶
Metadata Name: homepage_uri¶
Metadata Description: URL of a Web page for the organization owning this client¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.2.2 of this specification¶
This section registers the following values in the IANA "OAuth Extensions Error Registry" registry [IANA.OAuth.Parameters] established by [RFC6749].¶
Name: invalid_request¶
Usage Location: authorization endpoint¶
Protocol Extension: OpenID Federation¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Reference: Section 8.9 of this specification¶
Name: invalid_client¶
Usage Location: authorization endpoint¶
Protocol Extension: OpenID Federation¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Reference: Section 8.9 of this specification¶
Name: invalid_issuer¶
Usage Location: authorization endpoint¶
Protocol Extension: OpenID Federation¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Reference: Section 8.9 of this specification¶
Name: invalid_subject¶
Usage Location: authorization endpoint¶
Protocol Extension: OpenID Federation¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Reference: Section 8.9 of this specification¶
Name: invalid_trust_anchor¶
Usage Location: authorization endpoint¶
Protocol Extension: OpenID Federation¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Reference: Section 8.9 of this specification¶
Name: invalid_trust_chain¶
Usage Location: authorization endpoint¶
Protocol Extension: OpenID Federation¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Reference: Section 8.9 of this specification¶
Name: invalid_metadata¶
Usage Location: authorization endpoint¶
Protocol Extension: OpenID Federation¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Reference: Section 8.9 of this specification¶
Name: not_found¶
Usage Location: authorization endpoint¶
Protocol Extension: OpenID Federation¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Reference: Section 8.9 of this specification¶
Name: server_error¶
Usage Location: authorization endpoint¶
Protocol Extension: OpenID Federation¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Reference: Section 8.9 of this specification¶
This section registers the following media types [RFC2046] in the "Media Types" registry [IANA.MediaTypes] in the manner described in [RFC6838].¶
Type name: application¶
Subtype name: entity-statement+jwt¶
Required parameters: n/a¶
Optional parameters: n/a¶
Encoding considerations: binary; An Entity Statement is a JWT; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.¶
Security considerations: See Section 17 of this specification¶
Interoperability considerations: n/a¶
Published specification: Section 15.1 of this specification¶
Applications that use this media type: Applications that use this specification¶
Fragment identifier considerations: n/a¶
Additional information:¶
Person & email address to contact for further information:¶
Michael B. Jones, michael_b_jones@hotmail.com¶
Intended usage: COMMON¶
Restrictions on usage: none¶
Author: Michael B. Jones, michael_b_jones@hotmail.com¶
Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Provisional registration? No¶
Type name: application¶
Subtype name: trust-mark+jwt¶
Required parameters: n/a¶
Optional parameters: n/a¶
Encoding considerations: binary; A Trust Mark is a JWT; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.¶
Security considerations: See Section 17 of this specification¶
Interoperability considerations: n/a¶
Published specification: Section 15.2 of this specification¶
Applications that use this media type: Applications that use this specification¶
Fragment identifier considerations: n/a¶
Additional information:¶
Person & email address to contact for further information:¶
Michael B. Jones, michael_b_jones@hotmail.com¶
Intended usage: COMMON¶
Restrictions on usage: none¶
Author: Michael B. Jones, michael_b_jones@hotmail.com¶
Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Provisional registration? No¶
Type name: application¶
Subtype name: resolve-response+jwt¶
Required parameters: n/a¶
Optional parameters: n/a¶
Encoding considerations: binary; An Entity Resolve Response is a signed JWT; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.¶
Security considerations: See Section 17 of this specification¶
Interoperability considerations: n/a¶
Published specification: Section 15.3 of this specification¶
Applications that use this media type: Applications that use this specification¶
Fragment identifier considerations: n/a¶
Additional information:¶
Person & email address to contact for further information:¶
Michael B. Jones, michael_b_jones@hotmail.com¶
Intended usage: COMMON¶
Restrictions on usage: none¶
Author: Michael B. Jones, michael_b_jones@hotmail.com¶
Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Provisional registration? No¶
Type name: application¶
Subtype name: trust-chain+json¶
Required parameters: n/a¶
Optional parameters: n/a¶
Encoding considerations: binary; A Trust Chain is a JSON array of JWTs; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.¶
Security considerations: See Section 17 of this specification¶
Interoperability considerations: n/a¶
Published specification: Section 15.4 of this specification¶
Applications that use this media type: Applications that use this specification¶
Fragment identifier considerations: n/a¶
Additional information:¶
Person & email address to contact for further information:¶
Michael B. Jones, michael_b_jones@hotmail.com¶
Intended usage: COMMON¶
Restrictions on usage: none¶
Author: Michael B. Jones, michael_b_jones@hotmail.com¶
Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Provisional registration? No¶
Type name: application¶
Subtype name: trust-mark-delegation+jwt¶
Required parameters: n/a¶
Optional parameters: n/a¶
Encoding considerations: binary; A Trust Mark delegation is a signed JWT; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.¶
Security considerations: See Section 17 of this specification¶
Interoperability considerations: n/a¶
Published specification: Section 15.5 of this specification¶
Applications that use this media type: Applications that use this specification¶
Fragment identifier considerations: n/a¶
Additional information:¶
Person & email address to contact for further information:¶
Roland Hedberg, roland@catalogix.se¶
Intended usage: COMMON¶
Restrictions on usage: none¶
Author: Roland Hedberg, roland@catalogix.se¶
Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Provisional registration? No¶
Type name: application¶
Subtype name: jwk-set+jwt¶
Required parameters: n/a¶
Optional parameters: n/a¶
Encoding considerations: binary; A signed JWK Set is a signed JWT; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.¶
Security considerations: See Section 17 of this specification¶
Interoperability considerations: n/a¶
Published specification: Section 15.6 of this specification¶
Applications that use this media type: Applications that use this specification¶
Fragment identifier considerations: n/a¶
Additional information:¶
Person & email address to contact for further information:¶
Michael B. Jones, michael_b_jones@hotmail.com¶
Intended usage: COMMON¶
Restrictions on usage: none¶
Author: Michael B. Jones, michael_b_jones@hotmail.com¶
Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Provisional registration? No¶
Type name: application¶
Subtype name: explicit-registration-response+jwt¶
Required parameters: n/a¶
Optional parameters: n/a¶
Encoding considerations: binary; An Explicit Registration response is a JWT; JWT values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters.¶
Security considerations: See Section 17 of this specification¶
Interoperability considerations: n/a¶
Published specification: Section 15.7 of this specification¶
Applications that use this media type: Applications that use this specification¶
Fragment identifier considerations: n/a¶
Additional information:¶
Person & email address to contact for further information:¶
Michael B. Jones, michael_b_jones@hotmail.com¶
Intended usage: COMMON¶
Restrictions on usage: none¶
Author: Michael B. Jones, michael_b_jones@hotmail.com¶
Change controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Provisional registration? No¶
This specification registers the following parameter name in the IANA "OAuth Parameters" registry [IANA.OAuth.Parameters] established by [RFC6749].¶
Parameter Name:
trust_chain¶
Parameter Usage Location: authorization request¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 12.1.1.1.1 of this specification¶
This specification registers the following JWS header parameter in the IANA "JSON Web Signature and Encryption Header Parameters" registry [IANA.JOSE] established by [RFC7515].¶
This specification registers the following claims in the IANA "JSON Web Token Claims" registry [IANA.JWT.Claims] established by [RFC7519].¶
Claim Name: jwks¶
Claim Description: JSON Web Key Set¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 13.1 of this specification¶
Claim Name: metadata¶
Claim Description: Metadata object¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 13.2 of this specification¶
Claim Name: constraints¶
Claim Description: Constraints object¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 13.3 of this specification¶
Claim Name: crit¶
Claim Description: Critical Claim¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 13.4 of this specification¶
Claim Name: ref¶
Claim Description: Reference¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 13.5 of this specification¶
Claim Name: delegation¶
Claim Description: Delegation¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 13.6 of this specification¶
Claim Name: logo_uri¶
Claim Description: URI referencing a logo¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 13.7 of this specification¶
Claim Name: authority_hints¶
Claim Description: Authority Hints¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Claim Name: metadata_policy¶
Claim Description: Metadata Policy object¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Claim Name: metadata_policy_crit¶
Claim Description: Critical Metadata Policy Operators¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Claim Name: trust_marks¶
Claim Description: Trust Marks¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Claim Name: trust_mark_issuers¶
Claim Description: Trust Mark Issuers¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Claim Name: trust_mark_owners¶
Claim Description: Trust Mark Owners¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Claim Name: source_endpoint¶
Claim Description: Source Endpoint URL¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Claim Name: trust_chain¶
Claim Description: Trust Chain¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Claim Name: keys¶
Claim Description: Array of JWK values in a JWK Set¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 5.2 of this specification¶
Claim Name: trust_mark_id¶
Claim Description: Trust Mark Identifier¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 7.1 of this specification¶
Claim Name: trust_anchor¶
Claim Description: Trust Anchor ID¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 12.2.2 of this specification¶
This specification registers the following parameters in the IANA "JSON Web Key Parameters" registry [IANA.JOSE] established by [RFC7517].¶
Parameter Name: iat¶
Parameter Description: Issued At, as defined in RFC 7519¶
Used with "kty" Value(s): *¶
Parameter Information Class: Public¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 8.7.2 of this specification¶
Parameter Name: nbf¶
Parameter Description: Not Before, as defined in RFC 7519¶
Used with "kty" Value(s): *¶
Parameter Information Class: Public¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 8.7.2 of this specification¶
Parameter Name: exp¶
Parameter Description: Expiration Time, as defined in RFC 7519¶
Used with "kty" Value(s): *¶
Parameter Information Class: Public¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 8.7.2 of this specification¶
Parameter Name: revoked¶
Parameter Description: Revoked Key Properties¶
Used with "kty" Value(s): *¶
Parameter Information Class: Public¶
Change Controller: OpenID Foundation Artifact Binding Working Group - openid-specs-ab@lists.openid.net¶
Specification Document(s): Section 8.7.2 of this specification¶
This specification registers the following well-known URI in the IANA "Well-Known URIs" registry [IANA.well-known] established by [RFC5785].¶
Let us assume the following: The project LIGO would like to offer access to its wiki to all OPs in eduGAIN. LIGO is registered with the InCommon federation.¶
The following depicts a federation under the eduGAIN Trust Anchor:¶
eduGAIN
|
+------------------+------------------+
| |
SWAMID InCommon
| |
umu.se |
| |
op.umu.se wiki.ligo.org
Both SWAMID and InCommon are identity federations in their own right. They also have in common that they are both members of the eduGAIN federation.¶
SWAMID and InCommon are different in how they register Entities. SWAMID registers organizations and lets the organizations register Entities that belong to the organization, while InCommon registers all Entities directly and not beneath any organization Entity. Hence the differences in depth in the federations.¶
Let us assume a researcher from Umeå University would like to login to the LIGO Wiki. At the Wiki, the researcher will use some kind of discovery service to find the home identity provider (op.umu.se).¶
Once the RP part of the Wiki knows which OP it SHOULD talk to, it has to find out a few things about the OP. All those things can be found in the metadata. But finding the metadata is not enough; the RP also has to trust the metadata.¶
Let us make a detour and start with what it takes to build a federation.¶
These are the steps to set up a federation infrastructure:¶
Generation of Trust Anchor signing keys. These MUST be public/private key pairs.¶
Set up a signing service that can sign JWTs/Entity Statements using the Federation Entity Keys.¶
Set up web services that can publish signed Entity Statements, one for the URL corresponding to the federation's Entity Identifier returning an Entity Configuration and the other one providing the fetch endpoint, as described in Section 8.1.1.¶
Once these requirements have been satisfied, a Federation Operator can add Entities to the federation. Adding an Entity comes down to:¶
Providing the Entity with the federation's Entity Identifier and the public part of the key pairs used by the federation operator for signing Entity Statements.¶
Getting the Entity's Entity Identifier and the JWK Set that the Entity plans to publish in its Entity Configuration.¶
Before the federation operator starts adding Entities, there must be policies on who can be part of the federation and the layout of the federation. Is it supposed to be a one-layer federation like InCommon, a two-layer one like the SWAMID federation, or a multi-layer federation? The federation may also want to consider implementing other policies using the federation policy framework, as described in Section 6.¶
With the federation in place, things can start happening.¶
Federation Entity Discovery is a sequence of steps that starts with the RP fetching the Entity Configuration of the OP's Entity (in this case, https://op.umu.se) using the process defined in Section 9. What follows after that is this sequence of steps:¶
Pick out the Immediate Superior Entities using the authority hints.¶
Fetch the Entity Configuration for each such Entity. This uses the process defined in Section 9.¶
Use the fetch endpoint of each Immediate Superior to obtain Subordinate Statements about the Immediate Subordinate Entity, per Section 8.1.1.¶
How many times this has to be repeated depends on the depth of the federation. What follows below is the result of each step the RP has to take to find the OP's metadata using the federation setup described above.¶
When building the Trust Chain, the Subordinate Statements issued by each Immediate Superior about their Immediate Subordinates are used together with the Entity Configuration of the Trust Chain subject.¶
The Entity Configurations of Intermediates are not part of the Trust Chain.¶
The LIGO WIKI RP fetches the Entity Configuration from the OP (op.umu.se) using the process defined in Section 9.¶
The result is this Entity Configuration:¶
{
"authority_hints": [
"https://umu.se"
],
"exp": 1568397247,
"iat": 1568310847,
"iss": "https://op.umu.se",
"sub": "https://op.umu.se",
"jwks": {
"keys": [
{
"e": "AQAB",
"kid": "dEEtRjlzY3djcENuT01wOGxrZlkxb3RIQVJlMTY0...",
"kty": "RSA",
"n": "x97YKqc9Cs-DNtFrQ7_vhXoH9bwkDWW6En2jJ044yH..."
}
]
},
"metadata": {
"openid_provider": {
"issuer": "https://op.umu.se/openid",
"signed_jwks_uri": "https://op.umu.se/openid/jwks.jose",
"authorization_endpoint":
"https://op.umu.se/openid/authorization",
"client_registration_types_supported": [
"automatic",
"explicit"
],
"request_parameter_supported": true,
"grant_types_supported": [
"authorization_code",
"implicit",
"urn:ietf:params:oauth:grant-type:jwt-bearer"
],
"id_token_signing_alg_values_supported": [
"ES256", "RS256"
],
"logo_uri":
"https://www.umu.se/img/umu-logo-left-neg-SE.svg",
"op_policy_uri":
"https://www.umu.se/en/website/legal-information/",
"response_types_supported": [
"code",
"code id_token",
"token"
],
"subject_types_supported": [
"pairwise",
"public"
],
"token_endpoint": "https://op.umu.se/openid/token",
"federation_registration_endpoint":
"https://op.umu.se/openid/fedreg",
"token_endpoint_auth_methods_supported": [
"client_secret_post",
"client_secret_basic",
"client_secret_jwt",
"private_key_jwt"
]
}
}
}
The authority_hints points to the
Intermediate Entity https://umu.se.
So that is the next step.¶
This Entity Configuration is the first link in the Trust Chain.¶
The LIGO RP fetches the Entity Configuration from https://umu.se using the process defined in Section 9.¶
The request will look like this:¶
GET /.well-known/openid-federation HTTP/1.1 Host: umu.se
And the GET will return:¶
{
"authority_hints": [
"https://swamid.se"
],
"exp": 1568397247,
"iat": 1568310847,
"iss": "https://umu.se",
"sub": "https://umu.se",
"jwks": {
"keys": [
{
"e": "AQAB",
"kid": "endwNUZrNTJsX2NyQlp4bjhVcTFTTVltR2gxV2RV...",
"kty": "RSA",
"n": "vXdXzZwQo0hxRSmZEcDIsnpg-CMEkor50SOG-1XUlM..."
}
]
},
"metadata": {
"federation_entity": {
"contacts": ["ops@umu.se"],
"federation_fetch_endpoint": "https://umu.se/oidc/fedapi",
"homepage_uri": "https://www.umu.se",
"organization_name": "UmU"
}
}
}
The only piece of information that is used from this Entity Configuration
in this process is
the federation_fetch_endpoint,
which is used in the next step.¶
The RP uses the fetch endpoint provided by https://umu.se, as defined in Section 8.1.1, to fetch information about https://op.umu.se.¶
The request will look like this:¶
GET /oidc/fedapi?sub=https%3A%2F%2Fop.umu.se& iss=https%3A%2F%2Fumu.se HTTP/1.1 Host: umu.se
And the result is this:¶
{
"exp": 1568397247,
"iat": 1568310847,
"iss": "https://umu.se",
"sub": "https://op.umu.se",
"source_endpoint": "https://umu.se/oidc/fedapi",
"jwks": {
"keys": [
{
"e": "AQAB",
"kid": "dEEtRjlzY3djcENuT01wOGxrZlkxb3RIQVJlMTY0...",
"kty": "RSA",
"n": "x97YKqc9Cs-DNtFrQ7_vhXoH9bwkDWW6En2jJ044yH..."
}
]
},
"metadata_policy": {
"openid_provider": {
"contacts": {
"add": [
"ops@swamid.se"
]
},
"organization_name": {
"value": "University of Umeå"
},
"subject_types_supported": {
"value": [
"pairwise"
]
},
"token_endpoint_auth_methods_supported": {
"default": [
"private_key_jwt"
],
"subset_of": [
"private_key_jwt",
"client_secret_jwt"
],
"superset_of": [
"private_key_jwt"
]
}
}
}
}
This Subordinate Statement is the second link in the Trust Chain.¶
The LIGO Wiki RP fetches the Entity Configuration from https://swamid.se using the process defined in Section 9.¶
The request will look like this:¶
GET /.well-known/openid-federation HTTP/1.1 Host: swamid.se
And the GET will return:¶
{
"authority_hints": [
"https://edugain.geant.org"
],
"exp": 1568397247,
"iat": 1568310847,
"iss": "https://swamid.se",
"sub": "https://swamid.se",
"jwks": {
"keys": [
{
"e": "AQAB",
"kid": "N1pQTzFxUXZ1RXVsUkVuMG5uMnVDSURGRVdhUzdO...",
"kty": "RSA",
"n": "3EQc6cR_GSBq9km9-WCHY_lWJZWkcn0M05TGtH6D9S..."
}
]
},
"metadata": {
"federation_entity": {
"contacts": ["ops@swamid.se"],
"federation_fetch_endpoint":
"https://swamid.se/fedapi",
"homepage_uri": "https://www.sunet.se/swamid/",
"organization_name": "SWAMID"
}
}
}
The only piece of information that is used from this Entity Configuration
in this process is
the federation_fetch_endpoint,
which is used in the next step.¶
The LIGO Wiki RP uses the fetch endpoint provided by https://swamid.se as defined in Section 8.1.1 to fetch information about https://umu.se.¶
The request will look like this:¶
GET /fedapi?sub=https%3A%2F%2Fumu.se& iss=https%3A%2F%2Fswamid.se HTTP/1.1 Host: swamid.se
And the result is this:¶
{
"exp": 1568397247,
"iat": 1568310847,
"iss": "https://swamid.se",
"sub": "https://umu.se",
"source_endpoint": "https://swamid.se/fedapi",
"jwks": {
"keys": [
{
"e": "AQAB",
"kid": "endwNUZrNTJsX2NyQlp4bjhVcTFTTVltR2gxV2RV...",
"kty": "RSA",
"n": "vXdXzZwQo0hxRSmZEcDIsnpg-CMEkor50SOG-1XUlM..."
}
]
},
"metadata_policy": {
"openid_provider": {
"id_token_signing_alg_values_supported": {
"subset_of": [
"RS256",
"ES256",
"ES384",
"ES512"
]
},
"token_endpoint_auth_methods_supported": {
"subset_of": [
"client_secret_jwt",
"private_key_jwt"
]
},
"userinfo_signing_alg_values_supported": {
"subset_of": [
"ES256",
"ES384",
"ES512"
]
}
}
}
}
This Subordinate Statement is the third link in the Trust Chain.¶
If we assume that the issuer of this Subordinate Statement is not in the list of Trust Anchors the LIGO Wiki RP has access to, we have to go one step further.¶
The RP fetches the Entity Configuration from https://edugain.geant.org using the process defined in Section 9.¶
The request will look like this:¶
GET /.well-known/openid-federation HTTP/1.1 Host: edugain.geant.org
And the GET will return:¶
{
"exp": 1568397247,
"iat": 1568310847,
"iss": "https://edugain.geant.org",
"sub": "https://edugain.geant.org",
"jwks": {
"keys": [
{
"e": "AQAB",
"kid": "Sl9DcjFxR3hrRGdabUNIR21KT3dvdWMyc2VUM2Fr...",
"kty": "RSA",
"n": "xKlwocDXUw-mrvDSO4oRrTRrVuTwotoBFpozvlq-1q..."
}
]
},
"metadata": {
"federation_entity": {
"federation_fetch_endpoint": "https://geant.org/edugain/api"
}
}
}
Within the Trust Anchor Entity Configuration, the Relying Party
looks for the federation_fetch_endpoint
and gets the updated Federation Entity Keys of the Trust Anchor.
Each Entity within a
Federation may change their Federation Entity Keys,
or any other attributes, at any time. See
Section 11.2 for further details.¶
The LIGO Wiki RP uses the fetch endpoint of https://edugain.geant.org as defined in Section 8.1.1 to fetch information about "https://swamid.se".¶
The request will look like this:¶
GET /edugain/api?sub=https%3A%2F%2Fswamid.se& iss=https%3A%2F%2Fedugain.geant.org HTTP/1.1 Host: geant.org
And the result is this:¶
{
"exp": 1568397247,
"iat": 1568310847,
"iss": "https://edugain.geant.org",
"sub": "https://swamid.se",
"source_endpoint": "https://edugain.geant.org/edugain/api",
"jwks": {
"keys": [
{
"e": "AQAB",
"kid": "N1pQTzFxUXZ1RXVsUkVuMG5uMnVDSURGRVdhUzdO...",
"kty": "RSA",
"n": "3EQc6cR_GSBq9km9-WCHY_lWJZWkcn0M05TGtH6D9S..."
}
]
},
"metadata_policy": {
"openid_provider": {
"contacts": {
"add": ["ops@edugain.geant.org"]
}
},
"openid_relying_party": {
"contacts": {
"add": ["ops@edugain.geant.org"]
}
}
}
}
If we assume that the issuer of this statement appears in the list of Trust Anchors the LIGO Wiki RP has access to, this Subordinate Statement would be the fourth link in the Trust Chain. The Trust Anchor's Entity Configuration MAY also be included in the Trust Chain; in this case, it would the fifth and final link.¶
We now have retrieved all the members of the Trust Chain. Recapping, these Entity Statements were obtained:¶
Entity Configuration for the Leaf Entity https://op.umu.se - the first link in the Trust Chain¶
Entity Configuration for https://umu.se - not included in the Trust Chain¶
Subordinate Statement issued by https://umu.se about https://op.umu.se - the second link in the Trust Chain¶
Entity Configuration for https://swamid.se - not included in the Trust Chain¶
Subordinate Statement issued by https://swamid.se about https://umu.se - the third link in the Trust Chain¶
Entity Configuration for https://edugain.geant.org - optionally, the fifth and last link in the Trust Chain¶
Subordinate Statement issued by https://edugain.geant.org about https://swamid.se - the fourth link in the Trust Chain¶
Using the public keys of the Trust Anchor that the LIGO Wiki RP has been provided within some secure out-of-band way, it can now verify the Trust Chain as described in Section 10.2.¶
Having verified the chain, the LIGO Wiki RP can proceed with the next step.¶
Combining the metadata policies from the three Subordinate Statements we have by Immediate Superiors about their Immediate Subordinates and applying the combined policy to the metadata statement that the Leaf Entity presented, we get:¶
{
"authorization_endpoint":
"https://op.umu.se/openid/authorization",
"contacts": [
"ops@swamid.se",
"ops@edugain.geant.org"
],
"federation_registration_endpoint":
"https://op.umu.se/openid/fedreg",
"client_registration_types_supported": [
"automatic",
"explicit"
],
"grant_types_supported": [
"authorization_code",
"implicit",
"urn:ietf:params:oauth:grant-type:jwt-bearer"
],
"id_token_signing_alg_values_supported": [
"RS256",
"ES256"
],
"issuer": "https://op.umu.se/openid",
"signed_jwks_uri": "https://op.umu.se/openid/jwks.jose",
"logo_uri":
"https://www.umu.se/img/umu-logo-left-neg-SE.svg",
"organization_name": "University of Umeå",
"op_policy_uri":
"https://www.umu.se/en/website/legal-information/",
"request_parameter_supported": true,
"response_types_supported": [
"code",
"code id_token",
"token"
],
"subject_types_supported": [
"pairwise"
],
"token_endpoint": "https://op.umu.se/openid/token",
"token_endpoint_auth_methods_supported": [
"private_key_jwt",
"client_secret_jwt"
]
}
We have now reached the end of the Provider Discovery process.¶
As described in Section 12, there are two ways that can be used to do client registration:¶
federation_registration_endpoint,
which provides the RP's metadata. The OP MAY return a
metadata policy that adds restrictions over and above what the
Trust Chain already has defined.¶
The LIGO Wiki RP does not do any registration but goes directly to sending an Authentication Request.¶
Here is an example of such an Authentication Request:¶
GET /openid/authorization?
request=eyJ0eXAiOiJvYXV0aC1hdXRoei1yZXErand0IiwiYWxnIjoiU
lMyNTYiLCJraWQiOiJkVU4yYTAxd1JraGtTV3BsUVRodmNWQklOVUl3
VFVkT1VGVTJUbVZyU21oRVFYZ3paWGxwVHpkUU5BIn0.
eyJyZXNwb25zZV90eXBlIjogImNvZGUiLCAic2NvcGUiOiAib3Blbml
kIHByb2ZpbGUgZW1haWwiLCAiY2xpZW50X2lkIjogImh0dHBzOi8vd2
lraS5saWdvLm9yZyIsICJzdGF0ZSI6ICIyZmY3ZTU4OS0zODQ4LTQ2Z
GEtYTNkMi05NDllMTIzNWU2NzEiLCAibm9uY2UiOiAiZjU4MWExODYt
YWNhNC00NmIzLTk0ZmMtODA0ODQwODNlYjJjIiwgInJlZGlyZWN0X3V
yaSI6ICJodHRwczovL3dpa2kubGlnby5vcmcvb3BlbmlkL2NhbGxiYW
NrIiwgImlzcyI6ICJodHRwczovL3dpa2kubGlnby5vcmciLCAiaWF0I
jogMTU5MzU4ODA4NSwgImF1ZCI6ICJodHRwczovL29wLnVtdS5zZSJ9
.cRwSFNcDx6VsacAQDcIx
5OAt_Pj30I_uUKRh04N4QJd6MZ0f50sETRv8uspSt9fMa-5yV3uzthX
_v8OtQrV33gW1vzgOSRCdHgeCN40StbzjFk102seDwtU_Uzrcsy7KrX
YSBp8U0dBDjuxC6h18L8ExjeR-NFjcrhy0wwua7Tnb4QqtN0QCia6DD
8QBNVTL1Ga0YPmMdT25wS26wug23IgpbZB20VUosmMGgGtS5yCI5AwK
Bhozv-oBH5KxxHzH1Oss-RkIGiQnjRnaWwEOTITmfZWra1eHP254wFF
2se-EnWtz1q2XwsD9NSsOEJwWJPirPPJaKso8ng6qrrOSgw
&response_type=code
&client_id=https%3A%2F%2Fwiki.ligo.org
&redirect_uri=https%3A%2F%2Fwiki.ligo.org/openid/callback
&scope=openid+profile+email
HTTP/1.1
Host: op.umu.se
The OP receiving this Authentication Request will, unless the RP is already registered, start to dynamically fetch and establish trust with the RP.¶
The OP needs to establish a Trust Chain for the RP (wiki.ligo.org). The OP in this example is configured with public keys of two federations:¶
The OP starts to resolve metadata for the Client Identifier https://wiki.ligo.org by fetching the Entity Configuration using the process described in Section 9.¶
The process is the same as described in Appendix A.2 and will result in a Trust Chain with the following Entity Statements:¶
Using the public keys of the Trust Anchor that the LIGO Wiki RP has been provided within some secure out-of-band way, it can now verify the Trust Chain as described in Section 10.2.¶
We will not list the complete Entity Statements but only the
metadata
and metadata_policy parts.
There are two metadata policies:¶
"metadata_policy": {
"openid_provider": {
"contacts": {
"add": ["ops@edugain.geant.org"]
}
},
"openid_relying_party": {
"contacts": {
"add": ["ops@edugain.geant.org"]
}
}
}
"metadata_policy": {
"openid_relying_party": {
"application_type": {
"one_of": [
"web",
"native"
]
},
"contacts": {
"add": ["ops@incommon.org"]
},
"grant_types": {
"subset_of": [
"authorization_code",
"refresh_token"
]
}
}
}
Next, combine these and apply them to the metadata for wiki.ligo.org:¶
"metadata": {
"openid_relying_party": {
"application_type": "web",
"client_name": "LIGO Wiki",
"contacts": [
"ops@ligo.org"
],
"grant_types": [
"authorization_code",
"refresh_token"
],
"id_token_signed_response_alg": "RS256",
"signed_jwks_uri": "https://wiki.ligo.org/jwks.jose",
"redirect_uris": [
"https://wiki.ligo.org/openid/callback"
],
"response_types": [
"code"
],
"subject_type": "public",
"token_endpoint_auth_methods_supported": [
"private_key_jwt"
]
}
}
The final result is:¶
"metadata": {
"openid_relying_party": {
"application_type": "web",
"client_name": "LIGO Wiki",
"contacts": [
"ops@ligo.org",
"ops@edugain.geant.org",
"ops@incommon.org"
],
"grant_types": [
"refresh_token",
"authorization_code"
],
"id_token_signed_response_alg": "RS256",
"signed_jwks_uri": "https://wiki.ligo.org/jwks.jose",
"redirect_uris": [
"https://wiki.ligo.org/openid/callback"
],
"response_types": [
"code"
],
"subject_type": "public",
"token_endpoint_auth_methods_supported": [
"private_key_jwt"
]
}
}
Once the Trust Chain and the final Relying Party metadata
have been obtained, the OpenID Provider has
everything needed to validate the signature of the
Request Object in the Authentication Request, using the
public keys made available at the
signed_jwks_uri endpoint.¶
Here the LIGO Wiki RP sends an Explicit Registration request to the
federation_registration_endpoint
of the OP (op.umu.se). The request contains the RP's Entity Configuration.¶
An example JWT Claims Set for the RP's Entity Configuration is:¶
{
"iss": "https://wiki.ligo.org",
"sub": "https://wiki.ligo.org",
"iat": 1676045527,
"exp": 1676063610,
"aud": "https://op.umu.se",
"metadata": {
"openid_relying_party": {
"application_type": "web",
"client_name": "LIGO Wiki",
"contacts": ["ops@ligo.org"],
"grant_types": ["authorization_code"],
"id_token_signed_response_alg": "RS256",
"signed_jwks_uri": "https://wiki.ligo.org/jwks.jose",
"redirect_uris": [
"https://wiki.ligo.org/openid/callback"
],
"response_types": ["code"],
"subject_type": "public"
}
},
"jwks": {
"keys": [
{
"kty": "RSA",
"use": "sig",
"kid":
"U2JTWHY0VFg0a2FEVVdTaHptVDJsNDNiSDk5MXRBVEtNSFVkeXZwb",
"e": "AQAB",
"n":
"4AZjgqFwMhTVSLrpzzNcwaCyVD88C_Hb3Bmor97vH-2AzldhuVb8K..."
}
]
},
"authority_hints": ["https://incommon.org"]
}
The OP receives the RP's Entity Configuration and proceeds with the sequence of steps laid out in Appendix A.2.¶
The OP successfully resolves the same RP metadata described in Appendix A.3.1.2. It then registers the RP in compliance with its own OP metadata and returns the result in a registration Entity Statement.¶
Assuming the OP does not support refresh tokens it will register
the RP for the authorization_code grant
type only. This is reflected in the metadata returned to the RP.¶
The returned metadata also includes the
client_id, the
client_secret and other parameters that
the OP provisioned for the RP.¶
Here is an example JWT Claims Set of the registration Entity Statement returned by the OP to the RP after successful explicit client registration:¶
{
"iss": "https://op.umu.se",
"sub": "https://wiki.ligo.org",
"aud": "https://wiki.ligo.org",
"iat": 1601457619,
"exp": 1601544019,
"trust_anchor": "https://edugain.geant.org",
"metadata": {
"openid_relying_party": {
"client_id": "m3GyHw",
"client_secret_expires_at": 1604049619,
"client_secret":
"cb44eed577f3b5edf3e08362d47a0dc44630b3dc6ea99f7a79205",
"client_id_issued_at": 1601457619,
"application_type": "web",
"client_name": "LIGO Wiki",
"contacts": [
"ops@edugain.geant.org",
"ops@incommon.org",
"ops@ligo.org"
],
"grant_types": [
"authorization_code"
],
"id_token_signed_response_alg": "RS256",
"signed_jwks_uri": "https://wiki.ligo.org/jwks.jose",
"redirect_uris": [
"https://wiki.ligo.org/openid/callback"
],
"response_types": [
"code"
],
"subject_type": "public"
}
},
"authority_hints": [
"https://incommon.org"
],
"jwks": {
"keys": [
{
"kty": "RSA",
"use": "sig",
"kid":
"U2JTWHY0VFg0a2FEVVdTaHptVDJsNDNiSDk5MXRBVEtNSFVkeXZwb",
"e": "AQAB",
"n":
"4AZjgqFwMhTVSLrpzzNcwaCyVD88C_Hb3Bmor97vH-2AzldhuVb8K..."
},
{
"kty": "EC",
"use": "sig",
"kid": "LWtFcklLOGdrW",
"crv": "P-256",
"x": "X2S1dFE7zokQDST0bfHdlOWxOc8FC1l4_sG1Kwa4l4s",
"y": "812nU6OCKxgc2ZgSPt_dkXbYldG_smHJi4wXByDHc6g"
}
]
}
}
Copyright (c) 2024 The OpenID Foundation.¶
The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.¶
The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that MAY cover technology that MAY be required to practice this specification.¶
[[ To be removed from the final specification ]]¶
-42¶
Fixed #130: Allow multiple Trust Anchor values to be passed in resolve requests.¶
Require trust_chain claim in resolve response.¶
Fixed #161: Prohibit loops in Trust Chains.¶
Fixed #47: Described using and not using a provided Trust Chain during Automatic Registration.¶
Fixed #85: Clarified Trust Chain selection during Explicit Registration.
Also corrected the authority_hints value
in the Explicit Registration response to be the Immediate Superior
of the RP in the Trust Chain selected for it by the OP.¶
Fixed #35: Clarified that using non-interoperable JSON, as per Sections 4 and 8 of RFC 8259, can result in unpredictable metadata and metadata policy behavior.¶
Fixed #162: Trust Mark claim id
renamed to trust_mark_id.
Other more specific Trust Mark JWT typ header parameter values
can be used if defined by trust frameworks in use and understood by the implementation.¶
-41¶
Fixed #131: Changed anchor request parameter
to trust_anchor,
changed trust_anchor_id claim
to trust_anchor, and
changed type request parameter
to entity_type.¶
Explicitly typed base64url-encoded examples that were previously untyped.
Also added missing client_id and
iss values in some examples.¶
Fixed #7, #86, #134, and #148: Provides implementation considerations on Federation topologies.¶
Fixed #136: Defined additional error codes and rationalized naming.
Renamed trust_chain_validation_failed
to invalid_trust_chain and
renamed missing_trust_anchor
to invalid_trust_anchor.¶
Fixed #133: Refined wording about client authentication when using
Automatic Registration and added
token_endpoint_auth_methods_supported
in RP metadata example.¶
Reference OpenID Connect Relying Party Metadata Choices 1.0.¶
Fixed #143: Added Trust Mark Issuer and Trust Mark Owner to Terminology section.¶
Fixed #139: Clarified description of using request objects.¶
Fixed #140: Federation Entity Keys MUST NOT appear in metadata.¶
Fixed #105 and #106: Informatively say that the
require_signed_request_object
and require_pushed_authorization_requests
metadata parameters can be used.¶
Fixed #107: Clarified how to validate Trust Marks.¶
Fixed #114: Described why it may make sense to not support
the use of request_uri
other than in conjunction with a PAR request.¶
Fixed #108: Removed remark about trust mark delegation revocation.¶
Fixed #120: Required kid (Key ID)
header parameter in Signed JWK Set JWTs.¶
Define media type for Explicit Registration responses
application/explicit-registration-response+jwt
distinct from application/entity-statement+jwt.¶
Restrict audience values to the single Entity Identifier of the intended recipient.¶
-40¶
Renamed validation_failed error code to
trust_chain_validation_failed.
Fixed #89: Improved Entity Statement jwks claim description.¶
Fixed #88: Explicitly require audience validation for explicit registration requests and responses.¶
Fixed #28: Described validation of resolved metadata.¶
Fixed #98: Require that the audience of JWTs used for
client authentication at federation endpoints
with private_key_jwt
be the Entity Identifier of the endpoint's Entity.¶
Fixed #34: Deleted
request_authentication_methods_supported and
request_authentication_signing_alg_values_supported
and replaced with the use of standard Request Object
and PAR metadata values.
Also restricted PAR authentication methods to those
performing signing with the RP's keys.¶
Fixed #98: Required audience when using
private_key_jwt with PAR
to be the Authorization Server's Entity Identifier.¶
Reverted change to allow PAR requests not using Request Objects when the client authentication method uses a signature with with a Federation Entity Key.¶
Fixed #104: Removed the *_auth_signing_algs
metadata parameters in favor of
endpoint_auth_signing_alg_values_supported.¶
Required that the issuer OP and AS
metadata values match the Entity Identifier.¶
Fixed #69: Specified more details of successful and error responses to authentication requests using Automatic Registration.¶
Fixed #24: Removed trust_mark and
iat from Trust Mark Status endpoint.
Use GET at Trust Mark Status endpoint.¶
-39¶
Fixed #33: Corrected "add" operator values in examples to be arrays.¶
Endpoint URLs are not form-urlencoded in JSON metadata parameter values.¶
Fixed #52: Clarified that PAR requests must use Request Objects.¶
Fixed #64: Explicitly typed signed JWK Sets.¶
Fixed #55: Required validating explicit typing of JWTs.¶
Fixed #53: State that JWS and JWE Compact Serializations are used.¶
Fixed #49: Added request_authentication_signing_alg_values_supported to example.¶
Fixed #46: Corrected statment about preventing use of Request Object
for private_key_jwt client authentication.¶
Fixed #43: Allow multiple type request parameters in resolve requests.¶
Fixed #40: Changed section name from "Resolve Entity Statement" to "Resolve Entity".¶
Improved descriptions of the JWT Claims being registered, per feedback from the IANA Designated Expert.¶
Fixes #45: Tightened Trust Chain signature validation wording.¶
Fixed #40: Changed section name from "Resolve Entity Statement" to "Resolve Entity".¶
Fixed #39: Removed iss parameter from fetch endpoint.¶
Fixed #54: MAY NOT -> MUST NOT.¶
Fixed #58: Require authority_hints value
to contain the Entity Identifiers of all Immediate Superiors.¶
-38¶
Added section defining each media type, per IANA Designed Expert review.¶
Fixed #36: Simplified obtaining Entity Configurations.¶
Fixed #30: Simplified fetch endpoint to only return Subordinate Statements.¶
Removed text describing endpoints as being
"encoded in application/x-www-form-urlencoded format".¶
-37¶
Note that after the approval and publication of the fourth Implementer's Draft https://openid.net/specs/openid-federation-1_0-ID4.html, work on the OpenID Federation specification moved from the repository https://bitbucket.org/openid/connect/ to the repository https://github.com/openid/federation. Issue numbers before this draft are from the Bitbucket repository. Issue numbers starting with this draft are from the GitHub repository.¶
Fixed #15: Clarified that OpenID Federation can be used for trust establishment with any application protocols.¶
Fixed #18: Clarified use of valid Trust Marks.¶
Fixed #19: Clarified that Federation Entities publish their public keys.¶
Fixed #22: Defined that Entity Identifiers MUST use the
https scheme.¶
Clarified that additional client_registration_types
MAY be defined and used.¶
Corrected Usage Location values in IANA "OAuth Extensions Error Registry" registrations.¶
-36¶
Made the definiton of iat and exp consistent.¶
-35¶
Addresses #2124: The constraints claim must only appear in Subordinate Statements.¶
Fixes #2126: The max_path_length definition must be expressed in terms of Intermediate Entities, not Entity Statements, to prevent ambiguity.¶
Addresses #2139: Clarifies metadata statements (vs metadata policies).¶
Addressed #2143: Additional policy operators that modify metadata parameters must be applied after the value operator. Additional policy operators that check metadata parameters must be applied before the essential operator.¶
Addressed #2140: The historical keys response JWT uses reason values without referencing the ones defined in the X.509 CRL spec [RFC 5280].¶
Addressed #1802: Added a definition of "trust" within the introduction, to clarify its meaning within the context of the specification.¶
Fixed #2082: Allow Trust Chains to start with any Entity Configuration and not just those of Leaf Entities.¶
Fixed #2123: Stated that all members of a Trust Chain have an equal opportunity to contribute to metadata policies.¶
Fixed #2148: Require fetch, listing, and trust mark status federation endpoints to be published in Entity Configuration metadata.¶
Fixed #2149: Stated that entities MUST publish Subordinate Statements about their Immediate Subordinates.¶
Fixed #2150: Defined invalid_issuer error code.¶
Fixed #2152: Stated that "if not understood MUST be ignored" processing rule applies to federation endpoint request parameters.¶
Fixed #2151: Put federation endpoints in a more logical order.¶
-34¶
Addressed #2090: Metadata policy: Clarified the order in which the standard policy operators must be applied, the merge process when multiple Subordinate Statements contain metadata_policy claims for a given Entity Type, and that asserted metadata must be applied before the merged metadata policy.¶
Addressed #2078: Metadata policy: Specified mandatory and optional to support JSON types for each standard policy operator.¶
Addressed #2087: Metadata policy: Added an explicit description of the principles governing the metadata_policy and common requirements for all policy operators, standard as well as additional operators that maybe defined in future specifications that rely on OpenID Federation 1.0. In particular, stated the principles in regard to the 1) hierarchy of Entities in Trust Chains, 2) the specificity of policies, 3) the granularity of policies, 4) the action types of operators, 5) that metadata policy enforcement is integral to the trust chain, 6) the determinism of the metadata policy specification.¶
Addressed #2116: Metadata policy: Clarified that the metadata_policy is not intended to JSON type check metadata parameters.¶
Addressed #2135: Metadata policy: The space-separated list of strings exception should apply only to the "scope" oauth_client metadata parameter.¶
Addressed #2136: Metadata policy: Merges the two metadata policy examples and expands the example to include all standard policy operators¶
Addressed #2124: Renames the allowed_leaf_entity_types constraint to allowed_entity_types, changes its definition to also apply to Subordinate Entities that are Intermediate Entities, not only Subordinates that are Leaves.¶
Fixed #2119: Federation metadata_policy example figures and descriptions.¶
Changed the HTTP method used at the Trust Mark Status Endpoint back to POST because of the potentially large size of the request.¶
Fixed #2128: The federation_trust_mark_endpoint requires a sub request parameter.¶
Fixed #2120: Defined and consistently used the terms Subordinate, Immediate Subordinate, Superior, and Immediate Superior.¶
Fixed #2089: Added section Resolving the Trust Chain and Metadata with a Resolver.¶
Fixed #2131: JSON in Entity Statement example in figure 2.¶
Fixed #2088: Clarified tls_client_auth rules.¶
Fixed #2130: Clarified wording describing common metadata parameters.¶
Fixed #2133: Made treatment of
jwks Entity Statement claim
consistent when doing Explicit Registration.¶
Registered application/jwk-set+jwt media type.¶
Registered nbf JWK parameter.¶
Fixed #2132: Stated that Automatic Registration and Explicit Registration can also be used for OAuth 2.0 profiles other than OpenID Connect.¶
Fixed #2138: Required kid (Key ID)
header parameter in JWTs.¶
-33¶
Addressed #2111: The metadata_policy_crit claim MAY only appear in Subordinate Statements and its values apply to all metadata_policies found in the Trust Chain.¶
Fixed #2096: Authorization Signed Request Object may contain trust_chain in its payload and should not in its JWS header parameters.¶
Strengthen language requiring client verification with automatic registration.¶
Fixed #2076: Promoted Trust Marks to be a top-level section.¶
Added General-Purpose JWT Claims section.¶
Moved Federation Endpoints section before Obtaining Federation Entity Configuration Information section.¶
Fixed #2110: Explanatory text when multiple entity_type parameters are provided in the Subordinate Listing endpoint.¶
Fixed #2112, #2113, and #2114: Defined that client authentication is
not used by default and that the default client authentication method,
when used, is private_key_jwt.
Specified that requests using client authentication use HTTP POST.¶
Fixed #2104: Allow trust marks in Subordinate Statements for implementation profiles that might want this.¶
Fixed #2103: Addressed ambiguities in the definition of constraints.¶
-32¶
Tightened OpenID Connect Client Registration section.¶
Tightened appendix examples.¶
Fixed #2075: Trust Mark endpoint for the provisioning of the Trust Marks.¶
Fixed #2085: Trust Marked Entities Listing;
added sub URL query parameter.¶
Made fetch issuer unambiguous by making
the iss parameter REQUIRED.¶
Introduced the term "Subordinate Statement" and applied it throughout the specification. Also consistently use the term "registration Entity Statement" for Explicit Client Registration results.¶
Clarified where Entity Statement claims can and cannot occur.¶
Renamed policy_language_crit
to metadata_policy_crit.¶
Fixed #2093: Numbered the list defining the order policy operators are applied in.¶
-31¶
Fixed #2068: Clarifications that authority_hints must only appear in Leaf and Intermediate Entity Configurations.¶
Fixed #2062: Verified that metadata examples are consistent with the specification.¶
Fixed #1724: Numbered figures by adding captions to them.¶
Fixed #2033: Described the advantage of having the Trust Anchor host the resolve endpoint.¶
Fixed #1659: Described use of the trust_chain header parameter in resolve responses.¶
Addressed #2060: A concrete order must be specified for the application of all metadata policy operators.¶
Addressed #2069: Metadata parameters with null value must be treated as error when applying metadata policies.¶
Fixed #2034: Other use cases of Federation Automatic Registration, FAPI included.¶
Moved the definitions of organization_name, contacts, logo_uri, policy_uri, and homepage_uri from the federation_entity Entity Type definition to the set of metadata parameters applicable to all Entity Types.¶
Clarified the role of the Trust Anchor's Entity Configuration in Trust Chains.¶
Fixed #1751: Provided guidance to prevent stuck clients.¶
Fixed #2071: Removed most of the Claims Languages and Scripts text duplicating that in OpenID Connect Core.¶
Tightened descriptions of constraints and Trust Marks.¶
Tightened descriptions of Federation Endpoints.¶
Fixed #2080: Defined federation_historical_keys_endpoint metadata parameter.¶
Fixed #2081: Renamed
trust_marks_owners to
trust_mark_owners and renamed
trust_marks_issuers to
trust_mark_issuers.¶
Fixed #2079: Renamed the id Trust Mark status
request parameter to trust_mark_id to match
the parameter names used in Subordinate listing requests and
Trust Marked entities listing requests.¶
-30¶
Clarifies that when the metadata policy combination process encounters an error, such as being unable to merge two operators, the policy combination MUST be considered invalid.¶
Applications and protocols using Entity Statements MAY specify additional claims.¶
Addressed #1655: The definitions of aud and
trust_anchor_id are moved to the Explicit
Client Registration section.¶
Fixed #1957: Explicit Registration: Clarifies OP processing of Explicit Registration requests with a trust chain.¶
Addressed #1655: Explicit Registration: Simplifies the expression of the registered RP metadata - the metadata policy mechanism is no longer used.¶
Addressed #1655: Explicit Registration: An RP MUST always verify the
metadata it was registered with. The standard Trust Chain resolution
and application of metadata_policy is the
SHOULD method, but RPs are free to utilize other methods yielding the
same result, e.g. by calling a helper web endpoint provided by the
Trust Anchor.¶
Addressed #1655: Explicit Registration: Exact specification of the EC claims used in requests and the ES claims used in responses; normative language where necessary to remove ambiguities and guarantee interop.¶
Explicit Registration: The exp (expiration)
of the response ES must be the time when the OP is going to
expire the client registration. Intended to inform the RP when its
registration is going to expire so that it can re-register in advance
and prevent stuck end-users if the registration expires in the middle
of an OAuth flow.¶
Explicit Registration: Replaces the hard requirement that OPs must periodically ensure that a valid Trust Chain for the RP can be established with non-normative text common to both Automatic and Explicit Registration. The Trust Chain expiration MUST be the primary method for OPs to control the validity of registrations.¶
Resolving Trust Chain and Metadata: Adds a subsection describing the possibility of transient Trust Chain validation errors when the topology of a federation is updated and suggests a retry strategy.¶
Updated contributor affiliations.¶
Fixed #1947: Added source_endpoint as OPTIONAL in Entity Statement JWS.¶
Historical keys response: iat is OPTIONAL.¶
Added text on Trust Mark delegation.¶
Fixed #2041: Added normative language mandating the https scheme and any optional port and path, for all the Entity Identifiers and the federation endpoints.¶
Cite draft-ietf-oauth-resource-metadata.¶
Fixed #2002: Added sequence diagrams and representations of the general architecture and the Trust Chain.¶
Fixed #2061: Clarified that the constraints claim may only appear in statements issued by authorities.¶
Fixed #2062: Require metadata statements for all Entity Type Identifiers that apply to an Entity.¶
Replaced duplicative term "metadata type" with "Entity Type" and defined the term "Entity Type Identifier".¶
Added section headings to the Metadata section to more cleanly separate Entity Type Identifiers from Metadata Extensions.¶
Fixed #2064: Prohibited the use of null as a metadata value.¶
Rewrote request_authentication_methods_supported description.¶
Registered keys JWT claim and
iat, exp, and
revoked JWK parameters.¶
Fixed #1727: Changed specification name from "OpenID Connect Federation" to "OpenID Federation".¶
-29¶
Fixed #1921: brand new JWS Header parameter, trust_chain.¶
Fixed #1879, #1881, #1883, #1885: introductory text, metadata section, editorials.¶
-28¶
Fixed #1823: Metadata policy clarification text on essential term and sub_set, one_of, superset_of.¶
Listing endpoint - added the parameters trust_marked and trust_mark_id.¶
Historical keys endpoint, references to rfc7517 and use of claim keys, correction in the normative text.¶
Added the endpoint federation_trust_mark_list_endpoint for Trust Mark issuers.¶
-27¶
Fixed #1756: Clarified that the authority_hints in the Entity Statement of an explicit registration response is single-valued.¶
Added text about the usage of metadata besides metadata_policy.¶
Fixed #1745 #1746: Non-normative example of Trust Mark status endpoint.¶
Fixed #1747: Client Registration Response content-type set to application/entity-statement+jwt.¶
Fixed #1740: Metadata policy example for OpenID Connect, removed scopes.¶
Fixed #1755: clarification on the key to be used for Federation operations.¶
The "essential" policy operator can be used in conjunction with one_of, subset_of, superset_of to make their presence optional.¶
Fixed #1779: Entity Type as defined term.¶
Added Sequence Diagram representing a Federation Entity Discovery and metadata evaluation.¶
Fixed #1757: Federation Historical Keys endpoint support for revocation status. Endpoint enabled for all the Federation Entities.¶
Fixed #1803: Subordinate is a defined term and other small editorial changes after Heather's revision.¶
Added Cryptographic Trust Mechanism description.¶
Fixed #1660: Clarified that Explicit Registration uses no parameters and added Explicit Registration example.¶
Fixed #1782: Reference protected resource metadata draft.¶
Fixed #1809: Replaced use of "trust issuers" terminology.¶
Fixed #1661: Tightened descriptions of metadata standards used.¶
Fixed #1801: Better described function of "essential" metadata operator.¶
-26¶
Applied editorial improvements by Heather Flanagan.¶
-25¶
Fixed #1684: disambiguation on the role federation_entity.¶
Fixed #1703: Unsigned error response.¶
Fixed #1693: Trust mark status endpoint HTTP method changed to POST.¶
Fixed #1681: RS256 is not mandatory anymore for federation operations signatures.¶
Fixed #1701: trust_chain parameter with PAR and redirect_uri.¶
Fixed #1695: entity_type URL parameter for Listing endpoint.¶
Fixed #1712: federation_entity claims: organization_name is recommended, logo_uri is added.¶
Fixed #1702: removal of metadata type trust_mark_issuer, federation_status_endpoint moved in the federation_entity metadata and renamed to federation_trust_mark_status_endpoint.¶
Fixed #1716: Clarified how to retrieve the RP's Entity Configuration when using Automatic Registration.¶
Fixed #1656: Introductory text review.¶
-24¶
Fixed #1654: Text cleanup on how and who publishes the Entity Configuration.¶
Relaxed JWK Set representations: jwks, signed_jwks_uri and jwks_uri can coexist in the same Metadata for interoperability purposes across different Federations.¶
Fixed #1641: Federation Historical Keys endpoint.¶
Fixed #1673: added resolve endpoint JWT claims.¶
Fixed #1663: clarifications on the http status codes returning from /.well-known/openid-federation.¶
Fixed #1667: serialization format for federation endpoint made explicit.¶
Fixed #1662: ID Token section removed.¶
Fixed #1680: removal of the claim operation in Generic Errors.¶
Fixed #1669: error types in the section Generic Error Response.¶
Added Vladimir Dzhuvinov as an editor.¶
-23¶
Text on max_path_length¶
Fixed #1634: Trust Chain explanatory text.¶
Federation Entity Discovery as defined term.¶
Fixed #1645: Federation Entity Keys as defined term.¶
Fixed #1633: Explanatory text about who signs the Trust Mark and how.¶
Fixed #1650: typo in signed_jws_uri and jwks metadata claims.¶
-22¶
Rewritten text about metadata processing when doing Explicit Client Registration.¶
Fixed #1581: OP metadata claims enabled for AS.¶
Fixed #1594: self-issued trust_chain in the Authorization Request.¶
Fixed #1583: metadata policy one_of operator, explanatory text for multiple values.¶
Fixed #1584: Stated that domain name constraints are as specified in Section 4.2.1.10 of [RFC5280].¶
Added more text on considerations when using the resolve endpoint.¶
Removal of aud parameter in the fetch endpoint request.¶
General rewording with the terms Leaf Entity and Entity Configuration.¶
Fixed #1588: Explicitly described the differences between Automatic and Explicit Registration.¶
Fixed #1606: Described situation in which the requirement for signed requests with Automatic Registration could be relaxed.¶
Fixed #1629: authz Request Object, audience explanatory text.¶
Fixed #1630: Resolve endpoint response content type.¶
Fixed #1608: submission of the Trust Chain in the Explicit Client Registration Request.¶
-21¶
Fixed #1547: Metadata section restructured.¶
Fixed #1548: request_authentication_signing_alg_values_supported clarification text about the usage of private_key_jwt and request_object.¶
Added a new constraint, allowed_leaf_entity_types.¶
Resolve endpoint: Removed iss parameter in the request and specified the usage of the aud claim in the response.¶
Fixed #1513: request_authentication_methods_supported according to IANA OAuth 2.0 AS metadata registered names.¶
Fixed #1527: Defined the Trust Mark term and added non-normative examples.¶
Added Security Considerations regarding the role of the Trust Marks.¶
Editorial review, normative language, and typos.¶
Fixed #1535: Removed the sub claim from the non-normative example of the Authorization Request Object.¶
Fixed #1528: Added Claims Languages and Scripts section.¶
Fixed #1456: Added language about space-delimited string parameters from RFC 6749.¶
-20¶
Updated example for Resolve endpoint.¶
Recommended that Key IDs be the JWK Thumbprint of the key.¶
Fixed #1502 - Corrected usage of id_token_signed_response_alg.¶
Fixed #1506 - Referenced RFC 9126 for Pushed Authorization Requests.¶
Added Giuseppe De Marco as an editor and removed Samuel Gulliksson as an editor.¶
Fixed #1508 - Editorial review.¶
Fixed #1505 - Defined that signed_jwks_uri is preferred over
jwks_uri and jwks.¶
Fixed #1514 - Corrected RP metadata examples to use id_token_signed_response_alg.¶
Fixed #1512 - Registered the error codes missing_trust_anchor
and validation_failed.¶
Also registered the OP Metadata parameters
organization_name,
request_authentication_methods_supported,
request_authentication_signing_alg_values_supported,
signed_jwks_uri,
and
jwks
and the RP Metadata parameters
client_registration_types (which was previously misregistered as client_registration_type),
organization_name,
and
signed_jwks_uri.¶
Defined the term Federation Operator and described redundant retrieval of Trust Anchor keys.¶
Fixed #1519 - Corrected instances of client_registration_type
to client_registration_types_supported.¶
Fixed #1520 - Renamed federation_api_endpoint
to federation_fetch_endpoint.¶
Fixed #1521 - Changed swamid.sunet.se to swamid.se in examples.¶
Fixed #1523 - Added request_parameter_supported to examples.¶
Capitalized defined terms.¶
-19¶
Fixed #1497 - Removed trust_mark claim from federation entity metadata.¶
Fixed #1446 - Added trust_chain and removed is_leaf.¶
Fixed #1479 - Added jwks claim in OP metadata.¶
Fixed #1477 - Added request_authentication_methods_supported.¶
Fixed #1474 - Added the request_authentication_signing_alg_values_supported OP metadata parameter.¶
Rewrote trust_marks definition.¶
-18¶
Added the jwks claim name for OP Metadata.¶
Moved from a federation API to separate endpoints per operation.¶
Added descriptions of the list, resolve and status federation endpoints.¶
Registered the client_registration_types_supported and
federation_registration_endpoint
authorization server metadata parameters.¶
Registered the client_registration_type
dynamic client registration parameter.¶
Registered and used the application/entity-statement+jwt media type.¶
Registered the application/trust-mark+jwt media type.¶
Trust marks: the claim mark has been renamed to logo_uri.¶
New federation endpoint: Resolve Entity Statement.¶
New federation endpoint: Trust Mark Status.¶
Federation API, Fetch: iss parameter is optional.¶
Trust Marks: added non-normative examples.¶
Expanded Section 8.1: Included Entity configurations.¶
Fixed #1373 - More clearly defined the term Entity Statement, both in the Terminology section and in the Entity Statement section.¶
-17¶
Addressed many working group review comments.
Changes included adding the Overall Architecture section,
the trust_marks_issuers claim,
and the Setting Up a Federation section.¶
-16¶
Added Security Considerations section on Denial-of-Service attacks.¶
-15¶
Added signed_jwks_uri,
which had been lost somewhere along the road.¶
-14¶
Rewrote the federation policy section.¶
What previously was referred to as
client authentication in connection
with automatic client registration is now changed to be
request authentication.¶
Made a distinction between parameters and claims.¶
Corrected the description of the intended behavior when
essential is absent.¶
-13¶
Added 'trust_marks' as a parameter in the Entity Statement.¶
An RP's self-signed Entity Statement MUST have the OP's issuer identifier as the value of 'aud'.¶
Added RS256 as default signing algorithm for Entity Statements.¶
Specified that the value of 'aud' in the Entity Statement use in automatic client registration MUST have the ASs authorization endpoint URL as value. Also, the 'sub' claim MUST NOT be present.¶
Separating the usage of merge and combine as proposed by Vladimir Dzhuvinov in Bitbucket issue #1157.¶
An RP doing only explicit client registration is not required to
publish and support
/.well-known/openid-federation.¶
Every key in a JWK Set in an Entity Statement MUST have a kid.¶
-12¶
Made JWK Set OPTIONAL in an Entity Statement returned by OP as response of an explicit client registration¶
Renamed Entity type to client registration type.¶
Added more text describing client_registration_auth_methods_supported.¶
Made "Processing the Authentication Request" into two separate sections: one for Authentication Request and one for Pushed Authorization Request.¶
Added example of URLs to some examples in the appendix.¶
Changed the automatic client registration example in the appendix to use Request Object instead of a client_assertion.¶
-11¶
Added section on Trust Marks.¶
Clarified private_key_jwt usage in the authentication request.¶
Fixed Bitbucket issues #1150 and #1155 by Vladimir Dzhuvinov.¶
Fixed some examples to make them syntactically correct.¶
-10¶
Incorporated additional review feedback from Marcos Sanz. The primary change was moving constraints to their own section of the Entity Statement.¶
-09¶
Incorporated review feedback from Marcos Sanz. Major changes were as follows.¶
Separated Entity configuration discovery from operations provided by the federation API.¶
Defined new authentication error codes.¶
Also incorporated review feedback from Michael B. Jones.¶
-08¶
Incorporated review feedback from Michael B. Jones. Major changes were as follows.¶
Deleted sub_is_leaf Entity Statement
since it was redundant.¶
Added client_registration_type RP registration
metadata value
and client_registration_types_supported OP
metadata value.¶
Deleted openid_discovery metadata type
identifier
since its purpose is already served by
openid_provider.¶
Entity identifier paths are now included when using the Federation API, enabling use in multi-tenant deployments sharing a common domain name.¶
Renamed sub_is_leaf to
is_leaf
in the Entity Listings Request operation parameters.¶
Added crit and
policy_language_crit,
enabling control over which Entity Statement and policy language
extensions
MUST be understood and processed.¶
Renamed openid_client to
openid_relying_party.¶
Renamed oauth_service to
oauth_authorization_server.¶
Renamed implicit registration to
automatic
registration
to avoid naming confusion with the implicit grant type.¶
Renamed op to
operation
to avoid naming confusion with the use of "OP" as an acronym for
"OpenID Provider".¶
Renamed url to
uri
in several identifiers.¶
Restored Open Issues appendix.¶
Corrected document formatting issues.¶
-07¶
-06¶
-05¶
A major rewrite.¶
-04¶
The authors wish to acknowledge the contributions of the following individuals and organizations to this specification: Marcus Almgren, Pasquale Barbaro, Brian Campbell, David Chadwick, Michele D'Amico, Andrii Deinega, Erick Domingues, Heather Flanagan, Michael Fraser, Samuel Gulliksson, Joseph Heenan, Pedram Hosseyni, Marko Ivančić, Łukasz Jaromin, Takahiko Kawasaki, Torsten Lodderstedt, Francesco Marino, John Melati, Alexey Melnikov, Roberto Polli, Justin Richer, Jouke Roorda, Nat Sakimura, Mischa Sallé, Stefan Santesson, Marcos Sanz, Peter Brand, Michael Schwartz, Giada Sciarretta, Amir Sharif, Sean Turner, Niels van Dijk, Tim Würtele, Kristina Yasuda, Gabriel Zachmann, and the JRA3T3 task force of GEANT4-2.¶