OpenID Connect Dynamic Client Registration 1.0 - discussion draft 17

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.

Table of Contents

1.  Introduction
    1.1.  Requirements Notation and Conventions
2.  Terminology
3.  Client Registration
    3.1.  Client Registration Request
    3.2.  Client Registration Response
4.  Client Read
    4.1.  Client Read Request
    4.2.  Client Read Response
5.  Client Update
    5.1.  Client Update Request
    5.2.  Client Update Response
6.  Cleint Delete
    6.1.  Client Delete Request
    6.2.  Client Delete Response
7.  Client Registration Error Response
8.  "sector_identifier_url" Validation
9.  String Operations
10.  Validation
11.  Implementation Considerations
12.  Security Considerations
    12.1.  TLS Requirements
13.  Privacy Considerations
14.  IANA Considerations
15.  References
    15.1.  Normative References
    15.2.  Informative References
Appendix A.  Acknowledgements
Appendix B.  Notices
Appendix C.  Document History
§  Authors' Addresses

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.

Note: This specification will likely be modified to use the OAuth Dynamic Client Registration Protocol (Richer, J., Bradley, J., Jones, M., and M. Machulak, “OAuth Dynamic Client Registration Protocol,” January 2013.) [I‑D.ietf‑oauth‑dyn‑reg] once the OAuth registration draft is stable. While currently self-contained, this specification intentionally uses the same syntax and identifiers as the current version of the OAuth registration draft as of the time that this specification was last updated.

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 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [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.

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 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749], and the terms defined by OpenID Connect Messages 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” January 2013.) [OpenID.Messages].

This specification defines the following additional terms:

Client Registration Endpoint

OAuth 2.0 Protected Resource through which a Client can request new registration and manage the metadata associated with it

Registration Access Token

OAuth 2.0 Bearer Token issued by the Authorization Server through the Client Registration Endpoint which is used by the Client to authenticate itself during update and secret rotation operations

Self URL

URL of an OAuth Bearer token protected resource at which the client registration data may be obtained, updated, and deleted

3.  Client Registration

The Client Registration Endpoint is an OAuth 2.0 Protected Resource through which a Client can request new registration and manage the metadata associated with it. 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 OAuth 2.0 Bearer Token Usage (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [RFC6750] specification.

3.1.  Client Registration Request

To register a new client to the Authorization Server, the client sends HTTP POST messages to the Client Registration Endpoint with the parameters described below, which is called Client Metadata. They are encoded in the entity body as UTF-8 strings using the application/x-www-form-urlencoded format. 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.

[[Editor's Note (Nat): Why do we want it to be in POST params? There are so many of them and it is easier to do it in JSON with Accept: application/json and Content-Type: application/json just like SCIM? There are several advantages on it. (1) You do not have to URL encode the non-ascii strings. (2) it can be easily JWS signed. It is a big change, but if we want to do it, we have to do it now.]]

redirect_uris

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

application_type

OPTIONAL. Kind of the application. The default if not specified is web. The defined values are native or web. Web clients MUST only register URLs using the https: scheme as redirect_uris; they MAY 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 the constraints. This prevents sharing a Client ID across different types of Clients.

access_token

OPTIONAL. Access Token obtained out of band to authorize the registrant. 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 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749]. Access Tokens sent in the authorization header must be bearer tokens [RFC6750] (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.).

contacts

OPTIONAL. Space delimited list of e-mail 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.

client_name

OPTIONAL. Name of the Client to be presented to the user. If desired, representation of this claim in different languages and scripts is obtained by applying the rules set in Section 2.1.1.1.3 ("claims" member) of OpenID Connect Messages 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” January 2013.) [OpenID.Messages].

logo_url

OPTIONAL. URL that references a logo for the Client application.

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 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” January 2013.) [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 (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.) [RFC6749].

policy_url

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

tos_url

OPTIONAL. URL location 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.

jwk_url

OPTIONAL. URL for the Client's JSON Web Key Set [JWK] (Jones, M., “JSON Web Key (JWK),” December 2012.) document containing key(s) that are used for signing Token Endpoint Requests and OpenID Request Objects. If jwk_encryption_url is not provided it is also used to encrypt the 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 Set [JWK] (Jones, M., “JSON Web Key (JWK),” December 2012.) document containing key(s) that are used to encrypt the 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 signing Token Endpoint Requests and OpenID Request Objects. If x509_encryption_url is not provided, x509_url it is also used to encrypt the 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.

x509_encryption_url

OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or Certificate chain that is used to encrypt the 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. 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 8 ("sector_identifier_url" Validation).

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 (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Signature (JWS),” December 2012.) [JWS] alg algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) that MUST be required by the Authorization Server. The valid values are listed in Section 3.1 of JWA (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) [JWA]. All OpenID 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] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) required for UserInfo responses. The valid values are listed in Section 3.1 of JWA (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) [JWA]. If this is specified the response will be JWT (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” December 2012.) [JWT] serialized, and signed using JWS.

userinfo_encrypted_response_alg

OPTIONAL. JWE (Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2012.) [JWE] alg algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) required for encrypting UserInfo responses. The valid values are listed in Section 4.1 of JWA (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) [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 (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” December 2012.) [JWT] serialized, and encrypted using JWE.

userinfo_encrypted_response_enc

OPTIONAL. JWE enc algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) required for symmetric encryption of UserInfo responses. The valid values are listed in Section 4.2 JWA (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) [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 (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” December 2012.) [JWT] serialized, and encrypted using JWE.

id_token_signed_response_alg

OPTIONAL. JWS alg algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) required for the ID Token issued to this client_id. The valid values are listed in Section 3.1 of JWA (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) [JWA]. The default if not specified is RS256. The public key for validating the signature is provided by retrieving the document from the jwk_url element or the x509_url element from discovery.

id_token_encrypted_response_alg

OPTIONAL. JWE alg algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) required for encrypting the ID Token issued to this client_id. The valid values are listed in Section 4.1 of JWA (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) [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] (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) required for symmetric encryption of the ID Token issued to this client_id. The valid values are listed in Section 4.2 of JWA (Jones, M., “JSON Web Algorithms (JWA),” December 2012.) [JWA]. If "id_token_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 (Jones, M., Bradley, J., and N. Sakimura, “JSON Web Token (JWT),” December 2012.) [JWT] serialized, and encrypted using JWE.

default_max_age

OPTIONAL. Default max authentication age that specifies that the End-User must be actively authenticated if any present authentication is older than the specified number of seconds represented as an integer. (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. 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.

default_acr

OPTIONAL. Default authentication context class reference value. String that specifies the default value that the Authorization Server must use for processing requests from this client. The acr_values_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.

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_url

OPTIONAL. URL supplied by the RP to request that the user be redirected to this location after a logout has been performed, as specified in OpenID Connect Session Management 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and N. Agarwal, “OpenID Connect Session Management 1.0,” January 2013.) [OpenID.Session].

For example, a client could send the following registration request to the Client Registration Endpoint:

Following is a non-normative example request (with line wraps for display purposes only):

POST /clients HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: server.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJ ...

application_type=web
    &redirect_uris=https://client.example.org/callback
      %20https://client.example.org/callback2
    &client_name=My%20Example%20
    &client_name%23ja-Jpan-JP=
      %E3%82%AF%E3%83%A9%E3%82%A4%E3%82%A2%E3%83%B3%E3%83%88%E5%90%8D
    &logo_url=https://client.example.org/logo.png
    &subject_type=pairwise
    &sector_identifier_url=
      https://othercompany.com/file_of_redirect_uris.json
    &token_endpoint_auth_method=client_secret_basic
    &jwk_url=https://client.example.org/my_rsa_public_key.jwk
    &userinfo_encrypted_response_alg=RSA1_5
    &userinfo_encrypted_response_enc=A128CBC+HS256

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 to be used by the client to perform subsequent operations at the Self URL, which is returned in the same response.

All of the response items are returned as a JSON document (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] with the following fields as top-level members of the root JSON object.

_links

REQUIRED. A JSON object with a member self, which in turn holds a member href, a Self URL.
[[Editor's note: This is a bit pedantic, but is probably a correct way of doing it in link-rel style. Other options may be to specify in this spec that the Self URL is Registration Endpoint URL + ?client_Id=1234. ]]

client_id

REQUIRED. The unique Client identifier, MUST NOT be currently valid for any other registered Client.

client_secret

OPTIONAL. The 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 required for clients selecting a token_endpoint_auth_method of private_key_jwt.

registration_access_token

REQUIRED. The Access token to be used by the client to perform operations on the Self URL.

issued_at

OPTIONAL. Specifies the timestamp when the Client Identifier was issued. The timestamp value MUST be a positive integer. The value is expressed in the number of seconds since January 1, 1970 00:00:00 GMT. [[Editor's note: Added back from oauth-dyn-reg-04]]

expires_at

OPTIONAL. 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. See RFC 3339 (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.) [RFC3339] for details regarding date/times in general and UTC in particular.

Following is a non-normative example response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
    "_links": {
        "self": {
            "href": "https://server.example.com/clients/s6BhdRkqt3"
        }
    },
    "client_id": "s6BhdRkqt3",
    "client_secret": "cf136dc3c1fd9153029bb9c6cc9ecead918bad9887fce6c93f31185e5885805d",
    "registration_access_token": "this.is.an.access.token.value.ffx83",
    "token_endpoint_auth_method": "client_secret_basic",
    "expires_at": 2893276800,
    "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_url": "https://client.example.org/logo.png",
    "subject_type": "pairwise",
    "sector_identifier_url": "https://othercompany.com/file_of_redirect_uris.json",
    "jwk_url": "https://client.example.org/my_rsa_public_key.jwk",
    "userinfo_encrypted_response_alg": "RSA1_5",
    "userinfo_encrypted_response_enc": "A128CBC+HS256"
}

4.  Client Read

The client may request the client URL at the server to obtain the current registered values about the client. To do so, the client sends the HTTP GET request to the client URL.

4.1.  Client Read Request

The clients sends the HTTP GET request to e client_url .

Following is a non-normative example request (with line wraps for display purposes only):

GET /clients/s6BhdRkqt3 HTTP/1.1
Host: server.example.com
Authorization: Bearer this.is.an.access.token.value.ffx83

4.2.  Client Read Response

Upon successful request, the server returns the currently registered metadata about this client, except the Client Secret or Request Access Token.

Following is a non-normative example response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
    "_links": {
        "self": {
            "href": "https://server.example.com/clients/s6BhdRkqt3"
        }
    },
    "client_id": "s6BhdRkqt3",
    "client_secret": "cf136dc3c1fd9153029bb9c6cc9ecead918bad9887fce6c93f31185e5885805d",
    "registration_access_token": "this.is.an.access.token.value.ffx83",
    "token_endpoint_auth_method": "client_secret_basic",
    "expires_at": 2893276800,
    "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_url": "https://client.example.org/logo.png",
    "subject_type": "pairwise",
    "sector_identifier_url": "https://othercompany.com/file_of_redirect_uris.json",
    "jwk_url": "https://client.example.org/my_rsa_public_key.jwk",
    "userinfo_encrypted_response_alg": "RSA1_5",
    "userinfo_encrypted_response_enc": "A128CBC+HS256"
}

5.  Client Update

This operation updates a previously-registered client with new metadata at the Authorization Server.

5.1.  Client Update Request

The request is sent to the Self URL obtained from the client registration response with the parameters described in Client Metadata encoded in the entity body using the application/x-www-form-urlencoded format.

Parameters sent with this request are the same as the registration request except for access_token, which is the value received in the registration request. If included in the request, valid values of Client Metadata fields in this request MUST replace, not augment, the values previously associated with this Client. Empty values in Client Metadata MUST be taken as a request to clear any existing value of that field. Omitted values in the Client Metadata MUST remain unchanged by the Authorization Server. The Authorization Server MAY replace any invalid values with suitable values.

For example, a client could send the following request to the Client Registration Endpoint to update the client registration in the above example:

Following is a non-normative example request (with line wraps for display purposes only):

POST /clients/s6BhdRkqt3 HTTP/1.1
Accept: application/x-www-form-urlencoded
Host: server.example.com
Authorization: Bearer this.is.an.access.token.value.ffx83

redirect_uri=https://client.example.org/callback
    %20https://client.example.org/alt
    &client_name=My%20New%20Example%20
    &client_name%23ja-Jpan-JP=
      %E3%82%AF%E3%83%A9%E3%82%A4%E3%82%A2%E3%83%B3%E3%83%88%E5%90%8D
    &logo_url=https://client.example.org/newlogo.png

5.2.  Client Update Response

Upon successful update, the Client Registration Endpoint returns the Client ID, along with all current 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 suitable values. If this happens, the Authorization Server MUST include these fields in the response to the client.

The Authorization Server MUST NOT include the Client Secret or Request Access Token in this response.

These fields are returned in a JSON Document (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] as top-level members of the root JSON object.

Following is a non-normative example response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
    "_links": {
        "self": {
            "href": "https://server.example.com/clients/s6BhdRkqt3"
        }
    },
    "client_id": "s6BhdRkqt3",
    "client_secret": "cf136dc3c1fd9153029bb9c6cc9ecead918bad9887fce6c93f31185e5885805d",
    "registration_access_token": "this.is.an.access.token.value.ffx83",
    "token_endpoint_auth_method": "client_secret_basic",
    "expires_at": 2893276800,
    "application_type": "web",
    "redirect_uris": "https://client.example.org/callback https://client.example.org/alt",
    "client_name": "My New Example",
    "client_name#ja-Jpan-JP": "クライアント名",
    "logo_url": "https://client.example.org/newlogo.png",
    "subject_type": "pairwise",
    "sector_identifier_url": "https://othercompany.com/file_of_redirect_uris.json",
    "jwk_url": "https://client.example.org/my_rsa_public_key.jwk",
    "userinfo_encrypted_response_alg": "RSA1_5",
    "userinfo_encrypted_response_enc": "A128CBC+HS256"
}

6.  Cleint Delete

This operation allows a client to be de-registered/deleted from the server.

6.1.  Client Delete Request

To delete the client from the server, the client sends HTTP DELETE request to the client URL.

Following is a non-normative example request (with line wraps for display purposes only):

DELETE /clients/s6BhdRkqt3 HTTP/1.1
Host: server.example.com
Authorization: Bearer reg-23410913-abewfq.123483

6.2.  Client Delete Response

Upon the successful request, the server returns a HTTP 200 response.

7.  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 (Jones, M. and D. Hardt, “The OAuth 2.0 Authorization Framework: Bearer Token Usage,” October 2012.) [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.

The JSON object contains two members:

error_code

Error code.

error_description

Additional text description of the error for debugging.

This specification defines the following error codes:

invalid_client_id

Value of client_id is invalid.

invalid_client_secret

client_secret provided for the access to the Self URL is not valid for the provided client_id.

invalid_redirect_uri

Value of one or more redirect_uris is invalid.

invalid_configuration_parameter

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
  Content-Type: application/json
  Cache-Control: no-store

  {
   "error_code": "invalid_client_id",
   "error_description": "The value of the client_id parameter is invalid."
  }

8.  "sector_identifier_url" Validation

[[Editor's Note: This clause needs to be updated to read better.]]

Providers who use pairwise sub (subject) values SHOULD support this element.

It provides a way for a group of websites under a single administrative control to have consistent pairwise sub values independent of the individual domain names. It also provides a way for Clients to change redirect_uri domains without having to reregister all of their users.

This is further described in Section 2.4.1 of OpenID Connect Messages 1.0 (Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, “OpenID Connect Messages 1.0,” January 2013.) [OpenID.Messages].

The value of the sector_identifier_url must be a URL using the https: scheme that references a JSON file containing an array containing redirect_uri values.

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

9.  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 (Davis, M., Whistler, K., and M. Dürst, “Unicode Normalization Forms,” 09 2009.) [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.

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

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

12.  Security Considerations

Since requests to the Client Registration Endpoint result in the transmission of clear-text credentials (in the HTTP request and response), all communiucation with the Registration Endpoint MUST utilize TLS. See Section 12.1 (TLS Requirements) for more information on using TLS.

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.

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

12.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] (Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.) 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] (Dierks, T. and C. Allen, “The TLS Protocol Version 1.0,” January 1999.) 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 (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),” March 2011.) [RFC6125].

13.  Privacy Considerations

14.  IANA Considerations

This document makes no requests of IANA.

15.  References

15.1. Normative References

15.2. Informative References

Appendix A.  Acknowledgements

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.

Appendix C.  Document History

[[ To be removed from the final specification ]]

-17 discussion version

• Moved Terminology section out of Introduction to form an independent section and added several terminology definitions
• Deleted the operation parameter
• Deleted the rotate_secret
• Added Client Read Request (GET)
• Added Client Delete Request (DELETE)
• Added "Self URL"
• Added _links
• Added Editor's Notes
• Changed the Japanese client name to make it sound more natural
• Added issued_at
• Added client update example (that seems to be missing many parameters that were present in the registration request example)
• Cleand up the indents

-16

• Fixed #734 - Invalid JSON in examples.
• Fixed #736 - Client Update Operation Response: expires_at should be removed from example.
• Fixed #735 - Require expires_at value in Client Register response.
• Added Security Considerations section about TLS version requirements and usage.
• 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.

-15

• Fixed #708 - Registration access token requirement.

-14

• 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.
• Added Implementation Considerations section.
• Fixed #656 - Changed token_endpoint_auth_type to token_endpoint_auth_method and token_endpoint_auth_types_supported to token_endpoint_auth_methods_supported.
• Fixed #698 - Inconsistent use of articles.
• Deleted javascript_origin_uris, which is no longer present in Session.
• Reference and provide note to implementers about OAuth Dynamic Client Registration Protocol (Richer, J., Bradley, J., Jones, M., and M. Machulak, “OAuth Dynamic Client Registration Protocol,” January 2013.) [I‑D.ietf‑oauth‑dyn‑reg].
• 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

• 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.
• Renamed acrs_supported to acr_values_supported for naming consistency.
• Fixed #685 - The policy URL should be different from the terms-of-service URL. A new tos_url registration parameter was added.
• Clarified that jwk_url and jwk_encryption_url refer to documents containing JWK Sets - not single JWK keys.
• Re #601 add initiate_login_uri for unsolicited request

-12

• Made application_type REQUIRED and added an explanation about redirect_uris registration
• Section 2.1 clarification that updates replace all parameters previously set.
• Section 2.3 add rotate_secret to invalid client_id error
• Added registration_access_token for updating and made client secret optional
• added registration_access_token to example response
• removed client_id from request as the client_id is implicit in the access token for updates
• Changed redirect_uris from RECOMMENDED for code and REQUIRED for implicit to REQUIRED
• Changed 2.1 to only allow access_token as a parameter if type is rotate_secret
• Fixed reference in application_name and added example of ja-Hani-JP encoded name.
• Made application_type OPTIONAL with web as the default
• Fixes #642 - Registration separates application errors from bearer.
• Updated references to OAuth and Bearer to reflect current drafts
• Fix typo error_description
• Re #642 change error to error_code in 2.3 example
• 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_endpoint}_encryption_{alg,enc}_values_supported.
• 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 in the resolution to issue #614.
• Fixed #666 - JWS signature validation vs. verification.
• Referenced OAuth 2.0 RFCs -- RFC 6749 and RFC 6750.
• Fixed #674 - Description of require_auth_time.

-11

• Made rotate_secret a separate registration request type and stop client secret changing with every response, per issue #363
• Changed default ID Token signing algorithm to RS256, per issue #571
• Changed client.example.com to client.example.org, per issue #251
• Added text for authz to the registration endpoint, per issue #587
• Use standards track version of JSON Web Token spec (draft-ietf-oauth-json-web-token)

-10

• Split encrypted response configurations into separate parameters for alg, enc, int
• Removed extra "s" from signed response parameter names
• Add reference to JWA
• Updated Notices
• Updated References

-09

• Removed erroneous spanx declarations from example
• Fixed example in Sec 2.2 to show expires_at
• Fixed Sec 2.1.1 to clarify it is the registration server doing the certificate check
• Fixed Sec 2.1.1 example to include http portion of response
• Fixed #542 Sec 2.1 userinfo_signed_response_algs fixed to say signature. Clarify response is signed.
• Fixed Sec 2.1 userinfo_encrypted_response_algs Clarify response is JWE containing JWT
• Fixes #529 Sec 2.3 Clarify error response is Bearer and fix example
• Add default_max_age registration parameter
• Add default_acr registration parameter
• Add require_auth_time registration parameter

-08

• Replaced token_endpoint with a defined term Token Endpoint [OAuth 2.0]
• Added policy_url parameter
• Renamed expires_in but expires_at
• Registration Endpoint can be OAuth Protected
• Added parameters for requiring encryption and/or signing of OpenID Request Object, UserInfo and ID Token
• Added token_endpoint_auth_type and list of valid authentication types
• Added JWK and X509 URLs for signature and encryption
• Added user_id_type
• Changed sector_identifier to sector_identifier_url and added URL verification
• Use RFC 6125 to verify TLS endpoints
• Changed 'contact' to 'contacts', 'redirect_uri' to 'redirect_uris'
• Changed redirect_uris to RECOMMENDED for code flow and REQUIRED for implicit flow Clients
• Removed js_origin_uri
• Added section about string comparison rules needed
• Clarified redirect_uris matching
• Update John Bradley email and affiliation for Implementer's Draft

-07

• Changed request from posting a JSON object to being HTTP Form encoded.
• Added x509_url to support optional encryption.

-06

• Changes associated with renaming "Lite" to "Basic Client" and replacing "Core" and "Framework" with "Messages" and "Standard".
• Numerous cleanups, including updating references.

-05

• Changed redirect_url to redirect_uri and js_origin_url to js_origin_uri.

-04

• Correct issues raised by Johnny Bufu and discussed on the 7-Jul-11 working group call.

-03

• Incorporate working group decisions from 5-Jul-11 spec call.
• Consistency and cleanup pass, including removing unused references.

-02

• Incorporate working group decisions from 23-Jun-11 spec call.

-01

• Initial version.

Authors' Addresses