independent

roland@catalogix.se

Umea University

rebecka.gulliksson@umu.se

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 client credentials. During registration, the RP provides metadata about its services. 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. This document describes how a trusted third party can enhance the security between the OP and RP by providing additional integrity about their respective metadata. Using this approach, an attacker would have to obtain the private keys of the trusted third party, which would mitigate the risk of a compromised SSL connection.

The original specification of OpenID Connect defines how a Relaying Party and an OpenID Connect Provider dynamically can exchange information necessary for successful communication. One problem with using dynamic discovery and registration is that the information that is exchanged can not be easily verified as it is self-asserted. Software statements, as introduced by RFC 7591, is a possible choice for transferring verified data and trust in the data by using a trusted third party (that verifies and enforces some common policy) between clients and servers. This document describes how software statements can be used in dynamic client registration and provider discovery to transfer verified data and to create a trust in the information passed between the RP and OP that is independent on the usage of SSL.

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 inRFC 2119.

The trust model is based on chains of trust, linking together signing keys, represented as JWK Sets, usingJSON Web Signatures. The signature chain is rooted in the trusted third party's signature, and then built upon by the respective entity.   By verifying such signature chains, the entities can establish trust in the data verified by the trusted third party. Handling RP client registration is slightly more complex then dealing with OP configuration information and is therefor chosen as an example here. Players: Federation operator Developer Relying Party Admin

The Federation Operator (FO) acting as the trusted third part. The FO must have a globally unique identifier. It will publish a JWK Set, containing the signing keys that the FO will use for signing developer metadata, at a HTTPS URL which server certificate MUST appear in a well-known Certificate Transparency log. The FO will if the federation policy allows it sign a partial client registration request provided by the developer. There are several ways that the developer can use to make the registration request available to the. One that we recommend is that the developer publishes the request at an URLa where the FO can fetch it. The FO can add claims, representing federation policies, to the registration request before constructing a software statement and signing it. The signed software statement is returned to the developer.

The developer represents the organization responsible for the relying party (RP). The developer will create a client registration request that as an example can contain information pertaining to the organization. To the request it will add an extra parametersigning_key, that will contain a JWK representation of the public key that corresponds to the private key it will use to sign the registration request that the relying part admin constructs.

The Relying Party Admin (RPA) is the entity responsible for a specific RP. This entity will construct a client registration request containing claims specific to the RP. To this registration request it will add an extra parametersigning_key, that will contain a JWK representation of the public key that corresponds to the private key it will use to sign the JWK Set that represents the keys it will use in the OpenID Connect communication. The registration request will be sent to the developer who will add the, by the FO constructed, software statement before signing the RPs registration request.

The key chain from top to bottom: the federations key, the developers key signed by the federation and the RP's key signed by the developers key

It is assumed that an organization will only run one OpenID Connect Provider (OP). We can therefor dispens of the intermediate, the developer, from the schema described above. This leaves us with the FO and the OP Admin. The OP Admin (OPA) will create a Provider configuration and notify the FO about where and when it can be fetched. The Provider configuration is extended with one parameter signing_key where the OPA will publish the key it will use to sign the JWK Set used in the OIDC communication. The FO will if the federation policy allows it sign the Provider Configuration information. The FO can add claims, representing federation policies, to the Provider Configuration informaion before constructing the software statement, signing it and returning the software statement to the OPA. This software statement will later be part of a Provider Configuration response.

The trust between the entities is established using the above described extensions in the first tree 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 | | | <--- 3) Authentication ---> | | ------ ------ ]]> 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).

These extra metadata parameters appear in both Provider Configuration Discovery and Client Registration: OPTIONAL. Location of the entity's signed JWKS, SHOULD return the Content-Type "application/jose" to indicate that the JWKS is in the form of a JWS using the JWS Compact Serialization. OPTIONAL. A JWS representing the public part of the entity's key. OPTIONAL. A list of software statements. OPTIONAL. A JSON object where the member names are the issuer identifiers of the entity that has signed the software statement and the values are URLs pointing to the corresponding software statements.

The following is a non-normative example of a RP registration request after that the developer has added links to the relevant software statements:

For the pairs: software_statements/software_statements_uri and signed_metadata/signed_metadata_uri one and only one parameter from the pair MUST be present. Along the same lines 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.

Any parameters that the federation adds to the software statement that also appears in the Provider Configuration response (OpenID Connect Discovery 1.0 or in a Client Registration request (OpenID Connect Dynamic Client Registration 1.0) will override what ever value the same parameter has in the transferred metadata. The only exception is when the information provided by the RP/OP is a subset of what the developer/FO has specified.

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 MUST support dynamic client registration as described in OpenID Connect Dynamic Client Registration 1.0 . The RP makes a Client Registration Request including the additional metadata specified above.

A developer may be a member of more the one federation and the RPs it is responsible for may be members of one or more of these. This is then how to deal with this. The developer 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 really doesn't 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 software_statement_uris or software_statements.

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

When the OP receives a request like this it will chose which federation it will work within and then signal that by only return that entry in the software_statements/software_statement_uris in the registration response.

The following is a non-normative example of an OPs response on the client registration request above:

An OP may likewise be member of several federations. As with the developer it has the choice of whether it wants one key pair per federation or one key pair for everyone or anything in between. And like the RP developer it has to produce one signed metadata statement per key used.

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

Upon receiving metadata from an RP this is what the OP has to do: The OP will have to unpack the metadata such that it can get at the software statement that is included. This is the software statement that the FO constructed and signed based on input from the developer. Having the FO's JWK Set it should be able to find a key that can be used to verify the signature on the software statement. Once it has verified the signature of the software statement it can use the signing key included in it to verify the signature of the metadata. If there is a signed_jwks_uri claim in the metadata then when it has verified the signature of the metadata it can use the signing key included in the metadata to verify the signature on the JWK Set it fetched from the URL defined insigned_jwks_uri.

It's easier for the RP since there is no intermediate involved in producing the signed metadata for the OP. This means that the RP can verify the signature of the metadata using a key in the FOs JWK Set. If the OP' metadata contains a signed_jwks_uri claim the RP can use the signing key included in the metadata to verify the signature of the JWK Set found at that URL.

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 necessary steps for adding a Relying Party to a federation The following JWKS represents the signing key that the Federation Operator is using in the following example:

Developer creates its signing key pair.

The developer submits registration data to Federation Operator (FO).

The FO returns a signed software statement containing the submitted registration data, and any applied policy restrictions like response_types, signing/encryption algorithms to be used and additional specific policy parameters like the ones specified above. This is an example of a software statement constructed by the FO before it is signed by the FO:

The signed version of this software statement, or a link to it, is then expected to be included in the RPs client registration request before being signed by the developers signing key.

The RP gets a signing key

The RP produces a client registration request

Developer produces software statement based on client registration request

and signs it. We now have the signed software statement aka the metadata that the RP will present to the OP

The RP sends a client registration request to the OP

The OP fetches the software statement from the URI 'https://dev.example.com/rp1/idfed/swamid.jws' and then goes about unpacking the metadata. At this point in time the OP doesn't have the necessary key to verify the signature of the metadata. Therefor it has to unpack the JWT without verifying the signature. It will then get a JSON document looking like whats listed in step 6 above. From this document it can extract the software statement which should be signed by a key belonging to the FO. The OP should have the fetched the public version of that key from the FO at some time prior to this. It can now verify the signature of the software statement and unpack the JWT. The JSON document it then gets is the one listed in step 3. The signing key specified in that document can now be extracted and used to verify the signature of the metadata. What's remaining now for the OP is to put all the pieces of the client registration request together. It will have one piece from the developer augmented with the federation policy and then another piece from the RP.

Copyright (c) 2016 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 approved specification ]] -00 Created openid-connect-federation-1_0-00 from draft-hedberg-oidc-fed-01.