independent

roland@catalogix.se

Uninett AS

andreas.solberg@uninett.no https://www.linkedin.com/in/andreassolberg/

Schibsted Media Group

samuel.gulliksson@gmail.com

Microsoft

mbj@microsoft.com http://self-issued.info/

Ping Identity

ve7jtb@ve7jtb.com http://www.thread-safe.com/

OpenID Connect Working Group OIDC The OpenID Connect standard specifies how a Relying Party (RP) can discover metadata about an OpenID Provider (OP), and then register to obtain relying party credentials. The discovery and registration process does not involve any mechanisms of dynamically establishing trust in the exchanged information, but instead rely on-out-of band trust establishment. In an identity federation context, this is not sufficient. The participants of the federation must be able to trust information provided about other participants in the federation. OpenID Connect Federations specifies how trust can be dynamically obtained from resolving trust from a common trusted third party. While this specification is primarily targeting OpenID Connect, it is designed in order to allow for re-use by other protocols and in other use cases.

This specification describes how two entities that would like to interact can dynamically fetch and and resolve trust and metadata for a given protocol, by the use of third party trust issuers. An identity federation can be realized using this specification by the use of one or more levels of trust issuers. A trust issuer is an entity, which main purpose is to issue trust statements about entities, such as OpenID relying party and providers. This specification does not mandates 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. An entity will typically configure a local trust root to include the identifier and the certificate of a trusted third party – the federation. All entities involved in OpenID Connect Federation, including the trust issuers, will have their own unique identifier. This identifier is used to dynamically fetch entity statements. As a complete chain of entity statements is obtained, connecting the local trust root to the target entity, the entity may resolve the resulting trusted metadata, by flattening the metadata found in the trust chain. Note that a real-world entity like an organisation, a company may be represented by more than one entity in a federation. The OpenID Connect Federation trust chains are relying on cryptographically signed JWT documents, and the trust chain does not at all rely on TLS in order to establish trust. OpenID Connect Federation may very well be used for other purposes than building traditional identity federations. One of them could be to build an OpenID Connect deployment where the key rollover process does not fall back to TLS. Another could be allowing traditionally public/native clients, such as medical devices, to generate its own key pair, and use asymmetric crypto to increase the overall security.

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.

An entity statement is always a signed JWT. An entity statement is issued by the iss, and the statement considers the subject entity, the sub. To be able to resolve trust and metadata, one need to know the identifier of the target entity – we refer to this as the leaf entity. The leaf entity will always sign a statement about itself, and give some hints to other entities that may want to issue statements about itself. All other entities in a trust chain we refer to as intermediate entities. The local configured trust root, we refer to as the trust anchor. REQUIRED. The entity identifier of the entity that issues the statement. If the iss and the sub are identical, the issuer is making a statement about itself. REQUIRED. The entity identifier of the subject REQUIRED. The time the statement was issued. REQUIRED. The time the signed statement expires. REQUIRED. A JSON Web Key Set (JWKS) representing the public part of the subject entity's signing keys.These keys are used to verify the identity of the subject. A corresponding private key is used by the leaf entity to sign an entity statement about itself, and intermediate entities to sign statements about other entities. The keys that can be found here are primarily intended to sign entity statements, and can not be used in other protocols, unless the metadata type specification explicitly states how the keys can be used. In OpenID Connect, the jwks keys cannot be used within the Authorization/AccessToken/RefreshToken/UserInfo requests and responses. Instead OpenID Connect specific metadata includes claims for this purpose. OPTIONAL. A JSON object where the keys are the entity id's of the intermediate entities that may issue an entity statement about the issuer entity. The value MUST be a JSON array of entities that is further up in the trust chain. The array may be an empty list. The JSON array can be used to simplify the selection of trust chains without the need for following all possible trust chains. REQUIRED. JSON object including protocol specific metadata claims that represent the leaf node. To resolve the resulting metadata for a leaf node, the compound metadata documents included in the trust chain are merged by the metadata flattening process. The keys of the JSON object represent the metadata type identifier, and their value MUST be a JSON object representing the metadata according to the metadata schema of that metadata type. To allow for the leaf node to resolve a specific metadata type, all intermediate entities in the trust chain MUST contain a metadata document for this specific type. See section about metadata. An entity statement may contain multiple metadata statements, but only one for each metadata type. OPTIONAL. Boolean value that indicates whether the subject is considered a leaf node. A leaf node is not trusted to issue statements about other entities then itself. If this property is left out, it is considered to be false. OPTIONAL. If present, an JSON object containing one or more of the properties listed below. This is metadata describing the subject of this entity statement. The metadata included in the metadata claim is always referring to the leaf nodes, while the metadata in sub_meta refers to the immediate subject, which may be an intermediate trust issuer. OPTIONAL. String. The human readable name describing the subject entity. This may be, for example, the name of an organization. OPTIONAL. JSON array with one or more strings. Contact persons at the entity. OPTIONAL. URL to documentation of conditions and policies relevant to this entity OPTIONAL. URL to a generic home page representing this entity. The entity statement is signed using the private key of the issuer entity, in the form of a JSON Web Signature (JWS).

Non-normative example of a entity statement, before serialization and adding a signature. (postamble)

In order to configure trust when deploying a software component, it is recommended to align that configuration with the semantics of an entity statement. How the configuration is stored and the exact format is out of the scope of this specification, but it is recommended to allow the user to configure a list of entries containing sub, jwks and metadata. When the compound metadata from the trust chain is resolved, metadata from the local trust root can be applied in the metadata flattening process. This allows the configuration of a provider to put trust limitations applied to all metadata resolved for the various trust roots. For example, a provider may trust a large federation with a metadata limitation of only releasing the name and userid, and no other scopes or claims. The provider may add other trust roots with a more limited target group to allow for more scopes and claims.

The OpenID Connect Federations specification does allow new metadata types to be defined, to support use cases outside OpenID Connect. The metadata type identifier will uniquely identify which metadata specification to interpret. The metadata document MUST be a JSON document. Beyond that there is no restriction. Metadata used in OpenID Connect Federations typically re-uses existing metadata standards. If needed, the metadata schema is extended with additional properties relevant in a federated context.

The metadata type identifier is openid_client. 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: RECOMMENDED. JSON array containing a list of the RFC6749 scope values that a relying party may ask for. RECOMMENDED. JSON array containing a list of the Claim Names of the Claims that a OpenID RP may ask for.

The metadata type identifier is an openid_provider. All parameters defined in section 3 of OpenID Connect Discovery 1.0 In addition the following properties are allowed: OPTIONAL. A human readable name representing the organization owning the OpenID Provider. It is intended to be used in the user interface, being recognized by the end users that would be using the provider to authenticate.

The metadata type identifier is openid_discovery.

The metadata type identifier is oauth_as.

The metadata type identifier is oauth_client.

The metadata type identifier is oauth_api.

Given the entity identifier, the endpoint of the federation API endpoint of the entity is easily derived. All entities that are expected to expose entity statements about themselves or other entities, MUST implement a Federation API. The federation API endpoint of an entity is resolved from the entity identifier. The Federation API endpoint is found using the Well known URIs specification, with the suffix openid-federation. The scheme, host and port is taken directly from the entity identifier combined with the following path: /.well-known/openid-federation. The Federation API is an HTTP API that may support multiple operations. Fetching entities is one of the operations, and the only one that all entities are REQUIRED to support. All the other operations is OPTIONAL. The op (operation) parameter may be used to define new operations in a future version of the specification or a local deployment which have agreed upon additional functionality. While all operations in the specification make use of a GET request, other operations may choose to use other HTTP methods. If the op parameter is left out, it is considered to be a fetch entity statements request. Unless otherwise mentioned or agreed upon, requests to the federation API does not need to be authenticated.

Fetching entity statement is used to collect entity statements and a valid trust chain in order to establish trust with a remote peer. In order to fetch an entity statement, an entity needs to know the identifier of the entity to ask, and the identifier of the entity that you want the statement to be about.

The request MUST be an HTTP request using the GET method to a resolved federation API endpoint with the following query string parameters: OPTIONAL. If not present MUST be treated as fetch. REQUIRED. The entity identifier of the issuer from which you want an entity statement issued. Because of the normalization of the URL, multiple issuers may resolve to a shared federation API. This parameter makes it explicit exactly which issuer we want entity statements from. OPTIONAL. The entity identifier of the subject for which you would like an entity statement issued. If this parameter is left out, it is considered to be the same as the issuer, and would indicate a request for a self issued statement. OPTIONAL. The entity identifier of the requester. The issuing entity may choose to include this parameter to form the entity statement specifically for this target, in which the aud claim also should be present in the entity statement it self. OPTIONAL. If left out, it is assumed to be false. If set to true, it indicates that the requester would like the API to prefetch entity statements that may be relevant for consumer to establish a trust chain, and may save the consumer from performing additional API requests.

The following is a non-normative example of an API request for entity statement: (postamble)

As long as the request is correct, understood and accepted, the response is a signed entity statements. The content type MUST be in that case be set to application/jose. If the issuing entity does not recognize the subject or the issuer, it should return an error response as a JSON object. More about error responses below

A non-normative example of a response: (the signed JWT is truncated)

An entity may use the trust negotiation operation in order to fetch a resolved metadata of it self as seen/trusted by a remote peer. The remote peer will fetch the metadata and necessary trust chain to the requester, and perform metadata flattening. The remote peer should include it own trust root configuration when generating the resulting metadata. The metadata returned should be the same as the one used in the software.

Resolving metadata for a specific type of metadata, for a given peer. The relying party may ask a specific provider to resolve the relying party openid_client metadata with its own configured trust root. The result may tell what operations, scopes and claims the relying party is allowed to use. REQUIRED. MUST be set to resolve_metadata. REQUIRED. The entity identifier of the entity who's metadata are requested. Because of the normalization of the URL, multiple issuers may resolve to a shared federation API. This parameter makes it explicit exactly which issuer we want to interact with. REQUIRED. The entity identifier of the entity the information is requested for. REQUIRED. The metadata type to resolve. In this document we use the metadata types, openid_client and openid_provider.

The following is a non-normative example of an API request for trust negotiation:

The response is a generated flattened metadata of the type specified in the request.

A non-normative example of a response:

An entity may query another entity for a list of all the entities that that entity is prepared to issue statements about.

The following request parameters are allowed in the query part: REQUIRED. MUST be set to listing. REQUIRED. The entity identifier of the issuer from which an entity listing is requested. Because of the normalization of the URL, multiple issuers may resolve to a shared federation API. This parameter makes it explicit exactly which issuer we want to interact with. OPTIONAL. Provide this parameter to filter the results to entity statements that contain entries for this specific metadata type. OPTIONAL. If left out, result should include both leaf nodes and intermediate nodes. If set to true , the response should contain only leaf nodes. If set to false, the response should contain only intermediate nodes. OPTIONAL. A comma separated list of claim names that the requester would like to get for each entity. If left out or an empty string, the response should contain an empty object for each of the known entities.

The following is a non-normative example of an API request for trust negotiation:

The response MUST contain an JSON object where the known entity identifiers are the property keys, and a JSON object with the requested claims is the property value. Requested claims that the responder is not able to provide should be left out.

A non-normative example of a response:

TBD.

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 else than 200, giving an indication of the type of error. The response body MUST be a JSON object conatining the claims below and the content type MUST be set to application/json.: REQUIRED. Which operation was the request processed as. REQUIRED. The error code. REQUIRED. A human readable short text describing the error.

A non-normative example of an error response:

An entity (the Consumer) that wants to establish trust with a remote peer, must have the remote peer's entity identifier and a list of entity ID's of trusted 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 Fetch Entity Statements with both *iss* and *sub* set to the entity ID 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 the intermediate. If the received entity statement contains an authority hint this process is repeated. This time with the *iss* set to the intermediates entity ID and the *sub* to be the *iss* of the previous query. The Consumer should never 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 an entity statement issued by a trusted 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.

A trust chain consists of an ordered list of entity statements that starts with the self issued entity statement (ES[0]) of the remote peer and ends with an entity statement signed by a trusted trust anchor (ES[i]). Except for the self-signed entity statement (ES[0]) each entity statement refers back to the one preceding it, such that the *sub* in one entity statement (ES[j]) is the *iss* in the immediate preceding (ES[j-1]). A trust chain without any intermediate entities is also valid. To validate the chain, the following steps are done for each entity statement ES[j] j=i,..,0 : Verify that the statement contains all the required claims. If j < i: Verify that the *iss* in ES[j] is the same as the *sub* in ES[j+1] Verify that *iat* has a value in the past Verify that *exp* has value that is in the future. Verify the signature if j < i: verify the signature using the public key carried in the *jwks* claim in ES[j+1]. if j == i: verify the signature with the configured public key of the trust anchor.

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.

Each entity statement in a trust chain is signed and MUST have a expiration time (exp) set. The expiration time of the whole trust chain is the expiration time that is in the future and closest in time to the present time.

This specification allows for a smooth process of updating metadata and public keys. As described above in lifetime calculation each trust chain has a 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 remote party is fetching an updated version of the public key.

A trust anchor must publish a self-signed entity statement about itself. Such an entity statement may be part of a trust cahin or it might not. 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 root wants to roll over its signing keys it would have to: Add the new keys to the *jwks* representing the trust anchors signing keys. Keep signing the entity statement using the entity statement using the old keys for a long enough time period to allow all subordinates to have gotten access to the new keys. Switch to signing with the new keys. After a reasonable time period remove the old keys It has to be taken into considerations that clients may have manually configured pubic keys as part of configuration.

Since we expect the consumers to check the trust chain at regular reasonable frequent times we feel that we do not need to specify a standard revocation process. Specific federations may make a different choice and will then have to add such a process.

The metadata for a specific entity can be constructed by starting with the information in ES[i] and then adding the information from the statements ES[i-1] to ES[0] using the following rules: We define the specific metadata information in an entity statement ES[j] to be called ms[j]. This would be information in *metadata*/*openid_client* as specified in OpenID Connect Relying Party Metadata and OpenID Connect Provider Metadata. Given the metadata statements ms[n] (n=i, ..., 0). Start by assigning m_res = ms[i] then for every claim in ms_j (j=i-1, ... 0): If the claim does not appear in ms_res add it to m_res. If the claim appears in ms_res then replace the value of the claim in ms_res with the value of the claim in ms[j] if and only if the value in ms[j] is a subset of the value in ms_res. A subset is defined as: One string is a subset of another string if it is exactly the same, byte by byte. An array A is a subset of B if every element in A is a subset of an element in B. Boolean A is a subset of B if A is equal to B. The number A is a subset of the number B if A is less or equal to B. The dictionary A is a subset of the dictionary B if every key in A is in B and the value of A[x] is a subset of B[x]. The following is a non-normative example of a set of relying party-specific metadata statements that together form the metadata for an entity:

ms[2]

ms[1]

ms[0]

The metadata for the entity in question, using the rules above, would then be:

sum(ms[n]), (n=0...2)

This section describes how the trust framework in this specification is used to establish trust between an OpenID Relying Party and an OpenID Provider that has no explicit configuration or registration in advance. There is two alternative approaches to establish trust between a Relying Party and a Provider, what we call implicit 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.

The trust between the entities is established using the above described extensions in the first two steps of the communication between an RP and an OP. How the RP found the OP in the first place is out of scope for this document. | | | RP | ---- 2) Authentication request -----> | OP | | | | | ------ ------ ]]> After the discovery and registration is completed a first time, those steps SHOULD only be repeated if any changes occur (see notes in respective sections below).

The client_id of the RP MUST be set identical to the RP entity identifier. Without a registration process, the RP does not have a client_secret. Instead the implicit registration model requires the RP to make use of asymmetric cryptography. The RP MUST host a Federation API that allows the OP to fetch the entity statements.

The authentication request as specified in OpenID Connect Core.

When the OP receives an incoming authentication request, the OP supports OpenID Connect Federation and the incoming client_id is a valid URL, the OP should try to resolve and fetch the entity statement as described in fetching entity statements. The OP should validate the possible trust chains, and resolve the RP metadata with type openid_client. 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.

If the OP fails to establish trust with the RP, it should use the error_description error code, and an error_description that aids the RP to fix what is wrong.

The RP will have to use asymmetric crypto to authenticate to the token endpoint. The RP MUST authenticate the request by including the private_key_jwt parameter, as described in Section 9 of OpenID Connect Core .

This method involves performing an explicit registration of a new client the first time a Relying Party interacts with an OpenID Provider using something that basically foolws the steps in OpenID Connect Dynamic Client Registration 1.0 but where the client registration request is a signed entity statement.

The RP will start by gathering the OPs metadata using the process specified in Resolving trust chain and metadata above.

The OP MUST support dynamic relying party registration. That it does so is signaled by having the claim federation_registration_endpoint in the metadata. Given that the OP supports dynamic registration the RP progresses as follows: Once it has the list of acceptable trust chains for the OP it MUST choose the subset it wants to progress with. The subset can be as small as one trust chain but it can also contain more than one. Based on the trust anchors referenced in the subset of trust chains, the RP will choose a set of authority_hints from its own set that terminates in those trust anchors. The RP will now construct a self-signed entity statement where the metadata statement chosen is influenced by the OPs metadata and the authority_hints included are picked by the process described above. The entity statement is sent to the federation_registration_endpoint defined in this document.

After the OP receives the request, it collects and evaluates the trust chains starting with the authority_hints in the registration request. After it has verified at least one trust chain it can verify that the signature on the received registration request is correct. If it finds more then one acceptable trust chain it MUST chose one trust anchor from those chains as the one it will proceed with. At this point, if there already exists a client registration under the same entity_id then that registration MUST be regarded as invalid. *Note* that key material from the previous registration MUST be kept to make key rollover possible. The OP will now construct an entity statement containing a description of the part of the RP's metadata that the OP finds acceptable. *Note* that the client_id the OP chooses does not have to be the same as the entity_id of the RP. To the entity statement it will add one or more authority_hints, from its collection, that terminate in the trust anchor chosen above. It will sign and return the registration response (a signed entity statement) to the RP.

The RP Verifies the correctness of the received entity statement, making sure that the trust chains starting at the authority_hints terminates in trust anchors that were referenced in the entity statement it sent to the OP. The RP can *NOT* flatten the metadata using the trust chains that the OP provides. This since the trust chain provided by the OP is not valid for the RPs metadata. It has to do it using one of its own trust chains that ends in the trust anchor that the OP chose. When it has done the flattening then it store the configuration and can continue communicating with the OP using the agreed on metadata. At this point the RP also knows which trust chain it should use when evaluating the OPs metadata. So now it can flatten the OPs metadata using the relevant trust chain and store the result as the OPs metadata. If the RP was not OK, for some reason, with the received entity statement then it has the choice to restart the registration process or to give up.

A client registration using this specification is not expected to be valid for ever. The entity statements exchanged all have expiration times. Which means that the registration will eventually time out. An OP can also for some reason decided that a client registration is not valid anymore. To this can be added that the entities in the federation, for a number of reasons, over time may change how fast their signature will expire, thereby increasing or decreasing the lifetime of a trust chain.

At regular intervals the RP MUST: Starting with the OPs entity statement, resolve and verify the trust chains it chose to use when constructing the registration request. If those trust chains don't exist anymore or do not verify, then the registration should be regarded as invalid and a new registration process should be started. If the OPs entity statement was OK it must now verify that the entity statement it received about itself from the OP is still valid. Again, if that is not the case the registration should be regarded as invalid and a new registration process should be started.

At regular intervals the OP MUST: If the signature on the registration request has expired it MUST mark the registration as invalid and demand that the RP MUST re-register. Else starting with the RPs client registration request, the OP MUST verify that there still is a valid trust chain terminating in the trust anchor the OP chose during the registration process.

There are a number of expiration times that MUST considered: Each signature has a expirattion time. A relying party registration has a expiration time. Taking this into consideration, an OP MUST NOT assign a expiration time to a relying party registration that is after the expiration time of the metadata statement signatures.

Heather Flanagan Misha Salle The JRA3T3 task force of GEANT4-2 Michael Schwartz Peter Schober

TBD

TBD

Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce Nomura Research Institute, Ltd. Ping Identity Microsoft Illumila Nomura Research Institute, Ltd. Ping Identity Microsoft

A service Foodle would like to offer its services to all identity providers in eduGAIN. Foodle is managed and registered by the university NTNU. NTNU is part of the Norwegian Feide federation. Foodle is also directly trusted in the Swedish SWAMID federation. Both Feide and SWAMID are part of the international eduGAIN federation.

The Foodle service chooses to use the entity identifier https://foodl.org/. And upon deployment, Foodle is setup with an RSA key pair, with the following public key:

Foodle offers a WebFinger interface and a metadata API according to this specification, with the ability to issue entity statements about itself.

How trust is established and entities becomes part of a federation is out of scope of this specification. It could involve some kind of non-technical contract, agreement or term of use that is established, followed by a federation or trust issuer that registers an entity identifier, public key and a set of metadata that restricts the delegated trust that is represented in the entity statement about the joining party. The following example, assumes the following trust relations are established, and the following entities are able to issue entity statements: Foodle issues an entity statement about itself NTNU issues an entity statement about Foodle SWAMID issues an entity statement about Foodle Feide issues an entity statement about NTNU eduGAIN issues an entity statement about Feide eduGAIN issues an entity statement about SWAMID SWAMID issues an entity statement about the university of Umea - an OpenID provider for employees and students at the university of Umea Foodle has a local trust root configuration that looks like this (notice that the exact format and content on the trust root configuration is out of scope of this specification):

Let us assume a student from Umeå would like to login at Foodle. Some sort of discovery process involves the end user choosing an OpenID provider. OpenID Discovery using the e-mail address is one option. Foodle presenting a list of available providers for the user to choose from is another. After the discovery process, Foodle knows that the user would like to login using the OpenID provider with entity identifier https://www.umu.se/openid.

Foodle normalizes the entity identifier of the OpenID Provider, and performs a request to fetch the self-issued entity statement using the Federation API of the OpenID provider.

The API endpoint returns a list of signed entity statements. In this case we look for a self-issued statement from the Umeå university. We then decode and inspect the content:

In order to establish trust with this provider, the Foodle service provider would need to fetch sufficient entity statements to represent a complete chain from the self-issued statement to the locally configured trust root, which contains SWAMID. The information found in the authority_hints is critical in order to dynamically discover the trust chain. If such hints are not present, the relying party may resume to fixed configured trust roots to ask for trust statements. In this example, Foodle now fetches an entity statement from SWAMID using the Federation API endpoint of SWAMID, discovered in the authority_hints claim.

The decoded version of the entity statement is:

Notice that the entity statement about University of Umeå also contains an entry for openid_client metadata. This indicates that SWAMID expresses this university to be trusted to issue its own OpenID clients without the need for registering these directly in SWAMID. These two entity statements are sufficient to establish a path from the local configured trust anchor which trust SWAMID, to the self-issued statement from the University of Umeå. Here are the steps performed to validate the trust chain: Find the trusted public keys for SWAMID in the local trust configuration. Use these keys to validate the signature of the signed entity statement issued by SWAMID about the University of Umeå Check that the sub from the trust configuration matches the iss value of the first entity statement. Extract the jwks entry from this entity statement. These are the signing keys of the University of Umeå Validate the self-signed statement from University of Umeå using the keys found above. Check that the sub from the previous statement matches the iss of the self-issued statement. Check that the self-issued statement has the iss and sub to be the same.

The output from the trust chain validation is an ordered list of entity statements. In order to extract the needed metadata, we need to look at the metadata type relevant in the given context. In this case, we are establishing trust with an OpenID Provider, and we take a look at the openid_provider metadata object of the trust chain:

The metadata flattening process converts this to a single metadata object. The resulting metadata in this case would be:

Foodle after establishing trust with the University of Umeå and extracted a resulting set of metadata, will send an authentication request to the OpenID provider. This example involves the implicit registration. Here is an example of an authentication request:

The provider receiving this authentication request will, unless the RP is cached or statically configured, start to dynamically fetch and establish trust with the RP.

The provider needs to establish a trust chain for the RP from which a authentication was received. The provider in this example has the following configured trust root:

The provider starts to resolve metadata for the client identifier https://foodl.org/ by fetching the self-issued entity statement using the Federation API. uses WebFinger, the metadata API endpoints and the authority_hints in order to establish a full trust chain to the trust root. In this case there are two possible trust chains: eduGAIN -> Feide -> NTNU -> Foodle SWAMID -> Foodle

A research project has pooled resources and bought an extremely rare and expensive equipment (EREE) that MUST be accessible by all project participants disregarding which university/research organization/company they belong for. To that end the research project have created its own federation (EREE) and are expecting the participants to get their organizations OP to register with the EREE federation. These OPs are of course expected to be members in one or more other federations. So we have to EREE service and an EREE federation. Since the EREE equipment is placed in Sweden the EREE service is also member of the SWAMID federation.

The EREE service choose to use the entity identifier https://srv.eree.example.org/. And upon deployment, EREE is setup with a Elliptic Curve key pair, with the following public key:

The EPEE service is provided files containing authority_hints by its superiors. From the EPEE federation it gets:

from SWAMID:

and from UNINETT:

and so on On the federations side: SWAMID is prepared to issue an entity statement about the EPEE service The EPEE federation is prepared to issue an entity statement about the EPEE service UNINETT is prepared to issue an entity statement about the EPEE service And finally, from the federations the EPEE service also receives the public part of the federations signing keys.

A researcher from Umeå wants to access the EPEE service. The EPEE service provides a discovery service which allows the researcher to chose which identity provider to use. In this case https://op.umu.se/ .

Using the entity ID (issuer ID) of the identity provider the service performs a fetch entity statement request as described in Fetch Entity Statement

The decoded version of the entity statement is:

In order to establish trust with this provider, the EEPE service provider would need to fetch sufficient entity statements to represent a complete chain from the self issued statement to the trust anchor that represents the EPEE federations. The authority_hints in the self-signed entity statement points to 2 trust anchors "https://epee.example.org" and "https://swamid.se" of these only the *EPEE* one is interesting. The RP therefor chooses to only follow that trust path. The next step being fetching an entity statement about "https://op.umu.se" signed by the EPEE federation. This is done by doing a fetch entity statement:

The decoded version of the returned entity statement is:

A couple of things worth noting about the response: There is no authority_hint which means this a trust anchor The subject is marked as being a *leaf* which means that there can be no entities subordinate to https://op.umu.se The federation does not have any restrictions on what the OP can be configured to do. This means that flattening is going to be very easy.

These two entity statements are sufficient to establish a path from the local configured trust anchor which trust the EPEE federation, to the self-issued statement from the Identity provider at the University of Umeå. Here are the steps performed to validate the trust chain as described in validating the trust chain. We start with the signed entity statement issued by EPEE about the OP at the University of Umeå Verify that the *sub* in the entity statement is the OPs entity ID. Find the trusted public keys for the EPEE federation in the local trust configuration. Use these keys to validate the signature of the signed entity statement. Provided that works out OK Extract the jwks from the entity statement and convert it to a set of keys Now, we can work on the self-signed entity statement published by the OP@UmU. Verify that the *sub* and the *iss* in the entity statement is the OPs entity ID. Using the keys extracted above, verify the signature of the signed entity statement

The output from the trust chain validation is an ordered list of entity statements. In order to extract the needed metadata, we need to look at the metadata type relevant in the given context. In this case, we are establishing trust with an OpenID Provider, and we take a look at the *openid_provider* metadata object of the trust chain:

Since the first item in this list is empty the flattening process will return the second item as the result.

Now when the RP has trusted information about the OP it can do a dynamic client registration. To that end it collects information about itself that it wants to register. This should be no different from what a normal OIDC RP does. To this it adds information about the RP federation signing keys, the *sub* and *authority_hints*. Ones it has all that information it creates an entity statement. The result of all this work may look something like this:

Next it self-signs this statement and sends it as a client registration request to the *federation_registration_endpoint* of the OP.

To collect the trust chains the OP uses the *authority_hints* in the self-signed entity statement it received from the RP (the client registration request). In this case it is only one which points to *https://eree.example.org* . So the OP fetches the entity statement that the EPEE federation publishes on the EPEE RP.

With the response:

Unpacked this becomes:

The process here is the one described in validating the trust chain.

The OP does flattening on the information in the trust chain and comes up with:

Happy with the information in the client registration request the OP takes the flattened metadata and creates an entity statement by add *sub* and *authority_hints*:

The RP MUST collect the trust chain ending in the EPEE trust anchor and verify the correctness of the trust chain but refrain from flattening the metadata. This since the entity statement issued by the EPEE federation about the UmU OP are only valid for that entity and not for the EPEE RP. If the RP is OK with what the OP decided on regarding the RPs metadata then it will store this to be used in the following OIDC protocol exchange with the OP. In this example the RP decided on one specific trust anchor before sending the registration request. If that was not the case but the RP chose to send a registration request with more than one authority_hint then this is the time when then RP can flatten and store the provider metadata. This since the OP MUST choose one and only one authority (=trust anchor) for the registration response.

Copyright (c) 2018 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 ]] -06 Some rewrite Added example of explicit client registration -05 A major rewrite. -04 Changed client metadata names scopes to rp_scopes and claims to rp_claims. Added Open Issues appendix. Added additional references. Editorial improvements. Added standard Notices section, which is present in all OpenID specifications.