Draft N. Sakimura NRI J. Bradley Independent M. Jones Microsoft February 27, 2012 OpenID Connect Dynamic Client Registration 1.0 - draft 09 Abstract OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and RESTful manner. This specification describes how an OpenID Client can obtain the necessary client credentials required by the OpenID Connect protocol suite. Sakimura, et al. [Page 1] OpenID Connect Registration 1.0 draft 09 February 2012 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Client Registration Endpoint . . . . . . . . . . . . . . . . . 4 2.1. Client Registration Request . . . . . . . . . . . . . . . 4 2.1.1. sector_identifier_url Verification . . . . . . . . . . 7 2.2. Client Registration Response . . . . . . . . . . . . . . . 8 2.3. Client Registration Error Response . . . . . . . . . . . . 9 3. String Operations . . . . . . . . . . . . . . . . . . . . . . 10 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 6. Normative References . . . . . . . . . . . . . . . . . . . . . 13 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14 Appendix B. Notices . . . . . . . . . . . . . . . . . . . . . . . 15 Appendix C. Document History . . . . . . . . . . . . . . . . . . 16 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19 Sakimura, et al. [Page 2] OpenID Connect Registration 1.0 draft 09 February 2012 1. Introduction In order for an OpenID Connect Client to utilize OpenID services for a user, the Client needs to register with the OpenID Provider to acquire a Client ID and shared secret. This document describes how a new Client can register with the provider, and how a Client already in possession of a "client_id" can retrieve updated registration information. The Client Registration Endpoint may be co-resident with the token endpoint as an optimization in some deployments. 1.1. Requirements Notation and Conventions 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 [RFC2119]. Throughout this document, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value. 1.2. Terminology This specification uses the terms "Access Token", "Refresh Token", "Authorization Code", "Authorization Grant", "Authorization Server", "Authorization Endpoint", "Client", "Client Identifier", "Client Secret", "Protected Resource", "Resource Owner", "Resource Server", and "Token Endpoint" defined by OAuth 2.0 [OAuth2.0], and the terms defined by OpenID Connect Messages 1.0 [OpenID.Messages]. It defines no additional terms. Sakimura, et al. [Page 3] OpenID Connect Registration 1.0 draft 09 February 2012 2. Client Registration Endpoint The Client Registration Endpoint is an OAuth 2.0 Protected Resource that returns registration information for the Client to configure itself for the OpenID Provider. The OpenID Provider may require an Access Token that is provisioned out-of-band (in a manner that is out of scope for this specification) in order to restrict registration requests to only authorized Clients. In order to support open registration, the Client Registration Endpoint SHOULD accept requests without OAuth 2.0 Access Tokens. If an Access Token is required for Client registration, the Client Registration Endpoint MUST be able to accept Access Tokens in the manner described in the Bearer Tokens [OAuth.Bearer] specification. 2.1. Client Registration Request Clients MUST send requests encoded as a POST with the following parameters added to the HTTP request entity-body using "application/ x-www-form-urlencoded" format: type REQUIRED. Values "client_associate" (New Registrations), "client_update" (Updating parameters for an existing "client_id"). client_id OPTIONAL. The registered parameters for this "client_id" are updated. Used with "client_update". client_secret OPTIONAL. The "client_secret" used to authenticate requests that have "client_update" as the value of the "type" parameter. access_token OPTIONAL. An Access Token obtained out of band to authorize the registrant. This parameter is only used if the Client is provided the Access Token out of band. This parameter MUST NOT be sent if the Access Token is sent in the HTTP Authorization header as described in Section 7.1 of OAuth 2.0 [OAuth2.0]. Access Tokens sent in the authorization header must be Bearer Tokens [OAuth.Bearer]. contacts OPTIONAL. Space delimited list of email addresses for people allowed to administer the information for this Client. This is used by some providers to enable a web UI to modify the Client information. Sakimura, et al. [Page 4] OpenID Connect Registration 1.0 draft 09 February 2012 application_type OPTIONAL. "native" or "web". application_name OPTIONAL. Name of the Client to be presented to the user. logo_url OPTIONAL. The URL of a logo image for the Client where it can be retrieved. redirect_uris RECOMMENDED for Clients using the "code" flow with a query parameter encoded response. REQUIRED for Clients requesting implicit flow fragment encoded responses as defined in OAuth 2.0 [OAuth2.0]. A space-delimited list of redirect URIs. One of the URL MUST match the Scheme, Host, and Path segments of the "redirect_uri" in the authorization request. token_endpoint_auth_type OPTIONAL. The requested authentication type for the Token Endpoint. The options are "client_secret_post", "client_secret_basic", "client_secret_jwt", and "private_key_jwt", as described in Section 2.2.1 of OpenID Connect Messages 1.0 [OpenID.Messages]. Other Authentication methods may be defined by extension. If unspecified or omitted, the default is "client_secret_basic" HTTP Basic Authentication Scheme as specified in section 2.3.1 of OAuth 2.0 [OAuth2.0]. policy_url OPTIONAL. A URL location that the Relying Party Client provides to the End-User to read about the how the profile data will be used. The OpenID Provider SHOULD display this URL to the End-User if it is given. jwk_url OPTIONAL. URL for the Client's JSON Web Key [JWK] document that is used for JWS [JWS] signing of Token Endpoint Requests and OpenID Request Objects. If "jwk_encryption_url" is not provided it is also used for JWE [JWE] encryption of ID Token and User Info Endpoint Responses to the Client. If the Client registers both "x509_url" and "jwk_url", the keys contained in both formats SHOULD be the same. jwk_encryption_url OPTIONAL. URL for the Client's JSON Web Key [JWK] that is used for JWE [JWE] encryption of ID Token and User Info Endpoint Responses to the Client. If the Client registers both "jwk_encryption_url" and "x509_encryption_url", the keys contained in both formats SHOULD be the same. x509_url OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or Certificate chain that is used for JWS [JWE] signing of Token Endpoint Requests and OpenID Request Objects. If "x509_encryption_url" is not provided, "x509_url" it is also used for JWE [JWE] encryption of ID Token and User Info Endpoint Sakimura, et al. [Page 5] OpenID Connect Registration 1.0 draft 09 February 2012 Responses to the Client. If the Client registers both "x509_url" and "jwk_url", the keys contained in both formats SHOULD be the same. x509_encryption_url OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or Certificate chain that is used for JWE [JWE] encryption of ID Token and User Info Endpoint Responses to the Client. If the Client registers both "jwk_encryption_url" and "x509_encryption_url", the keys contained in both formats SHOULD be the same. sector_identifier_url OPTIONAL. A HTTPS scheme URL to be used in calculating Pseudonymous Identifiers by the OP. The URL contains a file with a single JSON array of "redirect_uri" values. Please see Section 2.1.1 (Section 2.1.1). user_id_type OPTIONAL. The "user_id_type" requested for responses to this "client_id". The "user_id_types_supported" element of discovery contains a list of the supported "user_id_type" values for this server. Valid types include "pairwise" and "public". require_signed_request_object OPTIONAL. The JWS [JWS] signature algorithm that MUST be required by the Authorization Server. All OpenID Request Objects from this "client_id" MUST be rejected if not signed by this algorithm. userinfo_signed_response_algs OPTIONAL. The JWS [JWS] signature algorithm required for UserInfo responses. If this is specified the response will be JWT [JWT] serialized, and signed using JWS [JWS]. userinfo_encrypted_response_algs OPTIONAL. A space delimited list of the JWE [JWE] "alg" and "enc" algorithms required for UserInfo responses. If this is requested in combination with signing the response will be signed then encrypted. If this is specified the response will be JWT [JWT] serialized, and encrypted using JWE [JWE]. id_token_signed_response_algs OPTIONAL. The JWS [JWS] signing algorithm required for the ID Token issued to this "client_id". The default if not specified is "HS256" using the provided "client_secret". id_token_encrypted_response_algs OPTIONAL. A space delimited list of the JWE [JWE] "alg" and "enc" algorithms required for the ID Token issued to this "client_id". If this is requested the response will be signed then encrypted. The default if not specified is no encryption. Sakimura, et al. [Page 6] OpenID Connect Registration 1.0 draft 09 February 2012 default_max_age OPTIONAL. (default max authentication age): Type: Integer - Specifies that the End-User must be actively authenticated if any present authentication is older than the specified number of seconds. (The "max_age" request parameter corresponds to the OpenID 2.0 PAPE "max_auth_age" request parameter.) The "max_age" claim in the request object overrides this default value. require_auth_time OPTIONAL. (default max authentication age): Type: Logical - If the value is true, then the "auth_time" claim in the "id_token" is REQUIRED. The returned Claim Value is the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/ time that the End-User authentication occurred. (The auth_time Claim semantically corresponds to the OpenID 2.0 PAPE auth_time response parameter.) The auth_time claim request in the request object overrides this setting. default_acr OPTIONAL. (default authentication context class reference): Type: String - Specifies the default value that the Authorization server must use for processing requests from this client. The " acrs_supported" element of discovery contains a list of the supported "acr" values for this server. The "acr" claim in the request object overrides this default value. Following is a non-normative example request: POST /connect/register HTTP/1.1 Accept: application/x-www-form-urlencoded Host: server.example.com type=client_associate &redirect_uris=https://client.example.com/callback%20https://client.example.com/callback2 &logo_url=https://client.example.com/logo.png &user_id_type=pairwise §or_identifier_url=https://othercompany.com/file_of_redirect_uris_for_our_sites.js &token_endpoint_auth_type=client_secret_basic &jwk_url=https://client.example.com/my_rsa_public_key.jwk &userinfo_encrypted_response_algs=RSA1_5%20A128CBC 2.1.1. sector_identifier_url Verification Providers who use pairwise "user_id" values SHOULD support this element. It provides a way for a group of websites under a single administrative control to have consistent pairwise "user_id" values independent of the individual domain names. It also provides a way for Clients to change "redirect_uri" domains without having to Sakimura, et al. [Page 7] OpenID Connect Registration 1.0 draft 09 February 2012 reregister all of their users. This is further described in Section 2.1.1.1.1 of OpenID Connect Messages 1.0 [OpenID.Messages]. The value of the "sector_identifier_url" must be a HTTPS scheme URL that identifies a JSON file containing an array containing "redirect_uri" values. The Registration Server MUST perform a TLS/ SSL server certificate check, per RFC 6125 [RFC6125]. The values of the registered "redirect_uris" must be included in the elements of the array, or registration MUST fail. GET /connect/sector_identifier.js HTTP/1.1 Accept: application/json Host: client.example.com HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache [ "https://client.example.com/callback", "https://client.example.com/callback2", "https://client.other_company.com/callback" ] 2.2. Client Registration Response The response is returned as a JSON object with all the parameters as top level elements. client_id REQUIRED. The unique Client identifier. client_secret REQUIRED. The Client secret. This should change with each response. expires_at REQUIRED. The number of seconds from 1970-01-01T0:0:0Z as measured in UTC that the "client_id" and "client_secret" will expire or "0" if they do not expire. See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular. Following is a non-normative example response: Sakimura, et al. [Page 8] OpenID Connect Registration 1.0 draft 09 February 2012 HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "client_id":"s6BhdRkqt3", "client_secret":"cf136dc3c1fd9153029bb9c6cc9ecead918bad9887fce6c93f31185e5885805d", "expires_at":2893276800 } 2.3. Client Registration Error Response When an error condition occurs, the Client Registration Endpoint returns an Error Response as defined in Section 3 of the OAuth 2.0 Bearer Tokens [OAuth.Bearer] specification. In addition to the error codes defined in Section 3.1 of OAuth 2.0 Bearer Tokens [OAuth.Bearer], this specification defines the following error codes: invalid_type The value of "type" is invalid or not supported. invalid_client_id The value of "client_id" is invalid. invalid_client_secret The "client_secret" provided for a "client_update" is not valid for the provided "client_id". invalid_configuration_parameter The value of one of the configuration parameters is invalid. Following is a non-normative example of an error response: HTTP/1.1 400 Bad Request WWW-Authenticate: Bearer realm="example.com", error="invalid_client_secret", error_description="The client_secret is wrong for this client_id" Sakimura, et al. [Page 9] OpenID Connect Registration 1.0 draft 09 February 2012 3. String Operations Processing some OpenID Connect messages requires comparing values in the messages to known values. For example, the member names in the Client registration response might be compared to specific member names such as "client_id". Comparing Unicode strings, however, has significant security implications. Therefore, comparisons between JSON strings and other Unicode strings MUST be performed as specified below: 1. Remove any JSON applied escaping to produce an array of Unicode code points. 2. Unicode Normalization [USA15] MUST NOT be applied at any point to either the JSON string or to the string it is to be compared against. 3. Comparisons between the two strings MUST be performed as a Unicode code point to code point equality comparison. In several places, this specification uses space delimited lists of strings. In all such cases, only the ASCII space character (0x20) MAY be used for this purpose. Sakimura, et al. [Page 10] OpenID Connect Registration 1.0 draft 09 February 2012 4. IANA Considerations This document makes no requests of IANA. Sakimura, et al. [Page 11] OpenID Connect Registration 1.0 draft 09 February 2012 5. Security Considerations Since requests to the Client Registration Endpoint result in the transmission of clear-text credentials (in the HTTP request and response), the server MUST require the use of a transport-layer security mechanism when sending requests to the Registration Endpoint. The server MUST support TLS 1.2 RFC 5246 [RFC5246] and/or TLS 1.0 [RFC2246] and MAY support additional transport-layer mechanisms meeting its security requirements. When using TLS, the Client MUST perform a TLS/SSL server certificate check, per RFC 6125 [RFC6125]. Requests to the Registration Endpoint for "client_update" MUST have some rate limiting on failures to prevent the Client secret from being disclosed though repeated access attempts. In a situation where the Authorization Server is supporting open Client registration, it must be extremely careful with any URL provided by the Client that will be displayed to the user (e.g. "logo_url" and "policy_url"). A rogue Client could specify a registration request with a reference to a drive-by download in the "policy_url". The Authorization Server should check to see if the "logo_url" and "policy_url" have the same host as the hosts defined in the array of "redirect_uris". Sakimura, et al. [Page 12] OpenID Connect Registration 1.0 draft 09 February 2012 6. Normative References [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web Encryption (JWE)", January 2012. [JWK] Jones, M., "JSON Web Key (JWK)", January 2012. [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature", January 2012. [JWT] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, "JSON Web Token", December 2011. [OAuth.Bearer] Jones, M., Hardt, D., and D. Recordon, "OAuth 2.0 Protocol: Bearer Tokens", February 2012. [OAuth2.0] Hammer, E., Ed., Recordon, D., and D. Hardt, "OAuth 2.0 Authorization Protocol", January 2012. [OpenID.Messages] Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, "OpenID Connect Messages 1.0", February 2012. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999. [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, March 2011. [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode Normalization Forms", Unicode Standard Annex 15, 09 2009. Sakimura, et al. [Page 13] OpenID Connect Registration 1.0 draft 09 February 2012 Appendix A. Acknowledgements Sakimura, et al. [Page 14] OpenID Connect Registration 1.0 draft 09 February 2012 Appendix B. Notices Copyright (c) 2011 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 (i) solely for the purposes of developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to OIDF as the source of the material, but that such attribution does not indicate the endorsement by 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. OpenID 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. Sakimura, et al. [Page 15] OpenID Connect Registration 1.0 draft 09 February 2012 Appendix C. Document History [[ To be removed from the final specification ]] -09 o Removed erroneous spanx declarations from example o Fixed example in Sec 2.2 to show expires_at o Fixed Sec 2.1.1 to clarify it is the registration server doing the certificate check o Fixed Sec 2.1.1 example to include http portion of response o Fixed #542 Sec 2.1 userinfo_signed_response_algs fixed to say signature. Clarify response is signed. o Fixed Sec 2.1 userinfo_encrypted_response_algs Clarify response is JWE containing JWT o Fixes #529 Sec 2.3 Clarify error response is Bearer and fix example o Add default_max_age registration parameter o Add default_acr registration parameter o Add require_auth_time registration parameter -08 o Replaced token_endpoint with a defined term Token Endpoint [OAuth 2.0] o Added policy_url parameter o Renamed expires_in but expires_at o Registration Endpoint can be OAuth Protected o Added parameters for requiring encryption and/or signing of OpenID Request Object, UserInfo and ID Token o Added token_endpoint_auth_type and list of valid authentication types Sakimura, et al. [Page 16] OpenID Connect Registration 1.0 draft 09 February 2012 o Added JWK and X509 URLs for signature and encryption o Added user_id_type o Changed sector_identifier to sector_identifier_url and added URL verification o Use RFC 6125 to verify TLS endpoints o Changed 'contact' to 'contacts', 'redirect_uri' to 'redirect_uris' o Changed redirect_uris to RECOMMENDED for code flow and REQUIRED for implicit flow Clients o Removed js_origin_uri o Added section about string comparison rules needed o Clarified redirect_uris matching o Update John Bradley email and affiliation for Implementer's Draft -07 o Changed request from posting a JSON object to being HTTP Form encoded. o Added x509_url to support optional encryption. -06 o Changes associated with renaming "Lite" to "Basic Client" and replacing "Core" and "Framework" with "Messages" and "Standard". o Numerous cleanups, including updating references. -05 o Changed "redirect_url" to "redirect_uri" and "js_origin_url" to "js_origin_uri". -04 o Correct issues raised by Johnny Bufu and discussed on the 7-Jul-11 working group call. -03 Sakimura, et al. [Page 17] OpenID Connect Registration 1.0 draft 09 February 2012 o Incorporate working group decisions from 5-Jul-11 spec call. o Consistency and cleanup pass, including removing unused references. -02 o Incorporate working group decisions from 23-Jun-11 spec call. -01 o Initial version. Sakimura, et al. [Page 18] OpenID Connect Registration 1.0 draft 09 February 2012 Authors' Addresses Nat Sakimura Nomura Research Institute, Ltd. Email: n-sakimura@nri.co.jp John Bradley Independent Email: ve7jtb@ve7jtb.com Michael B. Jones Microsoft Email: mbj@microsoft.com Sakimura, et al. [Page 19]