independent

roland@catalogix.se

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. During discovery and registration there is no automated mechanism for the OP or the RP to verify the information exchanged during this process. All the information is self-asserted. 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. This document describes how an identity federation can be built around a trusted third party, the federation operator.

The OpenID Connect specification defines how a Relying Party and an OpenID Connect Provider can exchange information dynamically about each other. This information is necessary for future successful OIDC communication. One problem with using dynamic discovery and registration is that the correctness of the information that is exchanged cannot be easily verified by the recipient as it is self-asserted. Another problem that has been raised is the dependency on TLS as the sole protection against attacks on the transferred information. These last couple of years a number of problems with OpenSSL, which is probably the most widely used TLS library, have been discovered that put reasonable doubt into this dependency. We are extending Signed Metadata, as introduced by OAuth 2.0 Authorization Server Metadata, to create what we call metadata statements. Metadata statements together with the use of a trusted third party (that verifies and enforces some common policy), can be used to transfer verified data and establish trust in the data between relying parties and provider.

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.

A metadata statement asserts metadata values about an entity (relying party or provider).

These extra metadata parameters appear in both provider and relying party metadata statements: OPTIONAL. A JSON Web Key Set (JWKS) representing the public part of the entity's signing keys. The keys that can be found here or at signing_keys_uri must not be confused with the keys that an OIDC entity is using for Authorization/AccessToken/RefreshToken/UserInfo requests and responses. Those keys are found at jwks_uri or in the case of relying party registration also possibly as values to jwks. The signing keys are used to sign metadata statements and can also be used by an OP to sign a relying party registration request response. OPTIONAL. Location where a JWKS representing the public part of the entity's signing keys can be found. SHOULD return the Content-Type "application/jose" to indicate that the JWKS is in the form of a JSON Web Signature (JWS) using the JWS Compact Serialization. The signing key used to sign the JWKS belongs to the immediate superior. That is, the entity that signs this entity's metadata statement also signs the JWKS stored at signing_keys_uri. The signing_keys_uri and signing_keys parameters MUST NOT be used together. Either signing_keys_uri or signing_keys MUST be present. OPTIONAL. JSON object where the names are federation identifiers and the values are signed JSON documents containing compounded metadata statements rooted in that federation. There is one value per name. OPTIONAL. JSON object where the names are the federation identifiers and the values are URLs pointing to a compounded metadata statement (CMS) rooted in that federation. Each URL points to just one CMS. OPTIONAL. This is the signed version of the jwks_uri parameter defined in OpenID Connect Dynamic Client Registration 1.0. SHOULD return the Content-Type "application/jose" to indicate that the JWKS is in the form of a JWS using the JWS Compact Serialization. The key used to sign the JWKS can be found in signing_keys or signing_keys_uri. OPTIONAL. Metadata statements that are used in different contexts will contain different parameters. For example, information that an OP publishes about itself is not the same as what an RP wants to register. This together with the differences in the roles between an OP and an RP, means that policies for RPs will not be the same as for OPs. There is therefore a need for tagging the Metadata statement such that a Metadata statement intended to be used in one context cannot be used in another. This is the reason for the federation_usage parameter. This parameter can be used to limit the usage to a specific context. The federation_usage value is a case sensitive string. The values specified in this document are 'discovery', 'registration' and 'response'. The corresponding contexts are: Provider Information Discovery Response Client Registration Request Client Registration Request response Metadata statements and signing keys can be transferred in two different ways: either by including the information in the statement or by providing a URI that points to the information. How metadata statements and signing keys are transferred is independent of each other. If both jwks_uri and signed_jwks_uri are present, which they might be for backward compatibility reasons, then signed_jwks_uri SHOULD be preferred. Metadata statements that do not contain metadata_statements or metadata_statement_uris are called level 0 metadata statements. An OP MUST sign its JWKs and therefore publish a signed_jwks_uri. An RP that is able to handle secrets MUST also sign its JWKS and publish a signed_jwks_uri.

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 this relying party expects to use. RECOMMENDED. JSON array containing a list of the Claim Names of the Claims that the OpenID Client wants values for.

All parameters defined in section 3 of OpenID Connect Discovery 1.0

To describe Compounded Metadata Statements, we need a way of describing the different components in such a statement. These are the basic components: Metadata Statement signing request by X without signing keys and signed metadata statements. Signing keys that belong to X Metadata Statement signed by X Using these basic components, we can now describe a simple signed Metadata Statement as:

A(ms_B + SK[B])

B being the entity that requested a signature by A of B's metadata statement and signing keys. Creating a compounded metadata statements involves adding previously signed metadata statements to the request before signing it. So, if we start off with C sending this signing request to B,

(ms_C + SK[C])

then B may want to add the signed metadata statement it received from A before signing. So we first get:

(ms_C + SK[C] + A(ms_B + SK[B]))

which is then signed by B before being returned to C. This is the resulting compounded metadata statement:

B(ms_C + SK[C) + A(ms_B + SK[B]))

Here we have three entities involved: A which is the top level entity (the federation operator) a second level entity (B) representing a federation member and C which could be an entity within the federation like an OP or an RP owned/controlled by B. If we assume that C is an RP then ms_C would typically be a relying party registration request and SK[C] would be the signing keys that the RP used to sign the JWKS placed at signed_jwks_uri. The statement signed by A (ms_b + SK[B]) would contain metadata common to all RPs owned by the member (ms_B) and the signing key (SK[B]) that the member uses to sign requests from the member's RPs. Note that the level N requester is the level N+1 signer.

The metadata for each entity in the federation is described by one or more metadata statements (for example, ms_0, ms_1, ..., ms_n). ms_0 (the level 0 metadata statement mentioned above) would be the most generic, and ms_1, ..., ms_n would in turn be successively more specific. ms_0 would typically contain information that belongs to the organization, for instance, tos_uri, contacts and the like, while ms_n would contain information that belongs to one specific entity like authorization_endpoint for an OP or redirect_uris for an RP.

The following is a non-normative example of a compounded metadata statement. Also note that the metadata_statement MUST be a signed JWT. In this example, only the parts of the signed JWT payload pertinent to the example are shown.

The trust model is based on linking together signing keys, represented as JWK Sets. Each signature chain is rooted in the trusted third party's signing keys. By verifying these signature chains, the entities can establish trust in the metadata.

The Federation Operator (FO) is the trusted third party. The FO MUST have a globally unique identifier. Every time it signs a metadata statement it MUST set iss to the identifier. It will publish a JWKS, containing the signing keys that the FO will use for signing metadata submitted to it, at an HTTPS URL which server certificate MUST appear in a well-known Certificate Transparency log. The key IDs of the FO's signing keys MUST be globally unique. For the following description, this is assumed to be true: A federation consists of a number of members, and each member has one or more representatives registered with the federation. These representatives are allowed to issue metadata signing requests on behalf of the member to the federation. Below such a representative is called a Level 0 Requester (L0Req). Within each member unless all entities belonging to the member are handled directly by the L0Req there may exist parties that are responsible for single or groups of entities. Within these parties we may have further subdivisions such that we end up with Level 0, 1, 2, 3 or more requesters. This document makes no assumption on the number of levels.

Even though we talk about a chain of trust model, the actual representation is as we have seen above a compounded metadata statement. The innermost metadata statement in the nest of metadata statements is the one that the FO has signed. That statement MUST NOT contain any references to other metadata statements. See simple signed metadata above. All other metadata statements in the nest MUST contain at least one reference to another metadata statement. An example of this is can be seen in .

These are the steps that are performed to construct a signed metadata statement. A metadata signing request may be about one specific entity or a group of similar entities. The requester constructs a signing request by collecting the necessary relying party or provider metadata as described in . If this is about the top most metadata statement (ms_0) then no metadata statement will be added to the metadata statement. If it is a more specific metadata statement (ms_1...n) then more general metadata statement/-s MUST be added. Dependent on setup the metadata statement can be added by the requester or the signer. The metadata statement is transported to the signing party. In the case of ms_0 this MUST be the FO. If it is ms_1 it is the L0Req. If it is ms_2 it is the L1Req and so on. The signing party verifies the information in the metadata statement, modifies and/or adds more information according to the policy before signing the statement. Once signed by the signer the signed metadata is sent back to the requester. An example of the construction of a compounded metadata statement. The Level 0 Requester (L0Req) sends a metadata statement request to the federation operator (FO).

FO ]]>

The FO verifies the information and if the federations policy so demands may add extra information. After signing with the FO's signing key the signed metadata statement is returned to the L0Req.

Next step that happens some time later is that the L1Req sends a Metadata Statement signing request to the L0Req.

L0Req ]]>

The L0Req verifies the information in the request and adds the signed L0Req metadata. The L0Req may also add other information to the Metadata Statement before it signs and returns it to the L1Req.

This was an example using 3 levels. As said before this document makes no assumption as to how many levels should be used.

Verifying a metadata statement, you first grab the innermost signed metadata statement. If this is signed by a FO, you have the public part of the signing keys from then you can verify the signature of the metadata statement. If the verification concludes that the signature was correct you can now take the signing keys that were included in the signed document and use those to verify the second innermost signed metadata statement. And so on. Verifying the received metadata statement involves running a function similar to this:

where the function get_payload unpacks the payload from the JWS without verifying the signature. The function verify_signature, on the other hand, does verify the signature of the JWS and if everything is correct returns the JWS payload.

Once you have a verified compounded metadata statement, you have to flatten it to get a useful metadata statement. To do this you can, for instance, use the method outlined in

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) Registration -----> | 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 OP MUST publish its provider metadata as specified by OpenID Connect Discovery 1.0. The RP makes a standard OpenID Provider Configuration Request. The OP responds with its provider configuration and the additional metadata parameters specified above. The OP SHOULD have the complete response signed by its superior in the signing chain and MAY have them signed in advance.

The OP MUST support dynamic relying party registration as described in OpenID Connect Dynamic Client Registration 1.0 . The RP makes a Client Registration Request including the additional metadata specified above. The RP SHOULD have the complete request signed by its superior in the signing chain and MAY have it signed in advance.

It is unlikely that an OP can prepare a number of signed Metadata statements representing relying party registration responses in advance. Still if the OP wants to have the whole response signed it has two choices. Either the superior signer has a service that can sign statements on-the-fly or the OP signs it itself. If the later the OP needs to have a blank (only containing signing_keys) metadata statement signed by the superior. Once it has that it can sign the response plus the signed metadata statement and construct a compounded metadata statement that can be verified using the method described in .

This draft allows any entity to belong to more than one federation. During the provider discovery and relying party registration processes, the parties have to agree on which federation to use. Ultimately, the OP decides. The relying party asks for the provider information The OP, using some rule, may publish one or several metadata_statements. If it publishes more than one metadata_statements, then they SHOULD be rooted in different federations. Based on what the OP published, the RP publishes a number of metadata_statements, all rooted in federations that the OP belongs to. If the RP published more than one metadata_statements, then the OP should/must choose one and make that known in the relying party registration response. One way of doing this is described in .

An organization may be a member of more than one federation. The RPs it is responsible for may be members of one or more of these. This is then how to deal with this. The organization registers and gets metadata signed by each federation. One extreme is that it will mint a new key pair for each federation, the other is that it will use the same key pair for all federations. It does not matter which it chooses, but the end result MUST be that there is one signed RP registration request per signing key. This is then published using metadata_statement_uris or metadata_statements.

The following is a non-normative example of an absolutely minimal relying party registration request sent to an OP:

As described above, when the OP receives a request like this it will choose which federation it will work within and then signal that by only returning that corresponding information in the metadata_statements / metadata_statement_uris in the registration response.

The following is a non-normative example of an OP's response on the relying party registration request above:

An OP has the choice of whether it wants one key pair per federation, one key pair for everyone, or anything in between. And, like the RP owner, it has to produce one signed metadata statement per key used.

The following is a non-normative example of an OP's response to a provider configuration request:

There are a number of timeouts that MUST considered: Each signature has a timeout. A relying party registration has a timeout. Taking this into consideration, an OP MUST NOT assign a lifetime to a relying party registration that exceeds the lifetime of the metadata statement signatures.

Heather Flanagan Andreas Åkre Solberg 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

The metadata for a specific entity can be constructed by starting with the information in ms_0 and then adding the information in ms_1 to ms_n using the following rule: Given two metadata statements ms_i and ms_j (j > i, i=0, ..., n-1, j=1, ..., n) For every claim in ms_j: If the claim does not appear in ms_i add it to ms_i. If the claim appears in ms_i then replace the value of the claim in ms_i 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_i else an error MUST be generated. 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 also 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. A dictionary A is a subset of a 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_0

ms_1

ms_2

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

sum(ms_0...2)

The story is that the organization UNINETT has applied and been accepted as a member of two federations: Feide and SWAMID. Now UNINETT is running a service (Foodle) that needs signed metadata statements to prove that it belongs to the federation that the OP belongs to when a user of the Foodle service wants to log in using an OP that belongs to either or both of the federations.

Now is the time to construct the signed metadata statements and get them signed by the federations. We'll start with Feide and UNINETT

UNINETT Metadata Statement request

UNINETT sends the Metadata statement signing request to Feide and Feide adds claims representing the Feide federation policy.

SUNET gets the same signing request as Feide got but adds a different set of policy claims.

Now UNINETT sits with two signed metadata statements one for each of the federations it belongs to

Time to create the Foodle (RP) metadata statement. We take a road similar to the request/request_uri path. That is, we include all the information about the relying party that needs to be protect from tampering by a MITM and places it in the metadata statement signing request. But first Foodle needs its own signing keys, not for signing Metadata Statements but for signing the JWKS document found at the URI pointed to by jwks_uri. It is vital to protect this key information from tampering since a lot of the security of the future OIDC communication will depend on the correctness of the keys found at the jwks_uri.

Foodle gets a key pair for signing the JWKS documents

Client Registration request

The Client Registration Request is sent to UNINETT who adds the two signed metadata statements it has. One for each of SWAMID and Feide. Since it knows that it is the Foodle RP which is the subject of the JWT it adds Foodle's identifier as 'sub'.

With SWAMID as Federation operator:

With Feide as Federation operator

Now, when Foodle wants to register as a relying party with an OP it adds the signed Metadata statement it received from UNINETT to the relying party registration request. Note that 'redirect_uri' MUST be in the registration request as this is required by the OIDC standard. If the 'redirect_uris' values that are transferred unprotected were to differ from what's in the signed metadata statement, the OP MUST refuse the registration.

Registration Request published by RP

An OP that has the public part of the signing keys for both the SWAMID and Feide federations can now verify the signature chains all the way from the Metadata statement signed by UNINETT up to the FOs. If that works, it can then flatten the compounded metadata statements.

The following open issues remain to be addressed in this specification. How are federation operator keys retrieved? A mechanism is needed for key rotation of federation operator keys for long-term security and maintainability of federations. A mechanism is needed for key revocation. A mechanism may be needed for bounding key lifetimes. What is the syntax for federation identifiers? Is it the URL of the root of the federation operator's metadata? Can both metadata_statements and metadata_statement_uris be present or are they mutually exclusive? How are signature timeouts represented? What happens after the timeout is expired? Consider adding rationale explaining the rule "The number A is a subset of the number B if A is less or equal to B". Why is the Constructing Entity Metadata appendix not normative? I believe that it should be. Change section titles "*** ***" to something meaningful.

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 ]] -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.