OAuth Working Group J. Richer, Ed.
Internet-Draft
Intended status: Experimental M. Jones
Expires: September 24, 2015 Microsoft
J. Bradley
Ping Identity
M. Machulak
Newcastle University
March 23, 2015
OAuth 2.0 Dynamic Client Registration Management Protocol
draft-ietf-oauth-dyn-reg-management-11
Abstract
This specification defines methods for management of dynamic OAuth
2.0 client registrations for use cases in which the properties of a
registered client may need to be changed during the lifetime of the
client. Not all authorization servers supporting dynamic client
registration will support these management methods.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 24, 2015.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
Richer, et al. Expires September 24, 2015 [Page 1]
Internet-Draft OAuth 2.0 Dynamic Registration Management March 2015
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
1.3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 3
2. Client Configuration Endpoint . . . . . . . . . . . . . . . . 5
2.1. Client Read Request . . . . . . . . . . . . . . . . . . . 6
2.2. Client Update Request . . . . . . . . . . . . . . . . . . 6
2.3. Client Delete Request . . . . . . . . . . . . . . . . . . 9
3. Client Information Response . . . . . . . . . . . . . . . . . 10
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 13
7. Normative References . . . . . . . . . . . . . . . . . . . . 13
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 13
Appendix B. Registration Tokens and Client Credentials . . . . . 14
B.1. Credential Rotation . . . . . . . . . . . . . . . . . . . 15
Appendix C. Forming the Client Configuration Endpoint URL . . . 15
Appendix D. Document History . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17
1. Introduction
In order for an OAuth 2.0 client to utilize an OAuth 2.0
authorization server, the client needs specific information to
interact with the server, including an OAuth 2.0 client identifier to
use with that server. The OAuth 2.0 Dynamic Client Registration
Protocol [OAuth.Registration] specification describes how an OAuth
2.0 client can be dynamically registered with an authorization server
to obtain this information and how metadata about the client can be
registered with the server.
This specification extends the core registration specification by
defining a set of methods for management of dynamic OAuth 2.0 client
registrations beyond those defined in the core registration
specification. In some situations, the registered metadata of a
client can change over time, either by modification at the
authorization server or by a change in the client software itself.
This specification provides methods for the current registration
state of a client to be queried at the authorization server, methods
for the registration of a client to be updated at the authorization
Richer, et al. Expires September 24, 2015 [Page 2]
Internet-Draft OAuth 2.0 Dynamic Registration Management March 2015
server, and methods for the client to be unregistered from the
authorization server.
1.1. Notational Conventions
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
document are to be interpreted as described in [RFC2119].
Unless otherwise noted, all the protocol parameter names and values
are case sensitive.
1.2. Terminology
This specification uses the terms "access token", "authorization
code", "authorization endpoint", "authorization grant",
"authorization server", "client", "client identifier", "client
secret", "grant type", "protected resource", "redirection URI",
"refresh token", "resource owner", "resource server", "response
type", and "token endpoint" defined by OAuth 2.0 [RFC6749] and the
terms defined by the OAuth 2.0 Client Dynamic Registration Protocol
[OAuth.Registration].
This specification defines the following terms:
Client Configuration Endpoint
OAuth 2.0 endpoint through which registration information for a
registered client can be managed. This URL for this endpoint is
returned by the authorization server in the client information
response.
Registration Access Token
OAuth 2.0 bearer token issued by the authorization server through
the client registration endpoint that is used to authenticate the
caller when accessing the client's registration information at the
client configuration endpoint. This access token is associated
with a particular registered client.
1.3. Protocol Flow
Richer, et al. Expires September 24, 2015 [Page 3]
Internet-Draft OAuth 2.0 Dynamic Registration Management March 2015
This extends the flow in the OAuth 2.0 Dynamic Client Registration
Protocol [OAuth.Registration] specification as follows:
+--------(A)- Initial Access Token (OPTIONAL)
|
| +----(B)- Software Statement (OPTIONAL)
| |
v v
+-----------+ +---------------+
| |--(C)- Client Registration Request -->| Client |
| | | Registration |
| |<-(D)- Client Information Response ---| Endpoint |
| | +---------------+
| |
| | +---------------+
| Client or |--(E)- Read or Update Request ------->| |
| Developer | | |
| |<-(F)- Client Information Response ---| Client |
| | | Configuration |
| | | Endpoint |
| | | |
| |--(G)- Delete Request --------------->| |
| | | |
| |<-(H)- Delete Confirmation -----------| |
+-----------+ +---------------+
Figure 1: Abstract Extended Dynamic Client Registration Flow
The abstract OAuth 2.0 client dynamic registration flow illustrated
in Figure 1 describes the interaction between the client or developer
and the endpoints defined in this specification and its parent. This
figure does not demonstrate error conditions. This flow includes the
following steps:
(A) Optionally, the client or developer is issued an initial access
token for use with the client registration endpoint. The method
by which the initial access token is issued to the client or
developer is out of scope for this specification.
(B) Optionally, the client or developer is issued a software
statement for use with the client registration endpoint. The
method by which the software statement is issued to the client or
developer is out of scope for this specification.
(C) The client or developer calls the client registration endpoint
with its desired registration metadata, optionally including the
initial access token from (A) if one is required by the
authorization server.
Richer, et al. Expires September 24, 2015 [Page 4]
Internet-Draft OAuth 2.0 Dynamic Registration Management March 2015
(D) The authorization server registers the client and returns:
* the client's registered metadata,
* a client identifier that is unique to the server,
* a set of client credentials such as a client secret, if
applicable for this client,
* a URI pointing to the client configuration endpoint, and
* a registration access token to be used when calling the client
configuration endpoint.
(E) The client or developer optionally calls the client
configuration endpoint with a read or update request using the
registration access token issued in (D). An update request
contains all of the client's registered metadata.
(F) The authorization server responds with the client's current
configuration, potentially including a new registration access
token and a new set of client credentials such as a client secret
if applicable for this client. If a new registration access token
is issued, it replaces the token issued in (D) for all subsequent
calls to the client configuration endpoint.
(G) The client or developer optionally calls the client
configuration endpoint with a delete request using the
registration access token issued in (D) or (F).
(H) The authorization server deprovisions the client and responds
with a confirmation that the deletion has taken place.
2. Client Configuration Endpoint
The client configuration endpoint is an OAuth 2.0 protected resource
that is provisioned by the server to facilitate viewing, updating,
and deleting a client's registered information. The location of this
endpoint is communicated to the client through the
"registration_client_uri" member of the client information response,
as specified in Section 3. The client MUST use its registration
access token in all calls to this endpoint as an OAuth 2.0 Bearer
Token [RFC6750].
The client configuration endpoint MUST be protected by a transport-
layer security mechanism, as described in Section 5.
Richer, et al. Expires September 24, 2015 [Page 5]
Internet-Draft OAuth 2.0 Dynamic Registration Management March 2015
Operations on this endpoint are switched through the use of different
HTTP methods [RFC7231]. If an authorization server does not support
a particular method on the client configuration endpoint, it MUST
respond with the appropriate error code.
2.1. Client Read Request
To read the current configuration of the client on the authorization
server, the client makes an HTTP GET request to the client
configuration endpoint, authenticating with its registration access
token.
Following is a non-normative example request (with line wraps for
display purposes only):
GET /register/s6BhdRkqt3 HTTP/1.1
Accept: application/json
Host: server.example.com
Authorization: Bearer reg-23410913-abewfq.123483
Upon successful read of the information for a currently active
client, the authorization server responds with an HTTP 200 OK with
content type of "application/json" and a payload, as described in
Section 3. Some values in the response, including the
"client_secret" and "registration_access_token", MAY be different
from those in the initial registration response. If the
authorization server includes a new client secret and/or registration
access token in its response, the client MUST immediately discard its
previous client secret and/or registration access token. The value
of the "client_id" MUST NOT change from the initial registration
response.
If the registration access token used to make this request is not
valid, the server MUST respond with an error as described in OAuth
Bearer Token Usage [RFC6750].
If the client does not exist on this server, the server MUST respond
with HTTP 401 Unauthorized and the registration access token used to
make this request SHOULD be immediately revoked.
If the client does not have permission to read its record, the server
MUST return an HTTP 403 Forbidden.
2.2. Client Update Request
To update previously-registered client's registration with an
authorization server, the client makes an HTTP PUT request to the
client configuration endpoint with a content type of "application/
Richer, et al. Expires September 24, 2015 [Page 6]
Internet-Draft OAuth 2.0 Dynamic Registration Management March 2015
json". The HTTP entity payload is a JSON [RFC7159] document
consisting of a JSON object and all parameters as top-level members
of that JSON object. This request is authenticated by the
registration access token issued to the client.
This request MUST include all client metadata fields as returned to
the client from a previous registration, read, or update operation.
The updated client metadata fields request MUST NOT include the
"registration_access_token", "registration_client_uri",
"client_secret_expires_at", or "client_id_issued_at" fields described
in Section 3.
Valid values of client metadata fields in this request MUST replace,
not augment, the values previously associated with this client.
Omitted fields MUST be treated as null or empty values by the server,
indicating the client's request to delete them from the client's
registration. The authorization server MAY ignore any null or empty
value in the request just as any other value.
The client MUST include its "client_id" field in the request, and it
MUST be the same as its currently-issued client identifier. If the
client includes the "client_secret" field in the request, the value
of this field MUST match the currently-issued client secret for that
client. The client MUST NOT be allowed to overwrite its existing
client secret with its own chosen value.
For all metadata fields, the authorization server MAY replace any
invalid values with suitable default values, and it MUST return any
such fields to the client in the response.
For example, a client could send the following request to the client
registration endpoint to update the client registration in the above
example with new information:
Richer, et al. Expires September 24, 2015 [Page 7]
Internet-Draft OAuth 2.0 Dynamic Registration Management March 2015
Following is a non-normative example request (with line wraps for
display purposes only):
PUT /register/s6BhdRkqt3 HTTP/1.1
Accept: application/json
Host: server.example.com
Authorization: Bearer reg-23410913-abewfq.123483
{
"client_id":"s6BhdRkqt3",
"client_secret": "cf136dc3c1fc93f31185e5885805d",
"redirect_uris":[
"https://client.example.org/callback",
"https://client.example.org/alt"],
"grant_types": ["authorization_code", "refresh_token"],
"token_endpoint_auth_method": "client_secret_basic",
"jwks_uri": "https://client.example.org/my_public_keys.jwks",
"client_name":"My New Example",
"client_name#fr":"Mon Nouvel Exemple",
"logo_uri":"https://client.example.org/newlogo.png",
"logo_uri#fr":"https://client.example.org/fr/newlogo.png"
}
This example uses client metadata values defined in
[OAuth.Registration].
Upon successful update, the authorization server responds with an
HTTP 200 OK Message with content type "application/json" and a
payload, as described in Section 3. Some values in the response,
including the "client_secret" and "registration_access_token", MAY be
different from those in the initial registration response. If the
authorization server includes a new client secret and/or registration
access token in its response, the client MUST immediately discard its
previous client secret and/or registration access token. The value
of the "client_id" MUST NOT change from the initial registration
response.
If the registration access token used to make this request is not
valid, the server MUST respond with an error as described in OAuth
Bearer Token Usage [RFC6750].
If the client does not exist on this server, the server MUST respond
with HTTP 401 Unauthorized, and the registration access token used to
make this request SHOULD be immediately revoked.
If the client is not allowed to update its records, the server MUST
respond with HTTP 403 Forbidden.
Richer, et al. Expires September 24, 2015 [Page 8]
Internet-Draft OAuth 2.0 Dynamic Registration Management March 2015
If the client attempts to set an invalid metadata field and the
authorization server does not set a default value, the authorization
server responds with an error as described in [OAuth.Registration].
2.3. Client Delete Request
To deprovision itself on the authorization server, the client makes
an HTTP DELETE request to the client configuration endpoint. This
request is authenticated by the registration access token issued to
the client as described in [