draft-ietf-oauth-dyn-reg-17.txt   draft-ietf-oauth-dyn-reg-18.txt 
OAuth Working Group J. Richer OAuth Working Group J. Richer
Internet-Draft The MITRE Corporation Internet-Draft The MITRE Corporation
Intended status: Standards Track M. Jones Intended status: Standards Track M. Jones
Expires: November 23, 2014 Microsoft Expires: January 4, 2015 Microsoft
J. Bradley J. Bradley
Ping Identity Ping Identity
M. Machulak M. Machulak
Newcastle University Newcastle University
P. Hunt P. Hunt
Oracle Corporation Oracle Corporation
May 22, 2014 July 3, 2014
OAuth 2.0 Dynamic Client Registration Protocol OAuth 2.0 Dynamic Client Registration Protocol
draft-ietf-oauth-dyn-reg-17 draft-ietf-oauth-dyn-reg-18
Abstract Abstract
This specification defines mechanisms for dynamically registering This specification defines mechanisms for dynamically registering
OAuth 2.0 clients with authorization servers. Registration requests OAuth 2.0 clients with authorization servers. Registration requests
send a set of desired client metadata values to the authorization send a set of desired client metadata values to the authorization
server and the resulting registration responses return a client server and the resulting registration responses return a client
identifier to use at the authorization server and the client metadata identifier to use at the authorization server and the client metadata
values registered for the client. The client can then use this values registered for the client. The client can then use this
registration information to communicate with the authorization server registration information to communicate with the authorization server
skipping to change at page 1, line 46 skipping to change at page 1, line 46
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 23, 2014. This Internet-Draft will expire on January 4, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
skipping to change at page 3, line 13 skipping to change at page 3, line 13
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
1.3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 6 1.3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 6
2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 7 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 7
2.1. Relationship between Grant Types and Response Types . . . 11 2.1. Relationship between Grant Types and Response Types . . . 11
2.2. Human Readable Client Metadata . . . . . . . . . . . . . . 11 2.2. Human Readable Client Metadata . . . . . . . . . . . . . . 12
2.3. Software Statement . . . . . . . . . . . . . . . . . . . . 12 2.3. Software Statement . . . . . . . . . . . . . . . . . . . . 13
3. Client Registration Endpoint . . . . . . . . . . . . . . . . . 13 3. Client Registration Endpoint . . . . . . . . . . . . . . . . . 14
3.1. Client Registration Request . . . . . . . . . . . . . . . 14 3.1. Client Registration Request . . . . . . . . . . . . . . . 14
3.2. Client Registration Response . . . . . . . . . . . . . . . 17 3.2. Client Registration Response . . . . . . . . . . . . . . . 17
4. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.1. Client Information Response . . . . . . . . . . . . . . . 17 4.1. Client Information Response . . . . . . . . . . . . . . . 17
4.2. Client Registration Error Response . . . . . . . . . . . . 18 4.2. Client Registration Error Response . . . . . . . . . . . . 18
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
5.1. OAuth Dynamic Registration Client Metadata Registry . . . 20 5.1. OAuth Dynamic Registration Client Metadata Registry . . . 20
5.1.1. Registration Template . . . . . . . . . . . . . . . . 21 5.1.1. Registration Template . . . . . . . . . . . . . . . . 21
5.1.2. Initial Registry Contents . . . . . . . . . . . . . . 21 5.1.2. Initial Registry Contents . . . . . . . . . . . . . . 21
5.2. OAuth Token Endpoint Authentication Methods Registry . . . 24 5.2. OAuth Token Endpoint Authentication Methods Registry . . . 24
skipping to change at page 3, line 51 skipping to change at page 3, line 51
A.3.2. Registration by the Developer . . . . . . . . . . . . 30 A.3.2. Registration by the Developer . . . . . . . . . . . . 30
A.4. Client ID per Client Instance or per Client Software . . . 30 A.4. Client ID per Client Instance or per Client Software . . . 30
A.4.1. Client ID per Client Software Instance . . . . . . . . 30 A.4.1. Client ID per Client Software Instance . . . . . . . . 30
A.4.2. Client ID Shared Among All Instances of Client A.4.2. Client ID Shared Among All Instances of Client
Software . . . . . . . . . . . . . . . . . . . . . . . 31 Software . . . . . . . . . . . . . . . . . . . . . . . 31
A.5. Stateful or Stateless Registration . . . . . . . . . . . . 31 A.5. Stateful or Stateless Registration . . . . . . . . . . . . 31
A.5.1. Stateful Client Registration . . . . . . . . . . . . . 31 A.5.1. Stateful Client Registration . . . . . . . . . . . . . 31
A.5.2. Stateless Client Registration . . . . . . . . . . . . 31 A.5.2. Stateless Client Registration . . . . . . . . . . . . 31
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . . 31 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . . 31
Appendix C. Document History . . . . . . . . . . . . . . . . . . 32 Appendix C. Document History . . . . . . . . . . . . . . . . . . 32
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 37 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38
1. Introduction 1. Introduction
In order for an OAuth 2.0 client to utilize an OAuth 2.0 In order for an OAuth 2.0 client to utilize an OAuth 2.0
authorization server, the client needs specific information to authorization server, the client needs specific information to
interact with the server, including an OAuth 2.0 client identifier 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 use at that server. This specification describes how an OAuth 2.0
client can be dynamically registered with an authorization server to client can be dynamically registered with an authorization server to
obtain this information. obtain this information.
As part of the registration process, this specification also defines As part of the registration process, this specification also defines
a mechanism for the client to present the authorization server with a a mechanism for the client to present the authorization server with a
set of metadata, such as a set of valid redirection URIs. This set of metadata, such as a set of valid redirection URIs. This
metadata can either be communicated in a self-asserted fashion or as metadata can either be communicated in a self-asserted fashion or as
a set of metadata called a software statement, which can be digitally a set of metadata called a software statement, which is digitally
signed or MACed; in the case of a software statement, the issuer is signed or MACed; in the case of a software statement, the issuer is
vouching for the validity of the data about the client. vouching for the validity of the data about the client.
Traditionally, registration of a client with an authorization server Traditionally, registration of a client with an authorization server
is performed manually. The mechanisms defined in this specification is performed manually. The mechanisms defined in this specification
can be used either for a client to dynamically register itself with can be used either for a client to dynamically register itself with
authorization servers or for a client developer to programmatically authorization servers or for a client developer to programmatically
register the client with authorization servers. register the client with authorization servers.
1.1. Notational Conventions 1.1. Notational Conventions
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
Unless otherwise noted, all the protocol parameter names and values Unless otherwise noted, all the protocol parameter names and values
are case sensitive. are case sensitive.
1.2. Terminology 1.2. Terminology
This specification uses the terms "access token", "refresh token", This specification uses the terms "access token", "authorization
"authorization code", "authorization grant", "authorization server", code", "authorization endpoint", "authorization grant",
"authorization endpoint", "client", "client identifier", "client "authorization server", "client", "client identifier", "client
secret", "protected resource", "resource owner", "resource server", secret", "grant type", "protected resource", "redirection URI",
"response type", and "token endpoint" defined by OAuth 2.0 [RFC6749] "refresh token", "resource owner", "resource server", "response
and uses the term "Claim" defined by JSON Web Token (JWT) [JWT]. type", and "token endpoint" defined by OAuth 2.0 [RFC6749] and uses
the term "Claim" defined by JSON Web Token (JWT) [JWT].
This specification defines the following terms: This specification defines the following terms:
Client Developer Client Developer
The person or organization that builds a client software package The person or organization that builds a client software package
and prepares it for distribution. and prepares it for distribution.
Client Instance Client Instance
A deployed instance of a piece of client software. A deployed instance of a piece of client software.
Client Software Client Software
Software implementing an OAuth 2.0 client. Software implementing an OAuth 2.0 client.
Client Registration Endpoint Client Registration Endpoint
OAuth 2.0 endpoint through which a client can be registered at an OAuth 2.0 endpoint through which a client can be registered at an
authorization server. The means by which the URL for this authorization server. The means by which the URL for this
endpoint is obtained are out of scope for this specification. endpoint is obtained are out of scope for this specification.
Initial Access Token Initial Access Token
OAuth 2.0 access token optionally issued by an Authorization OAuth 2.0 access token optionally issued by an authorization
Server and used to authorize calls to the client registration server to a developer or client and used to authorize calls to the
endpoint. The type and format of this token are likely service- client registration endpoint. The type and format of this token
specific and are out of scope for this specification. The means are likely service-specific and are out of scope for this
by which the authorization server issues this token as well as the specification. The means by which the authorization server issues
means by which the registration endpoint validates this token are this token as well as the means by which the registration endpoint
out of scope for this specification. 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.
Deployment Organization Deployment Organization
An administrative security domain under which, a software API is An administrative security domain under which, a software API is
deployed and protected by an OAuth 2.0 framework. In simple cloud deployed and protected by an OAuth 2.0 framework. In simple cloud
deployments, the software API publisher and the deployment deployments, the software API publisher and the deployment
organization may be the same. In other scenarios, a software organization may be the same. In other scenarios, a software
publisher may be working with many different deployment publisher may be working with many different deployment
organizations. organizations.
Software API Deployment Software API Deployment
skipping to change at page 6, line 6 skipping to change at page 6, line 9
Software API Publisher Software API Publisher
The organization that defines a particular web accessible API that The organization that defines a particular web accessible API that
may deployed in one or more deployment environments. A publisher may deployed in one or more deployment environments. A publisher
may be any commercial, public, private, or open source may be any commercial, public, private, or open source
organization that is responsible for publishing and distributing organization that is responsible for publishing and distributing
software that may be protected via OAuth 2.0. In some cases a software that may be protected via OAuth 2.0. In some cases a
software API publisher and a client developer may be the same software API publisher and a client developer may be the same
organization. organization.
Software Statement Software Statement
A digitally signed or MACed JSON Web Token (JWT) [JWT] that Digitally signed or MACed JSON Web Token (JWT) [JWT] that asserts
asserts metadata values about the client software. metadata values about the client software. In some cases, a
software statement will be issued directly by the organization or
developer that creates the client software. In other cases, a
software statement will be issued by a third party organization
for use by the organization or developer that creates the client
software. 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.
1.3. Protocol Flow 1.3. Protocol Flow
+--------(A)- Initial Access Token (OPTIONAL) +--------(A)- Initial Access Token (OPTIONAL)
| |
| +----(B)- Software Statement (OPTIONAL) | +----(B)- Software Statement (OPTIONAL)
| | | |
v v v v
+-----------+ +---------------+ +-----------+ +---------------+
| |--(C)- Client Registration Request -->| Client | | |--(C)- Client Registration Request -->| Client |
skipping to change at page 7, line 9 skipping to change at page 7, line 24
(D) The authorization server registers the client and returns the (D) The authorization server registers the client and returns the
client's registered metadata, a client identifier that is unique client's registered metadata, a client identifier that is unique
at the server, a set of client credentials such as a client secret at the server, a set of client credentials such as a client secret
if applicable for this client, and possibly other values. if applicable for this client, and possibly other values.
2. Client Metadata 2. Client Metadata
Clients have a set of metadata values associated with their client Clients have a set of metadata values associated with their client
identifier at an authorization server, such as the list of valid identifier at an authorization server, such as the list of valid
redirect URIs or a display name. redirection URIs or a display name.
The client metadata values are used in two ways: The client metadata values are used in two ways:
o as input values to registration requests, and o as input values to registration requests, and
o as output values in registration responses. o as output values in registration responses.
The following client metadata fields are defined by this The following client metadata fields are defined by this
specification. All client metadata fields are OPTIONAL. specification. The implementation and use of all client metadata
fields is OPTIONAL, other than "redirect_uris".
redirect_uris redirect_uris
Array of redirect URIs for use in redirect-based flows such as the Array of redirection URIs for use in redirect-based flows such as
authorization code and implicit grant types. It is RECOMMENDED the authorization code and implicit flows. As required by Section
that clients using these flows register this parameter, and an 2 of OAuth 2.0 [RFC6749], clients using flows with redirection
authorization server SHOULD require registration of valid redirect MUST register their redirection URI values. Authorization servers
URIs for all clients that use these grant types to protect against MUST implement support for this metadata value.
token and credential theft attacks.
token_endpoint_auth_method token_endpoint_auth_method
The requested authentication method for the token endpoint. The requested authentication method for the token endpoint.
Values defined by this specification are: Values defined by this specification are:
* "none": The client is a public client as defined in OAuth 2.0 * "none": The client is a public client as defined in OAuth 2.0
and does not have a client secret. and does not have a client secret.
* "client_secret_post": The client uses the HTTP POST parameters * "client_secret_post": The client uses the HTTP POST parameters
defined in OAuth 2.0 section 2.3.1. defined in OAuth 2.0 section 2.3.1.
skipping to change at page 8, line 32 skipping to change at page 8, line 46
* "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2 * "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2
Bearer Grant defined in OAuth SAML 2 Bearer Token Profiles Bearer Grant defined in OAuth SAML 2 Bearer Token Profiles
[OAuth.SAML2]. [OAuth.SAML2].
Authorization Servers MAY allow for other values as defined in Authorization Servers MAY allow for other values as defined in
grant type extensions to OAuth 2.0. The extension process is grant type extensions to OAuth 2.0. The extension process is
described in OAuth 2.0 Section 2.5. If the token endpoint is used described in OAuth 2.0 Section 2.5. If the token endpoint is used
in the grant type, the value of this parameter MUST be the same as 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 the value of the "grant_type" parameter passed to the token
endpoint defined in the extension. endpoint defined in the extension. 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".
response_types response_types
Array of the OAuth 2.0 response types that the client may use. Array of the OAuth 2.0 response types that the client may use.
These response types are defined as follows: These response types are defined as follows:
* "code": The Authorization Code response described in OAuth 2.0 * "code": The Authorization Code response described in OAuth 2.0
Section 4.1. Section 4.1.
* "token": The Implicit response described in OAuth 2.0 Section * "token": The Implicit response described in OAuth 2.0 Section
4.2. 4.2.
Authorization servers MAY allow for other values as defined in Authorization servers MAY allow for other values as defined in
response type extensions to OAuth 2.0. The extension process is response type extensions to OAuth 2.0. The extension process is
described in OAuth 2.0 Section 2.5. If the authorization endpoint described in OAuth 2.0 Section 2.5. If the authorization endpoint
is used by the grant type, the value of this parameter MUST be the 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 same as the value of the "response_type" parameter passed to the
authorization endpoint defined in the extension. authorization endpoint defined in the extension. If omitted, the
default is that the client will use only the "code" response type.
client_name client_name
Human-readable name of the client to be presented to the user Human-readable name of the client to be presented to the user
during authorization. If omitted, the authorization server MAY during authorization. If omitted, the authorization server MAY
display the raw "client_id" value to the user instead. It is display the raw "client_id" value to the user instead. It is
RECOMMENDED that clients always send this field. The value of RECOMMENDED that clients always send this field. The value of
this field MAY be internationalized, as described in Section 2.2. this field MAY be internationalized, as described in Section 2.2.
client_uri client_uri
URL of a Web page providing information about the client. If URL of a Web page providing information about the client. If
skipping to change at page 9, line 42 skipping to change at page 10, line 13
client with a default set of scopes. client with a default set of scopes.
contacts contacts
Array of strings representing ways to contact people responsible Array of strings representing ways to contact people responsible
for this client, typically email addresses. The authorization for this client, typically email addresses. The authorization
server MAY make these addresses available to end users for support server MAY make these addresses available to end users for support
requests for the client. requests for the client.
tos_uri tos_uri
URL that points to a human-readable Terms of Service document for URL that points to a human-readable Terms of Service document for
the client. The Authorization Server SHOULD display this URL to the client. The authorization server SHOULD display this URL to
the end-user if it is given. The Terms of Service usually the end-user if it is given. The Terms of Service usually
describe a contractual relationship between the end-user and the describe a contractual relationship between the end-user and the
client that the end-user accepts when authorizing the client. The client that the end-user accepts when authorizing the client. The
value of this field MUST point to a valid web page. The value of value of this field MUST point to a valid web page. The value of
this field MAY be internationalized, as described in Section 2.2. this field MAY be internationalized, as described in Section 2.2.
policy_uri policy_uri
URL that points to a human-readable Policy document for the URL that points to a human-readable Policy document for the
client. The authorization server SHOULD display this URL to the client. The authorization server SHOULD display this URL to the
end-user if it is given. The policy usually describes how an end- end-user if it is given. The policy usually describes how an end-
skipping to change at page 10, line 29 skipping to change at page 10, line 49
clients that cannot use the "jwks_uri" parameter. For instance, a clients that cannot use the "jwks_uri" parameter. For instance, a
native application might not have a location to host the contents native application might not have a location to host the contents
of the JWK Set that would be reachable by the authorization of the JWK Set that would be reachable by the authorization
server. The "jwks_uri" and "jwks" parameters MUST NOT be used server. The "jwks_uri" and "jwks" parameters MUST NOT be used
together. together.
software_id software_id
Identifier for the software that comprises a client. Unlike Identifier for the software that comprises a client. Unlike
"client_id", which is issued by the authorization server and may "client_id", which is issued by the authorization server and may
vary between instances, the "software_id" is asserted by the vary between instances, the "software_id" is asserted by the
client software and is intended to be shared among all instances client software on behalf of the software developer and is
of the client software. The identifier SHOULD NOT change when intended to be shared among all instances of the client software.
software version changes or when a new installation occurs. The identifier SHOULD NOT change when software version changes or
when a new installation occurs.
software_version software_version
Version identifier for the software that comprises a client. The Version identifier for the software that comprises a client. The
value of this field is a string that is intended to be compared value of this field is a string that is intended to be compared
using string equality matching. The value of the using string equality matching. The value of the
"software_version" SHOULD change on any update to the client "software_version" SHOULD change on any update to the client
software. software.
Extensions and profiles of this specification MAY expand this list. Extensions and profiles of this specification MAY expand this list.
The authorization server MUST ignore any client metadata values sent The authorization server MUST ignore any client metadata values sent
skipping to change at page 14, line 12 skipping to change at page 14, line 35
access token is verified and validated by the client registration access token is verified and validated by the client registration
endpoint is out of scope for this specification. endpoint is out of scope for this specification.
To support open registration and facilitate wider interoperability, To support open registration and facilitate wider interoperability,
the client registration endpoint SHOULD allow registration requests the client registration endpoint SHOULD allow registration requests
with no authorization (which is to say, with no initial access token with no authorization (which is to say, with no initial access token
in the request). These requests MAY be rate-limited or otherwise in the request). These requests MAY be rate-limited or otherwise
limited to prevent a denial-of-service attack on the client limited to prevent a denial-of-service attack on the client
registration endpoint. registration endpoint.
The client registration endpoint MUST ignore all parameters it does
not understand.
3.1. Client Registration Request 3.1. Client Registration Request
This operation registers a client with the authorization server. The This operation registers a client with the authorization server. The
authorization server assigns this client a unique client identifier, authorization server assigns this client a unique client identifier,
optionally assigns a client secret, and associates the metadata given optionally assigns a client secret, and associates the metadata given
in the request with the issued client identifier. The request in the request with the issued client identifier. The request
includes any client metadata parameters being specified for the includes any client metadata parameters being specified for the
client during the registration. The authorization server MAY client during the registration. The authorization server MAY
provision default values for any items omitted in the client provision default values for any items omitted in the client
metadata. metadata.
skipping to change at page 17, line 30 skipping to change at page 17, line 30
4.1. Client Information Response 4.1. Client Information Response
The response contains the client identifier as well as the client The response contains the client identifier as well as the client
secret, if the client is a confidential client. The response MAY secret, if the client is a confidential client. The response MAY
contain additional fields as specified by extensions to this contain additional fields as specified by extensions to this
specification. specification.
client_id client_id
REQUIRED. OAuth 2.0 client identifier. It SHOULD NOT be REQUIRED. OAuth 2.0 client identifier. It SHOULD NOT be
currently valid for any other registered client, though an currently valid for any other registered client, though an
Authorization Server MAY issue the same client identifier to authorization server MAY issue the same client identifier to
multiple instances of a registered client, at its discretion. multiple instances of a registered client, at its discretion.
client_secret client_secret
OPTIONAL. OAuth 2.0 client secret. If issued, this MUST be OPTIONAL. OAuth 2.0 client secret. If issued, this MUST be
unique for each "client_id". This value is used by confidential unique for each "client_id". This value is used by confidential
clients to authenticate to the token endpoint as described in clients to authenticate to the token endpoint as described in
OAuth 2.0 [RFC6749] Section 2.3.1. OAuth 2.0 [RFC6749] Section 2.3.1.
client_id_issued_at client_id_issued_at
OPTIONAL. Time at which the client identifier was issued. The OPTIONAL. Time at which the client identifier was issued. The
time is represented as the number of seconds from 1970-01- time is represented as the number of seconds from 1970-01-
01T0:0:0Z as measured in UTC until the date/time. 01T0:0:0Z as measured in UTC until the date/time.
client_secret_expires_at client_secret_expires_at
REQUIRED if "client_secret" is issued. Time at which the client REQUIRED if "client_secret" is issued. Time at which the client
secret will expire or 0 if it will not expire. The time is 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 represented as the number of seconds from 1970-01-01T0:0:0Z as
measured in UTC until the date/time. measured in UTC until the date/time.
Additionally, the Authorization Server MUST return all registered Additionally, the authorization server MUST return all registered
metadata about this client, including any fields provisioned by the metadata about this client, including any fields provisioned by the
authorization server itself. The authorization server MAY reject or authorization server itself. The authorization server MAY reject or
replace any of the client's requested metadata values submitted replace any of the client's requested metadata values submitted
during the registration or update requests and substitute them with during the registration or update requests and substitute them with
suitable values. suitable values.
The response is an "application/json" document with all parameters as The response is an "application/json" document with all parameters as
top-level members of a JSON object [RFC7159]. top-level members of a JSON object [RFC7159].
If a software statement was used as part of the registration, its If a software statement was used as part of the registration, its
value MUST be returned in the response along with other metadata. value MUST be returned in the response along with other metadata.
Client metadata elements used from the software statement MUST also Client metadata elements used from the software statement MUST also
be returned directly as top-level client metadata values in the be returned directly as top-level client metadata values in the
registration response (possibly with different values, since the registration response (possibly with different values, since the
values requested and the values used may differ). values requested and the values used may differ).
Following is a non-normative example response: Following is a non-normative example response:
HTTP/1.1 200 OK HTTP/1.1 201 Created
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
Pragma: no-cache Pragma: no-cache
{ {
"client_id":"s6BhdRkqt3", "client_id":"s6BhdRkqt3",
"client_secret": "cf136dc3c1fc93f31185e5885805d", "client_secret": "cf136dc3c1fc93f31185e5885805d",
"client_id_issued_at":2893256800, "client_id_issued_at":2893256800,
"client_secret_expires_at":2893276800, "client_secret_expires_at":2893276800,
"redirect_uris":[ "redirect_uris":[
skipping to change at page 19, line 7 skipping to change at page 19, line 7
When an OAuth 2.0 error condition occurs, such as the client When an OAuth 2.0 error condition occurs, such as the client
presenting an invalid initial access token, the authorization server presenting an invalid initial access token, the authorization server
returns an error response appropriate to the OAuth 2.0 token type. returns an error response appropriate to the OAuth 2.0 token type.
When a registration error condition occurs, the authorization server When a registration error condition occurs, the authorization server
returns an HTTP 400 status code (unless otherwise specified) with returns an HTTP 400 status code (unless otherwise specified) with
content type "application/json" consisting of a JSON object [RFC7159] content type "application/json" consisting of a JSON object [RFC7159]
describing the error in the response body. describing the error in the response body.
The JSON object contains two members: Two members are defined for inclusion in the JSON object:
error error
Single ASCII error code string. REQUIRED. Single ASCII error code string.
error_description error_description
Human-readable ASCII text description of the error used for OPTIONAL. Human-readable ASCII text description of the error used
debugging. for debugging.
Other members MAY also be included, and if not understood, MUST be
ignored.
This specification defines the following error codes: This specification defines the following error codes:
invalid_redirect_uri invalid_redirect_uri
The value of one or more redirection URIs is invalid. The value of one or more redirection URIs is invalid.
invalid_client_metadata invalid_client_metadata
The value of one of the client metadata fields is invalid and the The value of one of the client metadata fields is invalid and the
server has rejected this request. Note that an Authorization server has rejected this request. Note that an authorization
server MAY choose to substitute a valid value for any requested server MAY choose to substitute a valid value for any requested
parameter of a client's metadata. parameter of a client's metadata.
invalid_software_statement invalid_software_statement
The software statement presented is invalid. The software statement presented is invalid.
unapproved_software_statement unapproved_software_statement
The software statement presented is not approved for use by this The software statement presented is not approved for use by this
authorization server. authorization server.
Following is a non-normative example of an error response resulting Following is a non-normative example of an error response resulting
from a redirect URI that has been blacklisted by the authorization from a redirection URI that has been blacklisted by the authorization
server (with line wraps within values for display purposes only): server (with line wraps within values for display purposes only):
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
Pragma: no-cache Pragma: no-cache
{ {
"error": "invalid_redirect_uri", "error": "invalid_redirect_uri",
"error_description": "The redirect URI http://sketchy.example.com "error_description": "The redirection URI
is not allowed by this server." http://sketchy.example.com is not allowed by this server."
} }
Following is a non-normative example of an error response resulting Following is a non-normative example of an error response resulting
from an inconsistent combination of "response_types" and from an inconsistent combination of "response_types" and
"grant_types" values (with line wraps within values for display "grant_types" values (with line wraps within values for display
purposes only): purposes only):
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
skipping to change at page 21, line 33 skipping to change at page 21, line 33
authorization method, preferably including a URI that can be used authorization method, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required. relevant sections may also be included but is not required.
5.1.2. Initial Registry Contents 5.1.2. Initial Registry Contents
The initial contents of the OAuth Dynamic Registration Client The initial contents of the OAuth Dynamic Registration Client
Metadata registry are: Metadata registry are:
o Client Metadata Name: "redirect_uris" o Client Metadata Name: "redirect_uris"
o Client Metadata Description: Array of redirect URIs for use in o Client Metadata Description: Array of redirection URIs for use in
redirect-based flows redirect-based flows
o Change controller: IESG o Change controller: IESG
o Specification document(s): [[ this document ]] o Specification document(s): [[ this document ]]
o Client Metadata Name: "token_endpoint_auth_method" o Client Metadata Name: "token_endpoint_auth_method"
o Client Metadata Description: Requested authentication method for o Client Metadata Description: Requested authentication method for
the token endpoint the token endpoint
o Change controller: IESG o Change controller: IESG
o Specification document(s): [[ this document ]] o Specification document(s): [[ this document ]]
skipping to change at page 25, line 26 skipping to change at page 25, line 26
o Specification document(s): [[ this document ]] o Specification document(s): [[ this document ]]
o Token Endpoint Authorization Method Name: "client_secret_basic" o Token Endpoint Authorization Method Name: "client_secret_basic"
o Change controller: IESG o Change controller: IESG
o Specification document(s): [[ this document ]] o Specification document(s): [[ this document ]]
6. Security Considerations 6. Security Considerations
Since requests to the client registration endpoint result in the Since requests to the client registration endpoint result in the
transmission of clear-text credentials (in the HTTP request and transmission of clear-text credentials (in the HTTP request and
response), the Authorization Server MUST require the use of a response), the authorization server MUST require the use of a
transport-layer security mechanism when sending requests to the transport-layer security mechanism when sending requests to the
registration endpoint. The server MUST support TLS 1.2 RFC 5246 registration endpoint. The server MUST support TLS 1.2 RFC 5246
[RFC5246] and/or TLS 1.0 [RFC2246] and MAY support additional [RFC5246] and/or TLS 1.0 [RFC2246] and MAY support additional
transport-layer mechanisms meeting its security requirements. When transport-layer mechanisms meeting its security requirements. When
using TLS, the client MUST perform a TLS/SSL server certificate using TLS, the client MUST perform a TLS/SSL server certificate
check, per RFC 6125 [RFC6125]. check, per RFC 6125 [RFC6125].
For clients that use redirect-based grant types such as For clients that use redirect-based grant types such as
"authorization_code" and "implicit", authorization servers SHOULD "authorization_code" and "implicit", authorization servers MUST
require clients to register their "redirect_uris" in full. Requiring require clients to register their "redirect_uri" values. This can
clients to do so can help mitigate attacks where rogue actors inject help mitigate attacks where rogue actors inject and impersonate a
and impersonate a validly registered client and intercept its validly registered client and intercept its authorization code or
authorization code or tokens through an invalid redirect URI or open tokens through an invalid redirection URI or open redirector.
redirector.
Public clients MAY register with an authorization server using this Public clients MAY register with an authorization server using this
protocol, if the authorization server's policy allows them. Public protocol, if the authorization server's policy allows them. Public
clients use a "none" value for the "token_endpoint_auth_method" clients use a "none" value for the "token_endpoint_auth_method"
metadata field and are generally used with the "implicit" grant type. metadata field and are generally used with the "implicit" grant type.
Often these clients will be short-lived in-browser applications Often these clients will be short-lived in-browser applications
requesting access to a user's resources and access is tied to a requesting access to a user's resources and access is tied to a
user's active session at the authorization server. Since such user's active session at the authorization server. Since such
clients often do not have long-term storage, it's possible that 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 clients would need to re-register every time the browser application
skipping to change at page 26, line 40 skipping to change at page 26, line 39
server MUST treat all client metadata as self-asserted. For server MUST treat all client metadata as self-asserted. For
instance, a rogue client might use the name and logo of a legitimate instance, a rogue client might use the name and logo of a legitimate
client that it is trying to impersonate. Additionally, a rogue client that it is trying to impersonate. Additionally, a rogue
client might try to use the software identifier or software version client might try to use the software identifier or software version
of a legitimate client to attempt to associate itself on the of a legitimate client to attempt to associate itself on the
authorization server with instances of the legitimate client. To authorization server with instances of the legitimate client. To
counteract this, an authorization server needs to take steps to counteract this, an authorization server needs to take steps to
mitigate this risk by looking at the entire registration request and mitigate this risk by looking at the entire registration request and
client configuration. For instance, an authorization server could client configuration. For instance, an authorization server could
issue a warning if the domain/site of the logo doesn't match the issue a warning if the domain/site of the logo doesn't match the
domain/site of redirect URIs. An authorization server could also domain/site of redirection URIs. An authorization server could also
refuse registration requests from a known software identifier that is refuse registration requests from a known software identifier that is
requesting different redirect URIs or a different client homepage requesting different redirection URIs or a different client homepage
URI. An authorization server can also present warning messages to URI. An authorization server can also present warning messages to
end users about dynamically registered clients in all cases, end users about dynamically registered clients in all cases,
especially if such clients have been recently registered or have not especially if such clients have been recently registered or have not
been trusted by any users at the authorization server before. been trusted by any users at the authorization server before.
In a situation where the authorization server is supporting open In a situation where the authorization server is supporting open
client registration, it must be extremely careful with any URL client registration, it must be extremely careful with any URL
provided by the client that will be displayed to the user (e.g. provided by the client that will be displayed to the user (e.g.
"logo_uri", "tos_uri", "client_uri", and "policy_uri"). For "logo_uri", "tos_uri", "client_uri", and "policy_uri"). For
instance, a rogue client could specify a registration request with a instance, a rogue client could specify a registration request with a
skipping to change at page 27, line 34 skipping to change at page 27, line 33
by the issuer of the software statement. As such, presentation of by the issuer of the software statement. As such, presentation of
the software statement is not sufficient in most cases to fully the software statement is not sufficient in most cases to fully
identity a piece of client software. An initial access token, in identity a piece of client software. An initial access token, in
contrast, does not necessarily contain information about a particular contrast, does not necessarily contain information about a particular
piece of client software but instead represents authorization to use piece of client software but instead represents authorization to use
the registration endpoint. An authorization server MUST consider the the registration endpoint. An authorization server MUST consider the
full registration request, including the software statement, initial full registration request, including the software statement, initial
access token, and JSON client metadata values, when deciding whether access token, and JSON client metadata values, when deciding whether
to honor a given registration request. 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 Since a client identifier is a public value that can be used to
impersonate a client at the authorization endpoint, an authorization impersonate a client at the authorization endpoint, an authorization
server that decides to issue the same client identifier to multiple server that decides to issue the same client identifier to multiple
instances of a registered client MUST be very particular about the instances of a registered client MUST be very particular about the
circumstances under which this occurs. For instance, the circumstances under which this occurs. For instance, the
authorization server can limit a given client identifier to clients authorization server can limit a given client identifier to clients
using the same redirect-based flow and the same redirect URIs. An using the same redirect-based flow and the same redirection URIs. An
authorization server SHOULD NOT issue the same client secret to authorization server SHOULD NOT issue the same client secret to
multiple instances of a registered client, even if they are issued multiple instances of a registered client, even if they are issued
the same client identifier, or else the client secret could be the same client identifier, or else the client secret could be
leaked, allowing malicious imposters to impersonate a confidential leaked, allowing malicious imposters to impersonate a confidential
client. client.
7. References 7. References
7.1. Normative References 7.1. Normative References
[IANA.Language] [IANA.Language]
Internet Assigned Numbers Authority (IANA), "Language Internet Assigned Numbers Authority (IANA), "Language
Subtag Registry", 2005. Subtag Registry", 2005.
[JWK] Jones, M., "JSON Web Key (JWK)", [JWK] Jones, M., "JSON Web Key (JWK)",
draft-ietf-jose-json-web-key (work in progress), draft-ietf-jose-json-web-key (work in progress),
April 2014. July 2014.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature (work Signature (JWS)", draft-ietf-jose-json-web-signature (work
in progress), April 2014. in progress), July 2014.
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", draft-ietf-oauth-json-web-token (work in (JWT)", draft-ietf-oauth-json-web-token (work in
progress), April 2014. progress), July 2014.
[OAuth.JWT] [OAuth.JWT]
Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token
(JWT) Profile for OAuth 2.0 Client Authentication and (JWT) Profile for OAuth 2.0 Client Authentication and
Authorization Grants", draft-ietf-oauth-jwt-bearer (work Authorization Grants", draft-ietf-oauth-jwt-bearer (work
in progress), April 2014. in progress), April 2014.
[OAuth.SAML2] [OAuth.SAML2]
Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0
Profile for OAuth 2.0 Client Authentication and Profile for OAuth 2.0 Client Authentication and
skipping to change at page 29, line 23 skipping to change at page 29, line 26
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
7.2. Informative References 7.2. Informative References
[OAuth.Registration.Management] [OAuth.Registration.Management]
Richer, J., Jones, M., Bradley, J., Machulak, M., and P. Richer, J., Jones, M., Bradley, J., Machulak, M., and P.
Hunt, "OAuth 2.0 Dynamic Client Registration Management Hunt, "OAuth 2.0 Dynamic Client Registration Management
Protocol", draft-ietf-oauth-dyn-reg-management (work in Protocol", draft-ietf-oauth-dyn-reg-management (work in
progress), May 2014. progress), July 2014.
Appendix A. Use Cases Appendix A. Use Cases
This appendix describes different ways that this specification can be This appendix describes different ways that this specification can be
utilized, including describing some of the choices that may need to utilized, including describing some of the choices that may need to
be made. Some of the choices are independent and can be used in be made. Some of the choices are independent and can be used in
combination, whereas some of the choices are interrelated. combination, whereas some of the choices are interrelated.
A.1. Open versus Protected Dynamic Client Registration A.1. Open versus Protected Dynamic Client Registration
skipping to change at page 32, line 13 skipping to change at page 32, line 15
to various versions of this document: Amanda Anganes, Derek Atkins, to various versions of this document: Amanda Anganes, Derek Atkins,
Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov,
George Fletcher, Thomas Hardjono, Phil Hunt, William Kim, Torsten George Fletcher, Thomas Hardjono, Phil Hunt, William Kim, Torsten
Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Tony Nadalin, Nat Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Tony Nadalin, Nat
Sakimura, Christian Scholz, and Hannes Tschofenig. Sakimura, Christian Scholz, and Hannes Tschofenig.
Appendix C. Document History Appendix C. Document History
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
-18
o Corrected an example HTTP response status code to be 201 Created.
o Said more about who issues and uses initial access tokens and
software statements.
o Stated that the use of an initial access token is required when
the authorization server limits the parties that can register a
client.
o 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.
o Added the "application_type" metadata value, which had somehow
been omitted.
o Added missing default metadata values, which had somehow been
omitted.
o Clarified that the "software_id" is ultimately asserted by the
client developer.
o Clarified that the "error" member is required in error responses,
"error_description" member is optional, and other members may be
present.
o Added security consideration about registrations with duplicate
"software_id" and "software_version" values.
-17 -17
o Merged draft-ietf-oauth-dyn-reg-metadata back into this document. o Merged draft-ietf-oauth-dyn-reg-metadata back into this document.
o Removed "Core" from the document title. o Removed "Core" from the document title.
o Explicitly state that all metadata members are optional. o Explicitly state that all metadata members are optional.
o Clarified language around software statements for use in o Clarified language around software statements for use in
registration context. registration context.
 End of changes. 40 change blocks. 
67 lines changed or deleted 125 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/