OpenID Connect Federation= 1.0

<list style=3D"hanging">
<t hangText=3D"subset_of">
<vspace/>
The resulting = value of the claim will be the intersection of the
= values specified here and the values of the claim. For
instance, the Claim policy:
= <figure>
<artwork><![CDATA[
"response_types": {
"subset_of": ["code", = "code token", "code id_token"]}
]]></artwork>
= </figure>

= if applied to a metadata statement with:
= <figure>
<artwork><![CDATA[
= "response_types": ["code", "code id_token token", "code id_token"]
]]></artwork>
</figure>
= will result in the statement:

= <figure>
<artwork><![CDATA[
"response_types": ["code", "code id_token"]
]]></artwork>
</figure>
= </t>

  "response_types": {
    "subset_of": ["code", "code token", "code id_token"]}
</pre>
<pre>
  "response_types": ["code", "code =
id_token token", "code id_token"]
</pre>
<pre>
  "response_types": ["code", "code =
id_token"]
</pre>

and then the <dl> = part

<dl>
<dt>subset_of</dt>
<dd style=3D"margin-left: 8">
<br> =
The resulting value of the claim will be the intersection of the values =
specified here and the values of the claim. For instance, the Claim =
policy: </dd>

In the text = representation everything turned out as expected:

subset_of
   The resulting value of the claim =
will be the intersection of the
   values specified here =
and the values of the claim.  For instance,
   the Claim =
policy:

  "response_types": {
 =
   "subset_of": ["code", "code token", "code id_token"]}
   if applied to a metadata statement with:

  "response_types": ["code", "code id_token token", "code =
id_token"]

   will result in the =
statement:

  "response_types": ["code", =
"code id_token"]

Weird!

Running xml2rfc = 2.16.3

OpenID Connect Federation= 1.0 - draft 07 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/

Yubico

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

OpenID Connect Working Group OIDC The OpenID Connect standard specifies how an Relying Party (RP) can discover metadata about an OpenID Provider (OP), and then register to obtain RP 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 by resolving trust from a common trusted third party. While this specification is primarily targeting OpenID Connect, it is designed 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 resolve trust and metadata for= a given protocol through the use of third party trust issuers. A tr= ust issuer is an entity whose main purpose is to issue statements about entities, such as OpenID relying party and providers. An id= entity federation can be realized using this specification by the use of= 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 b= uilding blocks needed to build a dynamic and distributed trust network su= ch as a federation. All entities in an OpenID Connect federation MUST have a globall= y unique identifier. Note that a company, as with any real-world organization, may be= represented by more than one entity in a federation. OpenID Connect Federation trust chains rely on cryptographically signed JWT documents, and the trust chain does = not at all rely on TLS in order 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)= , the terms "OpenID Provider (OP)" and "Relying Party (RP)" by OIDC core This specification also defines the following terms: Something that has a separate and distinct existence and th= at can be identified in a context. An entity statement is issued by an entity, and concerns a subject entity and leaf= entities. An entity statement is always a signed JWT. A entity that issues an entity statement that appears somewhere in between those= issued by the trust anchor and the leaf entity in a trust c= hain. An entity defined by a certain protocol. E.g. OpenID Provider/Relying Party. An entity that represents a trusted third party. A sequence of entity statements that represents a trusted c= hain starting at a leaf entity and ending in a trust anchor.

An entity statement is issued by an entity and concerns a subject entity and leaf enti= ties in a federation. An entity statement is always a signed JWT. All entities in a federation MUST be prepared to publish an ent= ity statement about themselves. An entity statment is composed of the following claims: REQUIRED. The entity identifier of the is= suer of the statement. If the iss and= the sub are identical, the issuer is making a statement about itself. REQUIRED. The entity identifier of the su= bject REQUIRED. The time the statement was issu= ed. Its value is a JSON number representing the number of secon= ds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 for details regarding date/times in general and UTC in particul= ar. REQUIRED. Expiration time on or after which the statement MUST NOT be= accepted for processing. Its value is a JSON number represe= nting the number of seconds from 1970-01-01T0:0:0Z as measured in= UTC until the date/time. REQUIRED. A JSO= N Web Key Set (JWKS) representing the public part of the subject entity's signing keys. The corresponding private key is used by leaf entities to sign entity statements about thems= elves, and intermediate entities to sign statements about other en= tities. The keys that can be found here are primarily intended to s= ign entity statements, and should not be used in other protocol= s. OPTIONAL. A JSON object where= the keys are the entity id's of the intermediate entities that may i= ssue an entity statement about the issuer entity. The value MUST be= a JSON array of entities that are further up in the trust cha= in. The array may be an empty list. The JSON array can be used to simplify the selection of tru= st chains without the need for following all possible trust ch= ains. OPTIONAL. JSON object including prot= ocol specific metadata claims that represent the leaf entities. The keys of the JSON object represent the metadata type identifier, and their value MUST be a JSON object represent= ing the metadata according to the metadata schema of that metad= ata type. An entity statement may contain multiple metadata statements, but only one for each metadata type. OPTIONAL. JSON object that de= scribes a policy that MUST be applied to a leaf entity's metadata. An entity statement may contain multiple metadata policy statements, but only one for each metadata = type. OPTIONAL. Boolean value that indi= cates whether the subject is considered a leaf entity. A leaf ent= ity is not trusted to issue policy statements about other entities= =2E If this property is left out, it is considered to be false. The entity statement is signed using the private key of the is= suer entity, in the form of a JSON Web Sign= ature (JWS).

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

A trust anchor is an entity trusted by a number of other entit= ies to issue correct statements. Why they choose to trust this enti= ty is out of scope for this document.

In an OIDC Identity Federation, entities that together build a trust chain can be categorized as: An entity that represents a trus= ted third party In an OIDC Identity federation an RP or = an OP Neither a leaf nor a trust ancho= r 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 about the trust anchor (in the case with zero intermediates) or an intermediate issued by the trust anchor and finally a self-signed entity statement about the trust anch= or. A simple example: If we have an RP that belongs to organisatio= n A who is a member of federation F, the trust chain for such a set= up will contain the following entity statements: A self-signed entity statement about the RP published by th= e RP An entity statement about the RP published by Organisation = A An entity statement about Organisation A published by Feder= ation F A self-signed entity statement about Federation F published= by Federation F. 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] (the trust anchors self-signed entity statement), i>0 then: The *iss* entity in one entity statement is always the *sub= * entity in the next. ES[j]['iss'] =3D=3D ES[j+1]['sub'], j=3D0,...,i-1 There MUST always be a signing key carried in the jwks clai= m in ES[j] that can be used to verify the signature of ES[j-1], j=3Di,...,1 . The signing key that MUST be used to verify ES[i] is distribute= d from the trust anchors to the leaf entities in some secure out-of-band's way not described in this document.

The OpenID Connect Federations specification does allow new meta= data 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 ex= isting 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 Cli= ent Registration 1.0 are allowed in a metadata statement. To that list is added: RECOMMENDED. JSON arr= ay containing a list of the RFC6749 scope values that a RP may ask for. RECOMMENDED. JSON arr= ay containing a list of the Claim Names of the Claims that an = RP may ask for. OPTIONAL. A human = readable name representing the organization owning the RP.

The metadata type identifier is 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 OP. It is intended to be used in the user interface, being recognized= by the end users that would be using the OP to authenticate. OPTIONAL. URL of the OP's Federation specific Dynamic Client Registra= tion Endpoint. If the OP supports explicit client registration as described in expl= icit registration, then this claim is REQUIRED.

The metadata type identifier is openid_discovery.

The metadata type identifier is oauth_service. All parameters defined in section 2 of RFC 8414

The metadata type identifier is oauth_client. All parameters defined in section 2 of RFC 7591

The metadata type identifier is oauth_resource.

The metadata type identifier is federation_entity. The following properties are allowed: OPTIONAL. String. The human readable nam= e describing the subject entity. This may be, for example, th= e name of an organization. OPTIONAL. JSON array with one or mor= e 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 metadata for a specific entity can be constructed by startin= g with the information in leaf entity's entity statement and then applying the polices defined by the trust anchor and possible intermediates starting with the trust anchor.

Policies are expressed using a JSON object. There are a number of keywords defined that represents differen= t actions/checks that MUST be applied to the metadata. These keywords are: The resulting value of the claim will be the intersection o= f the values specified here and the values of the claim. For instance, the Claim policy:

if applied to a metadata statement with:

will result in the statement:

The value of the claim MUST be one of the ones listed here.= As an example, if the Claim policy:

is applied to the metadata statement

the result will be:

Disregarding what value the claim had, the value specified here will be added to the metadata statemen= t. As an example, if the Claim policy:

is applied to the metadata statement

the result will be:

Disregarding what value the claim had, if any, the claims value will be set to what is specified h= ere. As an example, if the Claim policy:

is applied to a metadata statement with no such claim the result will be that the metadata statement after apply = the policy contains the claim:

If no value is assigned to this claim then the claims value= will be set to what is specified here. As an example, if the Claim policy:

is applied to a metadata statement with the claim

then the metadata statement will afterwards contain:

Matches the claim value against a regular expression. If the value does not match it will be removed. The variant of regular expression used is POSIX BRE. As an example, if the Claim policy:

is applied to a metadata statement with the claim

the metadata statement will afterwards still contain the cl= aim because the value matched the regular expression:

If 'true' then claim MUST have a value. *essential* can be combined with all the other types.

Means that applying the policies to a metadata statement MU= ST result in this claim having a value.

Some policy types can be combined with others. Can be combined with *one_of*, *reg_exp* and *subset_of*. Can be combined with all the others. If *essential* is not present the interpretation is that essential=3Dtrue.

If there are more then one metadata policy in a trust chain the= n the policies MUST be combined before they are applied to the metadata statement. These are the policy types that can be combined when combining = 2 policies: The result of combining 2 *set_of* policies is the intersec= tion of the values. The result of combining 2 *one_of* policies is the intersec= tion of the values. The result of combining 2 *add* policies is the union of th= e values. All the other policy types can NOT be combined.

If applying a policy to a metadata statement results in some cl= aims having all their values removed and it is essential that a claim has a value then such a metadata statement MUST be regraded as broken and MUST NOT be used.

There might be parties that wants to extend the policy language= defined here, therefor if software compliant with this specific= ation encounters a key word it doesn't understand it MUST refuse to a= pply the policy.

The following is a non-normative example of a set of policies b= eing applied to an RP's metadata.

The RP's metadata

The federations policy for RPs

The organisations policy for RPs The metadata for the entity in question, policies above, would then be:

sum(ms[n]), (n=3D0...2)

All entities that are expected to publish entity statements about themselves or other entities, = MUST expose a Federation API endpoint. The federation API endpoint of an entity is resolved from the en= tity 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 fo= llowing path: /.well-known/openid-federation. *Note* that since the path component of a entity ID is not included when constructing the URL above, one API endpoint may serve as the federation API endpoint for several entities. 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 th= e other operations are OPTIONAL. The list of defined operations may= be extended in a future. While all operations in the specification make use of a GET requ= est, 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 ag= reed upon, requests to the federation API does not need to be authenticated.

Fetching entity statement is used to collect entity statements= one by one in order to gather trust chains. In order to fetch an entity statement, an entity needs to know= the identifier of the entity to ask (the issuer), and the identifie= r 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 t= he 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 o= f the normalization of the URL, multiple issuers may resolve to= a shared federation API. This parameter makes it explicit e= xactly which issuer we want entity statements from. OPTIONAL. The entity identifier of the = subject for which you would like an entity statement issued. If t= his 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 t= his target, in which the aud cl= aim also SHOULD be present in the entity statement self.

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

A positive response is a signed entity statement where the content type MUST be set to application/jose. If it is negative response it will be a JSON object and the content type MUST be set to application/json. 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 resolved metadata about itself as seen/trusted by a remote peer= =2E 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 anch= or was used.

The following is a non-normative example of an AP= I request for trust negotiation:

The response is a metadata statement that is the result of applying the metadata polices in the trust chain on the entit= y's metadata.

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= =2E

The request MUST be an HTTP request using the GET method and= the https scheme to a resolved federation API endpoint with t= he following query string parameters: REQUIRED. MUST be set to listing. REQUIRED. The entity identifier of the = entity from which an entity listing is requested. Because of the= normalization of the URL, multiple entity identifiers may= resolve to a shared federation API. This parameter makes = it explicit exactly which entity is expected. OPTIONAL. Provide this parameter to fi= lter the results to entity statements that contain entries for= this specific metadata type. OPTIONAL. If left out, result s= hould include both leaf entities and intermediate nodes. If set= to true, the response should contain only leaf entities. 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 values f= or for each entity. If left out or an empty string, the resp= onse should contain an empty object for each of the known enti= ties. The set of claim names that can be used are defined in metadata. *Note* that while type and sub_is_leaf can be used to filter out which entities to return this only affects what is re= turned about each returned entity.

The following is a non-normative example of an AP= I request for trust negotiation:

The response MUST contain an JSON object where the known ent= ity 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:

If the request was malformed, or some error occurred during processing of the request, the following standardized error for= mat should be used regardless of the operation specified. The HTTP response code MUST be something in 400/500-range, giv= ing an indication of the type of error. The response body MUST be a JS= ON object containing 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 (e.g., the Consumer) that wants to establish trust wit= h 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 ver= sion of their signing keys. The Consumer will first have to fetch sufficient entity statements to establish at least one chain of t= rust from the remote peer to one or more of the configured trust ancho= rs. After that the entity MUST validate the trust chains independentl= y, 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 us= e the process described in Fetch Ent= ity 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 each of the intermediates.= If the received entity statement contains an authority hint thi= s process is repeated. This time with the *iss* set to the intermediates entity ID and the *sub* to be the *iss* of the pr= evious query. The Consumer should never attempt to fetch entity statements it already has fetched during this process (loop prevention). Once the Consumer has found a trust anchor it wants to use it = MUST complete the trust chain by fetching the trust anchor's self-si= gned entity statement. A successful operation will return one or more lists of entity statements. Each of the lists terminating in a self-sign= ed entity statement 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= =2E

As described in The trust chain a trust chain consists of an ordered list of entity statements. So which ever 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: For each entity statement ES[j] j=3Di,..,0 : Verify that the statement contains all the required cla= ims. Verify that *iat* has a value in the past Verify that *exp* has a value that is in the future. For j=3D0,i verify that *iss* =3D=3D *sub*. For j=3D1,...,i-1: Verify that ES[j]['iss'] =3D=3D ES[j+1][= 'sub'] For j=3D0,...,i-1: Verify the signature of ES[j] using the = public key carried in ES[j+1]['jwks']. For j =3D=3D i: verify the signature with the configured pu= blic key of the trust anchor. Verifying the signature is a much more expensive operation then verifying the correctness of the statement and t= he timestamps. An implementer MAY therefor chose to not verify the= signature until all the other checks have been done. No information in the chain of statements should be used before the signature chain has been validated.

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 longe= r one.

Each entity statement in a trust chain is signed and MUST have = a expiration time (exp) set. The expiration time of the whole tru= st chain is set to the minimum value of exp within the chain.

This specification allows for a smooth process of updating metad= ata 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 o= n how quickly the consumer wants to find out that something has cha= nged in the trust chain.

If a leaf entity publishes its public keys in the metadata par= t using *jwks* setting an expiration time on the self-signed enti= ty statement can be used to control how often the remote party is fetching an updated version of the public key. If a leaf entity uses *jwks_uri* the remote party will in the = normal OIDC way fetch the keys anew from the *jwks_uri* URI when it discovers that the entity uses a key it has never seen before.

A trust anchor must publish a self-signed entity statement abo= ut itself. As described above in The trust chain it should be at the end of the trust chain. The trust anchor SHOULD set a reasonable expiration time on that statement, such that the consumers will re-fetch t= he entity statement at reasonable intervals. If the trust root wan= ts 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 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. What is= regarded as a reasonable time is dependent on the security = profile and risk assessment of the trust anchor. It has to be taken into consideration that clients may have manually configured pubic keys as part of their configuration.

Since the consumers are expected to check the trust chain at re= gular, 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 specifica= tion is used to establish trust between an RP and an OP that has no explicit configuration or registration in advance. There is two alternative approaches to establish trust between a= n RP and an OP, 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 o= f one of them.

The trust between the entities is established using t= he above described extensions in the first two steps of the communication between an RP and an OP. How the RP found the O= P in the first place is out of scope for this document. | | | RP | ---- 2) Authentication request -----> | OP | | | | | ------ ------ ]]> 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. The RP MUST authenticate at the authentication endpoint using the private_key_jwt method described in the client authentication section of OIDC core.

An authorization request example

When the OP receives an incoming authentication request, the OP supports OpenID Connect Federation and the incoming cl= ient_id is a valid URL, the OP should try to resolve and fetch trust chains starting with the RP's entity statement as described in fetchi= ng entity statements. The OP should validate the possible trust chains, as describ= ed in Trust chain validatio= n 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 specificatio= n in OpenID Connect Dynamic C= lient Registration 1.0. Once the OP has the RP's metadata it can verify the clients authentication.

If the OP fails to establish trust with the RP, it should us= e the invalid_request error code, and an error_description that aids the RP to understand what is wrong.

This method involves performing an explicit registration of a = new client the first time a RP interacts with an OP using something that basically follows the steps in OpenID Connect Dynamic Cli= ent 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 Resolvi= ng Trust Chains and Metadata above.

The OP MUST support dynamic client 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 th= e OP it MUST choose the subset it wants to progress with. Th= e subset can be as small as one trust chain but it can al= so contain more than one. Based on the trust anchors referenced in the subset of= trust chains, the RP will choose a set of authority_hin= ts from its own set that terminates in those trust anchors. The RP will now construct a self-signed entity stateme= nt where the metadata statement chosen is influenced by th= e OPs metadata and the authority_hints included are picked by= the process described above. The entity statement is sent to the federation_registration_endpoint<= /spanx> 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 registr= ation request is correct. If it finds more then one acceptable trust chain it = MUST chose one trust anchor from those chains as the one i= t will proceed with. At this point, if there already exists a client registration under the same entity_id then that regis= tration MUST be regarded as invalid. *Note* that key material= from the previous registration MUST be kept to make key rollov= er possible. The OP will now construct an entity statement contai= ning 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 hav= e 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 enti= ty 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 MUST NOT apply metadata policies from the tru= st chains that the OP provides because the trust chain p= rovided by the OP is not valid for the RPs metadata. The RP MUST policies to the metadata using one of its= own trust chains that ends in the trust anchor that the O= P chose . When it has metadata policies, it then stores 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. It can therefor= e apply the metadata policies on 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 rece= ived entity statement then it has the choice to restart th= e registration process or to give up.

A client registration using this specification is not expect= ed to be valid forever. The entity statements exchanged all have expiration times, which means that the registration will even= tually time out. An OP can also for administrative reasons decide th= at 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: Starting with the OPs entity statement, resolve and ve= rify the trust chains it chooses to use when constructing th= e registration request. If those trust chains do not exis= t anymore or do not verify, then the registration should = be regarded as invalid and a new registration process shou= ld be started. If the OPs entity statement was properly formed the RP= 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 pr= ocess should be started. What is regarded as reasonable intervals will depend on federation policies and risk assessment by the maintainer o= f the RP.

At regular intervals the OP MUST: If the signature on the registration request has expire= d it MUST mark the registration as invalid and demand that t= he RP MUST re-register. Else starting with the RPs client registration request, the = OP MUST verify that there still is a valid trust chain terminat= ing in the trust anchor the OP chose during the registration p= rocess.

An OP MUST NOT assign a expiration time to a RP's registration that is later then the trust chains expiration time.

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

TBD

OpenID Connect Discovery 1.0 Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce= OpenID Connect Discovery 1.0 Nomura Research Institute, Ltd. Ping Identity Microsoft Illumila OpenID Connect Dynamic Client Registration 1.0 Nomura Research Institute, Ltd. Ping Identity Microsoft

A service Foodle would like to offer its services to all OPs in eduGAIN. Foodle is managed and registered by the university NTNU. NTNU is part of the Norwegian Feide federation. Foodle is a= lso 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 deplo= yment, Foodle is setup with an RSA key pair, with the following public key:

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

How trust is established and entities becomes part of a federa= tion is out of scope of this specification. It could involve some ki= nd of non-technical contract, agreement or term of use that is established, followed by a federation or trust issuer that regi= sters an entity identifier, public key and a set of metadata that res= tricts the delegated trust that is represented in the entity statement= about the joining party. The following example, assumes the following trust relations a= re established, and the following entities are able to issue entit= y 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 OP for employees and students at the university of Ume= a Foodle has a local trust root configuration that contains publi= c signing keys for known federations:

"https://www.sunet.se/swamid"

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

Foodle normalizes the entity identifier of the OP, and performs a request to fetch the self-issued entity statement us= ing the Federation API of the OP.

The API endpoint returns a list of signed entity statements. I= n this case we look for a self-issued statement from the Ume&arin= g; university. We then decode and inspect the content:

In order to establish trust with this OP, the Foodle RP 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 or= der to dynamically discover the trust chain. If such hints are not present, the RP may resume to fixed configured trust roots to ask for entity statements. In this example, Foodle now fetches an entity statement from S= WAMID 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 indicat= es that SWAMID expresses this university to be trusted to issue its own= OpenID clients without the need for registering these directly in SWAM= ID. 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 ent= ity statement issued by SWAMID about the University of Umeå Check that the sub from the trust configuration matches th= e iss value of the first entity statement. Extract the jwks entry from this entity statement. These a= re 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 t= o 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 thi= s case, we are establishing trust with an OP, and we take the openid_provider metadata object from the entity statement published by the OP and the policy statements = from the other entities in the trust chain:

SWAMID's metadata policy for an openid_provider

UMU's metadata policy for an openid_provider and finally

The OP's metadata statement Applying the metadata policies to the metadata produces the following result:

Foodle after establishing trust with the University of Umeå and extracted metadata and a set of metadata policies, will sen= d an authentication request to the OP. This example involves the implicit registration. Here is an example of an authentication request:

The OP receiving this authentication request will, unless the RP is cached or statically configured, start to dynamically fet= ch and establish trust with the RP.

The OP needs to establish a trust chain for the RP from which = a authentication was received. The OP in this example are configu= red with public key of 2 federations:

"https://edugain.org/oidc" and

"https://www.sunet.se/swamid"

The RP 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_h= ints 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 r= are and expensive equipment (EREE) that MUST be accessible by all pro= ject 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 oth= er 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 b= y 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 stateme= nt 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 receiv= es 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 OP to use. In this case https://op.umu.se/ .

Using the entity ID (issuer ID) of the OP 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 OP, 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 point= s to 2 trust anchors "https://epee.example.org" and "https://swami= d.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 anch= or 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 there are no metadat= a policies to apply to the metadata statement.

These two entity statements are sufficient to establish a pa= th from the local configured trust anchor which trust the EPEE federa= tion, to the self-issued statement from the OP at the University of Umeå. Here are the steps performed to validate the t= rust chain as described in validating the trust chain. We start with the signed entity statement issued by EPEE abou= t 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 e= ntity statement. Provided that works out OK Extract the jwks from the entity statement and convert i= t to a set of keys Now, we can work on the self-signed entity statement publishe= d by the OP@UmU. Verify that the *sub* and the *iss* in the entity statem= ent 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, w= e need to look at the metadata type relevant in the given context. I= n this case, we are establishing trust with an OP, and we take a look at the *openid_provider* metadata and metadata_policy = objects of the trust chain:

Metadata polices

Metadata statement Since there is no metadata policy defined, the response will = just be the metadata statement as it is.

Now when the RP has trusted information about the OP it can d= o a dynamic client registration. To that end it collects informat= ion 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 cli= ent 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 applies the metadata policies on the leaf entity's metadata, all from the trust chain and comes up with:

Happy with the information in the client registration request= the OP takes the processed metadata and creates an entity stateme= nt by adding *sub* and *authority_hints*:

The RP MUST collect the trust chain ending in the EPEE trust an= chor and verify the correctness of the trust chain but refrain from proc= essing the metadata. This since the entity statement issued by the EPE= E 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 OI= DC protocol exchange with the OP. In this example the RP decided on one specific trust anchor bef= ore sending the registration request. If that was not the case but = the RP had chosen to send a registration request with more than one= authority_hint then this by time the RP could not apply any metadata polices to the metadata statement since it would not k= now which to use.

Copyright (c) 2018 The OpenID Foundation. The OpenID Foundation (OIDF) grants to any Contributor, develope= r, implementer, or other interested party a non-exclusive, royalty f= ree, worldwide copyright license to reproduce, prepare derivative work= s from, distribute, perform and display, this Implementers Draft or Final= Specification solely for the purposes of (i) developing specifica= tions, and (ii) implementing Implementers Drafts and Final Specification= s based on such documents, provided that attribution be made to the OIDF = as the source of the material, but that such attribution does not indica= te an endorsement by the OIDF. The technology described in this specification was made availabl= e from contributions from various sources, including members of the= OpenID Foundation and others. Although the OpenID Foundation has taken s= teps to help ensure that the technology is available for distribution, it= takes no position regarding the validity or scope of any intellectual p= roperty or other rights that might be claimed to pertain to the implement= ation or use of the technology described in this specification or the e= xtent to which any license under such rights might or might not be avai= lable; neither does it represent that it has made any independent effort= to identify any such rights. The OpenID Foundation and the contribut= ors 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 t= he implementer. The OpenID Intellectual Property Rights policy requi= res contributors to offer a patent promise not to assert certain pate= nt claims against other contributors and against implementers. The O= penID Foundation invites any interested party to bring to its attention= any copyrights, patents, patent applications, or other proprietary ri= ghts 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 Open= ID specifications.