identity 1.0 documentation

OpenID Connect Dynamic Client Registration 1.0

«  OpenID Connect Messages 1.0   ::   Contents   ::   OpenID Connect Discovery 1.0  »

OpenID Connect Dynamic Client Registration 1.0

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.

( drarft 19 , http://openid.net/specs/openid-connect-registration-1_0.html )

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.

( draft 19, http://openid.net/specs/openid-connect-registration-1_0.html#Introduction )

Note

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.

( draft 19, http://openid.net/specs/openid-connect-registration-1_0.html#rnc )

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:

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.

( draft 19, http://openid.net/specs/openid-connect-registration-1_0.html#terminology )

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
  • 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 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 [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.
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.

( draft 19, http://openid.net/specs/openid-connect-registration-1_0.html#client-metadata )

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

( draft 19, http://openid.net/specs/openid-connect-registration-1_0.html#LanguagesAndScripts )

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.

(draft 19, http://openid.net/specs/openid-connect-registration-1_0.html#ClientRegistration )

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:

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

( draft 19, http://openid.net/specs/openid-connect-registration-1_0.html#RegistrationRequest )

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

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

( draft 19, http://openid.net/specs/openid-connect-registration-1_0.html#RegistrationResponse )

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.

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

( draft 19, http://openid.net/specs/openid-connect-registration-1_0.html#RegistrationError )

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.

( draft 19, http://openid.net/specs/openid-connect-registration-1_0.html#AccessEndpoint )

5. Security Considerations

Since requests to the Client Registration Endpoint result in the transmission of clear-text credentials (in the HTTP request and response), the server MUST require the use of a transport-layer security mechanism when sending requests to the Registration Endpoint. The server MUST support TLS 1.2 RFC 5246 [RFC5246] and/or TLS 1.0 [RFC2246] and MAY support additional transport-layer mechanisms meeting its security requirements. When using TLS, the Client MUST perform a TLS/SSL server certificate check, per RFC 6125 [RFC6125].

Requests to the Registration Endpoint for client_update MUST have some rate limiting on failures to prevent the Client secret from being disclosed though repeated access attempts.

In a situation where the Authorization Server is supporting open Client registration, it must be extremely careful with any URL provided by the Client that will be displayed to the user (e.g. logo_url and policy_url). A rogue Client could specify a registration request with a reference to a drive-by download in the policy_url. The Authorization Server should check to see if the logo_url and policy_url have the same host as the hosts defined in the array of redirect_uris.

(draft 09,)

Todo

Check later....

6. Normative References

JWE
Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.
JWK
Jones, M., “JSON Web Key (JWK),” December 2011.
JWS
Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature,” December 2011.
JWT
Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Token,” December 2011.
OAuth.Bearer
Jones, M., Hardt, D., and D. Recordon, “OAuth 2.0 Protocol: Bearer Tokens,” December 2011.
OAuth2.0
Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, “OAuth 2.0 Authorization Protocol,” September 2011.
OpenID.Messages
Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., Jones, M., and E. Jay, “OpenID Connect Messages 1.0,” December 2011. (OpenID Connect Messages 1.0 )
RFC2119
Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
RFC2246
Dierks, T. and C. Allen, “The TLS Protocol Version 1.0,” RFC 2246, January 1999 (TXT).
RFC3339
Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” RFC 3339, July 2002 (TXT, HTML, XML).
RFC5246
Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” RFC 5246, August 2008 (TXT).
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 (TXT).
USA15
Davis, M., Whistler, K., and M. Dürst, “Unicode Normalization Forms,” Unicode Standard Annex 15, 09 2009.1

(draft 09)

«  OpenID Connect Messages 1.0   ::   Contents   ::   OpenID Connect Discovery 1.0  »