The following is an experimental rendering of the generated HTML that also resides at mrtopf.clprojects.net. It may not look exactly right. The clprojects version has proper fidelity but may be slightly out of date compared to this one.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en"><head><title>UMA Resource Registration</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="UMA Resource Registration">
<meta name="generator" content="xml2rfc v1.35 (http://xml.resource.org/)">
<style type='text/css'><!--
body
h1, h2, h3, h4, h5, h6
h1
h3
td.RFCbug
td.RFCbug span.RFC
td.RFCbug span.hotText
table.TOCbug
td.TOCbug
td.TOCbug a
td.header
td.author
td.author-text
/* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
a.info
a.info:hover
a.info span
a.info:hover span.info
a
a:link
a:visited
a:active
p
p.copyright
p.toc
table.toc
td.toc
ol.text
ul.text
li
/* RFC-2629 <spanx>s and <artwork>s. */
em
strong
dfn
cite
tt
tt, pre, pre dfn, pre em, pre cite, pre span
pre
pre dfn
pre em
pre .key
pre .id
pre .str
pre .val
pre .rep
pre .oth
pre .err
/* RFC-2629 <texttable>s. */
table.all, table.full, table.headers, table.none
table.all, table.full
table.headers, table.none
th
table.all th, table.full th
table.headers th
table.none th
table.all td
table.full td, table.headers td, table.none td
hr
hr.insert
--></style>
</head>
<body>
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
<tr><td class="header">Network Working Group</td><td class="header">C. Scholz, Ed.</td></tr>
<tr><td class="header">Internet-Draft</td><td class="header">COM.lounge GmbH</td></tr>
<tr><td class="header">Intended status: Standards Track</td><td class="header">M. Machulak</td></tr>
<tr><td class="header">Expires: July 11, 2011</td><td class="header">Newcastle University</td></tr>
<tr><td class="header"> </td><td class="header">E. Maler</td></tr>
<tr><td class="header"> </td><td class="header"> </td></tr>
<tr><td class="header"> </td><td class="header">P. Bryan</td></tr>
<tr><td class="header"> </td><td class="header">P. Bryan Consulting</td></tr>
<tr><td class="header"> </td><td class="header">January 7, 2011</td></tr>
</table></td></tr></table>
<h1><br />UMA Resource Registration<br />draft-uma-resource-reg</h1>
<h3>Abstract</h3>
<p>This specification defines the resource registration protocol for User-Managed Access (UMA). This protocol provides a method for a host to register, update, check, and delete resource-related information at an authorization manager (AM) so that the user's resources can be put under scoped protection.
</p>
<h3>Status of this Memo</h3>
<p>
This Internet-Draft is submitted in full
conformance with the provisions of BCP 78 and BCP 79.</p>
<p>
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/.</p>
<p>
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.”</p>
<p>
This Internet-Draft will expire on July 11, 2011.</p>
<h3>Copyright Notice</h3>
<p>
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved.</p>
<p>
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.</p>
<a name="toc"></a><br /><hr />
<h3>Table of Contents</h3>
<p class="toc">
<a href="#anchor1">1.</a>
Introduction<br />
<a href="#anchor2">1.1.</a>
Notational Conventions<br />
<a href="#anchor3">1.2.</a>
Terminology<br />
<a href="#anchor4">1.3.</a>
Requirements Analysis<br />
<a href="#anchor5">2.</a>
Prerequisites<br />
<a href="#anchor6">3.</a>
Example<br />
<a href="#action-desc">4.</a>
Action Description<br />
<a href="#resource-set-desc">5.</a>
Resource Set Description<br />
<a href="#reg-api">6.</a>
Resource Registration API<br />
<a href="#create-resource-set">6.1.</a>
Create Resource Set Description<br />
<a href="#read-resource-set">6.2.</a>
Read Resource Set Description<br />
<a href="#update-resource-set">6.3.</a>
Update Resource Set Description<br />
<a href="#delete-resource-set">6.4.</a>
Delete Resource Set Description<br />
<a href="#list-resource-sets">6.5.</a>
List Resource Set Descriptions<br />
<a href="#anchor7">7.</a>
Security Considerations<br />
<a href="#anchor8">8.</a>
Privacy Considerations<br />
<a href="#anchor9">9.</a>
TODOs<br />
<a href="#anchor10">10.</a>
Acknowledgments<br />
<a href="#anchor11">11.</a>
Document History<br />
<a href="#rfc.references1">12.</a>
Normative References<br />
<a href="#rfc.authors">§</a>
Authors' Addresses<br />
</p>
<br clear="all" />
<a name="anchor1"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1"></a><h3>1.
Introduction</h3>
<p>This specification defines the resource registration protocol for User-Managed Access (<a class='info' href='#draft-uma-core'>UMA<span> (</span><span class='info'>Scholz, C., “UMA 1.0 Core Protocol,” December 2010.</span><span>)</span></a> [draft‑uma‑core]). This protocol provides a method for a host to register, update, check, and delete resource-related information at an authorization manager (AM) so that the user's resources can be put under scoped protection.
</p>
<p>(Intellectual property notice: The User-Managed Access Work Group operates under <a href='http://kantarainitiative.org/confluence/display/GI/Option+Patent+and+Copyright+%28RAND%29'>Kantara IPR Policy - Option Patent & Copyright: Reciprocal Royalty Free with Opt-Out to Reasonable And Non discriminatory (RAND)</a> and the publication of this document is governed by the policies outlined in this option.)
</p>
<p>The host needs to register information about resources to be protected so that the AM can apply authorization constraints to them according to the user's wishes.
</p>
<p>The host determines (unilaterally or as instructed by the user) the universe of resources belonging to this user that are to be protected by the AM, and assigns a resource identifier to sets of these resources. Such a set might include a status update API endpoint (applying to the user's entire update stream), or an individual status update, or a photo album, or all photos with a particular user-assigned tag, or even the set of "all resources managed by this user at this host".
</p>
<p>The host also determines the universe of actions that is possible for requesting parties to perform on each resource set. Such actions might involve "viewing", "adding", "printing", or whatever other actions the application supports for that resource set. Typically each action covers a broad list of methods in the host's published API.
</p>
<p>Once the host has registered resource sets and their descriptive information with the AM, the AM (under the authorizing user's instructions) is able to map particular authorization constraints to a particular set of resources and a particular set of actions and to take part in the process of limiting (scoping) access to resource sets.
</p>
<p>Note that the host is free to offer the option to protect any subset of the user's resources using different AMs or other means entirely, or to protect some resources and not others; any such partitioning is outside the scope of this specification.
</p>
<a name="anchor2"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1.1"></a><h3>1.1.
Notational Conventions</h3>
<p>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 <a class='info' href='#RFC2119'>[RFC2119]<span> (</span><span class='info'>Bradner, “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.</span><span>)</span></a>.
</p>
<p>Unless otherwise noted, all the protocol parameter names and values are case sensitive.
</p>
<a name="anchor3"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1.2"></a><h3>1.2.
Terminology</h3>
<p>See <a class='info' href='#draft-uma-core'>UMA<span> (</span><span class='info'>Scholz, C., “UMA 1.0 Core Protocol,” December 2010.</span><span>)</span></a> [draft‑uma‑core] for additional term definitions.
</p>
<p></p>
<blockquote class="text"><dl>
<dt>registration endpoint</dt>
<dd>A protected endpoint at the AM capable of receiving resource information from a host.
</dd>
<dt>resource set description</dt>
<dd>A JSON-formatted data structure that represents a set of one or more resources to be AM-protected and maps possible actions to them.
</dd>
<dt>action description</dt>
<dd>A JSON-formatted data structure that represents a possible action on a resource set.
</dd>
</dl></blockquote>
<a name="anchor4"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.1.3"></a><h3>1.3.
Requirements Analysis</h3>
<p>This specification, in combination with the UMA core protocol specification and the scoped-access specification, has been informed by the following resource registration requirements:</p>
<ul class="text">
<li>The authorizing user needs to be presented with a user interface at the AM that clearly indicates what resources and actions are available when they're setting and mapping authorization constraints. (User interface considerations are out of scope of UMA protocol specifications, but this requirement has protocol dependencies.)
</li>
<li>The AM therefore needs to acquire from the host some description of resources and actions to be protected, which includes enough information to display to the authorizing user. (Solved by this specification.)
</li>
<li>The requester and requesting party, prior to receiving an access token, should not be exposed to resource information that compromises the authorizing user's privacy. For example, a protected set of resources might usefully but embarrassingly be described as "racy photos from beach vacation". It is assumed that the host already has access to such a description and that the nature of the host-AM trust relationship forged by the authorizing user may qualify the AM to see this description as well. (Solved by this specification.)
</li>
<li>The AM needs to be told the relevant resource set, in host-described terms, that corresponds to the resource the requester is seeking access to so that it can assess the requesting party's request for an access token against the correct authorization constraints. (Solved by the scoped-access specification.)
</li>
<li>Therefore, when the requester attempts access at the host and fails, the host needs to convey enough information to the AM (whether through the requester directly or by other means) for the latter to do this job. For privacy reasons, if the host asks the requester to convey information directly, privacy considerations come into play. (Solved by the scoped-access specification.)
</li>
<li>The host needs to be able to validate that a requester's access attempt in step 3, accompanied by an access token, matches the resource set and action set for which that access token was granted. (Solved by the scoped-access specification.)
</li>
<li>The AM therefore needs to associate each requester access token with a resource set and action set. (Solved by the core protocol specification. Currently it defines a run-time method for the host to ask the AM to confirm this match. An alternative solution that meets the requirement would be for the access token to securely contain this information.)
</li>
<li>The requester needs to know what actions are possible on the resource it is trying to access. (This requirement is considered out of scope for UMA; it is anticipated that host API documentation will pick up the slack.)
</li>
</ul>
<a name="anchor5"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.2"></a><h3>2.
Prerequisites</h3>
<p>In order for a host to be able to register resource information with an AM it needs to fulfill the following prerequisites:</p>
<ul class="text">
<li>The host has obtained a host access token from the AM as explained in UMA core protocol step 1.
</li>
<li>The host has obtained the URI of the registration API endpoint as part of the AM's metadata as described in UMA protocol step 1.
</li>
</ul>
<a name="anchor6"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.3"></a><h3>3.
Example</h3>
<p>The following example illustrates the intent and usage of the resource registration protocol.
</p>
<p>This example contains some steps that are exclusively in the realm of user experience rather than web protocol, to achieve realistic illustration; these steps are labeled "User experience only". Some other steps are exclusively internal to the operation of the entity being discussed; these are labeled "Internal only".
</p>
<p>An authorizing user, Alice Adams, has just uploaded a photo of her new puppy to a host, Photoz.example.com, and wants to ensure that this specific photo is not publicly accessible.
</p>
<p>Alice has already introduced this host to her AM, CopMonkey.example.com, and thus Photoz has already obtained an OAuth client ID and an UMA host access token from CopMonkey. However, Alice has not previously instructed Photoz to use CopMonkey to protect any other photos of hers.
</p>
<p>Alice has previously visited CopMonkey to map a default "do not share with anyone" authorization constraint to any resource sets registered by Photoz, until such time as she maps some other less-draconian constraints to those resources. (User experience only. This may have been done at the time Alice introduced the host to the AM, and/or it could have been a global or host-specific preference setting. A different constraint or no constraint at all might be associated with newly protected resources.) Other kinds of constraints she may eventually map to particular photos or albums might be "Share only with husband@email.example.net" or "Share only with people in my 'family' group".
</p>
<p>Photoz itself has a publicly documented API that offers two dozen different methods that apply to single photos, such as "addTags" and "getSizes", but rolls them up into two photo-related actions: "viewing" (consisting of varous read-only operations) and "all" (consisting of various reading, editing, and printing operations). It defines two Web-accessible JSON-encoded documents called action descriptions that represent these actions, which it is able to reuse for all of its users (not just Alice). The "name" parameter values are intended to be seen by Alice when she maps authorization constraints to specific resource sets and actions while visiting CopMonkey, such that Alice would see the strings "View Photo and Related Info" and "All Actions", likely accompanied by the referenced icons, in the CopMonkey interface. (Other users of Photoz might similarly see the same labels at CopMonkey or whatever other AM they use.)
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"action":
}</pre></div><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"action":
}</pre></div>
<p>While visiting Photoz, Alice selects a link or button that instructs the site to "Protect" or "Share" this single photo (user experience only; Photoz could have made this a default or preference setting).
</p>
<p>As a result, Photoz defines for itself a resource set that represents this photo (internal only; Photoz is the only application that knows how to map a particular photo to a particular resource set). Photoz also prepares the following resource set description, which is specific to Alice and her photo. The "name" parameter value is intended to be seen by Alice in mapping authorization constraints to specific resource sets and actions when she visits CopMonkey, such that Alice would see the string "Steve the puppy!", likely accompanied by the referenced icon, in the CopMonkey interface. The possible actions on this resource set are indicated with URI references to the action descriptions, as defined just above.
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"resource_set":
}</pre></div>
<p>Photoz uses the "create resource set description" method of CopMonkey's standard UMA-based resource registration API, presenting its Alice-specific host access token there, to register and assign an identifier to the resource set description. The resource set identifier path component of the URL matches the "_id" parameter value in the description.
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>PUT /host/photoz.example.com/resource/112210f47de98100
Content-Type: application/json
...
{
"resource_set":
}</pre></div>
<p>Once this description has been successfully registered, Photoz is responsible for responding to requesters' attempts to access this photo in the manner described in <a class='info' href='#draft-uma-core'>UMA<span> (</span><span class='info'>Scholz, C., “UMA 1.0 Core Protocol,” December 2010.</span><span>)</span></a> [draft‑uma‑core], achieving protection of the resource by "outsourcing" this task to CopMonkey.
</p>
<p>At the time Alice indicates she would like this photo protected, Photoz can choose to redirect Alice to CopMonkey for further authorization constraint mapping, access auditing, and other AM-related tasks (user experience only).
</p>
<p>Over time, as Alice uploads other photos and creates and organizes photo albums, and as Photoz makes new action functionality available, Photoz can use additional methods of the resource registration API to ensure that CopMonkey's understanding of Alice's protected resources matches its own.
</p>
<a name="action-desc"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.4"></a><h3>4.
Action Description</h3>
<p>The host defines an action that is available for use with resources it manages in an action description encoded in <a class='info' href='#RFC4627'>JSON<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> [RFC4627] form and made publicly accessible through a URI reference (it MAY include a fragment identifier). The actions available for use at any one host MUST have unique URI references so that the host's action descriptions are distinguishable by URI reference. Action descriptions MAY reside anywhere; the host is not required to self-host action descriptions and may wish to point to standardized action descriptions residing elsewhere.
</p>
<p>An action description is an object with the name "action" and with the following parameters:</p>
<blockquote class="text"><dl>
<dt>_id</dt>
<dd>REQUIRED. A string that uniquely identifies the action across all actions available at this host.
</dd>
<dt>name</dt>
<dd>REQUIRED. A human-readable string describing the action. The AM SHOULD use the name in its user interface to assist the user in mapping authorization constraints to resource sets with this permissible action.
</dd>
<dt>icon_uri</dt>
<dd>OPTIONAL. A URI for a graphic icon representing the action. If this is provided, the AM SHOULD use the referenced icon in its user interface to assist the user in mapping authorization constraints to resource sets with this permissible action.
</dd>
</dl></blockquote>
<p>For example, this description characterizes an action that involves reading or viewing resources (vs. creating them or edit them in some fashion):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"action":
}</pre></div>
<p>Action descriptions MAY contain extension parameters that are not defined in this specification. The names of extension parameters MUST begin with "x-" or "X-".
</p>
<a name="resource-set-desc"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.5"></a><h3>5.
Resource Set Description</h3>
<p>The host defines a resource set that needs UMA protection in a resource set description encoded in <a class='info' href='#RFC4627'>JSON<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> [RFC4627] form. The host registers the description and manages its lifecycle at the AM through the resource registration API.
</p>
<p>A resource set description is an object with the name "resource_set" and with the following parameters:</p>
<blockquote class="text"><dl>
<dt>_id</dt>
<dd>REQUIRED. A string that uniquely identifies the resource set across all resource sets belonging to this user. It is RECOMMENDED that this identifier be unique across all users' resource sets at this host. This identifier MUST match the resource set identifier path component of the URI used to manage this description in the resource registration API. (Typically this parameter's value is populated automatically in order to ensure the required uniqueness and matching.)
</dd>
<dt>name</dt>
<dd>REQUIRED. A human-readable string describing a set of one or more resources. The AM SHOULD use the name in its user interface to assist the user in mapping authorization constraints to this resource set.
</dd>
<dt>icon_uri</dt>
<dd>OPTIONAL. A URI for a graphic icon representing the resource set. If provided, the AM SHOULD use the referenced icon in its user interface to assist the user in mapping authorization constraints to this resource set.
</dd>
<dt>actions</dt>
<dd>REQUIRED. An array referencing one or more identifiers of actions that are permissible on this resource set. Each action identifier MUST correspond to an action registered by this host for this user at this AM.
</dd>
</dl></blockquote>
<p>For example, this description characterizes a resource set (a photo album) that can potentially be only viewed, or alternatively to which full access can be granted; the URIs point to action descriptions, as dictated in <a class='info' href='#action-desc'>Section 4<span> (</span><span class='info'>Action Description</span><span>)</span></a>:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"resource_set":
}</pre></div>
<p>Resource set descriptions descriptions MAY contain extension parameters that are not defined in this specification. The names of extension parameters MUST begin with "x-" or "X-".
</p>
<p>When a host creates or updates a resource set description (see <a class='info' href='#reg-api'>Section 6<span> (</span><span class='info'>Resource Registration API</span><span>)</span></a>), the AM MUST attempt to retrieve the referenced action descriptions. It MAY cache such descriptions as long as indicated in the HTTP header for the action description resource unless the resource set description is subsequently updated within the validity period. At the beginning of an authorizing user's login session at the AM, the AM MUST attempt to re-retrieve action descriptions applying to that user whose cached versions have expired.
</p>
<a name="reg-api"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6"></a><h3>6.
Resource Registration API</h3>
<p>The host uses a RESTful API at the AM's host_registration_uri to create, read, update, and delete resource set descriptions, along with listing groups of such descriptions. The host MUST use its valid host access token obtained previously in UMA protocol step 1 to gain access to the API.
</p>
<p>Individual resource set descriptions are managed at URIs with this structure: "
/host/
/resource_set/
"
</p>
<p>The components of these URIs are defined as follows:</p>
<blockquote class="text"><dl>
<dt>
</dt>
<dd>The AM's host_registration_uri as advertised in its metadata. This endpoint, its security requirements, and its requirements around advertisement in metadata are defined in UMA protocol step 1 (see <a class='info' href='#draft-uma-core'>UMA<span> (</span><span class='info'>Scholz, C., “UMA 1.0 Core Protocol,” December 2010.</span><span>)</span></a> [draft‑uma‑core]).
</dd>
<dt>
</dt>
<dd>A registration area at the AM that is specific to this host. The host MUST use the OAuth client identifier it was assigned by this AM as its host identifier. If the host identifier does not match the host access token used at the host registration endpoint, the AM MUST report an HTTP 403 Forbidden error (see example below) and fail to act on the request.
</dd>
<dt>
</dt>
<dd>An identifier for a resource set description. The identifier MUST match the "_id" parameter value in the description itself. Without a specific resource identifier path component, the URI applies to the set of resource set descriptions already registered. The identifier has meaning only to the host, except insofar as the AM is able to map this resource set description to a particular user by virtue of the particular host access token used to access the resource registration API. The host MAY use any identifier scheme to represent each resource set uniquely for each user. However, for privacy, it is RECOMMENDED that the host assign an identifier that is obscured with respect to any human-readable resource set label used at this host.
</dd>
</dl></blockquote>
<p>Following is a summary of supported registration API operations. Each is defined in its own section below. All other methods are unsupported.</p>
<ul class="text">
<li>Create resource set description: PUT /host/
/resource_set/
</li>
<li>Read resource set description: GET /host/
/resource_set/
</li>
<li>Update resource set description: PUT /host/
/resource_set/
</li>
<li>Delete resource set description: DELETE /host/
/resource_set/
</li>
<li>List resource set descriptions: GET /host/
/resource_set/
</li>
</ul>
<p>The AM MUST respond to host requests using HTTP methods other than those listed with an HTTP 403 Forbidden error and MUST fail to act on the request.
</p>
<p>HTTP response (unsupported method or host ID not matching the presented host access token):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 403 Forbidden
...
(Body provides user-readable explanation of the error.)</pre></div>
<a name="create-resource-set"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.1"></a><h3>6.1.
Create Resource Set Description</h3>
<p>Adds a new resource set description using the PUT method. The host assigns a unique identifier to the action. The host is free to use its own methods of identifying and describing resource sets; the AM MUST treat them as opaque for the purpose of authorizing access, other than associating them with the authorizing user represented by the host access token used to access the API. On successfully registering a resource set, the host MUST use UMA mechanisms to limit access to any resources corresponding to this resource set, as defined in <a class='info' href='#draft-uma-core'>UMA<span> (</span><span class='info'>Scholz, C., “UMA 1.0 Core Protocol,” December 2010.</span><span>)</span></a> [draft‑uma‑core].
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>PUT /host/
/user/
/resource/
Content-Type: application/json
...
(Body contains JSON representation of resource set description to be created.)</pre></div>
<p>HTTP response (success):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 201 Created
Content-Type: application/json
Location: (URL of the created resource, same as that which was PUT.)
...</pre></div>
<a name="read-resource-set"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.2"></a><h3>6.2.
Read Resource Set Description</h3>
<p>Reads a previously registered resource set description using the GET method.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>GET /host/
/user/
/resource/
HTTP/1.1
...</pre></div>
<p>HTTP response (success):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 200 OK
Content-Type: application/json
ETag: (entity tag of the resource artifact)
...
(Body contains JSON representation of the resource set description.)</pre></div>
<p>HTTP response (not found):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 404 Not Found
...
(Body provides user-readable explanation of the error.)</pre></div>
<a name="update-resource-set"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.3"></a><h3>6.3.
Update Resource Set Description</h3>
<p>Updates a previously registered resource set description using the PUT method.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>PUT /host/
/user/
/resource/
Content-Type: application/json
If-Match: (entity tag of the resource if operation is to be idempotent)
...
(Body contains JSON representation of resource set description to be updated.)</pre></div>
<p>HTTP response (success):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 204 No Content
...</pre></div>
<p>HTTP response (entity tag does not match):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 412 Precondition failed
...</pre></div>
<a name="delete-resource-set"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.4"></a><h3>6.4.
Delete Resource Set Description</h3>
<p>Deletes a previously registered resource set description using the DELETE method.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>DELETE /host/
/user/
/resource/
If-Match: (entity tag of the resource if operation to be idempotent)
...</pre></div>
<p>HTTP response (success):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 204 No content
...</pre></div>
<p>HTTP response (not found):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 404 Not Found
...
(Body provides user-readable explanation of the error.)</pre></div>
<p>HTTP response (entity tag does not match):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 412 Precondition failed
...</pre></div>
<a name="list-resource-sets"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.6.5"></a><h3>6.5.
List Resource Set Descriptions</h3>
<p>Lists all previously registered resource set identifiers for this user using the GET method. The list is in the form of a JSON array of
values.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>GET /host/
/resource_set/
...</pre></div>
<p>HTTP response:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 200 OK
Content-Type: application/json
...
(Body contains JSON array of
values.)</pre></div>
<a name="anchor7"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.7"></a><h3>7.
Security Considerations</h3>
<p>This specification relies mainly on OAuth security mechanisms for protecting the host registration endpoint at the AM so that only a properly authorized host can access it on behalf of the intended user. For example, the host needs to use a valid host access token issued through a user authorization process at the endpoint, and the interaction should take place over TLS. It is expected that the host will protect its client secret (if it was issued one) and will protect its host access token, particularly if used in "bearer token" fashion.
</p>
<p>In addition, this specification dictates a binding between the host access token and the host-specific registration area on the AM to prevent a host from interacting with a registration area not its own.
</p>
<a name="anchor8"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.8"></a><h3>8.
Privacy Considerations</h3>
<p>The AM comes to be in possession of information (such as names and icons) that may reveal information about the user, which the AM's trust relationship with the host is assumed to accommodate. However, the requester is a less-trusted party (in fact, entirely untrustworthy until it acquires a requester access token in UMA protocol step 2). This specification recommends obscuring resource set identifiers in order to avoid leaking personally identifiable information to requesters through the "scope" mechanism.
</p>
<a name="anchor9"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.9"></a><h3>9.
TODOs</h3>
<p></p>
<ul class="text">
<li>Isn't it the case (see <a class='info' href='#resource-set-desc'>Section 5<span> (</span><span class='info'>Resource Set Description</span><span>)</span></a>) that resource set IDs now MUST be unique across the whole host at this AM, such that we should REQUIRE this and not just that it be unique across this user at this host? (It's still a SHOULD that the ID be unique across this host for any AM.)
</li>
<li>In <a class='info' href='#action-desc'>Section 4<span> (</span><span class='info'>Action Description</span><span>)</span></a>, should the action description have an "_id" parameter or a normal "id" parameter so that the URI path component that must match the ID can be human-readable ("view") vs. machine-assigned gobbledygook?
</li>
<li>In <a class='info' href='#action-desc'>Section 4<span> (</span><span class='info'>Action Description</span><span>)</span></a>, are the new caching/refreshing rules for action description retrieval okay?
</li>
<li>Should the
component instead be a pseudonym assigned by the AM (during or after OAuth client ID provisioning)? Check this throughout the scoped-access spec progress.
</li>
<li>In <a class='info' href='#create-resource-set'>Section 6.1<span> (</span><span class='info'>Create Resource Set Description</span><span>)</span></a> and <a class='info' href='#update-resource-set'>Section 6.3<span> (</span><span class='info'>Update Resource Set Description</span><span>)</span></a>, specify error to produce if referenced actions can't be retrieved or are incorrectly formatted.
</li>
<li>Give example of what a list of resource set IDs looks like in <a class='info' href='#list-resource-sets'>Section 6.5<span> (</span><span class='info'>List Resource Set Descriptions</span><span>)</span></a>.
</li>
<li>Consider the question of i18n of resource set and action "name" strings in addition to the extension-parameter mechanism.
</li>
</ul>
<a name="anchor10"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.10"></a><h3>10.
Acknowledgments</h3>
<p></p>
<ul class="text">
<li>[TBS]
</li>
</ul>
<a name="anchor11"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<a name="rfc.section.11"></a><h3>11.
Document History</h3>
<p>Changes in 6 Jan 2011 version:</p>
<ul class="text">
<li>Removed action-related API methods.
</li>
<li>Revised Example section to take into account the new "passive" way of declaring actions.
</li>
<li>Added "_id" parameters.
</li>
<li>Changed "resource" to "resource set", "
, or "resource_set" as appropriate throughout.
</li>
<li>Removed user-specific path component of the registration URI.
</li>
<li>Allowed "X-" in addition to "x-" for extension parameters.
</li>
<li>Broke out the two descriptions into their own sections.
</li>
<li>A bit of editorial cleanup all over.
</li>
</ul>
<p>Changes in 30 Dec 2010 version:</p>
<ul class="text">
<li>Unsupported HTTP methods in registration API return 403
</li>
<li>Folded error section in to API section and changed from UMA-level error to 403
</li>
<li>Changed name of "resource" parameter to "resource_set"
</li>
<li>Added TODO issue about referencing standard sets of actions and reconsidering in-band IDs, and cleaned up the TODO list generally
</li>
<li>Fleshed out citations and requirements analysis
</li>
<li>Added huge worked-example section at the beginning (which contains issues not yet captured in the TODO section)
</li>
</ul>
<a name="rfc.references1"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<h3>12. Normative References</h3>
<table width="99%" border="0">
<tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
<td class="author-text">Bradner, “<a href="http://www.ietf.org/rfc/rfc2119.txt">Key words for use in RFCs to Indicate Requirement Levels</a>,” March 1997.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC4627">[RFC4627]</a></td>
<td class="author-text">Crockford, D., “<a href="http://tools.ietf.org/html/rfc4627">The application/json Media Type for JavaScript Object Notation (JSON)</a>,” July 2006.</td></tr>
<tr><td class="author-text" valign="top"><a name="draft-uma-core">[draft-uma-core]</a></td>
<td class="author-text">Scholz, C., “<a href="http://mrtopf.clprojects.net/uma/draft-uma-core.html">UMA 1.0 Core Protocol</a>,” December 2010.</td></tr>
</table>
<a name="rfc.authors"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
<h3>Authors' Addresses</h3>
<table width="99%" border="0" cellpadding="0" cellspacing="0">
<tr><td class="author-text"> </td>
<td class="author-text">Christian Scholz (editor)</td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">COM.lounge GmbH</td></tr>
<tr><td class="author" align="right">Email: </td>
<td class="author-text"><a href="mailto:cs@comlounge.net">cs@comlounge.net</a></td></tr>
<tr><td class="author" align="right">URI: </td>
<td class="author-text"><a href="http://comlounge.net">http://comlounge.net</a></td></tr>
<tr cellpadding="3"><td> </td><td> </td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">Maciej Machulak</td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">Newcastle University</td></tr>
<tr><td class="author" align="right">Email: </td>
<td class="author-text"><a href="mailto:m.p.machulak@ncl.ac.uk">m.p.machulak@ncl.ac.uk</a></td></tr>
<tr><td class="author" align="right">URI: </td>
<td class="author-text"><a href="http://ncl.ac.uk/">http://ncl.ac.uk/</a></td></tr>
<tr cellpadding="3"><td> </td><td> </td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">Eve Maler</td></tr>
<tr><td class="author" align="right">Email: </td>
<td class="author-text"><a href="mailto:eve@xmlgrrl.com">eve@xmlgrrl.com</a></td></tr>
<tr cellpadding="3"><td> </td><td> </td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">Paul Bryan</td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">P. Bryan Consulting</td></tr>
<tr><td class="author" align="right">Email: </td>
<td class="author-text"><a href="mailto:email@pbryan.net">email@pbryan.net</a></td></tr>
</table>
</body></html>