| Network Working Group | C. Scholz, Ed. |
| Internet-Draft | COM.lounge GmbH |
| Intended status: Standards Track | M. Machulak |
| Expires: October 14, 2011 | Newcastle University |
| E. Maler | |
| XMLgrrl.com | |
| April 12, 2011 |
OAuth Dynamic Client Registration Protocol
draft-oauth-dyn-reg-v1-01
This specification proposes an OAuth Dynamic Client Registration protocol.
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 October 14, 2011.
Copyright (c) 2011 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 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.
This informal draft discusses a number of requirements for and approaches to automatic registration of clients with an OAuth authorization server, with special emphasis on the needs of the OAuth-based User-Managed Access protocol [UMA-Core].
In some use-case scenarios it is desirable or necessary to allow OAuth clients to obtain authorization from an OAuth authorization server without the two parties having previously interacted. Nevertheless, in order for the authorization server to accurately represent to end-users which client is seeking authorization to access the end-user's resources, a method for automatic and unique registration of clients is needed.
The goal of this proposed registration protocol is for an authorization server to provide a client with a client identifier and optionally a client secret in a dynamic fashion. To accomplish this, the authorization server must first be provided with information about the client, with the client-name being the minimal information provided. In practice, additional information will need to be furnished to the authorization server, such as the client's homepage, icon, description, and so on.
The dynamic registration protocol proposed here is envisioned to be an additional task to be performed by the OAuth authorization server, namely registration of a new client identifier and optional secret and the issuance of this information to the client. This task would occur prior to the point at which the client wields its identifier and secret at the authorization server in order to obtain an access token in normal OAuth fashion.
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.
The UMA protocol involves two instances of OAuth flows. In the first, an end-user introduces a host (essentially an enhanced OAuth resource server) to an authorization manager (an enhanced OAuth authorization server) as a client of it, possibly without that host having obtained client identification information from that server previously. In the second, a requester (an enhanced OAuth client) approaches a host and authorization manager to get and use an access token in approximately the normal OAuth fashion, again possibly without that client having obtained client identification information from that server previously. Both the host-as-client and the requester-as-client thus may need dynamic client registration in order for the UMA protocol flow to proceed.
The needs for inter-party trust vary in different UMA use cases. In lightweight Web circumstances such as person-to-person calendar sharing, dynamic registration is entirely appropriate. In cases where high-sensitivity information is being protected or where a regulatory environment puts constraints on the building of trust relationships, such as sharing health records with medical professionals or giving access to tax records to outsourced bookkeeping staff, static means of provisioning client identifiers may be imposed.
More information about UMA use cases is available at [UMA-UC].
Following are proposed requirements for dynamic client registration.
In order for an authorization server to do proper user-delegated authorization and prevent unauthorized access it must be able to identify clients uniquely. As is done today in OAuth, the client identifier (and optional secret) should thus be issued by the authorization server and not simply accepted as proposed by the client.
In order for the authorization server to describe a client to an end-user in an authorization step it needs information about the client. This can be the client name at a minimum, but today servers usually request at least a description, a homepage URL, and an icon when doing manual registration.
In order to prevent spoofing of clients and enable dynamic building of strong trust relationships, the authorization server should have the option to verify the provided information. This might be solved using message signature verification; relatively weaker authentication might be achieved in a simpler way by pulling metadata from a trusted client URL.
In the UMA context, alternative types of applications might serve as both hosts (for example, as a device-based personal data store) and requesters (for example, to subscribe to a calendar or view a photo). Such applications, particularly native applications, may have special limitations, so new solutions to meeting the set of requirements presented here may be needed. We anticipate that each instance of a native application (that is, the specific instance running on each device) that is installed and run by the same user may need the option of getting a unique client identifier. In this case, there are implications around gathering and displaying enough information to ensure that the end-user is delegating authorization to the intended application.
When a client sends information to a server endpoint, it might take time for this data to propagate through big server installations that spread across various data centers. Care needs to be taken that subsequent interactions with the user after the registration process, such as an authorization request, show the correct data.
In the UMA context, dynamic registration of a host at an AM is almost certain to take place in the middle of an introduction and authorization process mediated by the end-user; even though the host needs a client identifier from the AM no matter which end-user caused the registration process to take place, the end-user may need to wait for the registration sub-process to finish in order to continue with the overall process. It may be necessary to ensure that the host interacts with the same AM server throughout.
In addition to general requirements for dynamic client registration, UMA seeks to optimize for the design principles and requirements found in the UMA Requirements document [UMA-Reqs], most particularly:
This section analyzes some options for exchanging client metadata for a client identifier and optional secret.
It currently seems impossible to specify a single registration flow that will satisfy all requirements, deployment needs, and client types. This document, therefore, presents as small a variety of options as possible. If it is possible to construct a single unified flow in the ultimate design, all other things being equal this would be preferred.
Regardless of flow option, the client needs to discover the authorization server's client registration endpoint.
The client MUST use the [RFC5785] and [hostmeta] discovery mechanisms to learn the URI of the client registration endpoint at the authorization server. The authorization server MUST provide a host-meta document containing a Link element with a rel value of: http://oauth.net/as/registration
For example:
<XRD>
<Host>http://server.example.com</Host>
<Link rel="http://oauth.net/as/registration"
href="https://server.example.com/register">
<Title>Client Registration Endpoint</Title>
</Link>
</XRD>
This registration flow works as follows:
+--------+ +---------------+
| Client |--(A)--- Registration Request --->| Authorization |
| | with Metadata | Server |
| | | |
| |<-(B)----Registration Response ---| |
| | with Client ID Info | |
+--------+ +---------------+
The client sends a JSON formatted document to the client registration endpoint. The client includes the following parameters in the request:
The client MAY include additional metadata in the request and the authorization server MAY ignore this additional information.
For example, the client might send the following request:
POST /register HTTP/1.1
Host: server.example.com
Content-Type: application/json
{
type: "push",
client_name: "Online Photo Gallery",
client_url: "http://onlinephotogallery.com",
client_description: "Uploading and also editing capabilities!",
client_icon: "http://onlinephotogallery.com/icon.png",
redirect_url: "https://onlinephotogallery.com/client_reg"
}
The parameters are included in the entity body of the HTTP request using the "application/json" media type as defined by [JSON]. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings.
After receiving and verifying information received from the client, the authorization server issues a client identifier and an optional client secret, and constructs the response by adding the following parameters to the entity body of the HTTP response with a 200 status code (OK):
The parameters are included in the entity body of the HTTP response using the "application/json" media type as defined by [JSON]. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings.
The authorization server MUST include the HTTP Cache-Control response header field with a value of no-store in any response containing client_secret.
For example, the authorization server might return the following response:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
client_id: "5UO9XcL4TQTa",
client_secret: "WdRKN3zeTc20"
}
If the request for registration is invalid or unauthorized, the authorization server constructs the response by adding the following parameters to the entity body of the HTTP response with a 400 status code (Bad Request) using the “application/json” media type:
An example error response (with line breaks for readability):
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error": "unauthorized_client",
"description": "This client is not on the
white list of this Authorization Server."
}
This registration flow works as follows:
+--------+ +---------------+
| Client |--(A)--- Registration Request --->| Authorization |
| | with URL | Server |
| | | |
| |<-(B)--- Client Discovery --------| |
| | | |
| |--(C)---- Host-Meta Document ---->| |
| | | |
| |<-(D)--- Registration Response ---| |
| | with Client ID Info | |
+--------+ +---------------+
The client sends a JSON formatted document to the client registration endpoint. The client includes the following parameters in the request:
The client MUST NOT include other metadata parameters, such as those defined in the pushed-metadata scenario.
For example, the client might send the following request:
POST /register HTTP/1.1
Host: server.example.com
Content-Type: application/json
{
type: "pull",
url: "http://onlinephotogallery.com"
}
The parameters are included in the entity body of the HTTP request using the "application/json" media type as defined by [JSON]. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings.
The authorization server evaluates this request and MAY perform a [RFC5785] and [hostmeta] discovery mechanism on the provided URL to the host-meta document for the client.
For example:
GET /.well-known/host-meta HTTP/1.1
Host: onlinephotogallery.com
The authorization server retrieves the host-meta document, which MUST contain:
For example:
<XRD>
<Host>http://onlinephotogallery.com</Host>
<Property type="http://oauth.net/client/name">
Online Photo Gallery
</Property>
<Property type="http://oauth.net/client/description">
Really nice Online Photo Gallery!
</Property>
<Link rel="http://oauth.net/client/uri"
href="http://onlinephotogallery.com">
<Title>Client URI</Title>
</Link>
<Link rel="http://oauth.net/client/redirect_uri"
href="https://onlinephotogallery.com/client_reg">
<Title>Client Redirect URI</Title>
</Link>
<Link rel="http://oauth.net/client/icon"
href="http://onlinephotogallery.com/icon.png">
<Title>Client Icon</Title>
</Link>
</XRD>
After receiving and verifying information retrieved from the client, the authorization server issues the client identifier and an optional client secret, and constructs the response by adding the following parameters to the entity body of the HTTP response with a 200 status code (OK):
The parameters are included in the entity body of the HTTP response using the "application/json" media type as defined by [JSON]. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings.
The authorization server MUST include the HTTP Cache-Control response header field with a value of no-store in any response containing the client_secret.
For example the authorization server might return the following response:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"client_id":"5UO9XcL4TQTa",
"client_secret":"WdRKN3zeTc20"
}
If the request for registration is invalid or unauthorized, the authorization server constructs the response by adding the following parameters to the entity body of the HTTP response with a 400 status code (Bad Request) using the “application/json” media type:
An example error response (with line breaks for readability):
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error": "unauthorized_client",
"description": "This client is not on the
white list of this Authorization Server."
}
If the host-meta discovery was not successful, the authorization server MUST use the error code hostmeta_error.
An example error response (with line breaks for readability):
HTTP/1.1 404 Not Found
Content-Type: application/json
Cache-Control: no-store
{
"error": "hostmeta_error",
"description": "The hostmeta document could
not be retrieved from the URL."
}
For a native application serving as an UMA host, we anticipate that the need for dynamic client registration to introduce this app to an UMA authorization manager may typically happen only once (or very infrequently), likely to a single authorization manager, and registration could usefully take place at the time the app is provisioned onto a device. By contrast, for a native app serving as an UMA requester, it may need to register at multiple authorization managers over time when seeking access tokens, at moments much later than the original provisioning of the app onto the device.
When a native application is provisioned on a device, such as through an app store model, often it has an associated "home base" web server application component with which it registers (outside of any UMA-related or OAuth-related interactions). This pairwise relationship can be exploited in a number of ways to allow trustable, unique metadata to be conveyed to an OAuth server and for this instance of the app to receive a client identifier and optional secret. We have discussed "device-initiated" and "home base-initiated" pattern options for OAuth dynamic client registration in these circumstances. Device-initiated flows seem more generically applicable (for example, for both UMA host and UMA requester needs). However, a home base-initiated flow may be preferable in case it is necessary to pre-determine a trust level towards an OAuth server. In this case, the home base server could initiate the registration process if and only if there exists a trust relationship between the two parties.
Following is one option for a device-initiated flow:
Following are some security considerations:
The authors thank the User-Managed Access Work Group participants, particularly the following, for their input to this document:
[[ to be removed by RFC editor before publication as an RFC ]]
| [OAuth-Sig] | Balfanz, D., "OAuth Signature proposals", 2010. |
| [hostmeta] | Hammer-Lahav, E., "Web Host Metadata", 2010. |
| [JSON] | Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", 2006. |
| [RFC2617] | Franks, J., Hallam-Baker, P.M., Hostetler, J.L., Lawrence, S.D., Leach, P.J., Luotonen, A. and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC5785] | Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, April 2010. |
| [UMA-Core] | Scholz, C., "UMA Requirements", 2010. |
| [UMA-UC] | Akram, H., "UMA Explained", 2010. |
| [UMA-Reqs] | Maler, E., "UMA Requirements", 2010. |