draft-ietf-oauth-dyn-reg-19.txt   draft-ietf-oauth-dyn-reg-20.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 6, 2015 Microsoft Expires: February 27, 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 5, 2014 August 26, 2014
OAuth 2.0 Dynamic Client Registration Protocol OAuth 2.0 Dynamic Client Registration Protocol
draft-ietf-oauth-dyn-reg-19 draft-ietf-oauth-dyn-reg-20
Abstract Abstract
This specification defines mechanisms for dynamically registering This specification defines mechanisms for dynamically registering
OAuth 2.0 clients with authorization servers. Registration requests OAuth 2.0 clients with authorization servers. Registration requests
send a set of desired client metadata values to the authorization send a set of desired client metadata values to the authorization
server and the resulting registration responses return a client server. 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
using the OAuth 2.0 protocol. This specification also defines a set using the OAuth 2.0 protocol. This specification also defines a set
of common client metadata fields and values for clients to use during of common client metadata fields and values for clients to use during
registration. registration.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
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 6, 2015. This Internet-Draft will expire on February 27, 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 4, line 48 skipping to change at page 4, line 48
OAuth 2.0 access token optionally issued by an authorization OAuth 2.0 access token optionally issued by an authorization
server to a developer or client and used to authorize calls to the server to a developer or client and used to authorize calls to the
client registration endpoint. The type and format of this token client registration endpoint. The type and format of this token
are likely service-specific and are out of scope for this are likely service-specific and are out of scope for this
specification. The means by which the authorization server issues specification. The means by which the authorization server issues
this token as well as the means by which the registration endpoint this token as well as the means by which the registration endpoint
validates this token are out of scope for this specification. Use validates this token are out of scope for this specification. Use
of an initial access token is required when the authorization of an initial access token is required when the authorization
server limits the parties that can register a client. server limits the parties that can register a client.
Deployment Organization Deployment Organization
An administrative security domain under which, a software API is An administrative security domain under which a software API is
deployed and protected by an OAuth 2.0 framework. In simple cloud deployed and protected by an OAuth 2.0 framework. In simple cloud
deployments, the software API publisher and the deployment deployments, the software API publisher and the deployment
organization may be the same. In other scenarios, a software organization may be the same. In other scenarios, a software
publisher may be working with many different deployment publisher may be working with many different deployment
organizations. organizations.
Software API Deployment Software API Deployment
A deployed instance of a software API that is protected by OAuth A deployed instance of a software API that is protected by OAuth
2.0 in a particular deployment organization domain. For any 2.0 in a particular deployment organization domain. For any
particular software API, there may be one or more deployments. A particular software API, there may be one or more deployments. A
software API deployment typically has an associated OAuth 2.0 software API deployment typically has an associated OAuth 2.0
skipping to change at page 7, line 40 skipping to change at page 7, line 40
* "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].
Authorization Servers MAY allow for other values as defined in If the token endpoint is used in the grant type, the value of this
grant type extensions to OAuth 2.0. The extension process is parameter MUST be the same as the value of the "grant_type"
described in OAuth 2.0 Section 2.5. If the token endpoint is used parameter passed to the token endpoint defined in the grant type
in the grant type, the value of this parameter MUST be the same as definition. Authorization Servers MAY allow for other values as
the value of the "grant_type" parameter passed to the token defined in the grant type extension process described in OAuth 2.0
endpoint defined in the extension. If omitted, the default is Section 2.5. If omitted, the default behavior is that the client
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 may use.
These response types are defined as follows: These response types are defined as follows:
* "code": The Authorization Code response described in OAuth 2.0 * "code": The Authorization Code response described in OAuth 2.0
Section 4.1. Section 4.1.
* "token": The Implicit response described in OAuth 2.0 * "token": The Implicit response described in OAuth 2.0
Section 4.2. Section 4.2.
Authorization servers MAY allow for other values as defined in If the authorization endpoint is used by the grant type, the value
response type extensions to OAuth 2.0. The extension process is of this parameter MUST be the same as the value of the
described in OAuth 2.0 Section 2.5. If the authorization endpoint "response_type" parameter passed to the authorization endpoint
is used by the grant type, the value of this parameter MUST be the defined in the grant type definition. Authorization servers MAY
same as the value of the "response_type" parameter passed to the allow for other values as defined in the grant type extension
authorization endpoint defined in the extension. 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 user Human-readable name of the client to be presented to the user
during authorization. If omitted, the authorization server MAY during authorization. If omitted, the authorization server MAY
display the raw "client_id" value to the user instead. It is display the raw "client_id" value to the user instead. It is
RECOMMENDED that clients always send this field. The value of RECOMMENDED that clients always send this field. The value of
this field MAY be internationalized, as described in Section 2.2. this field MAY be internationalized, as described in Section 2.2.
client_uri client_uri
URL of a web page providing information about the client. If URL of a web page providing information about the client. If
present, the server SHOULD display this URL to the end user in a present, the server SHOULD display this URL to the end user in a
skipping to change at page 9, line 22 skipping to change at page 9, line 22
field MAY be internationalized, as described in Section 2.2. 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 referencing the client's JSON Web Key Set [JWK] document,
which contains the client's public keys. The value of this field which contains the client's public keys. The value of this field
MUST point to a valid JWK Set document. These keys can be used by MUST point to a valid JWK Set document. These keys can be used by
higher level protocols that use signing or encryption. For higher level protocols that use signing or encryption. For
instance, these keys might be used by some applications 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 be key rotation. The "jwks_uri" and "jwks" parameters MUST NOT both
used together. 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 be public URLs. The "jwks_uri" and "jwks" parameters MUST NOT both
used together. be present in the same request or response.
software_id software_id
Identifier for the software that comprises a client. Unlike Identifier for the software that comprises a client. Unlike
"client_id", which is issued by the authorization server and may "client_id", which is issued by the authorization server and may
vary between instances, the "software_id" is asserted by the vary between instances, the "software_id" is asserted by the
client software on behalf of the software developer and is client software on behalf of the software developer and is
intended to be shared among all instances of the client software. intended to be shared among all instances of the client software.
The identifier SHOULD NOT change when software version changes or The identifier SHOULD NOT change when software version changes or
when a new installation occurs. when a new installation occurs.
software_version software_version
Version identifier for the software that comprises a client. The Version identifier for the software that comprises a client. The
skipping to change at page 12, line 4 skipping to change at page 11, line 51
for display on a wide variety of systems. for display on a wide variety of systems.
Implementer's Note: Many JSON libraries make it possible to reference Implementer's Note: Many JSON libraries make it possible to reference
members of a JSON object as members of an object construct in the members of a JSON object as members of an object construct in the
native programming environment of the library. However, while the native programming environment of the library. However, while the
"#" character is a valid character inside of a JSON object's member "#" character is a valid character inside of a JSON object's member
names, it is not a valid character for use in an object member name names, it is not a valid character for use in an object member name
in many programming environments. Therefore, implementations will in many programming environments. Therefore, implementations will
need to use alternative access forms for these claims. For instance, need to use alternative access forms for these claims. For instance,
in JavaScript, if one parses the JSON as follows, "var j = in JavaScript, if one parses the JSON as follows, "var j =
JSON.parse(json);", then the member "client_name#en-us" can be JSON.parse(json);", then as a workaround the member "client_name#en-
accessed using the JavaScript syntax "j["client_name#en-us"]". us" can be accessed using the JavaScript syntax "j["client_name#en-
us"]".
2.3. Software Statement 2.3. Software Statement
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
skipping to change at page 13, line 32 skipping to change at page 13, line 32
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.
To register, the client or developer sends an HTTP POST to the client
registration endpoint with a content type of "application/json". The
HTTP Entity Payload is a JSON [RFC7159] document consisting of a JSON
object and all requested client metadata values as top-level members
of that JSON object.
Client metadata values may also be provided in a software statement, Client metadata values may also be provided in a software statement,
as described in Section 2.3. Software statements are included in the as described in Section 2.3. Software statements are included in the
requesting JSON object using this member: requesting JSON object using this 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.
To register, the client or developer sends an HTTP POST to the client
registration endpoint with a content type of "application/json". The
HTTP Entity Payload is a JSON [RFC7159] document consisting of a JSON
object and all requested client metadata values as top-level members
of that JSON object.
For example, if the server supports open registration (with no 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:
The following is a non-normative example request not using an initial The following is a non-normative example request not using an initial
access token (with line wraps within values for display purposes access token (with line wraps within values for display purposes
only): only):
POST /register HTTP/1.1 POST /register HTTP/1.1
Content-Type: application/json Content-Type: application/json
skipping to change at page 16, line 31 skipping to change at page 16, line 31
The response contains the client identifier as well as the client The response contains the client identifier as well as the client
secret, if the client is a confidential client. The response MAY secret, if the client is a confidential client. The response MAY
contain additional fields as specified by extensions to this contain additional fields as specified by extensions to this
specification. specification.
client_id client_id
REQUIRED. OAuth 2.0 client identifier. It SHOULD NOT be REQUIRED. OAuth 2.0 client identifier. It SHOULD NOT be
currently valid for any other registered client, though an currently valid for any other registered client, though an
authorization server MAY issue the same client identifier to authorization server MAY issue the same client identifier to
multiple instances of a registered client, at its discretion. multiple instances of a registered client at its discretion.
client_secret client_secret
OPTIONAL. OAuth 2.0 client secret. If issued, this MUST be OPTIONAL. OAuth 2.0 client secret. If issued, this MUST be
unique for each "client_id". This value is used by confidential unique for each "client_id" and SHOULD be unique for multiple
clients to authenticate to the token endpoint as described in instances of a client using the same "client_id". This value is
OAuth 2.0 [RFC6749] Section 2.3.1. used by confidential clients to authenticate to the token endpoint
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.
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.
skipping to change at page 26, line 43 skipping to change at page 26, line 43
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 uses the same "software_id" and "software_version" values
as another client, the server should treat the new registration as as another client, the server should treat the new registration as
being suspect. It is possible that the new client is trying to being suspect. It is possible that the new client is trying to
impersonate the existing client. impersonate the existing client.
Since a client identifier is a public value that can be used to Since a client identifier is a public value that can be used to
impersonate a client at the authorization endpoint, an authorization impersonate a client at the authorization endpoint, an authorization
server that decides to issue the same client identifier to multiple server that decides to issue the same client identifier to multiple
instances of a registered client MUST be very particular about the instances of a registered client needs to be very particular about
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. References
skipping to change at page 31, line 23 skipping to change at page 31, line 23
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 ]]
-20
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.
o Removed "application_type". o Removed "application_type".
o Added redirection URI usage restrictions to the Security o Added redirection URI usage restrictions to the Security
Considerations section, based on the client type. Considerations section, based on the client type.
o Expanded the "tos_uri" and "policy_uri" descriptions. o Expanded the "tos_uri" and "policy_uri" descriptions.
skipping to change at page 34, line 50 skipping to change at page 35, line 4
o Removed secret_rotation as a client-initiated action, including o Removed secret_rotation as a client-initiated action, including
removing client secret rotation endpoint and parameters. removing client secret rotation endpoint and parameters.
o Changed _links structure to single value registration_access_url. o Changed _links structure to single value registration_access_url.
o Collapsed create/update/read responses into client info response. o Collapsed create/update/read responses into client info response.
o Changed return code of create action to 201. o Changed return code of create action to 201.
o Added section to describe suggested generation and composition of o Added section to describe suggested generation and composition of
Client Registration Access URL. Client Registration Access URL.
o Added clarifying text to PUT and POST requests to specify JSON in o Added clarifying text to PUT and POST requests to specify JSON in
the body. the body.
o Added Editor's Note to DELETE operation about its inclusion.
o Added Editor's Note to DELETE operation about its inclusion.
o Added Editor's Note to registration_access_url about alternate o Added Editor's Note to registration_access_url about alternate
syntax proposals. syntax proposals.
-05 -05
o changed redirect_uri and contact to lists instead of space o changed redirect_uri and contact to lists instead of space
delimited strings delimited strings
o removed operation parameter o removed operation parameter
o added _links structure o added _links structure
o made client update management more RESTful o made client update management more RESTful
 End of changes. 19 change blocks. 
38 lines changed or deleted 44 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/