Abstract

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0
protocol. It enables 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 defines how an OpenID Connect Relying Party
can dynamically register with the End-User's OpenID Provider,
providing information about itself to the OpenID Provider,
and obtaining information needed to use it,
including the OAuth 2.0 Client ID for this Relying Party.

1.
Introduction

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0
[RFC6749] (Hardt, D., “The OAuth 2.0 Authorization Framework,” October 2012.)
protocol. It enables 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.

In order for an OpenID Connect Relying Party to utilize OpenID Connect services for
an End-User, the RP needs to register with the OpenID Provider
to provide the OP information about itself and
to obtain information needed to use it,
including an OAuth 2.0 Client ID.
This document describes how an RP
can register with an OP, and how registration information
for the RP can be retrieved.

In the .txt version of 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.
In the HTML version of this document,
values to be taken literally are indicated by
the use of this fixed-width font.

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.
The contents
of this token are service-specific and are out of scope for this
specification. The means by which the Authorization Server issues this
token and the means by which the Registration Endpoint validates
it are also out of scope.

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.

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.

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:

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 omitted, 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.
Authorization Servers MAY reject Redirection URI values
using the http scheme, other than the
localhost case for 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.

OPTIONAL.
URL that references a logo for the Client application.
If present, the server SHOULD display this image to the End-User during approval.
The value of this field MUST point to a valid image file.
If desired, representation of
this Claim in different languages and scripts is represented
as described in Section 2.1 (Metadata Languages and Scripts).

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 (Metadata Languages and Scripts).

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 value of this field MUST point to a valid web page.
The OpenID Provider SHOULD display this
URL to the End-User if it is given.
If desired, representation of
this Claim in different languages and scripts is represented
as described in Section 2.1 (Metadata Languages and Scripts).

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 value of this field MUST point to a valid web page.
The OpenID Provider SHOULD display this
URL to the End-User if it is given.
If desired, representation of
this Claim in different languages and scripts is represented
as described in Section 2.1 (Metadata Languages and Scripts).

jwks_uri

OPTIONAL.
URL for the Client's JSON Web Key Set [JWK] (Jones, M., “JSON Web Key (JWK),” July 2014.) 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 referenced JWK Set
to indicate each key's intended usage.
Although some algorithms allow the same key to be used for
both signatures and encryption, doing so is
NOT RECOMMENDED, as it is less secure.
The JWK x5c parameter MAY be used
to provide X.509 representations of keys provided. When used, the bare key
values MUST still be present and MUST match those in the certificate.

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 ("sector_identifier_uri" Validation).
Providers that use pairwise sub (subject) values
SHOULD utilize the sector_identifier_uri value
provided in the Subject Identifier calculation for pairwise identifiers.

subject_type

OPTIONAL.
subject_type requested for
responses to this Client.
The subject_types_supported Discovery parameter
contains a list of the supported subject_type
values for this server. Valid types include
pairwise and
public.

OPTIONAL.
JWE enc
algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” July 2014.) REQUIRED for encrypting the ID Token
issued to this Client.
If id_token_encrypted_response_alg is specified,
the default for this value is A128CBC-HS256.
When id_token_encrypted_response_enc is included,
id_token_encrypted_response_alg MUST also be provided.

OPTIONAL.
JWE enc
algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” July 2014.) REQUIRED for encrypting UserInfo Responses.
If userinfo_encrypted_response_alg is specified,
the default for this value is A128CBC-HS256.
When userinfo_encrypted_response_enc is included,
userinfo_encrypted_response_alg MUST also be provided.

OPTIONAL.
JWE enc
algorithm [JWA] (Jones, M., “JSON Web Algorithms (JWA),” July 2014.) the RP is declaring that it may use for
encrypting Request Objects sent to the OP.
If request_object_encryption_alg is specified,
the default for this value is A128CBC-HS256.
When request_object_encryption_enc is included,
request_object_encryption_alg MUST also be provided.

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.
If omitted, no default Maximum Authentication Age is specified.

OPTIONAL.
Default requested Authentication Context Class Reference values.
Array of strings that
specifies the default acr
values that the OP 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 individual acr Claim request
override these default values.

OPTIONAL.
Array of request_uri values that are
pre-registered by the RP for use at the OP.
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.

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.

3.
Client Registration Endpoint

The Client Registration Endpoint is an
OAuth 2.0 Protected Resource through which
a new Client registration can be requested.
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 or developers.

3.1.
Client Registration Request

To register a new Client at 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
with the parameters represented as top-level members of the root JSON object.

The following is a non-normative example registration request
(with line wraps within values for display purposes only):

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.
An Authorization Server MAY ignore values provided by the client,
and MUST ignore any fields sent by the Client that it does not understand.

The response MAY contain a Registration Access Token that can be
used by the Client to perform subsequent operations upon
the resulting Client registration.

OPTIONAL.
Registration Access Token that can be used at the Client Configuration Endpoint to
perform subsequent operations upon the Client registration.

registration_client_uri

OPTIONAL.
Location of the Client Configuration Endpoint
where the Registration Access Token can be used to perform subsequent
operations upon the resulting Client registration.
Implementations MUST either return both
a Client Configuration Endpoint and a Registration Access Token
or neither of them.

client_id_issued_at

OPTIONAL.
Time at which the Client Identifier was issued.
Its value is a JSON number representing 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.
Its value is a JSON number representing the number of seconds from
1970-01-01T0:0:0Z as measured in UTC until the date/time.

The following is a non-normative example registration response
(with line wraps within values for display purposes only):

When a registration error condition occurs, the Client Registration Endpoint returns
a HTTP 400 Bad Request status code
including a JSON object describing the error in the response body.

The JSON object describing the error contains two members:

error

Error code.

error_description

Additional text description of the error for debugging.

Other members MAY also be used.

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.

4.1.
Forming the Client Configuration Endpoint URL

If a Client Configuration Endpoint and a Registration Access Token
are returned by the initial registration of the Client,
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 (Client Registration Response).
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

If the initial registration of the Client returned
a Client Configuration Endpoint and a Registration Access Token,
the current configuration of the Client on the Authorization Server
can be read by making an HTTP GET request to the
Client Configuration Endpoint with the Registration Access Token.
This operation SHOULD be idempotent --
not causing changes to the Client configuration.

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.
Note that some values, including the client_secret
value, might have been updated since the initial registration.
The mechanisms for such updates are beyond the scope of this specification.
However, since Read operations are intended to be idempotent,
the Client Read Request itself SHOULD NOT cause changes
to the Client's registered Metadata values.

The Authorization Server need not include the
registration_access_token or
registration_client_uri
value in this response unless they have been updated.

If the Client does not exist on this server, the Client is invalid,
or the Registration Access Token used is invalid,
the server MUST respond with the HTTP 401 Unauthorized status code.
If the Client does not have permission to read its record,
the server MUST return an HTTP 403 Forbidden.
Note that for security reasons, to inhibit brute force attacks,
endpoints MUST NOT return the HTTP 404 Not Found status code.

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.
This MUST be validated at registration time;
there is no requirement for the OP to retain the contents of this JSON file
or to retrieve or revalidate its contents in the future.

The following is a non-normative example request to and reply from
a sector_identifier_uri:

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:

Remove any JSON applied escaping to produce an array of
Unicode code points.

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.

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

While every effort will be made to prevent breaking
changes to these specifications, should they occur,
OpenID Connect implementations should continue to use the
specifically referenced draft versions above in preference
to the final versions, unless using a possible future
OpenID Connect profile or specification that
updates some or all of these references.

8.2.
Implementation Notes on Stateless Dynamic Client Registration

In some deployments, it is advantageous to enable Clients to obtain
the information necessary to interact with the Authorization Server,
such as a Client Identifier,
without the requirement that state about the Client be stored at the
Authorization Server.
The interfaces defined by this specification can be used for
stateless dynamic client registration.

One means of doing this is to encode necessary registration information
about the Client into the client_id
value returned by the initial registration of the Client.
This has the effect of having the Client store this information,
rather than the Authorization Server.
The particular encodings used by different Authorization Servers will differ.

When stateless dynamic client registration is used by the Authorization Server,
read operations are likely to not be possible,
because issuing a Registration Access Token might require
per-Client state at the Authorization Server.
In that case, no Client Configuration Endpoint or Registration Access Token
will be returned by the initial registration of the Client.

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.3 (TLS Requirements) for more information on using TLS.

9.1.
Impersonation

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.2.
Native Code Leakage

Implementers should be aware that on iOS, information is
returned to native applications using custom URI schemes,
but multiple applications can register the same URI scheme.
In this case, it is nondeterministic which application
receives the information.
This can result in an Authorization Code being leaked to
the wrong application.
Several possible solutions to this have been proposed
and are being discussed in the IETF OAuth working group.
It is expected that a standard solution to this problem
will be developed there.
At that point, an extension to OpenID Connect may
be published describing how to apply that solution
to OpenID Connect.

Appendix B.
Notices

Copyright (c) 2014 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.