draft-ietf-oauth-dyn-reg-20.txt   draft-ietf-oauth-dyn-reg-21.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: February 27, 2015 Microsoft Expires: June 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
August 26, 2014 December 1, 2014
OAuth 2.0 Dynamic Client Registration Protocol OAuth 2.0 Dynamic Client Registration Protocol
draft-ietf-oauth-dyn-reg-20 draft-ietf-oauth-dyn-reg-21
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 February 27, 2015. This Internet-Draft will expire on June 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
skipping to change at page 2, line 30 skipping to change at page 2, line 30
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 . . . 10
2.2. Human Readable Client Metadata . . . . . . . . . . . . . 10 2.2. Human Readable Client Metadata . . . . . . . . . . . . . 10
2.3. Software Statement . . . . . . . . . . . . . . . . . . . 12 2.3. Software Statement . . . . . . . . . . . . . . . . . . . 12
3. Client Registration Endpoint . . . . . . . . . . . . . . . . 12 3. Client Registration Endpoint . . . . . . . . . . . . . . . . 13
3.1. Client Registration Request . . . . . . . . . . . . . . . 13 3.1. Client Registration Request . . . . . . . . . . . . . . . 14
3.1.1. Client Registration Request Using a Software
Statement . . . . . . . . . . . . . . . . . . . . . . 15
3.2. Client Registration Response . . . . . . . . . . . . . . 16 3.2. Client Registration Response . . . . . . . . . . . . . . 16
4. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 16 4. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.1. Client Information Response . . . . . . . . . . . . . . . 16 4.1. Client Information Response . . . . . . . . . . . . . . . 17
4.2. Client Registration Error Response . . . . . . . . . . . 17 4.2. Client Registration Error Response . . . . . . . . . . . 18
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
5.1. OAuth Dynamic Registration Client Metadata Registry . . . 19 5.1. OAuth Dynamic Registration Client Metadata Registry . . . 20
5.1.1. Registration Template . . . . . . . . . . . . . . . . 20 5.1.1. Registration Template . . . . . . . . . . . . . . . . 20
5.1.2. Initial Registry Contents . . . . . . . . . . . . . . 20 5.1.2. Initial Registry Contents . . . . . . . . . . . . . . 21
5.2. OAuth Token Endpoint Authentication Methods Registry . . 22 5.2. OAuth Token Endpoint Authentication Methods Registry . . 23
5.2.1. Registration Template . . . . . . . . . . . . . . . . 23 5.2.1. Registration Template . . . . . . . . . . . . . . . . 24
5.2.2. Initial Registry Contents . . . . . . . . . . . . . . 23 5.2.2. Initial Registry Contents . . . . . . . . . . . . . . 24
6. Security Considerations . . . . . . . . . . . . . . . . . . . 24 6. Security Considerations . . . . . . . . . . . . . . . . . . . 24
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 27
7.1. Normative References . . . . . . . . . . . . . . . . . . 27 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 28
7.2. Informative References . . . . . . . . . . . . . . . . . 28 8.1. Normative References . . . . . . . . . . . . . . . . . . 28
Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . 28 8.2. Informative References . . . . . . . . . . . . . . . . . 29
A.1. Open versus Protected Dynamic Client Registration . . . . 28 Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . 29
A.1.1. Open Dynamic Client Registration . . . . . . . . . . 28 A.1. Open versus Protected Dynamic Client Registration . . . . 29
A.1.2. Protected Dynamic Client Registration . . . . . . . . 29 A.1.1. Open Dynamic Client Registration . . . . . . . . . . 30
A.2. Registration Without or With Software Statements . . . . 29 A.1.2. Protected Dynamic Client Registration . . . . . . . . 30
A.2.1. Registration Without a Software Statement . . . . . . 29 A.2. Registration Without or With Software Statements . . . . 30
A.2.2. Registration With a Software Statement . . . . . . . 29 A.2.1. Registration Without a Software Statement . . . . . . 30
A.3. Registration by the Client or Developer . . . . . . . . . 29 A.2.2. Registration With a Software Statement . . . . . . . 30
A.3.1. Registration by the Client . . . . . . . . . . . . . 29 A.3. Registration by the Client or Developer . . . . . . . . . 30
A.3.2. Registration by the Developer . . . . . . . . . . . . 29 A.3.1. Registration by the Client . . . . . . . . . . . . . 30
A.4. Client ID per Client Instance or per Client Software . . 30 A.3.2. Registration by the Developer . . . . . . . . . . . . 31
A.4.1. Client ID per Client Software Instance . . . . . . . 30 A.4. Client ID per Client Instance or per Client Software . . 31
A.4.1. Client ID per Client Software Instance . . . . . . . 31
A.4.2. Client ID Shared Among All Instances of Client A.4.2. Client ID Shared Among All Instances of Client
Software . . . . . . . . . . . . . . . . . . . . . . 30 Software . . . . . . . . . . . . . . . . . . . . . . 31
A.5. Stateful or Stateless Registration . . . . . . . . . . . 30 A.5. Stateful or Stateless Registration . . . . . . . . . . . 31
A.5.1. Stateful Client Registration . . . . . . . . . . . . 30 A.5.1. Stateful Client Registration . . . . . . . . . . . . 31
A.5.2. Stateless Client Registration . . . . . . . . . . . . 30 A.5.2. Stateless Client Registration . . . . . . . . . . . . 32
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 31 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 32
Appendix C. Document History . . . . . . . . . . . . . . . . . . 31 Appendix C. Document History . . . . . . . . . . . . . . . . . . 32
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37
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.
skipping to change at page 3, line 42 skipping to change at page 3, line 45
a set of metadata called a software statement, which is 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. Multiple register the client with authorization servers. Multiple
applications using OAuth 2.0 have previously developed mechanisms for applications using OAuth 2.0 have previously developed mechanisms for
accomplishing such registrations. This specficiation generalizes the accomplishing such registrations. This specification generalizes the
registration mechanisms defined by the OpenID Connect Dynamic Client registration mechanisms defined by the OpenID Connect Dynamic Client
Registration 1.0 [OpenID.Registration] specification and used by the Registration 1.0 [OpenID.Registration] specification and used by the
User Managed Access (UMA) Profile of OAuth 2.0 User Managed Access (UMA) Profile of OAuth 2.0
[I-D.hardjono-oauth-umacore] specification in a way that is [I-D.hardjono-oauth-umacore] specification in a way that is
compatible with both, while being applicable to a wider set of OAuth compatible with both, while being applicable to a wider set of OAuth
2.0 use cases. 2.0 use cases.
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',
skipping to change at page 6, line 29 skipping to change at page 6, line 29
with the client's desired registration metadata, optionally with the client's desired registration metadata, optionally
including the initial access token from (A) if one is required by including the initial access token from (A) if one is required by
the authorization server. the authorization server.
(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 Registered clients have a set of metadata values associated with
identifier at an authorization server, such as the list of valid their client identifier at an authorization server, such as the list
redirection URIs or a display name. of valid redirection URIs or a display name.
The 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.
redirect_uris redirect_uris
Array of redirection URI values for use in redirect-based flows Array of redirection URI values for use in redirect-based flows
skipping to change at page 7, line 43 skipping to change at page 7, line 43
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
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 may use. Array of the OAuth 2.0 response types that the client can 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 * "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
skipping to change at page 12, line 18 skipping to change at page 12, line 18
A software statement is a JSON Web Token (JWT) [JWT] that asserts A software statement is a JSON Web Token (JWT) [JWT] that asserts
metadata values about the client software as a bundle. A set of metadata values about the client software as a bundle. A set of
claims that can be used in a software statement are defined in claims that can be used in a software statement are defined in
Section 2. When presented to the authorization server as part of a Section 2. When presented to the authorization server as part of a
client registration request, the software statement MUST be digitally client registration request, the software statement MUST be digitally
signed or MACed using JWS [JWS] and MUST contain an "iss" (issuer) signed or MACed using JWS [JWS] and MUST contain an "iss" (issuer)
claim denoting the party attesting to the claims in the software claim denoting the party attesting to the claims in the software
statement. It is RECOMMENDED that software statements be digitally statement. It is RECOMMENDED that software statements be digitally
signed using the "RS256" signature algorithm, although particular signed using the "RS256" signature algorithm, although particular
applications MAY specify the use of different algorithms. applications MAY specify the use of different algorithms. It is
RECOMMENDED that software statements contain the "software_id" claim
to allow authorization servers to correlate different instances of
software using the same software statement.
For example, a software statement could contain the following claims:
{
"software_id": "4NRB1-0XZABZI9E6-5SM3R",
"client_name": "Example Statement-based Client",
"client_uri": "https://client.example.net/"
}
The following non-normative example JWT includes these claims and has
been asymmetrically signed using RS256:
Line breaks are for display purposes only
eyJhbGciOiJSUzI1NiJ9.
eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll
bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs
aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ.
GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa
zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0
5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY
fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk
U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf
IjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA
The means by which a client or developer obtains a software statement The means by which a client or developer obtains a software statement
are outside the scope of this specification. Some common methods are outside the scope of this specification. Some common methods
could include a client developer generating a client-specific JWT could include a client developer generating a client-specific JWT
registering with a software API publisher to obtain a software registering with a software API publisher to obtain a software
statement for a class of clients. The software statement is statement for a class of clients. The software statement is
typically distributed with all instances of a client application. typically distributed with all instances of a client application.
The criteria by which authorization servers determine whether to The criteria by which authorization servers determine whether to
trust and utilize the information in a software statement are beyond trust and utilize the information in a software statement are beyond
skipping to change at page 12, line 46 skipping to change at page 13, line 26
required in this case, are beyond the scope of this specification. required in this case, are beyond the scope of this specification.
3. Client Registration Endpoint 3. Client Registration Endpoint
The client registration endpoint is an OAuth 2.0 endpoint defined in The client registration endpoint is an OAuth 2.0 endpoint defined in
this document that is designed to allow a client to be registered this document that is designed to allow a client to be registered
with the authorization server. The client registration endpoint MUST with the authorization server. The client registration endpoint MUST
accept HTTP POST messages with request parameters encoded in the accept HTTP POST messages with request parameters encoded in the
entity body using the "application/json" format. The client entity body using the "application/json" format. The client
registration endpoint MUST be protected by a transport-layer security registration endpoint MUST be protected by a transport-layer security
mechanism, and the server MUST support TLS 1.2 RFC 5246 [RFC5246] mechanism, and the server MUST support TLS 1.2 RFC 5246 [RFC5246] and
and/or TLS 1.0 [RFC2246] and MAY support additional transport-layer MAY support additional transport-layer mechanisms meeting its
mechanisms meeting its security requirements. When using TLS, the security requirements. When using TLS, the client MUST perform a
client MUST perform a TLS/SSL server certificate check, per RFC 6125 TLS/SSL server certificate check, per RFC 6125 [RFC6125].
[RFC6125]. Implementation security considerations can be found in
Recommendations for Secure Use of TLS and DTLS [TLS.BCP].
The client registration endpoint MAY be an OAuth 2.0 protected The client registration endpoint MAY be an OAuth 2.0 protected
resource and accept an initial access token in the form of an OAuth resource and accept an initial access token in the form of an OAuth
2.0 [RFC6749] access token to limit registration to only previously 2.0 [RFC6749] access token to limit registration to only previously
authorized parties. The method by which the initial access token is authorized parties. The method by which the initial access token is
obtained by the client or developer is generally out-of-band and is obtained by the client or developer is generally out-of-band and is
out of scope for this specification. The method by which the initial out of scope for this specification. The method by which the initial
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.
skipping to change at page 13, line 32 skipping to change at page 14, line 16
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 optionally assigns a client secret, and associates the metadata
provided in the request with the issued client identifier. The provided in the request with the issued client identifier. The
request includes any client metadata parameters being specified for request includes any client metadata parameters being specified for
the client during the registration. The authorization server MAY the 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.
Client metadata values may also be provided in a software statement,
as described in Section 2.3. Software statements are included in the
requesting JSON object using this member:
software_statement
A software statement containing client metadata values about the
client software as claims.
To register, the client or developer sends an HTTP POST to the client To register, the client or developer sends an HTTP POST to the client
registration endpoint with a content type of "application/json". The registration endpoint with a content type of "application/json". The
HTTP Entity Payload is a JSON [RFC7159] document consisting of a JSON HTTP Entity Payload is a JSON [RFC7159] document consisting of a JSON
object and all requested client metadata values as top-level members object and all requested client metadata values as top-level members
of that JSON object. of that JSON object.
For example, if the server supports open registration (with no For example, if the server supports open registration (with no
initial access token), the client could send the following initial access token), the client could send the following
registration request to the client registration endpoint: registration request to the client registration endpoint:
skipping to change at page 15, line 27 skipping to change at page 15, line 30
"https://client.example.org/callback2"], "https://client.example.org/callback2"],
"client_name":"My Example Client", "client_name":"My Example Client",
"client_name#ja-Jpan-JP": "client_name#ja-Jpan-JP":
"\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D",
"token_endpoint_auth_method":"client_secret_basic", "token_endpoint_auth_method":"client_secret_basic",
"policy_uri":"https://client.example.org/policy.html", "policy_uri":"https://client.example.org/policy.html",
"jwks":{"keys":[{...omitted for brevity...}]}, "jwks":{"keys":[{...omitted for brevity...}]},
"example_extension_parameter": "example_value" "example_extension_parameter": "example_value"
} }
3.1.1. Client Registration Request Using a Software Statement
In addition to JSON elements, client metadata values MAY also be
provided in a software statement, as described in Section 2.3. The
authorization server MAY ignore the software statement if it does not
support this feature. If the server supports software statements,
client metadata values conveyed in the software statement MUST take
precedence over those conveyed using plain JSON elements.
Software statements are included in the requesting JSON object using
this OPTIONAL member:
software_statement
A software statement containing client metadata values about the
client software as claims.
In the following example, some registration parameters are conveyed In the following example, some registration parameters are conveyed
as claims in a software statement, while some values specific to the as claims in a software statement from the example in the Section 2.3
client instance are conveyed as regular parameters (with line wraps section, while some values specific to the client instance are
within values for display purposes only): conveyed as regular parameters (with line wraps within values for
display 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
Host: server.example.com Host: server.example.com
{ {
"redirect_uris":[ "redirect_uris":[
"https://client.example.org/callback", "https://client.example.org/callback",
"https://client.example.org/callback2" "https://client.example.org/callback2"
], ],
"software_statement":"eyJhbGciOiJFUzI1NiJ9. "software_statement":"eyJhbGciOiJSUzI1NiJ9.
eyJpc3Mi[...omitted for brevity...]. eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll
J9l-ZhwP[...omitted for brevity...]", bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs
aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ.
GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa
zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0
5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY
fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk
U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf
IjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA",
"scope":"read write", "scope":"read write",
"example_extension_parameter":"example_value" "example_extension_parameter":"example_value"
} }
3.2. Client Registration Response 3.2. Client Registration Response
Upon successful registration, the authorization server returns a Upon a successful registration request, the authorization server
client identifier for the client. The server responds with an HTTP returns a client identifier for the client. The server responds with
201 Created code and a body of type "application/json" with content an HTTP 201 Created code and a body of type "application/json" with
as described in Section 4.1. content as described in Section 4.1.
Upon an unsuccessful registration, the authorization server responds Upon an unsuccessful registration request, the authorization server
with an error, as described in Section 4.2. responds with an error, as described in Section 4.2.
4. Responses 4. Responses
The following responses are sent in response to registration The following responses are sent in response to registration
requests. requests.
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
skipping to change at page 16, line 41 skipping to change at page 17, line 26
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" and SHOULD be unique for multiple 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. 1970-01-01T0:0:0Z as measured in UTC until the date/time of
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. 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 or update requests and substitute them with during the registration 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 unmodified in the response along with other
Client metadata elements used from the software statement MUST also metadata using the "software_statement" member name. Client metadata
be returned directly as top-level client metadata values in the elements used from the software statement MUST also be returned
registration response (possibly with different values, since the directly as top-level client metadata values in the registration
values requested and the values used may differ). response (possibly with different values, since the 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 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",
skipping to change at page 24, line 21 skipping to change at page 25, line 5
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 MAY support additional transport-layer mechanisms
transport-layer mechanisms meeting its security requirements. When meeting its security requirements. When using TLS, the client MUST
using TLS, the client MUST perform a TLS/SSL server certificate perform a TLS/SSL server certificate check, per RFC 6125 [RFC6125].
check, per RFC 6125 [RFC6125]. Implementation security considerations can be found in
Recommendations for Secure Use of TLS and DTLS [TLS.BCP].
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 MUST "authorization_code" and "implicit", authorization servers MUST
require clients to register their redirection URI values. This can require clients to register their redirection URI values. This can
help mitigate attacks where rogue actors inject and impersonate a help mitigate attacks where rogue actors inject and impersonate a
validly registered client and intercept its authorization code or validly registered client and intercept its authorization code or
tokens through an invalid redirection URI or open redirector. tokens through an invalid redirection URI or open redirector.
Additionally, in order to prevent hijacking of the return values of Additionally, in order to prevent hijacking of the return values of
the redirection, registered redirection URI values MUST be one of: the redirection, registered redirection URI values MUST be one of:
skipping to change at page 26, line 17 skipping to change at page 26, line 50
"tos_uri", "client_uri", and "policy_uri" have the same host and "tos_uri", "client_uri", and "policy_uri" have the same host and
scheme as the those defined in the array of "redirect_uris" and that scheme as the those defined in the array of "redirect_uris" and that
all of these URIs resolve to valid web pages. all of these URIs resolve to valid web pages.
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 trusted, the values of client metadata within statement is valid and signed by an acceptable authority (such as the
the software statement MUST take precedence over those metadata software API publisher), the values of client metadata within the
values presented in the plain JSON object, which could have been software statement MUST take precedence over those metadata values
modified en route. presented in the plain JSON object, which could have been modified en
route.
The software statement is an item that is self-asserted by the The software statement is an item that is self-asserted by the
client, even though its contents have been digitally signed or MACed client, even though its contents have been digitally signed or MACed
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
skipping to change at page 27, line 5 skipping to change at page 27, line 39
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
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. Privacy Considerations
7.1. Normative References As the protocol described in this specification deals almost
exclusively with information about software and not about people,
there are very few privacy concerns for its use. The notable
exception is the "contacts" field as defined in Client Metadata
(Section 2), which contains contact information for the developers or
other parties responsible for the client software. These values are
intended to be displayed to end users and will be available to the
administrators of the authorization server. As such, the developer
may wish to provide an email address or other contact information
expressly dedicated to the purpose of supporting the client instead
of using their personal or professional addresses. Alternatively,
the developer may wish to provide a collective email address for the
client to allow for continuing contact and support of the client
software after the developer moves on and someone else takes over
that responsibility.
8. References
8.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)", draft-ietf-jose-json-web- [JWK] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web-
key (work in progress), July 2014. key (work in progress), 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
skipping to change at page 27, line 39 skipping to change at page 28, line 43
[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
Authorization Grants", draft-ietf-oauth-saml2-bearer (work Authorization Grants", draft-ietf-oauth-saml2-bearer (work
in progress), July 2014. in progress), July 2014.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
RFC 2246, January 1999.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. May 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5646] Phillips, A. and M. Davis, "Tags for Identifying [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying
Languages", BCP 47, RFC 5646, September 2009. Languages", BCP 47, RFC 5646, September 2009.
skipping to change at page 28, line 20 skipping to change at page 29, line 20
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
6749, October 2012. 6749, October 2012.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, October 2012. Framework: Bearer Token Usage", RFC 6750, October 2012.
[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 8.2. Informative References
[I-D.hardjono-oauth-umacore] [I-D.hardjono-oauth-umacore]
Hardjono, T., "User-Managed Access (UMA) Profile of OAuth Hardjono, T., "User-Managed Access (UMA) Profile of OAuth
2.0", draft-hardjono-oauth-umacore-10 (work in progress), 2.0", draft-hardjono-oauth-umacore-10 (work in progress),
July 2014. July 2014.
[OAuth.Registration.Management] [OAuth.Registration.Management]
Richer, J., Jones, M., Bradley, J., Machulak, M., and P. Richer, J., Jones, M., Bradley, J., and M. Machulak,
Hunt, "OAuth 2.0 Dynamic Client Registration Management "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), August 2014. progress), August 2014.
[OpenID.Registration] [OpenID.Registration]
Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect
Dynamic Client Registration 1.0", February 2014. Dynamic Client Registration 1.0", February 2014.
[TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of TLS and DTLS", November
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
A.1.1. Open Dynamic Client Registration A.1.1. Open Dynamic Client Registration
Authorization servers that support open registration allow Authorization servers that support open registration allow
registrations to be made with no initial access token. This allows registrations to be made with no initial access token. This allows
all client software to register with the authorization server. all client software to register with the authorization server.
A.1.2. Protected Dynamic Client Registration A.1.2. Protected Dynamic Client Registration
Authorization servers that support protected registration require Authorization servers that support protected registration require
that an initial access token be used when making registration that an initial access token be used when making registration
skipping to change at page 31, line 23 skipping to change at page 32, 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 ]]
-21
o Applied minor editorial fixes.
o Added software statement examples.
o Moved software statement request details to sub-section.
o Clarified that a server MAY ignore the software statement (just as
it MAY ignore other metadata values).
o Removed TLS 1.0.
o Added privacy considerations around "contacts" field.
o Marked software_id as RECOMMENDED inside of a software statement.
-20 -20
o Applied minor editorial fixes from working group comments. o Applied minor editorial fixes from working group comments.
-19 -19
o Added informative references to the OpenID Connect Dynamic Client o Added informative references to the OpenID Connect Dynamic Client
Registration and UMA specifications in the introduction. Registration and UMA specifications in the introduction.
o Clarified the "jwks" and "jwks_uri" descriptions and included an o Clarified the "jwks" and "jwks_uri" descriptions and included an
example situation in which they might be used. example situation in which they might be used.
 End of changes. 38 change blocks. 
97 lines changed or deleted 176 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/