Draft N. Sakimura NRI J. Bradley Ping Identity M. Jones Microsoft July 5, 2013 OpenID Connect Dynamic Client Registration 1.0 - draft 19 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 REST-like 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 July 2013 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 5 2.1. Metadata Languages and Scripts . . . . . . . . . . . . . . 9 3. Client Registration . . . . . . . . . . . . . . . . . . . . . 11 3.1. Client Registration Request . . . . . . . . . . . . . . . 11 3.2. Client Registration Response . . . . . . . . . . . . . . . 12 3.3. Client Registration Error Response . . . . . . . . . . . . 14 4. Client Configuration Endpoint . . . . . . . . . . . . . . . . 16 4.1. Forming the Client Configuration Endpoint URL . . . . . . 16 4.2. Client Read Request . . . . . . . . . . . . . . . . . . . 16 4.3. Client Read Response . . . . . . . . . . . . . . . . . . . 17 4.4. Client Read Error Response . . . . . . . . . . . . . . . . 18 5. "sector_identifier_uri" Validation . . . . . . . . . . . . . . 20 6. String Operations . . . . . . . . . . . . . . . . . . . . . . 21 7. Validation . . . . . . . . . . . . . . . . . . . . . . . . . . 22 8. Implementation Considerations . . . . . . . . . . . . . . . . 23 9. Security Considerations . . . . . . . . . . . . . . . . . . . 24 9.1. TLS Requirements . . . . . . . . . . . . . . . . . . . . . 24 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 11.1. Normative References . . . . . . . . . . . . . . . . . . . 26 11.2. Informative References . . . . . . . . . . . . . . . . . . 27 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 28 Appendix B. Notices . . . . . . . . . . . . . . . . . . . . . . . 29 Appendix C. Document History . . . . . . . . . . . . . . . . . . 30 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 Sakimura, et al. [Page 2] OpenID Connect Registration 1.0 July 2013 1. Introduction In order for an OpenID Connect Client to utilize OpenID services for an End-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 OP, and how registration information for the Client can be retrieved. The Client Registration Endpoint MAY be co-resident with the Token Endpoint as an optimization in some deployments. Note: This specification will likely be modified to use the OAuth 2.0 Dynamic Client Registration Protocol [I-D.ietf-oauth-dyn-reg] specification once it is stable. While currently self-contained, this specification intentionally uses the same syntax and identifiers as the OAuth Registration draft. As of the time of this writing, the two specifications are consistent with one another. 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. All uses of JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) [JWE] data structures in this specification utilize the JWS Compact Serialization or the JWE Compact Serialization; the JWS JSON Serialization and the JWE JSON Serialization are not used. 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 [RFC6749], and the terms defined by OpenID Connect Messages 1.0 [OpenID.Messages]. This specification defines the following additional terms: Sakimura, et al. [Page 3] OpenID Connect Registration 1.0 July 2013 Client Registration Endpoint OAuth 2.0 Protected Resource through which a Client can be registered at an Authorization Server. Client Configuration Endpoint OAuth 2.0 Endpoint through which registration information for a registered Client can be managed. This URL for this endpoint is returned by the Authorization Server in the Client Information Response. Registration Access Token OAuth 2.0 Bearer Token issued by the Authorization Server through the Client Registration Endpoint that is used to authenticate the caller when accessing the Client's registration information at the Client Configuration Endpoint. This Access Token is associated with a particular registered Client. Initial Access Token OAuth 2.0 Access Token optionally issued by an Authorization Server granting access to its Client Registration Endpoint. IMPORTANT NOTE TO READERS: The terminology definitions in this section are a normative portion of this specification, imposing requirements upon implementations. All the capitalized words in the text of this specification, such as "Client Registration Endpoint", reference these defined terms. Whenever the reader encounters them, their definitions found in this section must be followed. Sakimura, et al. [Page 4] OpenID Connect Registration 1.0 July 2013 2. Client Metadata Clients have metadata associated with their unique Client Identifier at the Authorization Server. These can range from human-facing display strings, such as a Client name, to items that impact the security of the protocol, such as the list of valid redirect URIs. Client Metadata values used by OpenID Connect are: redirect_uris REQUIRED. Array of redirection URI values used in the Authorization Code and Implicit grant types. One of these registered redirection URI values MUST exactly match the "redirect_uri" parameter value used in each Authorization Request, with the matching performed as described in Section 6.2.1 of [RFC3986] (Simple String Comparison). response_types OPTIONAL. JSON array containing a list of the OAuth 2.0 "response_type" values that the Client is declaring that it will restrict itself to using. If omitted, the default is that the Client will use only the "code" response type. grant_types OPTIONAL. JSON array containing a list of the OAuth 2.0 grant types that the Client is declaring that it will restrict itself to using. The grant type values used by OpenID Connect are: * "authorization_code": The Authorization Code Grant described in OAuth 2.0 Section 4.1. * "implicit": The Implicit Grant described in OAuth 2.0 Section 4.2. * "refresh_token": The Refresh Token Grant described in OAuth 2.0 Section 6. * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer grant type defined in OAuth JWT Bearer Token Profiles [OAuth.JWT]. The following table lists the correspondence between "response_type" values that the Client will use and "grant_type" values that MUST be included in the registered "grant_types" list: * "code": "authorization_code" * "id_token": "implicit" Sakimura, et al. [Page 5] OpenID Connect Registration 1.0 July 2013 * "token id_token": "implicit" * "code id_token": "authorization_code", "implicit" * "code token": "authorization_code", "implicit" * "code token id_token": "authorization_code", "implicit" If omitted, the default is that the Client will use only the "authorization_code" grant type. application_type OPTIONAL. Kind of the application. The default if not specified is "web". The defined values are "native" or "web". Web Clients using the OAuth implicit grant type MUST only register URLs using the "https" scheme as "redirect_uris"; they MUST NOT use "localhost" as the hostname. Native Clients MUST only register "redirect_uris" using custom URI schemes or URLs using the "http:" scheme with "localhost" as the hostname. Authorization Servers MAY place additional constraints on Native Clients. The Authorization Server MUST verify that all the registered "redirect_uris" conform to these constraints. This prevents sharing a Client ID across different types of Clients. contacts OPTIONAL. Array of e-mail addresses of people responsible for this Client. This might be used by some providers to enable a Web user interface to modify the Client information. client_name OPTIONAL. Name of the Client to be presented to the End-User. If desired, representation of this Claim in different languages and scripts is represented as described in Section 2.1. logo_uri OPTIONAL. URL that references a logo for the Client application. The value of this field MUST point to a valid image file. client_uri OPTIONAL. URL of the home page of the Client. The value of this field MUST point to a valid Web page. If present, the server SHOULD display this URL to the End-User in a followable fashion. If desired, representation of this Claim in different languages and scripts is represented as described in Section 2.1. token_endpoint_auth_method OPTIONAL. Requested authentication method 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 extensions. If unspecified or omitted, the default is "client_secret_basic" HTTP Basic Authentication Sakimura, et al. [Page 6] OpenID Connect Registration 1.0 July 2013 Scheme as specified in Section 2.3.1 of OAuth 2.0 [RFC6749]. policy_uri OPTIONAL. URL 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. tos_uri OPTIONAL. URL that the Relying Party Client provides to the End-User to read about the Relying Party's terms of service. The OpenID Provider SHOULD display this URL to the End-User if it is given. jwks_uri OPTIONAL. URL for the Client's JSON Web Key Set [JWK] document. If the Client signs requests to the Server, it contains the signing key(s) the Server uses to validate signatures from the Client. The JWK Set MAY also contain the Client's encryption keys(s), which are used by the Server to encrypt responses to the Client. When both signing and encryption keys are made available, a "use" (Key Use) parameter value is REQUIRED for all keys in the document to indicate each key's intended usage. OPTIONAL. sector_identifier_uri OPTIONAL. URL using the "https" scheme to be used in calculating Pseudonymous Identifiers by the OP. The URL references a file with a single JSON array of "redirect_uri" values. Please see Section 5. Providers that use pairwise "sub" (subject) values SHOULD provide a "sector_identifier_uri". subject_type OPTIONAL. "subject_type" requested for responses to this "client_id". The "subject_types_supported" element of discovery contains a list of the supported "subject_type" values for this server. Valid types include "pairwise" and "public". request_object_signing_alg OPTIONAL. JWS [JWS] "alg" algorithm [JWA] that MUST be used for requests to the Authorization Server. The valid values are listed in Section 3.1 of JWA [JWA]. All Request Objects from this "client_id" MUST be rejected if not signed by this algorithm. Servers SHOULD support "RS256". userinfo_signed_response_alg OPTIONAL. JWS "alg" algorithm [JWA] REQUIRED for UserInfo Responses. The valid values are listed in Section 3.1 of JWA [JWA]. If this is specified the response will be JWT [JWT] serialized, and signed using JWS. userinfo_encrypted_response_alg OPTIONAL. JWE [JWE] "alg" algorithm [JWA] REQUIRED for encrypting UserInfo Responses. The valid values are listed in Section 4.1 of JWA [JWA]. If this is requested in combination with signing the response will be signed then encrypted. If this is specified the response will be JWT Sakimura, et al. [Page 7] OpenID Connect Registration 1.0 July 2013 [JWT] serialized, and encrypted using JWE. userinfo_encrypted_response_enc OPTIONAL. JWE "enc" algorithm [JWA] REQUIRED for symmetric encryption of UserInfo Responses. The valid values are listed in Section 4.2 JWA [JWA]. If "userinfo_encrypted_response_alg" is specified the default for this value is "A128CBC-HS256". 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. id_token_signed_response_alg OPTIONAL. JWS "alg" algorithm [JWA] REQUIRED for the ID Token issued to this "client_id". The valid values are listed in Section 3.1 of JWA [JWA], with the exception of "none", which MUST NOT be used as the ID Token "alg" value. The default if not specified is "RS256". The public key for validating the signature is provided by retrieving the JWK Set referenced by the "jwks_uri" element from OpenID Connect Discovery 1.0 [OpenID.Discovery]. id_token_encrypted_response_alg OPTIONAL. JWE "alg" algorithm [JWA] REQUIRED for encrypting the ID Token issued to this "client_id". The valid values are listed in Section 4.1 of JWA [JWA]. If this is requested, the response will be signed then encrypted. The default, if not specified, is no encryption. id_token_encrypted_response_enc OPTIONAL. JWE "enc" algorithm [JWA] REQUIRED for symmetric encryption of the ID Token issued to this "client_id". The valid values are listed in Section 4.2 of JWA [JWA]. If "id_token_encrypted_response_alg" is specified, the default for this parameter is "A128CBC-HS256". 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. default_max_age OPTIONAL. Default Maximum Authentication Age. Specifies that the End-User MUST be actively authenticated if the End-User was authenticated longer ago than the specified number of seconds. The "max_age" request parameter overrides this default value. require_auth_time OPTIONAL. Boolean value specifying whether the "auth_time" Claim in the "id_token" is REQUIRED. It is REQUIRED when the value is "true". The "auth_time" Claim request in the Request Object overrides this setting. Sakimura, et al. [Page 8] OpenID Connect Registration 1.0 July 2013 default_acr_values OPTIONAL. Default requested Authentication Context Class Reference values. Array of strings that specifies the default "acr" values that the Authorization Server is being requested to use for processing requests from this Client, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the "acr" Claim Value in the issued ID Token. The "acr" Claim is requested as a Voluntary Claim by this parameter. The "acr_values_supported" discovery element contains a list of the supported "acr" values supported by this server. Values specified in the "acr_values" request parameter or an "acr" Claim request override these default values. initiate_login_uri OPTIONAL. URI using the "https" scheme that the Authorization Server can call to initiate a login at the Client. The URI MUST accept requests via both "GET" and "POST". The Client MUST understand the "login_hint" and "iss" parameters and SHOULD support the "target_link_uri" parameter. post_logout_redirect_uris OPTIONAL. Array of URLs supplied by the RP to which it MAY request that the End-User's User-Agent be redirected using the "post_logout_redirect_uri" parameter after a logout has been performed, as specified in OpenID Connect Session Management 1.0 [OpenID.Session]. request_uris OPTIONAL. Array of "request_uri" values that are pre- registered by the Client for use at the Authorization Server. Servers MAY cache the contents of the files referenced by these URIs and not retrieve them at the time they are used in a request. OPs can require that "request_uri" values used be pre-registered with the "require_request_uri_registration" discovery parameter. If the contents of the request file could ever change, these URI values SHOULD include the base64url encoded SHA-256 hash value of the file contents referenced by the URI as the value of the URI fragment. If the fragment value used for a URI changes, that signals the server that its cached value for that URI with the old fragment value is no longer valid. 2.1. Metadata Languages and Scripts Human-readable Client Metadata values and Client Metadata values that reference human-readable values MAY be represented in multiple languages and scripts. For example, values such as "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" might have multiple locale-specific values in some Client registrations. To specify the languages and scripts, BCP47 [RFC5646] language tags Sakimura, et al. [Page 9] OpenID Connect Registration 1.0 July 2013 are added to Client Metadata member names, delimited by a "#" character. The same syntax is used for representing languages and scripts for Client Metadata as is used for Claims, as described in Section 2.5.2 (Claims Languages and Scripts) of OpenID Connect Messages 1.0 [OpenID.Messages]. If such a human-readable field is sent without a language tag, parties using it MUST NOT make any assumptions about the language, character set, or script of the string value, and the string value MUST be used as-is wherever it is presented in a user interface. To facilitate interoperability, it is RECOMMENDED that any human- readable fields sent without language tags contain values suitable for display on a wide variety of systems. Sakimura, et al. [Page 10] OpenID Connect Registration 1.0 July 2013 3. Client Registration The Client Registration Endpoint is an OAuth 2.0 Protected Resource through which a Client can request a new registration and manage the Metadata associated with it. The OpenID Provider MAY require an Initial Access Token that is provisioned out-of-band (in a manner that is out of scope for this specification) to restrict registration requests to only authorized Clients. To support open registration, the Client Registration Endpoint SHOULD accept registration requests without OAuth 2.0 Access Tokens. These requests MAY be rate-limited or otherwise limited to prevent a denial-of-service attack on the Client Registration Endpoint. If an Initial Access Token is required for Client registration, the Client Registration Endpoint MUST be able to accept these Access Tokens in the manner described in the OAuth 2.0 Bearer Token Usage [RFC6750] specification. 3.1. Client Registration Request To register a new Client to the Authorization Server, the Client sends an HTTP "POST" message to the Client Registration Endpoint with any Client Metadata parameters that the Client chooses to specify for itself during the registration. The Authorization Server assigns this Client a unique Client Identifier, optionally assigns a Client Secret, and associates the Metadata given in the request with the issued Client Identifier. The Authorization Server MAY provision default values for any items omitted in the Client Metadata. The Client sends an HTTP "POST" to the Client Registration Endpoint with a content type of "application/json" and all parameters as top- level members of a JSON object. For example, a Client could send the following registration request to the Client Registration Endpoint: Sakimura, et al. [Page 11] OpenID Connect Registration 1.0 July 2013 The following is a non-normative example request (with line wraps within values for display purposes only): POST /connect/register HTTP/1.1 Content-Type: application/json Accept: application/json Host: server.example.com Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJ ... { "application_type": "web", "redirect_uris": ["https://client.example.org/callback", "https://client.example.org/callback2"], "client_name": "My Example", "client_name#ja-Jpan-JP": "クライアント名", "logo_uri": "https://client.example.org/logo.png", "subject_type": "pairwise", "sector_identifier_uri": "https://other.example.net/file_of_redirect_uris.json", "token_endpoint_auth_method": "client_secret_basic", "jwks_uri": "https://client.example.org/my_public_keys.jwks", "userinfo_encrypted_response_alg": "RSA1_5", "userinfo_encrypted_response_enc": "A128CBC-HS256", "contacts": ["ve7jtb@example.org", "mary@example.org"], "request_uris": ["https://client.example.org/rf.txt #qpXaRLh_n93TTR9F252ValdatUQvQiJi5BDub2BeznA"] } 3.2. Client Registration Response Upon successful registration, the Client Registration Endpoint returns the newly-created Client Identifier and, if applicable, a Client Secret, along with all registered Metadata about this Client, including any fields provisioned by the Authorization Server itself. The Authorization Server MAY reject or replace any of the Client's requested field values and substitute them with suitable values. If this happens, the Authorization Server MUST include these fields in the response to the Client. The response also contains a Registration Access Token that is used by the Client to perform subsequent operations upon the resulting Client registration. All of the response items are returned as a JSON document [RFC4627] with the following fields as top-level members of the root JSON Sakimura, et al. [Page 12] OpenID Connect Registration 1.0 July 2013 object. client_id REQUIRED. Unique Client identifier. It MUST NOT be currently valid for any other registered Client. client_secret OPTIONAL. Client secret. This MUST be unique for each "client_id". This value is used by Confidential Clients to authenticate to the Token Endpoint as described in OAuth 2.0 Section 2.3.1. It is not needed for Clients selecting a "token_endpoint_auth_method" of "private_key_jwt". registration_access_token REQUIRED. Access Token that is used at the Client Configuration Endpoint to perform subsequent operations upon the Client registration. registration_client_uri REQUIRED. Location where the Access Token can be used to perform subsequent operations upon the resulting Client registration. client_id_issued_at OPTIONAL. Time at which the Client Identifier was issued. The time is represented as the number of seconds from 1970-01- 01T0:0:0Z as measured in UTC until the date/time. client_secret_expires_at REQUIRED if "client_secret" is issued. Time at which the "client_secret" will expire or 0 if it will not expire. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. Sakimura, et al. [Page 13] OpenID Connect Registration 1.0 July 2013 The following is a non-normative example response (with line wraps within values for display purposes only): HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "client_id": "s6BhdRkqt3", "client_secret": "ZJYCqe3GGRvdrudKyZS0XhGv_Z45DuKhCUk0gBR1vZk", "client_secret_expires_at": 1577858400, "registration_access_token": "this.is.an.access.token.value.ffx83", "registration_client_uri": "https://server.example.com/connect/register?client_id=s6BhdRkqt3", "token_endpoint_auth_method": "client_secret_basic", "application_type": "web", "redirect_uris": ["https://client.example.org/callback", "https://client.example.org/callback2"], "client_name": "My Example", "client_name#ja-Jpan-JP": "クライアント名", "logo_uri": "https://client.example.org/logo.png", "subject_type": "pairwise", "sector_identifier_uri": "https://other.example.net/file_of_redirect_uris.json", "jwks_uri": "https://client.example.org/my_public_keys.jwks", "userinfo_encrypted_response_alg": "RSA1_5", "userinfo_encrypted_response_enc": "A128CBC-HS256", "contacts": ["ve7jtb@example.org", "mary@example.org"], "request_uris": ["https://client.example.org/rf.txt #qpXaRLh_n93TTR9F252ValdatUQvQiJi5BDub2BeznA"] } 3.3. Client Registration Error Response When an OAuth error condition occurs, the Client Registration Endpoint returns an Error Response as defined in Section 3 of the OAuth 2.0 Bearer Token Usage [RFC6750] specification. When a registration error condition occurs, the Client Registration Endpoint returns a HTTP 400 status code including a JSON object describing the error in the response body. Sakimura, et al. [Page 14] OpenID Connect Registration 1.0 July 2013 The JSON object contains two members: error Error code. error_description Additional text description of the error for debugging. This specification defines the following error codes: invalid_redirect_uri The value of one or more "redirect_uris" is invalid. invalid_client_metadata The value of one of the Client Metadata fields is invalid and the server has rejected this request. Note that an Authorization Server MAY choose to substitute a valid value for any requested parameter of a Client's Metadata. The following is a non-normative example error response: HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "error": "invalid_redirect_uri", "error_description": "The value of one or more redirect_uris are invalid." } Sakimura, et al. [Page 15] OpenID Connect Registration 1.0 July 2013 4. Client Configuration Endpoint The Client Configuration Endpoint is an OAuth 2.0 protected resource that is provisioned by the server for a specific Client to be able to view and update its registered information. The Client MUST use its Registration Access Token in all calls to this endpoint as an OAuth 2.0 Bearer Token [RFC6750]. Operations on this endpoint are switched through the use of different HTTP methods [RFC2616]. The only method defined for use at this endpoint by this specification is the HTTP "GET" method. 4.1. Forming the Client Configuration Endpoint URL The Authorization Server MUST provide the Client with the fully qualified URL in the "registration_client_uri" element of the Client Registration Response, per Section 3.2. The Authorization Server MUST NOT expect the Client to construct or discover this URL on its own. The Client MUST use the URL as given by the server and MUST NOT construct this URL from component pieces. Depending on deployment characteristics, the Client Configuration Endpoint URL can take any number of forms. It is RECOMMENDED that this endpoint URL be formed through the use of a server-constructed URL string which combines the Client Registration Endpoint's URL and the issued Client ID for this Client, with the latter as either a path parameter or a query parameter. For example, a Client with the Client ID "s6BhdRkqt3" could be given a Client Configuration Endpoint URL of "https://server.example.com/register/s6BhdRkqt3" (path parameter) or of "https://server.example.com/register?client_id=s6BhdRkqt3" (query parameter). In both of these cases, the Client simply uses the URL as given. These common patterns can help the Server to more easily determine the Client to which the request pertains, which MUST be matched against the Client to which the Registration Access Token was issued. If desired, the Server MAY simply return the Client Registration Endpoint URL as the Client Configuration Endpoint URL and change behavior based on the authentication context provided by the Registration Access Token. 4.2. Client Read Request To read the current configuration of the Client on the Authorization Server, the Client makes an HTTP "GET" request to the Client Configuration Endpoint with the Registration Access Token. Sakimura, et al. [Page 16] OpenID Connect Registration 1.0 July 2013 The following is a non-normative example request: GET /connect/register?client_id=s6BhdRkqt3 HTTP/1.1 Accept: application/json Host: server.example.com Authorization: Bearer this.is.an.access.token.value.ffx83 4.3. Client Read Response Upon a successful read operation, the Authorization Server SHOULD return all registered Metadata about this Client, including any fields provisioned by the Authorization Server itself. Some values, including the "client_secret" value, might have been updated since the initial registration. The Authorization Server need not include the "registration_access_token" or "registration_client_uri" value in this response unless they have been updated. The response is a JSON Document [RFC4627] with the Client Metadata as top-level members of a JSON object. Sakimura, et al. [Page 17] OpenID Connect Registration 1.0 July 2013 The following is a non-normative example response (with line wraps within values for display purposes only): HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "client_id": "s6BhdRkqt3", "client_secret": "OylyaC56ijpAQ7G5ZZGL7MMQ6Ap6mEeuhSTFVps2N4Q", "client_secret_expires_at": 17514165600, "registration_client_uri": "https://server.example.com/connect/register?client_id=s6BhdRkqt3", "token_endpoint_auth_method": "client_secret_basic", "application_type": "web", "redirect_uris": ["https://client.example.org/callback", "https://client.example.org/callback2"], "client_name": "My Example", "client_name#ja-Jpan-JP": "クライアント名", "logo_uri": "https://client.example.org/logo.png", "subject_type": "pairwise", "sector_identifier_uri": "https://other.example.net/file_of_redirect_uris.json", "jwks_uri": "https://client.example.org/my_public_keys.jwks", "userinfo_encrypted_response_alg": "RSA1_5", "userinfo_encrypted_response_enc": "A128CBC-HS256", "contacts": ["ve7jtb@example.org", "mary@example.org"], "request_uris": ["https://client.example.org/rf.txt #qpXaRLh_n93TTR9F252ValdatUQvQiJi5BDub2BeznA"] } 4.4. Client Read Error Response When a read error condition occurs, the Client Configuration Endpoint returns a HTTP 403 Forbidden status code. This indicates that the Access Token is invalid or the Client record requested is invalid or non-existent. Note that for security reasons, to inhibit brute force attacks, endpoints MUST NOT return 404 Not Found error codes. Sakimura, et al. [Page 18] OpenID Connect Registration 1.0 July 2013 The following is a non-normative example error response: HTTP/1.1 403 Forbidden Content-Type: application/json Cache-Control: no-store Pragma: no-cache Sakimura, et al. [Page 19] OpenID Connect Registration 1.0 July 2013 5. "sector_identifier_uri" Validation The sector identifier list provides a way for a group of Web sites under single administrative control to have consistent pairwise "sub" values, independent of their domain names, as described in Section 2.8.1 of OpenID Connect Messages 1.0 [OpenID.Messages]. It also provides a way for Clients to change "redirect_uri" domains without having to re-register all of their users. The value of the "sector_identifier_uri" MUST be a URL using the "https" scheme that references a JSON file containing an array of "redirect_uri" values. The values registered in "redirect_uris" MUST be included in the elements of the array, or registration MUST fail. The following is a non-normative example request to and reply from a "sector_identifier_uri". GET https://other.example.net/file_of_redirect_uris.json HTTP/1.1 Accept: application/json Host: client.example.org HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache [ "https://client.example.org/callback", "https://client.example.org/callback2", "https://client.other_company.example.net/callback" ] Sakimura, et al. [Page 20] OpenID Connect Registration 1.0 July 2013 6. 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 21] OpenID Connect Registration 1.0 July 2013 7. Validation If any of the validation procedures defined in this specification fail, any operations requiring the information that failed to correctly validate MUST be aborted and the information that failed to validate MUST NOT be used. Sakimura, et al. [Page 22] OpenID Connect Registration 1.0 July 2013 8. Implementation Considerations This specification defines features used by both Relying Parties and OpenID Providers that choose to implement Dynamic Client Registration. All of these Relying Parties and OpenID Providers MUST implement the features that are listed in this specification as being "REQUIRED" or are described with a "MUST". No other implementation considerations for implementations of Dynamic Client Registration are defined by this specification. Sakimura, et al. [Page 23] OpenID Connect Registration 1.0 July 2013 9. Security Considerations Since requests to the Client Registration Endpoint result in the transmission of clear-text credentials (in the HTTP request and response), all communication with the Registration Endpoint MUST utilize TLS. See Section 9.1 for more information on using TLS. A rogue RP might use the logo for the legitimate RP, which it is trying to impersonate. An OP needs to take steps to mitigate this phishing risk, since the logo could confuse users into thinking they're logging in to the legitimate RP. An OP could also warn if the domain/site of the logo doesn't match the domain/site of registered redirection URIs. An OP can also make warnings against untrusted RPs in all cases, especially if they're dynamically registered, have not been trusted by any users at the OP before, and want to use the logo feature. In a situation where the Authorization Server is supporting open Client registration, it needs to be extremely careful with any URL provided by the Client that will be displayed to the End-User (e.g. "logo_uri" and "policy_uri"). A rogue Client could specify a registration request with a reference to a drive-by download in the "policy_uri". The Authorization Server SHOULD check to see if the "logo_uri" and "policy_uri" have the same host as the hosts defined in the array of "redirect_uris". 9.1. TLS Requirements Implementations MUST support TLS. Which version(s) ought to be implemented will vary over time, and depend on the widespread deployment and known security vulnerabilities at the time of implementation. At the time of this writing, TLS version 1.2 [RFC5246] is the most recent version, but has very limited actual deployment, and might not be readily available in implementation toolkits. TLS version 1.0 [RFC2246] is the most widely deployed version, and will give the broadest interoperability. To protect against information disclosure and tampering, confidentiality protection MUST be applied using TLS with a ciphersuite that provides confidentiality and integrity protection. Whenever TLS is used, a TLS server certificate check MUST be performed, per RFC 6125 [RFC6125]. Sakimura, et al. [Page 24] OpenID Connect Registration 1.0 July 2013 10. IANA Considerations This document makes no requests of IANA. Sakimura, et al. [Page 25] OpenID Connect Registration 1.0 July 2013 11. References 11.1. Normative References [JWA] Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose-json-web-algorithms (work in progress), May 2013. [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web Encryption (JWE)", draft-ietf-jose-json-web-encryption (work in progress), May 2013. [JWK] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web-key (work in progress), May 2013. [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", draft-ietf-jose-json-web-signature (work in progress), May 2013. [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", draft-ietf-oauth-json-web-token (work in progress), May 2013. [OAuth.JWT] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0", draft-ietf-oauth-jwt-bearer (work in progress), March 2013. [OpenID.Discovery] Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0", July 2013. [OpenID.Messages] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", July 2013. [OpenID.Session] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and N. Agarwal, "OpenID Connect Session Management 1.0", July 2013. [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. Sakimura, et al. [Page 26] OpenID Connect Registration 1.0 July 2013 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC4627] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying Languages", BCP 47, RFC 5646, September 2009. [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. [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012. [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, October 2012. [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode Normalization Forms", Unicode Standard Annex 15, 09 2009. 11.2. Informative References [I-D.ietf-oauth-dyn-reg] Richer, J., Bradley, J., Jones, M., and M. Machulak, "OAuth 2.0 Dynamic Client Registration Protocol", draft-ietf-oauth-dyn-reg-13 (work in progress), July 2013. Sakimura, et al. [Page 27] OpenID Connect Registration 1.0 July 2013 Appendix A. Acknowledgements The OpenID Community would like to thank the following people for the work they have done in the drafting and editing of this specification. Amanda Anganes (aanganes@mitre.org), Mitre John Bradley (ve7jtb@ve7jtb.com), Ping Identity Brian Campbell (bcampbell@pingidentity.com), Ping Identity Vladimir Dzhuvinov (vladimir@nimbusds.com), Nimbus Directory Services Roland Hedberg (roland.hedberg@adm.umu.se), University of Umea Edmund Jay (ejay@mgi1.com), Illumila Michael B. Jones (mbj@microsoft.com), Microsoft Justin Richer (jricher@mitre.org), Mitre Nat Sakimura (n-sakimura@nri.co.jp), Nomura Research Institute, Ltd. Sakimura, et al. [Page 28] OpenID Connect Registration 1.0 July 2013 Appendix B. Notices Copyright (c) 2013 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. Sakimura, et al. [Page 29] OpenID Connect Registration 1.0 July 2013 Appendix C. Document History [[ To be removed from the final specification ]] -19 o Fixed #842 - Made "post_logout_redirect_uri" treatment parallel to "redirect_uri". o Corrected "error_code" to "error". o Stated that "redirect_uri" matches must be exact, with matching performed as described in Section 6.2.1 of RFC 3986 (Simple String Comparison). o Fixed #854 - Clarified that the "default_acr_values" values are in order of preference and that "default_acr_values" requests the "acr" Claim as a Voluntary Claim. o Fixed #859 - Added IMPORTANT NOTE TO READERS about the terminology definitions being a normative part of the specification. -18 o Added subsection on Forming the Client Configuration Endpoint URL to help clarify its semantics to developers. This was explained in the OAuth Registration spec but wasn't previously explained here. o Renamed "expires_at" to "client_secret_expires_at" and "issued_at" to "client_id_issued_at", tracking OAuth Registration changes. o Stated that the JWS Compact Serialization and the JWE Compact Serialization are always used for JWS and JWE data structures. -17 o Fixed #820 - Removed assumption that Clients that want encrypted responses also sign requests. -16 o Fixed #803 - No longer use "client_id" query parameter. o Fixed #804 - Removed "access_token" from client metadata. -15 Sakimura, et al. [Page 30] OpenID Connect Registration 1.0 July 2013 o Fixed #708 - Registration access token requirement. o Fixed #734 - Invalid JSON in examples. o Fixed #736 - Client Update Operation Response: expires_at should be removed from example. o Fixed #735 - Require expires_at value in Client Register response. o Added Security Considerations section about TLS version requirements and usage. o State that when any validations fail, any operations requiring the information that failed to correctly validate MUST be aborted and the information that failed to validate MUST NOT be used. o Fixed #746 - Deleted the "operation" parameter. o Fixed #745 - Deleted the "rotate_secret" operation. o Changed the Japanese client name to make it sound more natural. o Added optional "issued_at" response value. o Added client update example. o Fixed #727 - Deleted invalid_client_secret error. o Fixed #744 - Promoted "max_age" to being a top-level parameter. o Fixed #765 - Created "acr_values" top-level request parameter and changed "default_acr" registration parameter to "default_acr_values". o Fixed #747 - Changed requests from being form-urlencoded to JSON. o Fixed #755 - Removed client update operation. o Fixed #751 - Added client read operation. o Fixed #749 - Added "registration_access_url". o Fixed #756 - State that an updated "client_secret" value can be returned by a read operation. o Fixed #774 - Moved invalid client_id from 3.3 to 4.3 and fixed example. Sakimura, et al. [Page 31] OpenID Connect Registration 1.0 July 2013 o Fixed #774 - Removed invalid client_id and made GET return 403 Forbidden. o Fixed missing registration_access_url in GET example response. o Fixed #776 - Removed client adding client_id query parameter but make the examples include it as part of the registration_access_url. o Fixed #775 - Made redirects_uri, contacts, and default_acr_values arrays to match the examples. o Changed "invalid_configuration_parameter" error to "invalid_client_metadata" to match the OAuth Registration spec. o Fixed #777 - Added "Pragma: no-cache" to the example responses that were missing it. o Fixed #773 - Added "request_uris" registration parameter to pre- register "request_uri" values. Also clarified that Request File contents may be cached. o Fixed #758 - State the registration requests can be rate-limited to prevent a DoS attack. o Fixed #782 - Changed uses of "_url" in identifiers to "_uri". o Fixed #783 - Changed "registration_access_url" to "registered_client_uri". o Fixed #703 - Added the PKIX JWK key type for X.509 certificates and consolidated the "x509_uri", "x509_encryption_uri", and "jwk_encryption_uri" parameters into a combined "jwk_uri" parameter. o Fixed #786 - Changed the name of "jwk_uri" to "jwks_uri". o Added the "response_types" registration parameter. o Added the "grant_types" registration parameter. o Added table documenting correspondence between "response_type" values used and "grant_type" values used. o Fixed #788 - Renamed "OpenID Request Object" to "Request Object". -14 Sakimura, et al. [Page 32] OpenID Connect Registration 1.0 July 2013 o Changed the syntax of some elements to match the syntax used in the OAuth Dynamic Client Registration draft. Specifically, changed "type" to "operation", changed "associate" to "register", and changed "application_name" to "client_name". Also changed the responses of "client_register" and "client_update" to include full client information instead of just the Client ID. o Added Implementation Considerations section. o Fixed #656 - Changed "token_endpoint_auth_type" to "token_endpoint_auth_method" and "token_endpoint_auth_types_supported" to "token_endpoint_auth_methods_supported". o Fixed #698 - Inconsistent use of articles. o Deleted "javascript_origin_uris", which is no longer present in Session. o Reference and provide note to implementers about OAuth Dynamic Client Registration Protocol [I-D.ietf-oauth-dyn-reg]. o Changed token_endpoint_auth_method example result value from "client_secret_basic client_secret_post" to "client_secret_basic" since the definition requires the value to be a single method. -13 o Fixed #687 - Inconsistency between "user_id" and "prn" claims. The fix changed these names: user_id -> sub, user_id_types_supported -> subject_types_supported, user_id_type -> subject_type, and prn -> sub. o Renamed "acrs_supported" to "acr_values_supported" for naming consistency. o Fixed #685 - The policy URL should be different from the terms-of- service URL. A new "tos_url" registration parameter was added. o Clarified that "jwk_url" and "jwk_encryption_url" refer to documents containing JWK Sets - not single JWK keys. o Re #601 add initiate_login_uri for unsolicited request -12 o Made application_type REQUIRED and added an explanation about redirect_uris registration Sakimura, et al. [Page 33] OpenID Connect Registration 1.0 July 2013 o Section 2.1 clarification that updates replace all parameters previously set. o Section 2.3 add rotate_secret to invalid client_id error o Added registration_access_token for updating and made client secret optional o added registration_access_token to example response o removed client_id from request as the client_id is implicit in the access token for updates o Changed redirect_uris from RECOMMENDED for code and REQUIRED for implicit to REQUIRED o Changed 2.1 to only allow access_token as a parameter if type is rotate_secret o Fixed reference in application_name and added example of ja-Hani-JP encoded name. o Made application_type OPTIONAL with web as the default o Fixes #642 - Registration separates application errors from bearer. o Updated references to OAuth and Bearer to reflect current drafts o Fix typo error_description o Re #642 change error to error_code in 2.3 example o Fixed #614 - Discovery - 3.2 Distinguishing between signature and integrity parameters for HMAC algorithms. This fix tracks the parameter changes made to the JWE spec in draft-ietf-jose-json-web-encryption-06. It deletes the parameters {userinfo,id_token}_encrypted_response_int. It replaces the parameters {userinfo,id_token,request_object,token_endpoint}_algs_supported with {userinfo,id_token,request_object,token_endpoint}_signing_alg _values_supported and {userinfo,id_token,request_object,token_endp oint}_encryption_{alg,enc}_values_supported. o Fixed #673 - Registration 2.1: Rename require_signed_request_object to request_object_alg. The actual change was to rename require_signed_request_object to request_object_signing_alg, following the naming convention used Sakimura, et al. [Page 34] OpenID Connect Registration 1.0 July 2013 in the resolution to issue #614. o Fixed #666 - JWS signature validation vs. verification. o Referenced OAuth 2.0 RFCs -- RFC 6749 and RFC 6750. o Fixed #674 - Description of require_auth_time. -11 o Made "rotate_secret" a separate registration request type and stop client secret changing with every response, per issue #363 o Changed default ID Token signing algorithm to RS256, per issue #571 o Changed client.example.com to client.example.org, per issue #251 o Added text for authz to the registration endpoint, per issue #587 o Use standards track version of JSON Web Token spec (draft-ietf-oauth-json-web-token) -10 o Split encrypted response configurations into separate parameters for alg, enc, int o Removed extra "s" from signed response parameter names o Add reference to JWA o Updated Notices o Updated References -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 Sakimura, et al. [Page 35] OpenID Connect Registration 1.0 July 2013 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 to 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 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 Sakimura, et al. [Page 36] OpenID Connect Registration 1.0 July 2013 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 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 37] OpenID Connect Registration 1.0 July 2013 Authors' Addresses Nat Sakimura Nomura Research Institute, Ltd. Email: n-sakimura@nri.co.jp John Bradley Ping Identity Email: ve7jtb@ve7jtb.com Michael B. Jones Microsoft Email: mbj@microsoft.com Sakimura, et al. [Page 38]