| R. Hedberg, Ed. | |
| independent | |
| M. Jones | |
| Microsoft | |
| A. Solberg | |
| Uninett | |
| S. Gulliksson | |
| Schibsted | |
| J. Bradley | |
| Yubico | |
| September 9, 2021 |
OpenID Connect Federation 1.0 - draft 17
openid-connect-federation-1_0
A federation can be expressed as an agreement between parties that trust each other. In bilateral federations, you can have direct trust between the parties. 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 is interacting 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 describes the basic components you will need to build a multilateral federation and it provides a guide on how to apply them when the underlying protocol used is OpenID Connect.
This specification describes how two entities that would like to interact can dynamically fetch and resolve trust and metadata for a given protocol through the use of third-party trust anchor. A trust anchor is an entity whose main purpose is to issue statements about entities, such as OpenID Connect Relying Parties, OpenID Providers, and participating organizations. An identity federation can be realized using this specification using one or more levels of trust issuers. This specification does not mandate a specific way or restrict how a federation may be built. Instead, the specification provides the basic technical trust infrastructure building blocks needed to build 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. Furthermore, note that a company, as with any real-world organization, MAY be represented by more than one entity in a federation. It is also true that an entity can be part of more than one federation.
OpenID Connect Federation trust chains rely on cryptographically signed JSON Web Token (JWT) documents, and the trust chain does not at all rely on TLS [RFC8446] to establish trust.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
This specification uses the terms "Claim Name", "Claim Value", "JSON Web Token (JWT)", defined by JSON Web Token (JWT) and the terms "OpenID Provider (OP)" and "Relying Party (RP)" defined by OpenID Connect Core 1.0.
This specification also defines the following terms:
The basic component is the entity statement, which is a cryptographically signed JSON Web Token (JWT). A set of entity statements can form a path from a leaf entity to a trust anchor. This is done by having authority hints in an entity statement pointing to its nearest superiors. Starting with an entity statement, you can then find the next level of entity statements by following the authority hints. And then repeat this until you hit a trust anchor.
Once you have followed a path, you have collected a set of entity statements that forms a chain. You can verify that this chain has not been tampered with by verifying the signature of each statement. How this is done is described in Section 3.2.
With a verified trust chain in hand, you can now apply federation policy to the published metadata. How this is done is described in Section 5.
Note that this specification is only dealing with trust in that the other party is part of the same federation as you and that you can trust that the metadata you get that describes the other party is what was sent. The specification does not touch protocol operations outside those of metadata exchange. In OpenID Connect terms, these are protocol operations other than discovery and registration.
The fact that we use OpenID Connect in all the examples in this specification does not mean that the specification can only be used together with OpenID Connect. On the contrary, it can equally well be used to build an OAuth 2.0 federations or for that matter, other protocols that depend on dynamic exchange of entity metadata.
An entity statement is issued by an entity and concerns a subject entity and leaf entities in a federation. An entity statement is always a signed JWT. All entities in a federation SHOULD be prepared to publish an entity statement about themselves. If they are not able to do so themselves someone else MUST do it for them.
An entity statement is composed of the following claims:
The following is a non-normative example of a trust_marks_issuers claim value:
{
"https://openid.net/certification/op": ["*"],
"https://refeds.org/wp-content/uploads/2016/01/Sirtfi-1.0.pdf":
["https://swamid.sunet.se"]
}
The entity statement is signed using the private key of the issuer entity, in the form of a JSON Web Signature (JWS). Entities MUST support signing Entity Statements with the RSA SHA-256 algorithm (an alg value of RS256). Consequently entities MUST support signature verification where the statement was signed using RS256.
The following is a non-normative example of an entity statement before serialization and adding a signature. 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,
"crit": ["jti"],
"jti": "7l2lncFdY6SlhNia",
"policy_language_crit": ["regexp"],
"metadata_policy": {
"openid_provider": {
"issuer": {"value": "https://ntnu.no"},
"organization_name": {"value": "NTNU"},
"id_token_signing_alg_values_supported":
{"subset_of": ["RS256", "RS384", "RS512"]},
"op_policy_uri": {
"regexp":
"^https:\/\/[\\w-]+\\.example\\.com\/[\\w-]+\\.html"}
},
"openid_relying_party": {
"organization_name": {"value": "NTNU"},
"grant_types_supported": {
"subset_of": ["authorization_code", "implicit"]},
"scopes": {
"subset_of": ["openid", "profile", "email", "phone"]}
}
},
"constraints": {
"max_path_length": 2
},
"jwks": {
"keys": [
{
"alg": "RS256",
"e": "AQAB",
"key_ops": ["verify"],
"kid": "key1",
"kty": "RSA",
"n": "pnXBOusEANuug6ewezb9J_...",
"use": "sig"
}
]
},
"authority_hints": [
"https://edugain.org/federation"
]
}
In an OpenID Connect Identity Federation, entities that together build a trust chain can be categorized as:
A trust chain begins with a leaf entity's self-signed entity statement, has zero or more entity statements issued by intermediates about subordinates, and ends with an entity statement issued by the trust anchor about the top-most intermediate (if there are intermediates) or the leaf entity (if there are no intermediates).
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:
A trust chain MUST always be possible to order such that: If we name the entity statements ES[0] (the leaf entity's self-signed entity statement) to ES[i] (an entity statement issued by the trust anchor), i>0 then:
The signing key that MUST be used to verify ES[i] is distributed from the trust anchors to any entity that needs to verify a trust chain in some secure out-of-band way not described in this document.
This specification does allow new metadata types to be defined, to support use cases outside OpenID Connect federations. The metadata type identifier will uniquely identify which metadata specification to utilize.
The metadata document MUST be a JSON document. Beyond that there is no restriction.
Metadata used in federations typically reuses existing metadata standards. If needed, the metadata schema is extended with additional properties relevant in a federated context. For instance, for OpenID Connect Federations, this specification uses metadata values from OpenID Connect Discovery 1.0 and OpenID Connect Dynamic Client Registration 1.0 and adds additional values used for federations.
The metadata type identifier is openid_relying_party.
All parameters defined in Section 2 of OpenID Connect Dynamic Client Registration 1.0 are allowed in a metadata statement.
To that list is added:
There are more claims defined in
[RFC7519]; of these, aud SHOULD NOT be used, since the issuer cannot know who the audience is. nbf and jti are deemed to not be very useful in this context and are therefore to be omitted.
The following is a non-normative example of a signed JWKS before serialization and adding a signature.
{
"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",
"iat": 1618410883
}
The metadata type identifier is openid_provider.
All parameters defined in Section 3 of OpenID Connect Discovery 1.0 are applicable.
In addition, the following parameters are defined by this specification:
The only request authentication method that can be used if doing authentication as described in
OpenID Connect Core 1.0 is request_object. If pushed authorization is used then one of private_key_jwt, tls_client_auth and self_signed_tls_client_auth can be used.
The following is a non-normative example of OP metadata:'
{
"issuer": "https://server.example.com",
"authorization_endpoint":
"https://server.example.com/authorization",
"token_endpoint": "https://server.example.com/token",
"signed_jwks_uri": "https://server.example.com/jws.json",
"response_types_supported": ["code", "id_token", "id_token token"],
"subject_types_supported": ["public"],
"id_token_signing_alg_values_supported": ["RS256", "ES256"],
"token_endpoint_auth_methods_supported": ["private_key_jwt"],
"pushed_authorization_request_endpoint":
"https://server.example.com/par",
"client_registration_types_supported": ["automatic", "explicit"],
"federation_registration_endpoint":
"https://server.example.com/fedreg",
"request_authentication_methods_supported": {
"ar": ["request_object"],
"par": ["private_key_jwt", "self_signed_tls_client_auth"]
}
}
The metadata type identifier is oauth_authorization_server.
All parameters defined in Section 2 of RFC 8414 are applicable.
The metadata type identifier is oauth_client.
All parameters defined in Section 2 of RFC 7591 are applicable.
The metadata type identifier is oauth_resource. There is no standard that specifies what parameters can occur in the metadata for this kind of entity. So for the time being, this can be regarded as a placeholder.
The metadata type identifier is federation_entity.
All entities participating in a federation are of this type.
The following properties are allowed:
Example
"federation_entity": {
"federation_api_endpoint":
"https://example.com/federation_api_endpoint",
"name": "The example cooperation",
"homepage_uri": "https://www.example.com"
}
An entity can publish metadata policies pertaining to entities of a specific type. Entity type identifiers specified in this document can be found in Section 4.
Each such metadata policy has the following structure:
It SHOULD be noted that claim names without language tags are different from the same claim but with language tags.
An example of a policy entry:
"id_token_signing_alg": {
"default": "ES256",
"one_of" : ["ES256", "ES384", "ES512"]
}
Which fits into a metadata policy like this:
"metadata_policy" : {
"openid_relying_party": {
"id_token_signing_alg": {
"default": "ES256",
"one_of" : ["ES256", "ES384", "ES512"]
}
}
}
Value modifiers are:
Value checks are:
As stated, a policy entry can contain one or more operators. Not all operators are allowed to appear together in a policy entry.
Other restrictions are:
If there is more than one metadata policy in a trust chain, then the policies MUST be combined before they are applied to the metadata statement.
Using the notation we have defined in Section 3.2, policies are combined starting with ES[i] and then adding the policies from ES[j] j=i-1,..,1 before applying the combined policy to the entity's metadata.
After each combination, the policy for each parameter MUST adhere to the rules defined in Section 5.1.2.
Once combining the Metadata policies has been accomplished, the next step is to apply the combined policy to the metadata.
Doing that, one follows these steps for each parameter in the policy.
A federation's policy for RPs:
{
"scopes": {
"subset_of": [
"openid",
"eduperson",
"phone"
],
"superset_of": [
"openid"
],
"default": [
"openid",
"eduperson"
]
},
"id_token_signed_response_alg": {
"one_of": [
"ES256",
"ES384",
"ES512"
]
},
"contacts": {
"add": "helpdesk@federation.example.org"
},
"application_type": {
"value": "web"
}
}
An organization's policy for RPs:
{
"scopes": {
"subset_of": [
"openid",
"eduperson",
"address"
],
"default": [
"openid",
"eduperson"
]
},
"id_token_signed_response_alg": {
"one_of": [
"ES256",
"ES384"
],
"default": "ES256"
},
"contacts": {
"add": "helpdesk@org.example.org"
}
}
The combined metadata policy then becomes:
{
"scopes": {
"subset_of": [
"openid",
"eduperson"
],
"superset_of": [
"openid"
],
"default": [
"openid",
"eduperson"
]
},
"id_token_signed_response_alg": {
"one_of": [
"ES256",
"ES384"
],
"default": "ES256"
},
"contacts": {
"add": [
"helpdesk@federation.example.org",
"helpdesk@org.example.org"
]
},
"application_type": {
"value": "web"
}
}
If applying policies to a metadata statement results in incorrect metadata, then such a metadata statement MUST be regarded as broken and MUST NOT be used.
There might be parties that want to extend the policy language defined here. If that happens then the rule is that if software compliant with this specification encounters a keyword it does not understand, it MUST ignore it unless it is listed in a policy_language_crit list, as is done for JWS header parameters with the crit parameter. If the policy language extension keyword is listed in the policy_language_crit list and not understood, then the metadata MUST be rejected.
The following is a non-normative example of a set of policies being applied to an RP's metadata.
The RP's metadata:
{
"contacts": [
"rp_admins@cs.example.com"
],
"redirect_uris": [
"https://cs.example.com/rp1"
],
"response_types": [
"code"
]
}
The federation's policy for RPs:
{
"scopes": {
"superset_of": [
"openid",
"eduperson"
],
"default": [
"openid",
"eduperson"
]
},
"response_types": {
"subset_of": [
"code",
"code id_token"
]
}
}
The organization's policy for RPs:
{
"contacts": {
"add": "helpdesk@example.com"
},
"logo_uri": {
"one_of": [
"https://example.com/logo_small.jpg",
"https://example.com/logo_big.jpg"
],
"default": "https://example.com/logo_small.jpg"
},
"policy_uri": {
"value": "https://example.com/policy.html"
},
"tos_uri": {
"value": "https://example.com/tos.html"
}
}
The metadata for the entity in question, after applying the policies above, would then become:
{
"contacts": [
"rp_admins@cs.example.com",
"helpdesk@example.com"
],
"logo_uri": "https://example.com/logo_small.jpg",
"policy_uri": "https://example.com/policy.html",
"tos_uri": "https://example.com/tos.html",
"scopes": [
"openid",
"eduperson"
],
"response_types": [
"code"
],
"redirect_uris": [
"https://cs.example.com/rp1"
]
}
A constraint specification can contain the following claims:
The following is a non-normative example of such a specification:
{
"naming_constraints": {
"permitted": [
"https://.example.com"
],
"excluded": [
"https://east.example.com"
]
},
"max_path_length": 2
}
If a subordinate entity statement contains a constraint specification that is more restrictive than the one in effect, then the more restrictive constraint is in effect from here on.
If a subordinate entity statement contains a constraint specification that is less restrictive than the one in effect, then it MUST be ignored.
The max_path_length constraint specifies the maximum number of entity statement a trust chain can have between the entity statement that contains the constraint specification and the leaf's entity statement.
A max_path_length constraint of zero indicates that no entity statement MAY appear between this entity statement and the leaf entity statement. Where it appears, the max_path_length constraint MUST have a value that is greater than or equal to zero. Where max_path_length does not appear, no limit is imposed.
Assuming that we have a trust chain with four entity statements:
Then the trust chain fulfills the constraints if:
The trust chain does not fulfill the constraints if:
The naming_constraints member specifies a namespace within which all subject entity identifiers in subordinate entity statements in a trust chain MUST be located.
Restrictions are defined in terms of permitted or excluded name subtrees. Any name matching a restriction in the excluded claim is invalid regardless of information appearing in the permitted claim.
The constraint MUST be specified as a fully qualified domain name and MAY specify a host or a domain. Examples would be "host.example.com" and ".example.com". When the constraint begins with a period, it MAY be expanded with one or more labels. That is, the constraint ".example.com" is satisfied by both host.example.com and my.host.example.com. However, the constraint ".example.com" is not satisfied by "example.com". When the constraint does not begin with a period, it specifies a host.
In this specification we use the US NSTIC definition: "A trustmark is used to indicate that a product or service provider has met the requirements of the Identity Ecosystem, as determined by an accreditation authority".
Technically, trust marks as used by this specification are signed JWTs that represent a statement of conformance to a well-scoped set of trust and/or interoperability requirements.
The trust marks are signed by a federation accredited authority. The validation of such a signed statement is performed in the same way that a self-signed entity statement is validated.
Note that a federation MAY allow an entity to self-sign some trust marks.
These are the properties that can occur in a trust mark:
Other claims MAY be used in conjunction with the claims outlined above. The claim naming recommendations outlined in Section 5.1.2 of OpenID Connect Core 1.0 apply.
An entity SHOULD NOT try to validate a trust mark until it knows which trust anchors it wants to use.
Validating a trust mark follows the procedure set out in Section 8.
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 federation entities. A trust anchor uses the trust_marks_issuers claim in its entity statement to publish this information.
For other externally issued trust marks, it is an out-of-band process to define and announce accreditation authorities to other entities and it is left to the discretion of the receiving party to assign an appropriate level of trust to such trust marks.
An example of a self-signed certification mark:
{
"iss": "https://example.com/op",
"sub": "https://example.com/op",
"iat": 1579621160,
"id": "https://openid.net/certification/op",
"mark": "http://openid.net/wordpress-content/uploads/2016/
05/oid-l-certification-mark-l-cmyk-150dpi-90mm.jpg",
"ref": "https://openid.net/wordpress-content/uploads/2015/
09/RolandHedberg-pyoidc-0.7.7-Basic-26-Sept-2015.zip"
}
An example of a third-party accreditation authority:
{
"iss": "https://swamid.sunet.se",
"sub": "https://umu.se/op",
"iat": 1577833200,
"exp": 1609369200,
"id":
"https://refeds.org/wp-content/uploads/2016/01/Sirtfi-1.0.pdf"
}
The configuration endpoint is found using the Well-Known URIs specification, with the suffix openid-federation. The scheme, host, and port are taken directly from the entity identifier combined with the following path: /.well-known/openid-federation.
If the entity identifier contains a path, it is concatenated after /.well-known/openid-federation in the same manner that path components are concatenated to the well-known identifier in the OAuth 2.0 Authorization Server Metadata [RFC8414] specification. Of course, in real multi-tenant deployments, in which the entity identifier might be of the form https://multi-tenant-service.example.com/my-tenant-identifier the tenant is very likely to not have control over the path https://multi-tenant-service.example.com/.well-known/openid-federation/my-tenant-identifier whereas it is very likely to have control over the path https://multi-tenant-service.example.com/my-tenant-identifier/.well-known/openid-federation. Therefore, if using the configuration endpoint at the URL with the tenant path after the well-known part fails, it is RECOMMENDED that callers retry at the URL with the tenant path before the well-known part (even though this violates [RFC8615]).
Federation Entities SHOULD make an Entity Configuration Document available at the configuration endpoint. There is only one exception to this rule and that is for an RP that only does explicit registration. Since it posts the self-signed entity statement to the OP during client registration, the OP has everything it needs from the RP.
A federation Entity Configuration Document MUST be queried using an HTTP GET request at the previously specified path. The requesting party would make the following request to the Entity https://example.com to obtain its Configuration information:
GET /.well-known/openid-federation HTTP/1.1 Host: example.com
The response is a self-signed Entity Statement, as described in Section 3.1. If the entity is an intermediate entity or a trust anchor, the response MUST contain metadata for a federation entity.
A positive response is a signed entity statement, where the content type MUST be set to application/jose. In case of an error, the response will be a JSON object, the content type MUST be set to application/json, and the error response uses the applicable HTTP status code value.
The following is a non-normative example response from an intermediate entity, before serialization and adding a signature:
200 OK
Last-Modified: Thu, 29 Aug 2019 08:54:26 GMT
Content-Type: application/jose
{
"iss": "https://example.com",
"sub": "https://example.com",
"iat": 1516239022,
"exp": 1516298022,
"metadata": {
"federation_entity": {
"federation_api_endpoint":
"https://example.com/federation_api_endpoint",
"name": "The example cooperation",
"homepage_uri": "https://www.example.com"
}
},
"authority_hints": ["https://federation.example.com"],
"jwks": {
"keys": [
{
"alg": "RS256",
"e": "AQAB",
"key_ops": [
"verify"
],
"kid": "key1",
"kty": "RSA",
"n": "pnXBOusEANuug6ewezb9J_...",
"use": "sig"
}
]
}
}
All entities that are expected to publish entity statements about other entities MUST expose a Federation API endpoint.
The federation API endpoint of an entity can be found in the configuration response as described in Section 6 or by other means.
The Federation API is an HTTPS API that MAY support multiple operations. Fetching entity statements is one of the operations, and the only one that all Federation API endpoints are REQUIRED to support. All the other operations are OPTIONAL. The list of defined operations MAY be extended in the future.
While all operations on the federation API endpoint make use of a GET request, other operations MAY choose to use other HTTP methods. If the operation parameter is left out, it is treated as a fetch entity statements request. Unless otherwise mentioned or agreed upon, requests to the federation API do not need to be authenticated.
Fetching entity statements is performed to collect entity statements one by one to gather trust chains.
To fetch an entity statement, an entity needs to know the identifier of the entity to ask (the issuer), the federation API endpoint of that entity and the identifier of the entity that you want the statement to be about (the subject).
The request MUST be an HTTP request using the GET method and the https scheme to a resolved federation API endpoint with the following query string parameters:
The following is a non-normative example of an API request for an entity statement:
GET /federation_api_endpoint? iss=https%3A%2F%2Fopenid.sunet.se%2Ffederation HTTP/1.1 Host: openid.sunet.se
A positive response is a signed entity statement where the content type MUST be set to application/jose. If it is a negative response, it will be a JSON object and the content type MUST be set to application/json. See more about error responses in Section 7.4.
The following is a non-normative example of a response, before serialization and adding a signature:
200 OK
Last-Modified: Mon, 17 Dec 2018 11:15:56 GMT
Content-Type: application/jose
{
"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"
],
"jwks_uri": "https://openid.sunet.se/rp/jwks.json"
}
},
"jwks": {
"keys": [
{
"alg": "RS256",
"e": "AQAB",
"key_ops": [
"verify"
],
"kid": "key1",
"kty": "RSA",
"n": "pnXBOusEANuug6ewezb9J_...",
"use": "sig"
}
]
},
"authority_hints": [
"https://edugain.org/federation"
]
}
An entity MAY use the trust negotiation operation to fetch resolved metadata about itself as seen/trusted by a remote peer. The result may, for instance, tell an RP what operations, scopes and claims an OP would allow the RP to use if a specific trust anchor was used.
The request MUST be an HTTP request using the GET method and the https scheme to a resolved federation API endpoint with the following query string parameters:
The following is a non-normative example of an API request for trust negotiation:
GET /federation_api_endpoint? operation=resolve_metadata& respondent=https%3A%2F%2Fopenid.sunet.se%2Ffederation& type=openid_provider& anchor=https%3A%2F%2Fswamid.se& peer=https%3A%2F%2Fidp.umu.se%2Fopenid HTTP/1.1 Host: openid.sunet.se
The response is a metadata statement that is the result of applying the metadata policies in the trust chain on the entity's metadata.
The following is a non-normative example of a response:
200 OK
Last-Modified: Wed, 22 Jul 2018 19:15:56 GMT
Content-Type: application/json
{
"organization_name": "University of Umea",
"contacts": [
"legal@umu.se",
"technical@umu.se"
],
"logo_uri":
"https://www.umu.se/SRWStatic/img/umu-logo-left-neg-SE.svg",
"op_policy_uri":
"https://www.umu.se/en/about-the-website/legal-information/",
"authorization_endpoint":
"https://idp.umu.se/openid/authorization",
"token_endpoint": "https://idp.umu.se/openid/token",
"response_types_supported": [
"code",
"code id_token",
"token"
],
"grant_types_supported": [
"authorization_code",
"implicit",
"urn:ietf:params:oauth:grant-type:jwt-bearer"
],
"subject_types_supported": [
"pairwise"
],
"id_token_signing_alg_values_supported": [
"RS256"
],
"issuer": "https://idp.umu.se/openid",
"jwks_uri": "https://idp.umu.se/openid/jwks_uri.json"
}
An entity MAY query another entity for a list of all the entities immediately subordinate to that entity and about which that entity is prepared to issue statements about. (In some cases, this MAY be a very large list.)
The request MUST be an HTTP request using the GET method and the https scheme to a resolved federation API endpoint with the following query string parameters:
The following is a non-normative example of an API request for trust negotiation:
GET /federation_api_endpoint? operation=listing& iss=https%3A%2F%2Fopenid.sunet.se%2Ffederation HTTP/1.1 Host: openid.sunet.se
The response MUST contain an JSON list with the known entity identifiers.
The following is a non-normative example of a response:
200 OK Last-Modified: Wed, 22 Jul 2018 19:15:56 GMT Content-Type: application/json [ "https://ntnu.andreas.labs.uninett.no/", "https://blackboard.ntnu.no/openid/callback", "https://serviceprovider.andreas.labs.uninett.no/application17" ]
If the request was malformed, or some error occurred during processing of the request, the following standardized error format SHOULD be used regardless of the operation specified.
The HTTP response code MUST be something in 400/500-range, giving an indication of the type of error. The response body MUST be a JSON object containing the claims below and the content type MUST be set to application/json.
The following is a non-normative example of an error response:
400 Bad request
Last-Modified: Wed, 22 Jul 2018 19:15:56 GMT
Content-Type: application/json
{
"operation": "fetch",
"error": "invalid_request",
"error_description":
"Required request parameter [iss] was missing."
}
An entity (e.g., the Consumer) that wants to establish trust with a remote peer, MUST have the remote peer's entity identifier and a list of entity identifiers of trust anchors together with the public version of their signing keys. The Consumer will first have to fetch sufficient entity statements to establish at least one chain of trust from the remote peer to one or more of the configured trust anchors. After that the entity MUST validate the trust chains independently, and -- if there are multiple valid trust chains and if the application demands it -- choose one.
Depending on the circumstances, the Consumer MAY either be handed the remote peer's self-issued entity statement, or it may have to fetch it by itself. If it needs to fetch it, it will use the process described in Section 7.1.1 with both iss and sub containing the entity identifier of the remote peer.
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 statement about the remote peer from each of the intermediates. If the received entity statement contains an authority hint this process is repeated. This time with the iss set to the intermediate's entity identifier and the sub to be the iss of the previous query. The Consumer SHOULD NOT attempt to fetch entity statements it already has fetched during this process (loop prevention).
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 the remote peer to at least one of the trusted trust anchors, then the list will be empty and there is no way of establishing trust in the remote peer's information. How the Consumer deals with this is out of scope for this specification.
As described in Section 3.2, a trust chain consists of an ordered list of entity statements. So whichever way the Consumer 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.
To validate the chain, the following MUST be done:
Verifying the signature is a much more expensive operation then verifying the correctness of the statement and the timestamps. An implementer MAY therefor chose to not verify the signature until all the other checks have been done.
Consumers MAY cache Entity Statements or signature verification results for a given time until they expire Section 8.4.
Note that the second bullet point means that, at each step in the trust chain resolution, it MUST be verified that the signing JWK is also present in the jwks statement claim issued by the superior.
If multiple valid trust chains are found, the Consumer will need to decide on which one to use.
One simple rule would be to prefer a shorter chain over a longer one.
Consumers MAY follow other rules according to local policy.
Each entity statement in a trust chain is signed and MUST have an expiration time (exp) set. The expiration time of the whole trust chain is set to the minimum value of exp within the chain.
This specification allows for a smooth process of updating metadata and public keys.
As described above in Section 8.4, each trust chain has an expiration time. A consumer of metadata using this specification MUST support refreshing a trust chain when it expires. How often a consumer SHOULD re-evaluate the trust chain depends on how quickly the consumer wants to find out that something has changed in the trust chain.
If a leaf entity publishes its public keys in the metadata part using jwks, setting an expiration time on the self-signed entity statement can be used to control how often the receiving entity is fetching an updated version of the public key.
A trust anchor MUST publish a self-signed entity statement about itself. The trust anchor SHOULD set a reasonable expiration time on that statement, such that the consumers will re-fetch the entity statement at reasonable intervals. If the trust anchor wants to roll over its signing keys it would have to:
It MUST be taken into consideration that clients MAY have manually configured public keys as part of their configuration.
Since the consumers are expected to check the trust chain at regular, reasonably frequent times, this specification does not specify a standard revocation process. Specific federations MAY make a different choice and will then have to add such a process.
This section describes how the trust framework in this specification is used to establish trust between an RP and an OP that have no explicit configuration or registration in advance.
There are two alternative approaches to establish trust between an RP and an OP, which we call automatic 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 disable the use of one of them.
Independent of whether the RP uses automatic or explicit registration, the way that the RP learns about the OP is the same. It will use the procedure that is described in Section 8.
Automatic registration allows an RP to send Authorization Requests to an OP without first registering with the OP. It basically works by the OP using the Client ID in the request to find the RP's metadata using the process outlined in Section 8 and then verifies that the RP is in control of a private key that is a companion to one of the public keys the RP published through its metadata.
For automatic registration to work a number of things MUST be valid:
The Authentication Request is performed by passing a Request Object by value as described in Section 6.1 in OpenID Connect Core 1.0 or using pushed authorization as described in Pushed Authorization Requests.
In the case where a Request Object is used, 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. The JWT MUST be signed and MAY be encrypted. The following restrictions apply to the JWT:
The following is a non-normative example of the Claims in a Request Object before base64url encoding and signing:
{
"aud": "https://op.example.org/authorization",
"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",
"sub": "https://rp.example.com"
}
The following is a non-normative example of an Authorization Request using the request parameter (with line wraps within values for display purposes only):
https://server.example.com/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=eyJhbGciOiJSUzI1NiIsImtpZCI6ImRVTjJhMDF3Umtoa1
NXcGxRVGh2Y1ZCSU5VSXdUVWRPVUZVMlRtVnJTbWhFUVhnelpYbHB
UemRRTkEifQ.eyJzdWIiOiAiaHR0cHM6Ly9ycC5leGFtcGxlLmNvb
SIsICJpc3MiOiAiaHR0cHM6Ly9ycC5leGFtcGxlLmNvbSIsICJpYX
QiOiAxNTkzNjE1Nzk0LCAiZXhwIjogMTU5MzYxNTg1NCwgImF1ZCI
6ICJodHRwczovL29wLmV4YW1wbGUub3JnL2F1dGhvcml6YXRpb24i
LCAianRpIjogIjlhNDY2Njc3ZDZkOTQ5OWZiOTFjNDg4YTY1NzA0N
TU2In0.mFq0V4KIb6eM-WV5vvQAvSSwoUyi-cy_ASMDgR1-amotjK
6El0T1WV9-Hdrkgi_zBJtARs6VE380GmwpXXuMF1p6y-IoyIBJUSR
w9LaeK9oi3d1stTT_J6VL8JwsNuetB6r9YLAQS-1p6mFKsv7TQSjk
xNHfw0BTxfZftcDnooCqusC17xrz11qEY1CCtjDbbxYM1cYfzGFwS
I0UZneQUZqa2ChOqWTguumG7XonB5NFZWieAtvyyPZaSI7AW5wCs2
sH6kjMxOHEAIvxygZZwKpTiToccYtU7t0n2xKRr-oYDQaFjuRIemE
xsuzVl6pbvCVYqyjxFscS9NgDB-hAAQ
When the OP receives an incoming Authentication Request, the OP supports OpenID Connect 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 try to resolve and fetch trust chains starting with the RP's entity statement as described in Section 8.1.
The OP MUST then validate the possible trust chains, as described in Section 8.2, and resolve the RP metadata with type openid_relying_party.
The OP SHOULD furthermore consider the resolved metadata of the RP, and verify that it complies with the client metadata specification in OpenID Connect Dynamic Client Registration 1.0.
Once the OP has the RP's metadata, it can verify that the client was actually the one sending the Authorization Request by verifying the signature of the Request Object using the key material the client published through its metadata.
Pushed Authorization provides an interoperable way to push the payload of a Request Object directly to the AS in exchange for a request_uri.
When it comes to request authentication, the applicable methods are three:
Note that if mTLS is used, TLS client authentication MUST be configured and, in case of self-signed certificates, the server must omit trust chain validation (optional_no_ca).
Using the example above, a request 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.eyJzdWIiOiAiaHR0cHM6Ly9ycC 5leGFtcGxlLmNvbSIsICJpc3MiOiAiaHR0cHM6Ly9ycC5leGFtc GxlLmNvbSIsICJpYXQiOiAxNTg5NzA0NzAxLCAiZXhwIjogMTU4 OTcwNDc2MSwgImF1ZCI6ICJodHRwczovL29wLmV4YW1wbGUub3J nL2F1dGhvcml6YXRpb24iLCAianRpIjogIjM5ZDVhZTU1MmQ5Yz Q4ZjBiOTEyZGM1NTY4ZWQ1MGQ2In0.oUt9Knx_lxb4V2S0tyNFH CNZeP7sImBy5XDsFxv1cUpGkAojNXSy2dnU5HEzscMgNW4wguz6 KDkC01aq5OfN04SuVItS66bsx0h4Gs7grKAp_51bClzreBVzU4g _-dFTgF15T9VLIgM_juFNPA_g4Lx7Eb5r37rWTUrzXdmfxeou0X FC2p9BIqItU3m9gmH0ojdBCUX5Up0iDsys6_npYomqitAcvaBRD PiuUBa5Iar9HVR-H7FMAr7aq7s-dH5gx2CHIfM3-qlc2-_Apsy0 BrQl6VePR6j-3q6JCWvNw7l4_F2UpHeanHb31fLKQbK-1yoXDNz DwA7B0ZqmuSmMFQ
There are three different paths the OP MUST follow when processing the Authentication Request depending on which request authentication method that was used. It all starts the same though. When the OP receives an incoming Authentication Request, the OP supports OpenID Connect Federation, the incoming Client ID is a valid URL, the OP does not have the Client ID registered as a known client and the OP supports the request authentication method used then the OP SHOULD try to resolve and fetch trust chains starting with the RP's entity statement as described in Section 8.1.
The OP SHOULD validate the possible trust chains, as described in Section 8.2, and resolve the RP metadata with type openid_relying_party.
The OP SHOULD consider the resolved metadata of the RP, and verify that it complies with the client metadata specification in OpenID Connect Dynamic Client Registration 1.0.
Once the OP has the RP's metadata, it can verify the client. This is where it diverges depending on which client authentication method was used.
If the OP fails to establish trust with the RP, it SHOULD use an appropriate error code, and an error_description that aids the RP to understand what is wrong.
In addition to the error codes defined in Section 3.1.2.6 of OpenID Connect Core, this specification also defines the following error codes:
The following is a non-normative example error response:
HTTP/1.1 302 Found
Location: https://client.example.org/cb?
error=missing_trust_anchor
&error_description=
Could%20not%20find%20a%20trusted%20anchor
&state=af0ifjsldkj
This method involves performing an explicit registration of a new client the first time an RP interacts with an OP using something that basically follows the steps in OpenID Connect Dynamic Client Registration 1.0 but where the client registration request is a signed entity statement.
The OP MUST support OpenID Dynamic Client Registration as extended by this specification. This is signaled by having the claim federation_registration_endpoint in the OP's metadata.
Given that the OP supports explicit registration, the RP progresses as follows:
The trust chains MUST be constructed using the received entity statement.
A client registration using this specification is not expected to be valid forever. The entity statements exchanged all have expiration times, which means that the registration will eventually time out. An OP can also, for administrative reasons, decide that a client registration is not valid anymore. An example of this could be that the OP leaves the federation in use.
At regular intervals, the RP MUST:
What is regarded as reasonable intervals will depend on federation policies and risk assessment by the maintainer of the RP.
At regular intervals, the OP MUST:
An OP MUST NOT assign an expiration time to an RP's registration that is later than the trust chain's expiration time.
TBD Register federation_types_supported for OP metadata with initial values automatic and explicit.
TBD Register federation_type for RP registration metadata.
TBD Register federation_registration_endpoint for the OP metadata.
Some of the interfaces defined in this specification could be used for Denial of Service attacks (DOS), most notably, Entity Listings (Section 7.3) and automatic client registration (Section 10.1). If you plan to provide these interfaces as a service, you should consider applying normal defense methods, such as those described in [RFC4732].
| [RFC8446] | Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018. |
Let us assume the following: The project LIGO would like to offer access to its wiki to all OPs in EduGAIN. LIGO is registered to the InCommon federation.
The players
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 both are 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 at 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 couple of things about the OP. All if 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 you have to go through to set up your own federation. What you minimally have to do is:
Once you have this, you can start adding entities to your federation. Adding an entity comes down to:
Now before the federation operator starts adding entities, there have to be policies in place on who can be part of the federation and the layout of the federation. Is it supposed to be a one-layer federation like Internet2, a two-layer one like the SWAMID federation, or a multi-layer federation? The federation may also want to think about implementing other policies using the federation policy framework, as described in Section 5.
With the federation in place, things can start happening.
Metadata discovery is a sequence of steps that starts with the RP fetching the self-signed entity statement of the leaf (in this case https://op.umu.se) using the process defined in Section 6. What follows thereafter is this sequence of steps:
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 entity statements issued by a superior about its subordinate are used together with the self-signed entity statement issued by the leaf.
The self-signed entity statement concerning intermediates are not part of the trust chain.
The LIGO WIKI RP fetches the self-signed entity statement from the OP (op.umu.se) using the process defined in Section 6.
The result is this entity statement.
{
"authority_hints": [
"https://umu.se"
],
"exp": 1568397247,
"iat": 1568310847,
"iss": "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",
"jwks_uri": "https://op.umu.se/openid/jwks_uri.json",
"authorization_endpoint":
"https://op.umu.se/openid/authorization",
"client_registration_type": [
"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/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"
]
}
},
"sub": "https://op.umu.se"
}
The authority_hints points to the intermediate https://umu.se. So that is the next step.
This entity statement is the first link in the trust chain.
The LIGO RP fetches the self-signed entity statement from "https://umu.se" using the process defined in Section 6.
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",
"jwks": {
"keys": [
{
"e": "AQAB",
"kid": "endwNUZrNTJsX2NyQlp4bjhVcTFTTVltR2gxV2RV...",
"kty": "RSA",
"n": "vXdXzZwQo0hxRSmZEcDIsnpg-CMEkor50SOG-1XUlM..."
}
]
},
"metadata": {
"federation_entity": {
"contacts": "ops@umu.se",
"federation_api_endpoint": "https://umu.se/oidc/fedapi",
"homepage_uri": "https://www.umu.se",
"name": "UmU"
}
},
"sub": "https://umu.se"
}
The only piece of information that is used from this entity statement is the federation_api_endpoint, which is used in the next step.
The RP uses the federation API and the "fetch" command as defined in Section 7.1.1 to fetch information about "https://op.umu.se" from the API endpoint published in https://umu.se's configuration.
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:
{
"authority_hints": [
"https://swamid.se"
],
"exp": 1568397247,
"iat": 1568310847,
"iss": "https://umu.se",
"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\u00e5"
},
"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"
]
}
}
},
"sub": "https://op.umu.se"
}
This is the second link in the trust chain.
Notable here is that this path leads to two trust anchors using the same next step ("https://swamid.se").
The LIGO Wiki RP fetches the self-signed entity statement from "https://swamid.se" using the process defined in Section 6.
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",
"jwks": {
"keys": [
{
"e": "AQAB",
"kid": "N1pQTzFxUXZ1RXVsUkVuMG5uMnVDSURGRVdhUzdO...",
"kty": "RSA",
"n": "3EQc6cR_GSBq9km9-WCHY_lWJZWkcn0M05TGtH6D9S..."
}
]
},
"metadata": {
"federation_entity": {
"contacts": "ops@swamid.se",
"federation_api_endpoint":
"https://swamid.sunet.se/fedapi",
"homepage_uri": "https://www.sunet.se/swamid/",
"name": "SWAMID"
}
},
"sub": "https://swamid.se"
}
The only piece of information that is used from this entity statement is the federation_api_endpoint, which is used in the next step.
The LIGO Wiki RP uses the federation API and the "fetch" command as defined in Section 7.1.1 to fetch information about "https://umu.se" from the API endpoint published in https://swamid.se's configuration.
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:
{
"authority_hints": [
"https://edugain.geant.org"
],
"exp": 1568397247,
"iat": 1568310847,
"iss": "https://swamid.se",
"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"
]
}
}
},
"sub": "https://umu.se"
}
This is the third link in the trust chain.
If we assume that the issuer of this entity statement is not in the list of trust anchors the LIGO Wiki RP has access to we have to go one step further.
RP fetches the self-signed entity statement from "https://edugain.geant.org" using the process defined in Section 6.
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",
"jwks": {
"keys": [
{
"e": "AQAB",
"kid": "Sl9DcjFxR3hrRGdabUNIR21KT3dvdWMyc2VUM2Fr...",
"kty": "RSA",
"n": "xKlwocDXUw-mrvDSO4oRrTRrVuTwotoBFpozvlq-1q..."
}
]
},
"metadata": {
"federation_entity": {
"federation_api_endpoint": "https://geant.org/edugain/api"
}
},
"sub": "https://edugain.geant.org"
}
Again, the only thing we need is the federation_api_endpoint. As described in Section 9.2, note SHOULD also be taken to jwks as the trust anchor MAY be performing a key rollover.
The LIGO Wiki RP uses the federation API and the "fetch" command as defined in Section 7.1.1 to fetch information about "https://swamid.se" from the API endpoint published in https://edugain.geant.org's configuration.
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",
"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"
}
}
},
"sub": "https://swamid.se"
}
If we assume that the issuer of this statement appears in the list of trust anchors the LIGO Wiki RP has access to this would be the fourth and final entity statement in the trust chain.
We now have the whole chain from the self-signed entity statement of the leaf up until the last one that is issued by a trust anchor. All in all, we have:
We also have the self-signed entity statements from https://umu.se, https://swamid.se and https://edugain.geant.org about themselves but those are not used in the trust chain verification.
Using the public keys of the trust anchor that the LIGO Wiki RP has been provided with in some secure out-of-band way, it can now verify the trust chain as described in Section 8.2.
Having verified the chain, the LIGO Wiki RP can proceed with the next step.
Combining the metadata policies from the tree entity statements we have by a superior about its subordinate and applying the combined policy to the metadata statement that the leaf entity presented, we get:
{
"authorization_endpoint":
"https://op.umu.se/openid/authorization",
"claims_parameter_supported": false,
"contacts": [
"ops@swamid.se"
],
"federation_registration_endpoint":
"https://op.umu.se/openid/fedreg",
"client_registration_type": [
"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",
"jwks_uri": "https://op.umu.se/openid/jwks_uri.json",
"logo_uri":
"https://www.umu.se/img/umu-logo-left-neg-SE.svg",
"organization_name": "University of Ume\u00e5",
"op_policy_uri":
"https://www.umu.se/en/website/legal-information/",
"request_parameter_supported": false,
"request_uri_parameter_supported": true,
"require_request_uri_registration": 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"
],
"version": "3.0"
}
We have now reached the end of the Provider Discovery process.
As described in Section 10, there are two ways which can be used to do client registration:
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 /authorize?
request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImRVTjJhMDF3Umtoa1NXc
GxRVGh2Y1ZCSU5VSXdUVWRPVUZVMlRtVnJTbWhFUVhnelpYbHBUemRR
TkEifQ.eyJyZXNwb25zZV90eXBlIjogImNvZGUiLCAic2NvcGUiOiAi
b3BlbmlkIHByb2ZpbGUgZW1haWwiLCAiY2xpZW50X2lkIjogImh0dHB
zOi8vd2lraS5saWdvLm9yZyIsICJzdGF0ZSI6ICIyZmY3ZTU4OS0zOD
Q4LTQ2ZGEtYTNkMi05NDllMTIzNWU2NzEiLCAibm9uY2UiOiAiZjU4M
WExODYtYWNhNC00NmIzLTk0ZmMtODA0ODQwODNlYjJjIiwgInJlZGly
ZWN0X3VyaSI6ICJodHRwczovL3dpa2kubGlnby5vcmcvb3BlbmlkL2N
hbGxiYWNrIiwgImlzcyI6ICIiLCAiaWF0IjogMTU5MzU4ODA4NSwgIm
F1ZCI6ICJodHRwczovL29wLnVtdS5zZSJ9.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 self-issued entity statement using the process described in Section 6.
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 with in some secure out-of-band way, it can now verify the trust chain as described in Section 8.2.
"metadata_policy": {
"openid_provider": {
"contacts": {
"add": "ops@edugain.geant.org"
}
},
"openid_relying_party": {
"contacts": {
"add": "ops@edugain.geant.org"
}
}
}
We will not list the complete entity statements but only the metadata and metadata_policy parts. There are two metadata policies:
"metadata_policy": {
"openid_relying_party": {
"application_type": {
"one_of": [
"web",
"native"
]
},
"contacts": {
"add": "ops@incommon.org"
},
"grant_types": {
"subset_of": [
"authorization_code",
"refresh_token"
]
}
}
}
If you combine these and apply them to the metadata for wiki.ligo.org :
"metadata": {
"application_type": "web",
"client_name": "LIGO Wiki",
"contacts": [
"ops@ligo.org"
],
"grant_types": [
"authorization_code",
"refresh_token"
],
"id_token_signing_alg_values_supported": [
"RS256",
"RS512"
],
"jwks_uri": "https://wiki.ligo.org/jwks.json",
"redirect_uris": [
"https://wiki.ligo.org/callback"
],
"response_types": [
"code"
],
"subject_type": "public"
}
You will get
{
"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_signing_alg_values_supported": [
"RS256",
"RS512"
],
"jwks_uri": "https://wiki.ligo.org/jwks.json",
"redirect_uris": [
"https://wiki.ligo.org/callback"
],
"response_types": [
"code"
],
"subject_type": "public"
}
Having that, the registration is done, and the OP MUST now use the keys found at the URL specified in jwks_uri to verify the signature on the Request Object in the Authentication Request.
Here the LIGO Wiki RP sends a client registration request to the federation_registration_endpoint of the OP (op.umu.se). What it sends is a self-signed entity statement.
Once the OP has the entity statement, it proceeds with the same sequence of steps as laid out in Appendix A.2.
The OP will end up with the same RP metadata as was described in Appendix A.3.1.2, but what it now can do is return a metadata policy that it wants to be applied to the RP's metadata. This metadata policy will be combined with the trust chain's combined metadata policy before being applied to the RP's metadata.
If we assume that the OP does not support refresh tokens, it MAY want to add a metadata policy that says:
"metadata_policy": {
"openid_relying_party": {
"grant_types": {
"subset_of": [
"authorization_code"
]
}
}
}
Thus, the entity statement returned by the OP to the RP MAY look like this:
{
"trust_anchor_id": "https://edugain.geant.org",
"metadata_policy": {
"openid_relying_party": {
"application_type": {
"one_of": [
"web",
"native"
]
},
"contacts": {
"add": [
"ops@incommon.org",
"ops@edugain.geant.org"
]
},
"grant_types": {
"subset_of": [
"authorization_code",
"refresh_token"
]
}
"registration_access_token": {
"value": "nLe19cJ5e9SXXiPqnRRuxpjyWI73bDhD"
},
"client_id": {
"value": "m3GyHw"
},
"client_secret_expires_at": {
"value": 1604049619
},
"registration_client_uri": {
"value":
"https://op.umu.se/openid/registration?client_id=m3GyHw"
},
"client_secret": {
"value":
"cb44eed577f3b5edf3e08362d47a0dc44630b3dc6ea99f7a79205"
},
"client_id_issued_at": {
"value": 1601457619
}
}
},
"authority_hints": [
"https://incommon.org"
],
"aud": "https://wiki.ligo.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"
}
]
},
"iss": "https://op.umu.se",
"iat": 1601457619,
"exp": 1601544019
}
And the resulting metadata used by the RP could look like:
{
"application_type": "web",
"client_name": "LIGO Wiki",
"contacts": [
"ops@edugain.geant.org",
"ops@incommon.org",
"ops@ligo.org"
],
"grant_types": [
"authorization_code"
],
"id_token_signing_alg_values_supported": [
"RS256",
"RS512"
],
"jwks_uri": "https://wiki.ligo.org/jwks.json",
"redirect_uris": [
"https://wiki.ligo.org/callback"
],
"response_types": [
"code"
],
"subject_type": "public"
}
Copyright (c) 2021 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.
The authors wish to acknowledge the contributions of the following individuals and organizations to this specification: Vladimir Dzhuvinov, Heather Flanagan, Jouke Roorda, Mischa Sallé, Marcos Sanz, Peter Schober, Michael Schwartz, and the JRA3T3 task force of GEANT4-2.
The following open issues remain to be addressed in this specification.
[[ To be removed from the final specification ]]
-17
-16
-15
-14
-13
-12
-11
-10
-09
-08
-07
-06
-05
-04