Draft N. Sakimura NRI J. Bradley, Ed. Protiviti M. Jones Microsoft July 12, 2011 OpenID Connect Dynamic Client Registration 1.0 - draft 04 Abstract OpenID Connect is an identity protocol that provides authentication, authorization, and attribute transmission capability. It allows third party attested claims from distributed sources. The specification suite party attested claims from distributed sources. The specification suite consists of Core, UserInfo, Protocol Bindings, Discovery, Dynamic Client Registration, Session Management, and Framework. This specification is the "Dynamic Client Registration" part of the suite that defines how clients register with OpenID Providers. Sakimura, et al. [Page 1] OpenID Connect Client Registration 1.0 - draft 04 July 2011 Requirements Language 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]. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Client Registration Endpoint . . . . . . . . . . . . . . . . . 6 4.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 6 4.2. Response . . . . . . . . . . . . . . . . . . . . . . . . . 7 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 7. Normative References . . . . . . . . . . . . . . . . . . . . . 10 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 Appendix B. Document History . . . . . . . . . . . . . . . . . . 12 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 Sakimura, et al. [Page 2] OpenID Connect Client Registration 1.0 - draft 04 July 2011 1. Introduction In order for an OpenID Connect [OpenID.Core] 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. Sakimura, et al. [Page 3] OpenID Connect Client Registration 1.0 - draft 04 July 2011 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" that are defined by OAuth 2.0 [OAuth.2.0], and the terminology defined in the OpenID Connect Core 1.0 [OpenID.Core] specification. Sakimura, et al. [Page 4] OpenID Connect Client Registration 1.0 - draft 04 July 2011 3. Discovery OpenID Connect uses the registration_endpoint from the Provider Configuration Response Sec 4.2 [OpenID.Discovery]. Sakimura, et al. [Page 5] OpenID Connect Client Registration 1.0 - draft 04 July 2011 4. Client Registration Endpoint The Client Registration Endpoint returns registration information for the client to configure itself for the OpenID Provider. 4.1. Request Clients MUST send requests encoded as POST with the following encoded as top level elements of a JSON object: type REQUIRED. Values "client_associate", "client_update" client_id OPTIONAL. Used with "client_update" client_secret OPTIONAL. Used with "client_update" contact OPTIONAL. JSON Array of e-mail addresses for people allowed to administer the application. application_type OPTIONAL. "native" or "web" application_name OPTIONAL. Name of the application to be presented to the user. logo_url OPTIONAL. URL that a logo for the application can be retrieved from. redirect_url OPTIONAL. JSON Array of redirect URL js_origin_url OPTIONAL. JSON Array of Java Script Origins (used for Post Message flow) jwk_url OPTIONAL. URL for the RP's JSON Web Key [JWK] sector_identifier OPTIONAL URL to be used in calculating Pseudonymous Identifiers by the OP. The URL contains a file with an array of redirect_url POST /connect/register HTTP/1.1 Accept: application/json Host: server.example.com { "type": "client_associate", "redirect_uri": ["https://client.example.com/callback", "https://client.example.com/callback2"], "logo_url" : "https://client.example.com/logo.png" } Sakimura, et al. [Page 6] OpenID Connect Client Registration 1.0 - draft 04 July 2011 4.2. 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_in REQUIRED. The number of seconds that this id and secret are good for or "0" if it does not expire. The following is an example response. HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "client_id":"SlAV32hkKG", "client_secret":"cf136dc3c1fd9153029bb9c6cc9ecead918bad9887fce6c93f31185e5885805d", "expires_in":3600 } Sakimura, et al. [Page 7] OpenID Connect Client Registration 1.0 - draft 04 July 2011 5. IANA Considerations This document makes no request of IANA. Sakimura, et al. [Page 8] OpenID Connect Client Registration 1.0 - draft 04 July 2011 6. 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 token endpoint. The server MUST support TLS 1.2 as defined in [RFC5246], and MAY support additional transport-layer mechanisms meeting its security requirements. Sakimura, et al. [Page 9] OpenID Connect Client Registration 1.0 - draft 04 July 2011 7. Normative References [JWK] Jones, M., "JSON Web Key (JWK)", April 2011. [OAuth.2.0] Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "OAuth 2.0 Authorization Protocol", July 2011. [OpenID.Core] Recordon, D., Sakimura, N., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, "OpenID Connect Core 1.0", July 2011. [OpenID.Discovery] Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0", July 2011. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Sakimura, et al. [Page 10] OpenID Connect Client Registration 1.0 - draft 04 July 2011 Appendix A. Acknowledgements Sakimura, et al. [Page 11] OpenID Connect Client Registration 1.0 - draft 04 July 2011 Appendix B. Document History [[ To be removed from the final specification ]] -04 o Correct issues raised by Johnny Bufu and discussed on the 7-Jul-11 working group call. -03 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 12] OpenID Connect Client Registration 1.0 - draft 04 July 2011 Authors' Addresses Nat Sakimura Nomura Research Institute, Ltd. Email: n-sakimura@nri.co.jp John Bradley (editor) Protiviti Government Services Email: jbradley@mac.com Michael B. Jones Microsoft Corporation Email: mbj@microsoft.com Sakimura, et al. [Page 13]