OAuth 2.0 Dynamic Client
Registration Protocolietf@justin.richer.orgMicrosoftmbj@microsoft.comhttp://self-issued.info/Ping Identityve7jtb@ve7jtb.comNewcastle Universitym.p.machulak@ncl.ac.ukhttp://ncl.ac.uk/Oracle Corporationphil.hunt@yahoo.com
Security
OAuth Working GroupThis specification defines mechanisms for dynamically registering
OAuth 2.0 clients with authorization servers. Registration requests send
a set of desired client metadata values to the authorization server. The
resulting registration responses return a client identifier to use at
the authorization server and the client metadata values registered for
the client. The client can then use this registration information to
communicate with the authorization server using the OAuth 2.0 protocol.
This specification also defines a set of common client metadata fields
and values for clients to use during registration.In order for an OAuth 2.0 client to utilize an OAuth 2.0
authorization server, the client needs specific information to interact
with the server, including an OAuth 2.0 client identifier to use at that
server. This specification describes how an OAuth 2.0 client can be
dynamically registered with an authorization server to obtain this
information.As part of the registration process, this specification also defines
a mechanism for the client to present the authorization server with a
set of metadata, such as a set of valid redirection URIs. This metadata
can either be communicated in a self-asserted fashion or as a set of
metadata called a software statement, which is digitally signed or
MACed; in the case of a software statement, the issuer is vouching for
the validity of the data about the client.Traditionally, registration of a client with an authorization server
is performed manually. The mechanisms defined in this specification can
be used either for a client to dynamically register itself with
authorization servers or for a client developer to programmatically
register the client with authorization servers. Multiple applications
using OAuth 2.0 have previously developed mechanisms for accomplishing
such registrations. This specification generalizes the registration
mechanisms defined by the OpenID
Connect Dynamic Client Registration 1.0 specification and used by
the User Managed Access (UMA)
Profile of OAuth 2.0 specification in a way that is compatible
with both, while being applicable to a wider set of OAuth 2.0 use
cases.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 .Unless otherwise noted, all the protocol parameter names and values
are case sensitive.This specification uses the terms "access token", "authorization
code", "authorization endpoint", "authorization grant", "authorization
server", "client", "client identifier", "client secret", "grant type",
"protected resource", "redirection URI", "refresh token", "resource
owner", "resource server", "response type", and "token endpoint"
defined by OAuth 2.0 and uses the term
"Claim" defined by JSON Web Token (JWT).This specification defines the following terms:Software implementing an
OAuth 2.0 client.A deployed instance of a
piece of client software.The person or organization
that builds a client software package and prepares it for
distribution. At the time of building the client, the developer is
often not aware of who the deploying service provider
organizations will be. Client developers will need to use dynamic
registration when they are unable to predict aspects of the
software, such as the deployment URLs, at compile time. For
instance, this can occur when the software API publisher and the
deploying organization are not the same.OAuth 2.0
endpoint through which a client can be registered at an
authorization server. The means by which the URL for this endpoint
is obtained are out of scope for this specification.OAuth 2.0 access token
optionally issued by an authorization server to a developer or
client and used to authorize calls to the client registration
endpoint. The type and format of this token are likely
service-specific and are out of scope for this specification. The
means by which the authorization server issues this token as well
as the means by which the registration endpoint validates this
token are out of scope for this specification. Use of an initial
access token is required when the authorization server limits the
parties that can register a client.An administrative
security domain under which a software API (service) is deployed
and protected by an OAuth 2.0 framework. In some OAuth scenarios,
the deployment organization and the software API publisher are the
same. In these cases, the deploying organization will often have a
close relationship with client software developers. In many other
cases, the definer of the service may be an independent
third-party publisher or a standards organization. When working to
a published specification for an API, the client software
developer is unable to have a prior relationship with the
potentially many deployment organizations deploying the software
API (service).A deployed instance
of a software API that is protected by OAuth 2.0 (a protected
resource) in a particular deployment organization domain. For any
particular software API, there may be one or more deployments. A
software API deployment typically has an associated OAuth 2.0
authorization server as well as a client registration endpoint.
The means by which endpoints are obtained are out of scope for
this specification.The organization
that defines a particular web accessible API that may be deployed
in one or more deployment environments. A publisher may be any
standards body, commercial, public, private, or open source
organization that is responsible for publishing and distributing
software and API specifications that may be protected via OAuth
2.0. In some cases, a software API publisher and a client
developer may be the same organization. At the time of publication
of a web accessible API, the software publisher often does not
have a prior relationship with the deploying organizations.Digitally signed or
MACed JSON Web Token (JWT) that asserts
metadata values about the client software. In some cases, a
software statement will be issued directly by the client
developer. In other cases, a software statement will be issued by
a third party organization for use by the client developer. In
both cases, the trust relationship the authorization server has
with the issuer of the software statement is intended to be used
as an input to the evaluation of whether the registration request
is accepted. A software statement can be presented to an
authorization server as part of a client registration request.The abstract OAuth 2.0 client dynamic registration flow illustrated
in Figure 1 describes the interaction between the client or developer
and the endpoint defined in this specification. This figure does not
demonstrate error conditions. This flow includes the following
steps:Optionally, the client or developer is issued an
initial access token giving access to the client registration
endpoint. The method by which the initial access token is issued
to the client or developer is out of scope for this
specification.Optionally, the client or developer is issued a
software statement for use with the client registration endpoint.
The method by which the software statement is issued to the client
or developer is out of scope for this specification.The client or developer calls the client
registration endpoint with the client's desired registration
metadata, optionally including the initial access token from (A)
if one is required by the authorization server.The authorization server registers the client
and returns the client's registered metadata, a client identifier
that is unique at the server, a set of client credentials such as
a client secret if applicable for this client, and possibly other
values.Examples of different configurations and usages are included in
.Registered clients have a set of metadata values associated with
their client identifier at an authorization server, such as the list of
valid redirection URIs or a display name.These client metadata values are used in two ways:as input values to registration requests, andas output values in registration responses.The following client metadata fields are defined by this
specification. The implementation and use of all client metadata fields
is OPTIONAL, unless stated otherwise.Array of redirection URI values
for use in redirect-based flows such as the authorization code and
implicit flows. As required by Section 2 of OAuth 2.0, clients using flows with
redirection MUST register their redirection URI values.
Authorization servers that support dynamic registration for
redirect-based flows MUST implement support for this metadata
value.The requested
authentication method for the token endpoint. Values defined by this
specification are: none: The client is a public
client as defined in OAuth 2.0 and does not have a client
secret.client_secret_post: The client
uses the HTTP POST parameters defined in OAuth 2.0 section
2.3.1.client_secret_basic: the client
uses HTTP Basic defined in OAuth 2.0 section 2.3.1 Additional values can be defined via the IANA OAuth Token
Endpoint Authentication Methods Registry established in . Absolute URIs can also be used as values
for this parameter without being registered. If unspecified or
omitted, the default is client_secret_basic,
denoting HTTP Basic Authentication Scheme as specified in Section
2.3.1 of OAuth 2.0.Array of OAuth 2.0 grant types
that the client may use. These grant types are defined as follows:
authorization_code: The
Authorization Code Grant described in OAuth 2.0 Section 4.1implicit: The Implicit Grant
described in OAuth 2.0 Section 4.2password: The Resource Owner
Password Credentials Grant described in OAuth 2.0 Section
4.3client_credentials: The Client
Credentials Grant described in OAuth 2.0 Section 4.4refresh_token: The Refresh Token
Grant described in OAuth 2.0 Section 6.urn:ietf:params:oauth:grant-type:jwt-bearer:
The JWT Bearer Grant defined in OAuth
JWT Bearer Token Profiles.urn:ietf:params:oauth:grant-type:saml2-bearer:
The SAML 2 Bearer Grant defined in OAuth SAML 2 Bearer Token
Profiles.If the token endpoint is used in the grant type, the value
of this parameter MUST be the same as the value of the grant_type parameter passed to the token
endpoint defined in the grant type definition. Authorization servers
MAY allow for other values as defined in the grant type extension
process described in OAuth 2.0 Section 2.5. If omitted, the default
behavior is that the client will use only the authorization_code
Grant Type.Array of the OAuth 2.0
response types that the client can use. These response types are
defined as follows: code: The authorization code
response described in OAuth 2.0 Section 4.1.token: The implicit response
described in OAuth 2.0 Section 4.2.If the authorization endpoint is used by the grant type,
the value of this parameter MUST be the same as the value of the
response_type parameter passed to the
authorization endpoint defined in the grant type definition.
Authorization servers MAY allow for other values as defined in the
grant type extension process is described in OAuth 2.0 Section 2.5.
If omitted, the default is that the client will use only the code response type.Human-readable name of the client
to be presented to the end-user during authorization. If omitted,
the authorization server MAY display the raw client_id
value to the end-user instead. It is RECOMMENDED that clients always
send this field. The value of this field MAY be internationalized,
as described in .URL of a web page providing
information about the client. If present, the server SHOULD display
this URL to the end-user in a clickable fashion. It is RECOMMENDED
that clients always send this field. The value of this field MUST
point to a valid web page. The value of this field MAY be
internationalized, as described in .URL that references a logo for the
client. 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. The value of this field MAY be internationalized,
as described in .Space separated list of scope values
(as described in Section 3.3 of OAuth
2.0) that the client can use when requesting access tokens.
The semantics of values in this list is service specific. If
omitted, an authorization server MAY register a client with a
default set of scopes.Array of strings representing ways
to contact people responsible for this client, typically email
addresses. The authorization server MAY make these contact addresses
available to end-users for support requests for the client. See
for information on Privacy
Considerations.URL that points to a human-readable
terms of service document for the client that describes a
contractual relationship between the end-user and the client that
the end-user accepts when authorizing the client. The authorization
server SHOULD display this URL to the end-user if it is provided.
The value of this field MUST point to a valid web page. The value of
this field MAY be internationalized, as described in .URL that points to a
human-readable privacy policy document that describes how the
deployment organization collects, uses, retains, and discloses
personal data. The authorization server SHOULD display this URL to
the end-user if it is provided. The value of this field MUST point
to a valid web page. The value of this field MAY be
internationalized, as described in .URL referencing the client's JSON
Web Key Set document, which contains the
client's public keys. The value of this field MUST point to a valid
JWK Set document. These keys can be used by higher level protocols
that use signing or encryption. For instance, these keys might be
used by some applications for validating signed requests made to the
token endpoint when using JWTs for client authentication . Use of this parameter is preferred over the
jwks parameter, as it allows for easier
key rotation. The jwks_uri and jwks parameters MUST NOT both be present in the
same request or response.Client's JSON Web Key Set document value, which contains the client's public
keys. The value of this field MUST be a JSON object containing a
valid JWK Set. These keys can be used by higher level protocols that
use signing or encryption. This parameter is intended to be used by
clients that cannot use the jwks_uri
parameter, such as native clients that cannot host public URLs. The
jwks_uri and jwks
parameters MUST NOT both be present in the same request or
response.A unique identifier (e.g. a UUID)
assigned by the client developer or software publisher used by
registration endpoints to identify the client software to be
dynamically registered. Unlike client_id,
which is issued by the authorization server and SHOULD vary between
instances, the software_id SHOULD remain
the same for all instances of the client software. The software_id SHOULD remain the same across
multiple updates or versions of the same piece of software. The
value of this field is not intended to be human-readable and is
usually opaque to the client and authorization server.A version identifier for the
client software identified by software_id.
The value of the software_version SHOULD
change on any update to the client software identified by the same
software_id. The value of this field is
a string that is intended to be compared using string equality
matching. The value of this field is not intended to be human
readable and is usually opaque to the client and authorization
server.Extensions and profiles of this specification MAY expand this list.
The authorization server MUST ignore any client metadata values sent by
the client that it does not understand.Client metadata values can either be communicated directly in the
body of a registration request, as described in , or included as claims in a software
statement, as described in , or a
mixture of both. If the same client metadata name is present in both
locations and the software statement is trusted by the authorization
server, the value of a claim in the software statement MUST take
precedence.The grant_types and response_types values described above are
partially orthogonal, as they refer to arguments passed to different
endpoints in the OAuth protocol. However, they are related in that the
grant_types available to a client
influence the response_types that the
client is allowed to use, and vice versa. For instance, a grant_types value that includes authorization_code implies a response_types
value that includes code, as both values
are defined as part of the OAuth 2.0 authorization code grant. As
such, a server supporting these fields SHOULD take steps to ensure
that a client cannot register itself into an inconsistent state, for
example by returning an invalid_client_metadata
error response to an inconsistent registration request.The correlation between the two fields is listed in the table
below.grant_types value includes:response_types value includes:authorization_codecodeimplicittokenpassword(none)client_credentials(none)refresh_token(none)urn:ietf:params:oauth:grant-type:jwt-bearer(none)urn:ietf:params:oauth:grant-type:saml2-bearer(none)Extensions and profiles of this document that introduce new values
to either the grant_types or response_types parameter MUST document all
correspondences between these two parameter types.Human-readable client metadata values and client metadata values
that reference human-readable values MAY be represented in multiple
languages and scripts. For example, the values of fields such as
client_name, tos_uri,
policy_uri, logo_uri,
and client_uri might have multiple
locale-specific values in some client registrations to facilitate use
in different locations.To specify the languages and scripts, BCP47 language tags are added to client
metadata member names, delimited by a # character. Since JSON member names are case sensitive, it is
RECOMMENDED that language tag values used in Claim Names be spelled
using the character case with which they are registered in the IANA Language Subtag Registry. In
particular, normally language names are spelled with lowercase
characters, region names are spelled with uppercase characters, and
languages are spelled with mixed case characters. However, since BCP47
language tag values are case insensitive, implementations SHOULD
interpret the language tag values supplied in a case insensitive
manner. Per the recommendations in BCP47, language tag values used in
metadata member names should only be as specific as necessary. For
instance, using fr might be sufficient in
many contexts, rather than fr-CA or fr-FR.For example, a client could represent its name in English as "client_name#en": "My Client" and its name in
Japanese as "client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"
within the same registration request. The authorization server MAY
display any or all of these names to the resource owner during the
authorization step, choosing which name to display based on system
configuration, user preferences or other factors.If any 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 clients and servers use a
human-readable field without any language tags in addition to any
language-specific fields, and it is RECOMMENDED that any
human-readable fields sent without language tags contain values
suitable for display on a wide variety of systems.Implementer's Note: Many JSON libraries make it possible to
reference members of a JSON object as members of an object construct
in the native programming environment of the library. However, while
the # character is a valid character
inside of a JSON object's member names, it is not a valid character
for use in an object member name in many programming environments.
Therefore, implementations will need to use alternative access forms
for these claims. For instance, in JavaScript, if one parses the JSON
as follows, var j = JSON.parse(json);,
then as a workaround the member client_name#en-us
can be accessed using the JavaScript syntax j["client_name#en-us"].A software statement is a JSON Web Token (JWT)
that asserts metadata values about the client software as a bundle. A
set of claims that can be used in a software statement are defined in
. When presented to the authorization
server as part of a client registration request, the software
statement MUST be digitally signed or MACed using JWS and MUST contain an iss
(issuer) claim denoting the party attesting to the claims in the
software statement. It is RECOMMENDED that software statements be
digitally signed using the RS256 signature
algorithm, although particular applications MAY specify the use of
different algorithms. It is RECOMMENDED that software statements
contain the software_id claim to allow
authorization servers to correlate different instances of software
using the same software statement.For example, a software statement could contain the following
claims:The following non-normative example JWT includes these claims and
has been asymmetrically signed using RS256:The means by which a client or developer obtains a software
statement are outside the scope of this specification. Some common
methods could include a client developer generating a client-specific
JWT registering with a software API publisher to obtain a software
statement for a class of clients. The software statement is typically
distributed with all instances of a client application.The criteria by which authorization servers determine whether to
trust and utilize the information in a software statement are beyond
the scope of this specification.In some cases, authorization servers MAY choose to accept a
software statement value directly as a client identifier in an
authorization request, without a prior dynamic client registration
having been performed. The circumstances under which an authorization
server would do so, and the specific software statement
characteristics required in this case, are beyond the scope of this
specification.The client registration endpoint is an OAuth 2.0 endpoint defined in
this document that is designed to allow a client to be registered with
the authorization server. The client registration endpoint MUST accept
HTTP POST messages with request parameters encoded in the entity body
using the application/json format. The
client registration endpoint MUST be protected by a transport-layer
security mechanism, as described in .The client registration endpoint MAY be an OAuth 2.0 protected
resource and accept an initial access token in the form of an OAuth 2.0 access token to limit registration to
only previously authorized parties. The method by which the initial
access token is obtained by the client or developer is generally
out-of-band and is out of scope for this specification. The method by
which the initial access token is verified and validated by the client
registration endpoint is out of scope for this specification.To support open registration and facilitate wider interoperability,
the client registration endpoint SHOULD allow registration requests with
no authorization (which is to say, with no initial access token in the
request). These requests MAY be rate-limited or otherwise limited to
prevent a denial-of-service attack on the client registration
endpoint.This operation registers a client with the authorization server.
The authorization server assigns this client a unique client
identifier, optionally assigns a client secret, and associates the
metadata provided in the request with the issued client identifier.
The request includes any client metadata parameters being specified
for the client during the registration. The authorization server MAY
provision default values for any items omitted in the client
metadata.To register, the client or developer sends an HTTP POST to the
client registration endpoint with a content type of application/json. The HTTP Entity Payload is a
JSON document consisting of a JSON
object and all requested client metadata values as top-level members
of that JSON object.For example, if the server supports open registration (with no
initial access token), the client could send the following
registration request to the client registration endpoint:Alternatively, if the server supports authorized registration, the
developer or the client will be provisioned with an initial access
token. (The method by which the initial access token is obtained is
out of scope for this specification.) The developer or client sends
the following authorized registration request to the client
registration endpoint. Note that the initial access token sent in this
example as an OAuth 2.0 Bearer Token , but any
OAuth 2.0 token type could be used by an authorization server.In addition to JSON elements, client metadata values MAY also be
provided in a software statement, as described in . The authorization server MAY ignore
the software statement if it does not support this feature. If the
server supports software statements, client metadata values conveyed
in the software statement MUST take precedence over those conveyed
using plain JSON elements.Software statements are included in the requesting JSON object
using this OPTIONAL member: A software statement
containing client metadata values about the client software as
claims.Upon a successful registration request, the authorization server
returns a client identifier for the client. The server responds with
an HTTP 201 Created code and a body of type application/json
with content as described in .Upon an unsuccessful registration request, the authorization server
responds with an error, as described in .The response contains the client identifier as well as the client
secret, if the client is a confidential client. The response MAY
contain additional fields as specified by extensions to this
specification. REQUIRED. OAuth 2.0 client
identifier. It SHOULD NOT be currently valid for any other
registered client, though an authorization server MAY issue the
same client identifier to multiple instances of a registered
client at its discretion. OPTIONAL. OAuth 2.0 client
secret. If issued, this MUST be unique for each client_id and SHOULD be unique for multiple
instances of a client using the same 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. OPTIONAL. Time at
which the client identifier was issued. The time is represented
as the number of seconds from 1970-01-01T0:0:0Z as measured in
UTC until the date/time of issuance. REQUIRED if
client_secret is issued. Time at
which the client secret will expire or 0 if it will not expire.
The time is represented as the number of seconds from
1970-01-01T0:0:0Z as measured in UTC until the date/time of
expiration.Additionally, the authorization server MUST return 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 metadata values submitted
during the registration and substitute them with suitable
values.The response is an application/json
document with all parameters as top-level members of a JSON object.If a software statement was used as part of the registration, its
value MUST be returned unmodified in the response along with other
metadata using the software_statement
member name. Client metadata elements used from the software
statement MUST also be returned directly as top-level client
metadata values in the registration response (possibly with
different values, since the values requested and the values used may
differ).When an OAuth 2.0 error condition occurs, such as the client
presenting an invalid initial access token, the authorization server
returns an error response appropriate to the OAuth 2.0 token
type.When a registration error condition occurs, the authorization
server returns an HTTP 400 status code (unless otherwise specified)
with content type application/json
consisting of a JSON object describing
the error in the response body.Two members are defined for inclusion in the JSON object: REQUIRED. Single ASCII error code
string. OPTIONAL.
Human-readable ASCII text description of the error used for
debugging. Other members MAY also be included, and if not understood,
MUST be ignored.This specification defines the following error codes: The value of one or
more redirection URIs is invalid. 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 software
statement presented is invalid. The
software statement presented is not approved for use by this
authorization server.This specification establishes the OAuth Dynamic Registration
Client Metadata registry.OAuth registration client metadata values are registered with a
Specification Required () after a two-week
review period on the oauth-ext-review@ietf.org mailing list, on the
advice of one or more Designated Experts. However, to allow for the
allocation of values prior to publication, the Designated Expert(s)
may approve registration once they are satisfied that such a
specification will be published.Registration requests must be sent to the oauth-ext-review@ietf.org
mailing list for review and comment, with an appropriate subject
(e.g., "Request to register OAuth Dynamic Registration Client Metadata
name: example").Within the review period, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation
and, if applicable, suggestions as to how to make the request
successful.IANA must only accept registry updates from the Designated
Expert(s) and should direct all requests for registration to the
review mailing list. The name requested
(e.g., "example"). This name is case sensitive. Names that match
other registered names in a case insensitive manner SHOULD NOT
be accepted. Brief
description of the metadata value (e.g., "Example
description"). For Standards Track
RFCs, state "IESG". For others, give the name of the responsible
party. Other details (e.g., postal address, email address, home
page URI) may also be included. Reference to
the document(s) that specify the token endpoint authorization
method, preferably including a URI that can be used to retrieve
a copy of the document(s). An indication of the relevant
sections may also be included but is not required.The initial contents of the OAuth Dynamic Registration Client
Metadata registry are:Client Metadata Name: redirect_urisClient Metadata Description: Array of redirection URIs for
use in redirect-based flowsChange controller: IESGSpecification document(s): [[ this document ]]Client Metadata Name: token_endpoint_auth_methodClient Metadata Description: Requested authentication method
for the token endpointChange controller: IESGSpecification document(s): [[ this document ]]Client Metadata Name: grant_typesClient Metadata Description: Array of OAuth 2.0 grant types
that the client may useChange controller: IESGSpecification document(s): [[ this document ]]Client Metadata Name: response_typesClient Metadata Description: Array of the OAuth 2.0 response
types that the client may useChange controller: IESGSpecification document(s): [[ this document ]]Client Metadata Name: client_nameClient Metadata Description: Human-readable name of the
client to be presented to the userChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: client_uriClient Metadata Description: URL of a Web page providing
information about the clientChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: logo_uriClient Metadata Description: URL that references a logo for
the clientChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: scopeClient Metadata Description: Space separated list of scope
valuesChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: contactsClient Metadata Description: Array of strings representing
ways to contact people responsible for this client, typically
email addressesChange Controller: IESGSpecification document(s): [[ this document ]]Client Metadata Name: tos_uriClient Metadata Description: URL that points to a
human-readable Terms of Service document for the clientChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: policy_uriClient Metadata Description: URL that points to a
human-readable Policy document for the clientChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: jwks_uriClient Metadata Description: URL referencing the client's
JSON Web Key Set document representing
the client's public keysChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: jwksClient Metadata Description: Client's JSON
Web Key Set document representing the client's public
keysChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: software_idClient Metadata Description: Identifier for the software that
comprises a clientChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: software_versionClient Metadata Description: Version identifier for the
software that comprises a clientChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: client_idClient Metadata Description: Client identifierChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: client_secretClient Metadata Description: Client secretChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: client_id_issued_atClient Metadata Description: Time at which the client
identifier was issuedChange Controller: IESGSpecification Document(s): [[ this document ]]Client Metadata Name: client_secret_expires_atClient Metadata Description: Time at which the client secret
will expireChange Controller: IESGSpecification Document(s): [[ this document ]]This specification establishes the OAuth Token Endpoint
Authentication Methods registry.Additional values for use as token_endpoint_auth_method
metadata values are registered with a Specification Required () after a two-week review period on the
oauth-ext-review@ietf.org mailing list, on the advice of one or more
Designated Experts. However, to allow for the allocation of values
prior to publication, the Designated Expert(s) may approve
registration once they are satisfied that such a specification will be
published.Registration requests must be sent to the oauth-ext-review@ietf.org
mailing list for review and comment, with an appropriate subject
(e.g., "Request to register token_endpoint_auth_method value:
example").Within the review period, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation
and, if applicable, suggestions as to how to make the request
successful.IANA must only accept registry updates from the Designated
Expert(s) and should direct all requests for registration to the
review mailing list.
The name requested (e.g., "example"). This name is case
sensitive. Names that match other registered names in a case
insensitive manner SHOULD NOT be accepted. For Standards Track
RFCs, state "IESG". For others, give the name of the responsible
party. Other details (e.g., postal address, email address, home
page URI) may also be included. Reference to
the document(s) that specify the token endpoint authorization
method, preferably including a URI that can be used to retrieve
a copy of the document(s). An indication of the relevant
sections may also be included but is not required.The initial contents of the OAuth Token Endpoint Authentication
Methods registry are:Token Endpoint Authorization Method Name: noneChange controller: IESGSpecification document(s): [[ this document ]]Token Endpoint Authorization Method Name: client_secret_postChange controller: IESGSpecification document(s): [[ this document ]]Token Endpoint Authorization Method Name: client_secret_basicChange controller: IESGSpecification document(s): [[ this document ]]Since requests to the client registration endpoint result in the
transmission of clear-text credentials (in the HTTP request and
response), the authorization 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 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. Implementation security
considerations can be found in Recommendations for Secure Use of TLS and
DTLS.For clients that use redirect-based grant types such as authorization_code and implicit,
authorization servers MUST require clients to register their redirection
URI values. This can help mitigate attacks where rogue actors inject and
impersonate a validly registered client and intercept its authorization
code or tokens through an invalid redirection URI or open redirector.
Additionally, in order to prevent hijacking of the return values of the
redirection, registered redirection URI values MUST be one of:A remote web site protected by TLS (e.g.,
https://client.example.com/oauth_redirect)A web site hosted on the local machine using an HTTP URI (e.g.,
http://localhost:8080/oauth_redirect)A non-HTTP application-specific URL that is available only to the
client application (e.g., exampleapp://oauth_redirect)Public clients MAY register with an authorization server using this
protocol, if the authorization server's policy allows them. Public
clients use a none value for the token_endpoint_auth_method metadata field and are
generally used with the implicit grant type.
Often these clients will be short-lived in-browser applications
requesting access to a user's resources and access is tied to a user's
active session at the authorization server. Since such clients often do
not have long-term storage, it's possible that such clients would need
to re-register every time the browser application is loaded.
Additionally, such clients may not have ample opportunity to unregister
themselves using the delete action before the browser closes. To avoid
the resulting proliferation of dead client identifiers, an authorization
server MAY decide to expire registrations for existing clients meeting
certain criteria after a period of time has elapsed.Since different OAuth 2.0 grant types have different security and
usage parameters, an authorization server MAY require separate
registrations for a piece of software to support multiple grant types.
For instance, an authorization server might require that all clients
using the authorization_code grant type make
use of a client secret for the token_endpoint_auth_method,
but any clients using the implicit grant
type do not use any authentication at the token endpoint. In such a
situation, a server MAY disallow clients from registering for both the
authorization_code and implicit
grant types simultaneously. Similarly, the authorization_code
grant type is used to represent access on behalf of an end-user, but the
client_credentials grant type represents
access on behalf of the client itself. For security reasons, an
authorization server could require that different scopes be used for
these different use cases, and as a consequence it MAY disallow these
two grant types from being registered together by the same client. In
all of these cases, the authorization server would respond with an
invalid_client_metadata error response.Unless used as a claim in a software statement, the authorization
server MUST treat all client metadata as self-asserted. For instance, a
rogue client might use the name and logo of a legitimate client that it
is trying to impersonate. Additionally, a rogue client might try to use
the software identifier or software version of a legitimate client to
attempt to associate itself on the authorization server with instances
of the legitimate client. To counteract this, an authorization server
needs to take steps to mitigate this risk by looking at the entire
registration request and client configuration. For instance, an
authorization server could issue a warning if the domain/site of the
logo doesn't match the domain/site of redirection URIs. An authorization
server could also refuse registration requests from a known software
identifier that is requesting different redirection URIs or a different
client URI. An authorization server can also present warning messages to
end-users about dynamically registered clients in all cases, especially
if such clients have been recently registered or have not been trusted
by any users at the authorization server before.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_uri, tos_uri,
client_uri, and policy_uri).
For instance, 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,
tos_uri, client_uri,
and policy_uri have the same host and scheme
as the those defined in the array of redirect_uris
and that all of these URIs resolve to valid web pages.Clients MAY use both the direct JSON object and the JWT-encoded
software statement to present client metadata to the authorization
server as part of the registration request. A software statement is
cryptographically protected and represents claims made by the issuer of
the statement, while the JSON object represents the self-asserted claims
made by the client or developer directly. If the software statement is
valid and signed by an acceptable authority (such as the software API
publisher), the values of client metadata within the software statement
MUST take precedence over those metadata values presented in the plain
JSON object, which could have been modified en route.The software statement is an item that is self-asserted by the
client, even though its contents have been digitally signed or MACed by
the issuer of the software statement. As such, presentation of the
software statement is not sufficient in most cases to fully identity a
piece of client software. An initial access token, in contrast, does not
necessarily contain information about a particular piece of client
software but instead represents authorization to use the registration
endpoint. An authorization server MUST consider the full registration
request, including the software statement, initial access token, and
JSON client metadata values, when deciding whether to honor a given
registration request.If an authorization server receives a registration request for a
client that uses the same software_id and
software_version values as another client,
the server should treat the new registration as being suspect. It is
possible that the new client is trying to impersonate the existing
client.Since a client identifier is a public value that can be used to
impersonate a client at the authorization endpoint, an authorization
server that decides to issue the same client identifier to multiple
instances of a registered client needs to be very particular about the
circumstances under which this occurs. For instance, the authorization
server can limit a given client identifier to clients using the same
redirect-based flow and the same redirection URIs. An authorization
server SHOULD NOT issue the same client secret to multiple instances of
a registered client, even if they are issued the same client identifier,
or else the client secret could be leaked, allowing malicious impostors
to impersonate a confidential client.As the protocol described in this specification deals almost
exclusively with information about software and not about people, there
are very few privacy concerns for its use. The notable exception is the
contacts field as defined in Client Metadata, which contains contact
information for the developers or other parties responsible for the
client software. These values are intended to be displayed to end-users
and will be available to the administrators of the authorization server.
As such, the developer may wish to provide an email address or other
contact information expressly dedicated to the purpose of supporting the
client instead of using their personal or professional addresses.
Alternatively, the developer may wish to provide a collective email
address for the client to allow for continuing contact and support of
the client software after the developer moves on and someone else takes
over that responsibility.In general, the metadata for a client, such as the client name and
software identifier, are common across all instances of a piece of
client software and therefore pose no privacy issues for end-users.
Client identifiers, on the other hand, are often unique to a specific
instance of a client. For clients such as web sites that are used by
many users, there may not be significant privacy concerns regarding the
client identifier, but for clients such as native applications that are
installed on a single end-user's device, the client identifier could be
uniquely tracked during OAuth 2.0 transactions and its use tied to that
single end-user. However, as the client software still needs to be
authorized by a resource owner through an OAuth 2.0 authorization grant,
this type of tracking can occur whether or not the client identifier is
unique by correlating the authenticated resource owner with the
requesting client identifier.Note that clients are forbidden by this specification from creating
their own client identifier. If the client were able to do so, an
individual client instance could be tracked across multiple colluding
authorization servers, leading to privacy and security issues.
Additionally, client identifiers are generally issued uniquely per
registration request, even for the same instance of software. In this
way, an application could marginally improve privacy by registering
multiple times and appearing to be completely separate applications.
However, this technique does incur significant usability cost in the
form of requiring multiple authorizations per resource owner and is
therefore unlikely to be used in practice.JSON Web Token (JWT)Microsoftmbj@microsoft.comhttp://self-issued.info/Ping Identityve7jtb@ve7jtb.comhttp://www.thread-safe.com/Nomura Research
Instituten-sakimura@nri.co.jphttp://nat.sakimura.org/JSON Web Token (JWT)
Profile for OAuth 2.0 Client Authentication and Authorization
GrantsMicrosoftmbj@microsoft.comhttp://self-issued.info/Ping Identitybrian.d.campbell@gmail.comSalesforcecmortimore@salesforce.comSAML 2.0 Profile for
OAuth 2.0 Client Authentication and Authorization GrantsPing Identitybrian.d.campbell@gmail.comSalesforce.comcmortimore@salesforce.comMicrosoftmbj@microsoft.comhttp://self-issued.info/JSON Web Signature (JWS)Microsoftmbj@microsoft.comhttp://self-issued.info/Ping Identityve7jtb@ve7jtb.comhttp://www.thread-safe.com/Nomura Research
Instituten-sakimura@nri.co.jphttp://nat.sakimura.org/JSON Web Key (JWK)Microsoftmbj@microsoft.comhttp://self-issued.info/Language Subtag RegistryInternet Assigned Numbers Authority
(IANA)OAuth 2.0
Dynamic Client Registration Management ProtocolThe MITRE Corporationjricher@mitre.orgMicrosoftmbj@microsoft.comhttp://self-issued.info/Ping Identityve7jtb@ve7jtb.comNewcastle Universitym.p.machulak@ncl.ac.ukhttp://ncl.ac.uk/OpenID Connect Dynamic Client Registration 1.0Nomura Research Institute,
Ltd.Ping IdentityMicrosoftThis appendix describes different ways that this specification can be
utilized, including describing some of the choices that may need to be
made. Some of the choices are independent and can be used in
combination, whereas some of the choices are interrelated.Authorization servers that support open registration allow
registrations to be made with no initial access token. This allows
all client software to register with the authorization server.Authorization servers that support protected registration require
that an initial access token be used when making registration
requests. While the method by which a client or developer receives
this initial access token and the method by which the authorization
server validates this initial access token are out of scope for this
specification, a common approach is for the developer to use a
manual pre-registration portal at the authorization server that
issues an initial access token to the developer.When a software statement is not used in the registration
request, the authorization server must be willing to use client
metadata values without them being digitally signed or MACed (and
thereby attested to) by any authority. (Note that this choice is
independent of the Open versus Protected choice, and that an initial
access token is another possible form of attestation.)A software statement can be used in a registration request to
provide attestation by an authority for a set of client metadata
values. This can be useful when the authorization server wants to
restrict registration to client software attested to by a set of
authorities or when it wants to know that multiple registration
requests refer to the same piece of client software.In some use cases, client software will dynamically register
itself with an authorization server to obtain a client identifier
and other information needed to interact with the authorization
server. In this case, no client identifier for the authorization
server is packaged with the client software.In some cases, the developer (or development software being used
by the developer) will pre-register the client software with the
authorization server or a set of authorization servers. In this
case, the client identifier value(s) for the authorization server(s)
can be packaged with the client software.In some cases, each deployed instance of a piece of client
software will dynamically register and obtain distinct client
identifier values. This can be advantageous, for instance, if the
code flow is being used, as it also enables each client instance to
have its own client secret. This can be useful for native clients,
which cannot maintain the secrecy of a client secret value packaged
with the software, but which may be able to maintain the secrecy of
a per-instance client secret.In some cases, each deployed instance of a piece of client
software will share a common client identifier value. For instance,
this is often the case for in-browser clients using the implicit
flow, when no client secret is involved. Particular authorization
servers might choose, for instance, to maintain a mapping between
software statement values and client identifier values, and return
the same client identifier value for all registration requests for a
particular piece of software. The circumstances under which an
authorization server would do so, and the specific software
statement characteristics required in this case, are beyond the
scope of this specification.In some cases, authorization servers will maintain state about
registered clients, typically indexing this state using the client
identifier value. This state would typically include the client
metadata values associated with the client registration, and
possibly other state specific to the authorization server's
implementation. When stateful registration is used, operations to
support retrieving and/or updating this state may be supported. One
possible set of operations upon stateful registrations is described
in the
specification.In some cases, authorization servers will be implemented in a
manner the enables them to not maintain any local state about
registered clients. One means of doing this is to encode all the
registration state in the returned client identifier value, and
possibly encrypting the state to the authorization server to
maintain the confidentiality and integrity of the state.The authors thank the OAuth Working Group, the User-Managed Access
Working Group, and the OpenID Connect Working Group participants for
their input to this document. In particular, the following individuals
have been instrumental in their review and contribution to various
versions of this document: Amanda Anganes, Derek Atkins, Tim Bray,
Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, George Fletcher,
Thomas Hardjono, Phil Hunt, William Kim, Torsten Lodderstedt, Eve Maler,
Josh Mandel, Nov Matake, Tony Nadalin, Nat Sakimura, Christian Scholz,
and Hannes Tschofenig.[[ to be removed by the RFC editor before publication as an RFC
]]-24Clarified some party definitions.Clarified the opaqueness of software_id and
software_statement.Created a forward pointer to the Security Considerations section
for TLS requirements on the registration endpoint.Added a forward pointer to the Privacy Considerations section for
the contacts field.Wrote privacy considerations about client_id tracking.-23Updated author information.-22Reorganized registration response sections.Addressed shepherd comments.Added concrete JWK set to example.-21Applied minor editorial fixes.Added software statement examples.Moved software statement request details to sub-section.Clarified that a server MAY ignore the software statement (just
as it MAY ignore other metadata values).Removed TLS 1.0.Added privacy considerations around "contacts" field.Marked software_id as RECOMMENDED inside of a software
statement.-20Applied minor editorial fixes from working group comments.-19Added informative references to the OpenID Connect Dynamic Client
Registration and UMA specifications in the introduction.Clarified the jwks and jwks_uri descriptions and included an example
situation in which they might be used.Removed application_type.Added redirection URI usage restrictions to the Security
Considerations section, based on the client type.Expanded the tos_uri and policy_uri descriptions.-18 Corrected an example HTTP response status code to be 201
Created.Said more about who issues and uses initial access tokens and
software statements.Stated that the use of an initial access token is required when
the authorization server limits the parties that can register a
client.Stated that the implementation and use of all client metadata
fields is OPTIONAL, other than redirect_uris,
which MUST be used for redirect-based flows and implemented to
fulfill the requirement in Section 2 of OAuth 2.0.Added the application_type metadata
value, which had somehow been omitted.Added missing default metadata values, which had somehow been
omitted.Clarified that the software_id is
ultimately asserted by the client developer.Clarified that the error member is
required in error responses, error_description
member is optional, and other members may be present.Added security consideration about registrations with duplicate
software_id and software_version
values.-17 Merged draft-ietf-oauth-dyn-reg-metadata back into this
document.Removed "Core" from the document title.Explicitly state that all metadata members are optional.Clarified language around software statements for use in
registration context.Clarified that software statements need to be digitally signed or
MACed.Added a jwks metadata parameter to
parallel the jwks_uri parameter.Removed normative language from terminology.Expanded abstract and introduction.Addressed review comments from several working group members.-16 Replaced references to draft-jones-oauth-dyn-reg-metadata and
draft-jones-oauth-dyn-reg-management with
draft-ietf-oauth-dyn-reg-metadata and
draft-ietf-oauth-dyn-reg-management.Addressed review comments by Phil Hunt and Tony Nadalin.-15 Partitioned the Dynamic Client Registration specification into
core, metadata, and management specifications. This built on work
first published as draft-richer-oauth-dyn-reg-core-00 and
draft-richer-oauth-dyn-reg-management-00.Added the ability to use Software Statements. This built on work
first published as draft-hunt-oauth-software-statement-00 and
draft-hunt-oauth-client-association-00.Created the IANA OAuth Registration Client Metadata registry for
registering Client Metadata values.Defined Client Instance term and stated that multiple instances
can use the same client identifier value under certain
circumstances.Rewrote the introduction.Rewrote the Use Cases appendix.-14Added software_id and software_version metadata fieldsAdded direct references to RFC6750 errors in read/update/delete
methods-13Fixed broken example text in registration request and in delete
requestAdded security discussion of separating clients of different
grant typesFixed error reference to point to RFC6750 instead of RFC6749Clarified that servers must respond to all requests to
configuration endpoint, even if it's just an error codeLowercased all Terms to conform to style used in RFC6750-12Improved definition of Initial Access TokenChanged developer registration scenario to have the Initial
Access Token gotten through a normal OAuth 2.0 flowMoved non-normative client lifecycle examples to appendixMarked differentiating between auth servers as out of scopeAdded protocol flow diagramAdded credential rotation discussionCalled out Client Registration Endpoint as an OAuth 2.0 Protected
ResourceCleaned up several pieces of text-11Added localized text to registration request and response
examples.Removed client_secret_jwt and private_key_jwt.Clarified tos_uri and policy_uri definitions.Added the OAuth Token Endpoint Authentication Methods registry
for registering token_endpoint_auth_method
metadata values.Removed uses of non-ASCII characters, per RFC formatting
rules.Changed expires_at to client_secret_expires_at and issued_at to client_id_issued_at
for greater clarity.Added explanatory text for different credentials (Initial Access
Token, Registration Access Token, Client Credentials) and what
they're used for.Added Client Lifecycle discussion and examples.Defined Initial Access Token in Terminology section.-10Added language to point out that scope values are
service-specificClarified normative language around client metadataAdded extensibility to token_endpoint_auth_method using absolute
URIsAdded security consideration about registering redirect URIsChanged erroneous 403 responses to 401's with notes about token
handlingAdded example for initial registration credential-09Added method of internationalization for Client Metadata
valuesFixed SAML reference-08Collapsed jwk_uri, jwk_encryption_uri, x509_uri, and
x509_encryption_uri into a single jwks_uri parameterRenamed grant_type to grant_types since it's a plural valueFormalized name of "OAuth 2.0" throughout documentAdded JWT Bearer Assertion and SAML 2 Bearer Assertion to example
grant typesAdded response_types parameter and explanatory text on its use
with and relationship to grant_types-07Changed registration_access_url to registration_client_uriFixed missing text in 5.1Added Pragma: no-cache to examplesChanged "no such client" error to 403Renamed Client Registration Access Endpoint to Client
Configuration EndpointChanged all the parameter names containing "_url" to instead use
"_uri"Updated example text for forming Client Configuration Endpoint
URL-06Removed secret_rotation as a client-initiated action, including
removing client secret rotation endpoint and parameters.Changed _links structure to single value
registration_access_url.Collapsed create/update/read responses into client info
response.Changed return code of create action to 201.Added section to describe suggested generation and composition of
Client Registration Access URL.Added clarifying text to PUT and POST requests to specify JSON in
the body.Added Editor's Note to DELETE operation about its inclusion.Added Editor's Note to registration_access_url about alternate
syntax proposals.-05changed redirect_uri and contact to lists instead of space
delimited stringsremoved operation parameteradded _links structuremade client update management more RESTfulsplit endpoint into three partschanged input to JSON from form-encodedadded READ and DELETE operationsremoved Requirements sectionchanged token_endpoint_auth_type back to
token_endpoint_auth_method to match OIDC who changed to match us-04removed default_acr, too undefined in the general OAuth2 caseremoved default_max_auth_age, since there's no mechanism for
supplying a non-default max_auth_age in OAuth2clarified signing and encryption URLschanged token_endpoint_auth_method to token_endpoint_auth_type to
match OIDC-03added scope and grant_type claimsfixed various typos and changed wording for better clarityendpoint now returns the full set of client informationoperations on client_update allow for three actions on metadata:
leave existing value, clear existing value, replace existing value
with new value-02Reorganized contributors and referencesMoved OAuth references to RFCReorganized model/protocol sections for clarityChanged terminology to "client register" instead of "client
associate"Specified that client_id must match across all subsequent
requestsFixed RFC2XML formatting, especially on lists-01Merged UMA and OpenID Connect registrations into a single
documentChanged to form-parameter inputs to endpointRemoved pull-based registration-00Imported original UMA draft specification