draft-ietf-oauth-dyn-reg-27.txt   draft-ietf-oauth-dyn-reg-28.txt 
OAuth Working Group J. Richer, Ed. OAuth Working Group J. Richer, Ed.
Internet-Draft Internet-Draft
Intended status: Standards Track M. Jones Intended status: Standards Track M. Jones
Expires: September 26, 2015 Microsoft Expires: October 23, 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
March 25, 2015 April 21, 2015
OAuth 2.0 Dynamic Client Registration Protocol OAuth 2.0 Dynamic Client Registration Protocol
draft-ietf-oauth-dyn-reg-27 draft-ietf-oauth-dyn-reg-28
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. The resulting registration responses return a client server. 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 September 26, 2015. This Internet-Draft will expire on October 23, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 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
skipping to change at page 2, line 27 skipping to change at page 2, line 27
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
1.3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 5
2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 6 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Relationship between Grant Types and Response Types . . . 10 2.1. Relationship between Grant Types and Response Types . . . 11
2.2. Human-Readable Client Metadata . . . . . . . . . . . . . 11 2.2. Human-Readable Client Metadata . . . . . . . . . . . . . 11
2.3. Software Statement . . . . . . . . . . . . . . . . . . . 12 2.3. Software Statement . . . . . . . . . . . . . . . . . . . 12
3. Client Registration Endpoint . . . . . . . . . . . . . . . . 13 3. Client Registration Endpoint . . . . . . . . . . . . . . . . 14
3.1. Client Registration Request . . . . . . . . . . . . . . . 14 3.1. Client Registration Request . . . . . . . . . . . . . . . 14
3.1.1. Client Registration Request Using a Software 3.1.1. Client Registration Request Using a Software
Statement . . . . . . . . . . . . . . . . . . . . . . 16 Statement . . . . . . . . . . . . . . . . . . . . . . 16
3.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 17 3.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.1. Client Information Response . . . . . . . . . . . . . 17 3.2.1. Client Information Response . . . . . . . . . . . . . 17
3.2.2. Client Registration Error Response . . . . . . . . . 19 3.2.2. Client Registration Error Response . . . . . . . . . 19
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
4.1. OAuth Dynamic Client Registration Metadata Registry . . . 21 4.1. OAuth Dynamic Client Registration Metadata Registry . . . 21
4.1.1. Registration Template . . . . . . . . . . . . . . . . 21 4.1.1. Registration Template . . . . . . . . . . . . . . . . 21
4.1.2. Initial Registry Contents . . . . . . . . . . . . . . 22 4.1.2. Initial Registry Contents . . . . . . . . . . . . . . 22
4.2. OAuth Token Endpoint Authentication Methods Registry . . 24 4.2. OAuth Token Endpoint Authentication Methods Registry . . 24
4.2.1. Registration Template . . . . . . . . . . . . . . . . 25 4.2.1. Registration Template . . . . . . . . . . . . . . . . 25
4.2.2. Initial Registry Contents . . . . . . . . . . . . . . 25 4.2.2. Initial Registry Contents . . . . . . . . . . . . . . 25
5. Security Considerations . . . . . . . . . . . . . . . . . . . 25 5. Security Considerations . . . . . . . . . . . . . . . . . . . 25
6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 28 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 29
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.1. Normative References . . . . . . . . . . . . . . . . . . 29 7.1. Normative References . . . . . . . . . . . . . . . . . . 30
7.2. Informative References . . . . . . . . . . . . . . . . . 31 7.2. Informative References . . . . . . . . . . . . . . . . . 31
Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . 31 Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . 31
A.1. Open versus Protected Dynamic Client Registration . . . . 31 A.1. Open versus Protected Dynamic Client Registration . . . . 32
A.1.1. Open Dynamic Client Registration . . . . . . . . . . 31 A.1.1. Open Dynamic Client Registration . . . . . . . . . . 32
A.1.2. Protected Dynamic Client Registration . . . . . . . . 31 A.1.2. Protected Dynamic Client Registration . . . . . . . . 32
A.2. Registration Without or With Software Statements . . . . 32 A.2. Registration Without or With Software Statements . . . . 32
A.2.1. Registration Without a Software Statement . . . . . . 32 A.2.1. Registration Without a Software Statement . . . . . . 32
A.2.2. Registration With a Software Statement . . . . . . . 32 A.2.2. Registration With a Software Statement . . . . . . . 32
A.3. Registration by the Client or Developer . . . . . . . . . 32 A.3. Registration by the Client or Developer . . . . . . . . . 32
A.3.1. Registration by the Client . . . . . . . . . . . . . 32 A.3.1. Registration by the Client . . . . . . . . . . . . . 32
A.3.2. Registration by the Developer . . . . . . . . . . . . 32 A.3.2. Registration by the Developer . . . . . . . . . . . . 33
A.4. Client ID per Client Instance or per Client Software . . 32 A.4. Client ID per Client Instance or per Client Software . . 33
A.4.1. Client ID per Client Software Instance . . . . . . . 32 A.4.1. Client ID per Client Software Instance . . . . . . . 33
A.4.2. Client ID Shared Among All Instances of Client A.4.2. Client ID Shared Among All Instances of Client
Software . . . . . . . . . . . . . . . . . . . . . . 33 Software . . . . . . . . . . . . . . . . . . . . . . 33
A.5. Stateful or Stateless Registration . . . . . . . . . . . 33 A.5. Stateful or Stateless Registration . . . . . . . . . . . 33
A.5.1. Stateful Client Registration . . . . . . . . . . . . 33 A.5.1. Stateful Client Registration . . . . . . . . . . . . 33
A.5.2. Stateless Client Registration . . . . . . . . . . . . 33 A.5.2. Stateless Client Registration . . . . . . . . . . . . 34
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 33 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 34
Appendix C. Document History . . . . . . . . . . . . . . . . . . 34 Appendix C. Document History . . . . . . . . . . . . . . . . . . 34
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40
1. Introduction 1. Introduction
In order for an OAuth 2.0 [RFC6749] client to utilize an OAuth 2.0 In order for an OAuth 2.0 [RFC6749] 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
skipping to change at page 7, line 12 skipping to change at page 7, line 12
their client identifier at an authorization server, such as the list their client identifier at an authorization server, such as the list
of valid redirection URIs or a display name. of valid redirection URIs or a display name.
These client metadata values are used in two ways: These 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. The implementation and use of all client metadata specification. The implementation and use of all client metadata
fields is OPTIONAL, unless stated otherwise. fields is OPTIONAL, unless stated otherwise. All data member types
(strings, arrays, numbers) are defined in terms of their JSON
[RFC7159] representations.
redirect_uris redirect_uris
Array of redirection URI values for use in redirect-based flows Array of redirection URI strings for use in redirect-based flows
such as the authorization code and implicit flows. As required by such as the authorization code and implicit flows. As required by
Section 2 of OAuth 2.0 [RFC6749], clients using flows with Section 2 of OAuth 2.0 [RFC6749], clients using flows with
redirection MUST register their redirection URI values. redirection MUST register their redirection URI values.
Authorization servers that support dynamic registration for Authorization servers that support dynamic registration for
redirect-based flows MUST implement support for this metadata redirect-based flows MUST implement support for this metadata
value. value.
token_endpoint_auth_method token_endpoint_auth_method
The requested authentication method for the token endpoint. String indicator of the requested authentication method for the
Values defined by this specification are: token endpoint. 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.
* "client_secret_basic": the client uses HTTP Basic defined in * "client_secret_basic": the client uses HTTP Basic defined in
OAuth 2.0 section 2.3.1 OAuth 2.0 section 2.3.1
Additional values can be defined via the IANA OAuth Token Endpoint Additional values can be defined via the IANA OAuth Token Endpoint
Authentication Methods Registry established in Section 4.2. Authentication Methods Registry established in Section 4.2.
Absolute URIs can also be used as values for this parameter Absolute URIs can also be used as values for this parameter
without being registered. If unspecified or omitted, the default without being registered. If unspecified or omitted, the default
is "client_secret_basic", denoting HTTP Basic Authentication is "client_secret_basic", denoting HTTP Basic Authentication
Scheme as specified in Section 2.3.1 of OAuth 2.0. Scheme as specified in Section 2.3.1 of OAuth 2.0.
grant_types grant_types
Array of OAuth 2.0 grant types that the client may use. These Array of OAuth 2.0 grant type strings that the client can use at
grant types are defined as follows: the token endpoint. These grant types are defined as follows:
* "authorization_code": The Authorization Code Grant described in * "authorization_code": The Authorization Code Grant described in
OAuth 2.0 Section 4.1 OAuth 2.0 Section 4.1
* "implicit": The Implicit Grant described in OAuth 2.0 * "implicit": The Implicit Grant described in OAuth 2.0
Section 4.2 Section 4.2
* "password": The Resource Owner Password Credentials Grant * "password": The Resource Owner Password Credentials Grant
described in OAuth 2.0 Section 4.3 described in OAuth 2.0 Section 4.3
* "client_credentials": The Client Credentials Grant described in * "client_credentials": The Client Credentials Grant described in
OAuth 2.0 Section 4.4 OAuth 2.0 Section 4.4
* "refresh_token": The Refresh Token Grant described in OAuth 2.0 * "refresh_token": The Refresh Token Grant described in OAuth 2.0
Section 6. Section 6.
* "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer
Grant defined in OAuth JWT Bearer Token Profiles [OAuth.JWT]. Grant defined in OAuth JWT Bearer Token Profiles [OAuth.JWT].
* "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].
If the token endpoint is used in the grant type, the value of this 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 MUST be the same as the value of the "grant_type"
parameter passed to the token endpoint defined in the grant type parameter passed to the token endpoint defined in the grant type
definition. Authorization servers MAY allow for other values as definition. Authorization servers MAY allow for other values as
skipping to change at page 8, line 19 skipping to change at page 8, line 21
[OAuth.SAML2]. [OAuth.SAML2].
If the token endpoint is used in the grant type, the value of this 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 MUST be the same as the value of the "grant_type"
parameter passed to the token endpoint defined in the grant type parameter passed to the token endpoint defined in the grant type
definition. Authorization servers MAY allow for other values as definition. Authorization servers MAY allow for other values as
defined in the grant type extension process described in OAuth 2.0 defined in the grant type extension process described in OAuth 2.0
Section 2.5. If omitted, the default behavior is that the client Section 2.5. If omitted, the default behavior is that the client
will use only the "authorization_code" Grant Type. will use only the "authorization_code" Grant Type.
response_types response_types
Array of the OAuth 2.0 response types that the client can use. Array of the OAuth 2.0 response type strings that the client can
These response types are defined as follows: use at the authorization endpoint. 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 * "token": The implicit response described in OAuth 2.0
Section 4.2. Section 4.2.
If the authorization endpoint is used by the grant type, the value If the authorization endpoint is used by the grant type, the value
of this parameter MUST be the same as the value of the of this parameter MUST be the same as the value of the
"response_type" parameter passed to the authorization endpoint "response_type" parameter passed to the authorization endpoint
defined in the grant type definition. Authorization servers MAY defined in the grant type definition. Authorization servers MAY
allow for other values as defined in the grant type extension allow for other values as defined in the grant type extension
process is described in OAuth 2.0 Section 2.5. If omitted, the 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. 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 end-user Human-readable string name of the client to be presented to the
during authorization. If omitted, the authorization server MAY end-user during authorization. If omitted, the authorization
display the raw "client_id" value to the end-user instead. It is server MAY display the raw "client_id" value to the end-user
RECOMMENDED that clients always send this field. The value of instead. It is RECOMMENDED that clients always send this field.
this field MAY be internationalized, as described in Section 2.2. The value of 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 string of a web page providing information about the client.
present, the server SHOULD display this URL to the end-user in a If present, the server SHOULD display this URL to the end-user in
clickable fashion. It is RECOMMENDED that clients always send a clickable fashion. It is RECOMMENDED that clients always send
this field. The value of this field MUST point to a valid web this field. The value of this field MUST point to a valid web
page. The value of this field MAY be internationalized, as page. The value of this field MAY be internationalized, as
described in Section 2.2. described in Section 2.2.
logo_uri logo_uri
URL that references a logo for the client. If present, the server URL string that references a logo for the client. If present, the
SHOULD display this image to the end-user during approval. The server SHOULD display this image to the end-user during approval.
value of this field MUST point to a valid image file. The value The value of this field MUST point to a valid image file. The
of this field MAY be internationalized, as described in value of this field MAY be internationalized, as described in
Section 2.2. Section 2.2.
scope scope
Space separated list of scope values (as described in Section 3.3 String containing a space separated list of scope values (as
of OAuth 2.0 [RFC6749]) that the client can use when requesting described in Section 3.3 of OAuth 2.0 [RFC6749]) that the client
access tokens. The semantics of values in this list is service can use when requesting access tokens. The semantics of values in
specific. If omitted, an authorization server MAY register a this list is service specific. If omitted, an authorization
client with a default set of scopes. server MAY register a 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 contact addresses available to end-users for server MAY make these contact addresses available to end-users for
support requests for the client. See Section 6 for information on support requests for the client. See Section 6 for information on
Privacy Considerations. Privacy Considerations.
tos_uri tos_uri
URL that points to a human-readable terms of service document for URL string that points to a human-readable terms of service
the client that describes a contractual relationship between the document for the client that describes a contractual relationship
end-user and the client that the end-user accepts when authorizing between the end-user and the client that the end-user accepts when
the client. The authorization server SHOULD display this URL to authorizing the client. The authorization server SHOULD display
the end-user if it is provided. The value of this field MUST this URL to the end-user if it is provided. The value of this
point to a valid web page. The value of this field MAY be field MUST point to a valid web page. The value of this field MAY
internationalized, as described in Section 2.2. be internationalized, as described in Section 2.2.
policy_uri policy_uri
URL that points to a human-readable privacy policy document that URL string that points to a human-readable privacy policy document
describes how the deployment organization collects, uses, retains, that describes how the deployment organization collects, uses,
and discloses personal data. The authorization server SHOULD retains, and discloses personal data. The authorization server
display this URL to the end-user if it is provided. The value of SHOULD display this URL to the end-user if it is provided. The
this field MUST point to a valid web page. The value of this value of this field MUST point to a valid web page. The value of
field MAY be internationalized, as described in Section 2.2. this field MAY be internationalized, as described in Section 2.2.
jwks_uri jwks_uri
URL referencing the client's JSON Web Key Set [JWK] document, URL string referencing the client's JSON Web Key Set [JWK]
which contains the client's public keys. The value of this field document, which contains the client's public keys. The value of
MUST point to a valid JWK Set document. These keys can be used by this field MUST point to a valid JWK Set document. These keys can
higher level protocols that use signing or encryption. For be used by higher level protocols that use signing or encryption.
instance, these keys might be used by some applications for For instance, these keys might be used by some applications for
validating signed requests made to the token endpoint when using validating signed requests made to the token endpoint when using
JWTs for client authentication [OAuth.JWT]. Use of this parameter JWTs for client authentication [OAuth.JWT]. Use of this parameter
is preferred over the "jwks" parameter, as it allows for easier is preferred over the "jwks" parameter, as it allows for easier
key rotation. The "jwks_uri" and "jwks" parameters MUST NOT both key rotation. The "jwks_uri" and "jwks" parameters MUST NOT both
be present in the same request or response. be present in the same request or response.
jwks jwks
Client's JSON Web Key Set [JWK] document value, which contains the Client's JSON Web Key Set [JWK] document value, which contains the
client's public keys. The value of this field MUST be a JSON 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 object containing a valid JWK Set. These keys can be used by
higher level protocols that use signing or encryption. This higher level protocols that use signing or encryption. This
parameter is intended to be used by clients that cannot use the parameter is intended to be used by clients that cannot use the
"jwks_uri" parameter, such as native clients that cannot host "jwks_uri" parameter, such as native clients that cannot host
public URLs. The "jwks_uri" and "jwks" parameters MUST NOT both public URLs. The "jwks_uri" and "jwks" parameters MUST NOT both
be present in the same request or response. be present in the same request or response.
software_id software_id
A unique identifier (e.g. a UUID) assigned by the client developer A unique identifier string (e.g. a UUID) assigned by the client
or software publisher used by registration endpoints to identify developer or software publisher used by registration endpoints to
the client software to be dynamically registered. Unlike identify the client software to be dynamically registered. Unlike
"client_id", which is issued by the authorization server and "client_id", which is issued by the authorization server and
SHOULD vary between instances, the "software_id" SHOULD remain the SHOULD vary between instances, the "software_id" SHOULD remain the
same for all instances of the client software. The "software_id" same for all instances of the client software. The "software_id"
SHOULD remain the same across multiple updates or versions of the SHOULD remain the same across multiple updates or versions of the
same piece of software. The value of this field is not intended same piece of software. The value of this field is not intended
to be human-readable and is usually opaque to the client and to be human-readable and is usually opaque to the client and
authorization server. authorization server.
software_version software_version
A version identifier for the client software identified by A version identifier string for the client software identified by
"software_id". The value of the "software_version" SHOULD change "software_id". The value of the "software_version" SHOULD change
on any update to the client software identified by the same on any update to the client software identified by the same
"software_id". The value of this field is a string that is "software_id". The value of this field is intended to be compared
intended to be compared using string equality matching. The value using string equality matching and no other comparison semantics
of this field is not intended to be human readable and is usually are defined by this specification. The value of this field is
opaque to the client and authorization server. outside the scope of this speicification, but it is not intended
to be human readable and is usually opaque to the client and
authorization server. The definition of what constitutes an
update to client software that would trigger a change to this
value is specific to the software itself and is outside the scope
of this specification.
Extensions and profiles of this specification MAY expand this list Extensions and profiles of this specification can expand this list
with metadata names and descriptions registered in accordance with with metadata names and descriptions registered in accordance with
the IANA Considerations in Section 4 of this document. The the IANA Considerations in Section 4 of this document. The
authorization server MUST ignore any client metadata sent by the authorization server MUST ignore any client metadata sent by the
client that it does not understand (for instance, by silently client that it does not understand (for instance, by silently
removing unknown metadata from the client's registration record removing unknown metadata from the client's registration record
during processing). during processing). The authorization server MAY reject any
requested client metadata values by replacing requested values with
suitable defaults as described in Section 3.2.1 or by returning an
error response as described in Section 3.2.2.
Client metadata values can either be communicated directly in the Client metadata values can either be communicated directly in the
body of a registration request, as described in Section 3.1, or body of a registration request, as described in Section 3.1, or
included as claims in a software statement, as described in included as claims in a software statement, as described in
Section 2.3, or a mixture of both. If the same client metadata name Section 2.3, or a mixture of both. If the same client metadata name
is present in both locations and the software statement is trusted by is present in both locations and the software statement is trusted by
the authorization server, the value of a claim in the software the authorization server, the value of a claim in the software
statement MUST take precedence. statement MUST take precedence.
2.1. Relationship between Grant Types and Response Types 2.1. Relationship between Grant Types and Response Types
skipping to change at page 16, line 50 skipping to change at page 16, line 50
authorization server MAY ignore the software statement if it does not authorization server MAY ignore the software statement if it does not
support this feature. If the server supports software statements, support this feature. If the server supports software statements,
client metadata values conveyed in the software statement MUST take client metadata values conveyed in the software statement MUST take
precedence over those conveyed using plain JSON elements. precedence over those conveyed using plain JSON elements.
Software statements are included in the requesting JSON object using Software statements are included in the requesting JSON object using
this OPTIONAL member: this OPTIONAL member:
software_statement software_statement
A software statement containing client metadata values about the A software statement containing client metadata values about the
client software as claims. client software as claims. This is a string value containing the
entire signed JWT.
In the following example, some registration parameters are conveyed In the following example, some registration parameters are conveyed
as claims in a software statement from the example in Section 2.3, as claims in a software statement from the example in Section 2.3,
while some values specific to the client instance are conveyed as while some values specific to the client instance are conveyed as
regular parameters (with line wraps within values for display regular parameters (with line wraps within values for display
purposes only): purposes only):
POST /register HTTP/1.1 POST /register HTTP/1.1
Content-Type: application/json Content-Type: application/json
Accept: application/json Accept: application/json
skipping to change at page 18, line 4 skipping to change at page 18, line 4
responds with an error, as described in Section 3.2.2. responds with an error, as described in Section 3.2.2.
3.2.1. Client Information Response 3.2.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 string. 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 string. If issued, this MUST
unique for each "client_id" and SHOULD be unique for multiple be unique for each "client_id" and SHOULD be unique for multiple
instances of a client using the same "client_id". This value is instances of a client using the same "client_id". This value is
used by confidential clients to authenticate to the token endpoint used by confidential clients to authenticate to the token endpoint
as described in OAuth 2.0 [RFC6749] Section 2.3.1. as described in 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 time is represented as the number of seconds from
1970-01-01T0:0:0Z as measured in UTC until the date/time of 1970-01-01T0:0:0Z as measured in UTC until the date/time of
issuance. issuance.
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 of expiration. measured in UTC until the date/time of expiration.
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 and substitute them with suitable values. during the registration and substitute them with suitable values.
The client or developer can check the values in the response to
determine if the registration is sufficient for use (e.g., the
registered "token_endpoint_auth_method" is supported by the client
software) and determine a course of action appropriate for the client
software. The response to such a situation is out of scope for this
specification but could include filing a report with the application
developer or authorization server provider.
The response is an "application/json" document with all parameters as The successful registration response uses an HTTP 201 Created status
top-level members of a JSON object [RFC7159]. code with a body of type "application/json" consisting of a single
JSON object [RFC7159] with all parameters as top-level members of the
object.
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 unmodified in the response along with other value MUST be returned unmodified in the response along with other
metadata using the "software_statement" member name. Client metadata metadata using the "software_statement" member name. Client metadata
elements used from the software statement MUST also be returned elements used from the software statement MUST also be returned
directly as top-level client metadata values in the registration directly as top-level client metadata values in the registration
response (possibly with different values, since the values requested response (possibly with different values, since the values requested
and the values used may differ). and the values used may differ).
Following is a non-normative example response: Following is a non-normative example response of a successful
registration:
HTTP/1.1 201 Created 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,
skipping to change at page 26, line 34 skipping to change at page 26, line 34
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 is possible that such clients often do not have long-term storage, it is 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
is loaded. Additionally, such clients may not have ample opportunity is loaded. To avoid the resulting proliferation of dead client
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 identifiers, an authorization server MAY decide to expire
registrations for existing clients meeting certain criteria after a registrations for existing clients meeting certain criteria after a
period of time has elapsed. period of time has elapsed. Alternatively, such clients could be
registered on the server where the in-browser application's code is
served from, and the client's configuration pushed to the browser
along side the code.
Since different OAuth 2.0 grant types have different security and Since different OAuth 2.0 grant types have different security and
usage parameters, an authorization server MAY require separate usage parameters, an authorization server MAY require separate
registrations for a piece of software to support multiple grant registrations for a piece of software to support multiple grant
types. For instance, an authorization server might require that all types. For instance, an authorization server might require that all
clients using the "authorization_code" grant type make use of a clients using the "authorization_code" grant type make use of a
client secret for the "token_endpoint_auth_method", but any clients client secret for the "token_endpoint_auth_method", but any clients
using the "implicit" grant type do not use any authentication at the using the "implicit" grant type do not use any authentication at the
token endpoint. In such a situation, a server MAY disallow clients token endpoint. In such a situation, a server MAY disallow clients
from registering for both the "authorization_code" and "implicit" from registering for both the "authorization_code" and "implicit"
skipping to change at page 27, line 19 skipping to change at page 27, line 20
cases, the authorization server would respond with an cases, the authorization server would respond with an
"invalid_client_metadata" error response. "invalid_client_metadata" error response.
Unless used as a claim in a software statement, the authorization Unless used as a claim in a software statement, the authorization
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 MUST take appropriate steps
mitigate this risk by looking at the entire registration request and to mitigate this risk by looking at the entire registration request
client configuration. For instance, an authorization server could and client configuration. For instance, an authorization server
issue a warning if the domain/site of the logo doesn't match the could issue a warning if the domain/site of the logo doesn't match
domain/site of redirection URIs. An authorization server could also the domain/site of redirection URIs. An authorization server could
refuse registration requests from a known software identifier that is also refuse registration requests from a known software identifier
requesting different redirection URIs or a different client URI. An that is requesting different redirection URIs or a different client
authorization server can also present warning messages to end-users URI. An authorization server can also present warning messages to
about dynamically registered clients in all cases, especially if such end-users about dynamically registered clients in all cases,
clients have been recently registered or have not been trusted by any especially if such clients have been recently registered or have not
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
reference to a drive-by download in the "policy_uri". The reference to a drive-by download in the "policy_uri", enticing the
authorization server SHOULD check to see if the "logo_uri", user to click on it during the authorization. The authorization
"tos_uri", "client_uri", and "policy_uri" have the same host and server SHOULD check to see if the "logo_uri", "tos_uri",
scheme as the those defined in the array of "redirect_uris" and that "client_uri", and "policy_uri" have the same host and scheme as the
all of these URIs resolve to valid web pages. those defined in the array of "redirect_uris" and that all of these
URIs resolve to valid web pages. Since these URI values that are
intended to be displayed to the user at the authorization page, the
authorization server SHOULD protect the user from malicious content
hosted at the URLs where possible. For instance, before presenting
the URLs to the user at the authorization page, the authorization
server could download the content hosted at the URLs, check the
content against a malware scanner and blacklist filter, determine
whether or not there is mixed secure and non-secure content at the
URL, and other possible server-side mitigations. Note that the
content in these URLs can change at any time and the authorization
server cannot provide complete confidence in the safety of the URLs,
but these practices could help. To further mitigate this kind of
threat, the authorization server can also warn the user that the URL
links have been provided by a third party, should be treated with
caution, and are not hosted by the authorization server itself. For
instance, instead of providing the links directly in an HTML anchor,
the authorization server can direct the user to an interstitial
warning page before allowing the user to continue to the target URL.
Clients MAY use both the direct JSON object and the JWT-encoded Clients MAY use both the direct JSON object and the JWT-encoded
software statement to present client metadata to the authorization software statement to present client metadata to the authorization
server as part of the registration request. A software statement is server as part of the registration request. A software statement is
cryptographically protected and represents claims made by the issuer cryptographically protected and represents claims made by the issuer
of the statement, while the JSON object represents the self-asserted of the statement, while the JSON object represents the self-asserted
claims made by the client or developer directly. If the software claims made by the client or developer directly. If the software
statement is valid and signed by an acceptable authority (such as the statement is valid and signed by an acceptable authority (such as the
software API publisher), the values of client metadata within the software API publisher), the values of client metadata within the
software statement MUST take precedence over those metadata values software statement MUST take precedence over those metadata values
presented in the plain JSON object, which could have been modified en presented in the plain JSON object, which could have been intercepted
route. and modified.
The software statement is an item that is self-asserted by the Like all metadata values, the software statement is an item that is
client, even though its contents have been digitally signed or MACed self-asserted by the client, even though its contents have been
by the issuer of the software statement. As such, presentation of digitally signed or MACed by the issuer of the software statement.
the software statement is not sufficient in most cases to fully As such, presentation of the software statement is not sufficient in
identity a piece of client software. An initial access token, in most cases to fully identify a piece of client software. An initial
contrast, does not necessarily contain information about a particular access token, in contrast, does not necessarily contain information
piece of client software but instead represents authorization to use about a particular piece of client software but instead represents
the registration endpoint. An authorization server MUST consider the authorization to use the registration endpoint. An authorization
full registration request, including the software statement, initial server MUST consider the full registration request, including the
access token, and JSON client metadata values, when deciding whether software statement, initial access token, and JSON client metadata
to honor a given registration request. values, when deciding whether to honor a given registration request.
If an authorization server receives a registration request for a If an authorization server receives a registration request for a
client that uses the same "software_id" and "software_version" values client that is not intended to have multiple instances registered
as another client, the server should treat the new registration as simultaneously and the authorization server can infer a duplication
being suspect. It is possible that the new client is trying to of registration (e.g., it uses the same "software_id" and
impersonate the existing client. "software_version" values as another existing client), the server
SHOULD treat the new registration as being suspect and reject the
registration. It is possible that the new client is trying to
impersonate the existing client in order to trick users into
authorizing it, or that the original registration is no longer valid.
The details of managing this situation are specific to the
authorization server deployment and outside the scope of this
specification.
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 needs to be very particular about instances of a registered client needs to be very particular about
the circumstances under which this occurs. For instance, the 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 redirection 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
skipping to change at page 34, line 12 skipping to change at page 34, line 30
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 ]]
-28
o Clarified all client metadata as JSON arrays, strings, or numbers.
o Expanded security considerations advice around external URLs.
o Added text to say what happens if the client doesn't get back the
registration it expected in the response.
o Added more explicit references to HTTP 201 response from
registration.
o Clarified client version definition.
o Removed spurious reference to "delete action".
o Fixed intended normative and non-normative language in several
sections.
o Stated what a server should do if a suspected duplicate client
tries to register.
-27 -27
1: Changed a registry name missed in -26. o Changed a registry name missed in -26.
-26 -26
o Used consistent registry name. o Used consistent registry name.
-25 -25
o Updated author information. o Updated author information.
o Clarified registry contents. o Clarified registry contents.
o Added forward pointer to IANA from metadata section. o Added forward pointer to IANA from metadata section.
 End of changes. 45 change blocks. 
117 lines changed or deleted 180 lines changed or added

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