| Wiki Markup |
|---|
{note}The following is an experimental rendering of the generated HTML that also resides at [mrtopf.clprojects.net|http://mrtopf.clprojects.net/uma/]. It may not look exactly right. The clprojects version has proper fidelity but may be slightly out of date compared to this one.{note}
{html}
<!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 {
font-family: verdana, charcoal, helvetica, arial, sans-serif;
font-size: small; color: #000; background-color: #FFF;
margin: 2em;
}
h1, h2, h3, h4, h5, h6 {
font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
font-weight: bold; font-style: normal;
}
h1 { color: #900; background-color: transparent; text-align: right; }
h3 { color: #333; background-color: transparent; }
td.RFCbug {
font-size: x-small; text-decoration: none;
width: 30px; height: 30px; padding-top: 2px;
text-align: justify; vertical-align: middle;
background-color: #000;
}
td.RFCbug span.RFC {
font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
font-weight: bold; color: #666;
}
td.RFCbug span.hotText {
font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
font-weight: normal; text-align: center; color: #FFF;
}
table.TOCbug { width: 30px; height: 15px; }
td.TOCbug {
text-align: center; width: 30px; height: 15px;
color: #FFF; background-color: #900;
}
td.TOCbug a {
font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
font-weight: bold; font-size: x-small; text-decoration: none;
color: #FFF; background-color: transparent;
}
td.header {
font-family: arial, helvetica, sans-serif; font-size: x-small;
vertical-align: top; width: 33%;
color: #FFF; background-color: #666;
}
td.author { font-weight: bold; font-size: x-small; margin-left: 4em; }
td.author-text { font-size: x-small; }
/* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
a.info {
/* This is the key. */
position: relative;
z-index: 24;
text-decoration: none;
}
a.info:hover {
z-index: 25;
color: #FFF; background-color: #900;
}
a.info span { display: none; }
a.info:hover span.info {
/* The span will display just on :hover state. */
display: block;
position: absolute;
font-size: smaller;
top: 2em; left: -5em; width: 15em;
padding: 2px; border: 1px solid #333;
color: #900; background-color: #EEE;
text-align: left;
}
a { font-weight: bold; }
a:link { color: #900; background-color: transparent; }
a:visited { color: #633; background-color: transparent; }
a:active { color: #633; background-color: transparent; }
p { margin-left: 2em; margin-right: 2em; }
p.copyright { font-size: x-small; }
p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }
ol.text { margin-left: 2em; margin-right: 2em; }
ul.text { margin-left: 2em; margin-right: 2em; }
li { margin-left: 3em; }
/* RFC-2629 <spanx>s and <artwork>s. */
em { font-style: italic; }
strong { font-weight: bold; }
dfn { font-weight: bold; font-style: normal; }
cite { font-weight: normal; font-style: normal; }
tt { color: #036; }
tt, pre, pre dfn, pre em, pre cite, pre span {
font-family: "Courier New", Courier, monospace; font-size: small;
}
pre {
text-align: left; padding: 4px;
color: #000; background-color: #CCC;
}
pre dfn { color: #900; }
pre em { color: #66F; background-color: #FFC; font-weight: normal; }
pre .key { color: #33C; font-weight: bold; }
pre .id { color: #900; }
pre .str { color: #000; background-color: #CFF; }
pre .val { color: #066; }
pre .rep { color: #909; }
pre .oth { color: #000; background-color: #FCF; }
pre .err { background-color: #FCC; }
/* RFC-2629 <texttable>s. */
table.all, table.full, table.headers, table.none {
font-size: small; text-align: center; border-width: 2px;
vertical-align: top; border-collapse: collapse;
}
table.all, table.full { border-style: solid; border-color: black; }
table.headers, table.none { border-style: none; }
th {
font-weight: bold; border-color: black;
border-width: 2px 2px 3px 2px;
}
table.all th, table.full th { border-style: solid; }
table.headers th { border-style: none none solid none; }
table.none th { border-style: none; }
table.all td {
border-style: solid; border-color: #333;
border-width: 1px 2px;
}
table.full td, table.headers td, table.none td { border-style: none; }
hr { height: 1px; }
hr.insert {
width: 80%; border-style: none; border-width: 0;
color: #CCC; background-color: #CCC;
}
--></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 311, 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">December>January 307, 2010<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 311, 2011.</p>
<h3>Copyright Notice</h3>
<p>
Copyright (c) 20102011 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="#anchor7#action-desc">4.</a>
Action and Description<br />
<a href="#resource-set-desc">5.</a>
Resource Set Descriptions<brDescription<br />
<a href="#reg-api">5>6.</a>
Resource Registration API<br />
<a href="#anchor8">5#create-resource-set">6.1.</a>
Create Resource ActionSet Description<br />
<a href="#anchor9">5#read-resource-set">6.2.</a>
Read ActionResource Set Description<br />
<a href="#anchor10">5#update-resource-set">6.3.</a>
Update Resource ActionSet Description<br />
<a href="#anchor11">5#delete-resource-set">6.4.</a>
Delete Resource ActionSet Description<br />
<a href="#anchor12">5#list-resource-sets">6.5.</a>
List ActionResource Set Descriptions<br />
<a href="#anchor13#anchor7">5>7.6.</a>
CreateSecurity ResourceConsiderations<br Set Description<br />
<a href="#anchor14#anchor8">5>8.7.</a>
ReadPrivacy ResourceConsiderations<br Set Description<br />
<a href="#anchor15#anchor9">5>9.8.</a>
Update Resource Set Description<br TODOs<br />
<a href="#anchor16#anchor10">5>10.9.</a>
Delete Resource Set Description<br Acknowledgments<br />
<a href="#anchor17#anchor11">5>11.10.</a>
List Resource Set Descriptions<brDocument History<br />
<a href="#anchor18#rfc.references1">6>12.</a>
SecurityNormative Considerations<brReferences<br />
<a href="#anchor19">7.#rfc.authors">§</a>
PrivacyAuthors' Considerations<brAddresses<br />
<a href</p>
<br clear="#anchor20">8.</a>
TODOs<brall" />
<a hrefname="#anchor21">9.</a>
Acknowledgments<br />
<a href="#anchor22">10.</a>
Document History<br />
<a href="#rfc.references1">11.</a>
Normative References<br />
<a href="#rfc.authors">§</a>
Authors' Addresses<br />
</p>
<br clear="all" />
<a name="anchor1"><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 registersneeds two kinds of information with the AM: to register information about resources to be protected andso informationthat aboutthe potentialAM actionscan thatapply can be performed on themauthorization 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 eachsets set of one or morethese resources. Such a set might include a status update API endpoint (applying to the user's entire update stream), or an individual status update, a single photo,or a photo album, or even all photos with a particular user-assigned tag.
</p>
<p>The host also determines (often unilaterally based on its API features, but possibly with user input), 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, and assigns an action identifier to each. Such actions might involve "viewing", "adding", "printing", or whatever other actions the application supports for that resource set. </p>Typically <p>Onceeach theaction hostcovers hasa registeredbroad theselist identifiersof andmethods other 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. This mapping conceptually constitutes a "policy", and its resource-set-and-actions component is involvedto take part in steps 2 and 3the process of thelimiting UMA(scoping) protocolaccess asto an analogue of the OAuth concept of "scope"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 at the AM. (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 shouldand notrequesting beparty, exposedprior to in-the-clear versions of identifiers for resources in case they compromisereceiving 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 compromisinglyembarrassingly 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 specificationlspecification.)
</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>The host therefore
<li>Therefore, when the requester attempts access at the host and fails, the host needs to tellconvey enough theinformation requesterto the relevantAM resource(whether setthrough --the andrequester nodirectly more,or forby privacyother reasonsmeans) --for when the requesterlatter attemptsto accessdo atthis thejob. hostFor andprivacy failsreasons, so thatif the host asks the requester canto convey it to the AM 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 at access 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>
<li>The</ul>
host
has already defined, for its own use, sets of resources and possible actions applicable to this user, along with associated identifiers for them and details about them that will help the user in correctly setting policy over them at the AM.
</li>
</ul>
<a name="anchor6"></a><br /><hr /<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>A<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-Draconiandraconian constraints to those resources. (User experience only;. thisThis 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.) OtherA kindsdifferent ofconstraint constraintsor sheno mayconstraint eventuallyat mapall tomight particularbe photosassociated orwith albums newly protected resources.) Other kinds of constraints she may eventually map to particular photos or albums might be "Share only with husband@email.comexample.net" or "Share only with people in my 'family' group".
</p>
<p>Photoz itself has a anpublicly documented API that allowsoffers fortwo photodozen viewingdifferent andmethods printing.that Itapply definesto forsingle itselfphotos, andsuch foras applications"addTags" using that APIand "getSizes", actionsbut applicablerolls tothem photosup thatinto aretwo accessed by authorized third parties (internal only; this is comparable to determining and documenting OAuth scopes).
</p>
<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). 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 URL to a particular resource set).
</p>
<p>Photoz prepares the following two action descriptions, which are probably standard for this site across all of its users. The "name" parameter values are intended to be used by Alice (and similarly by other users of the same site) in mapping authorization constraints to specific resource sets and actions when she visits CopMonkey, such that Alice would see the strings "View" and "Print", likely accompanied by the referenced icons, when she visits there.
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"action":
{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":
{
"_id": "view"
"name": "View Photo and Related Info",
"icon_uri": "http://www.example.com/icons/reading-glasses"
}
}</pre></div><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"action":
{
"_id": "all"
"name": "PrintAll Actions",
"icon_uri": "http://www.example.com/icons/printergalaxy"
}
}</pre></div>
<p>Photoz<p>While usesvisiting thePhotoz, "createAlice actionselects description"a methodlink ofor CopMonkey'sbutton resourcethat registrationinstructs API,the presentingsite its Alice-specific host access token there, to register and assign identifiers to these action descriptions. The "com.photoz" path component reflects Photz's unique host identifier (its OAuth client ID). Since this is Photoz's first-ever use of this API, the "ABCD001" path component has the effect of assigning a unique identifier to an Alice-specific area underneath Photoz's host registration area. The "view" and "print" path components, respectively, assign unique identifiers to these action descriptions that can then be referenced in resource set descriptions. (Photoz likely could have registered action descriptions at any time upon being introduced to CopMonkey by Alice.) @@should we prepare for actions to be reusable across users by allowing/requiring them to be registered "above" the user-specific level? @@show token being used etc. in the method?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>PUT /host/com.photoz/user/ABCD001/action/view
Content-Type: application/json
...
{><pre>{
"resource_set":
{
"action": {"_id": "112210f47de98100"
"name": "ViewSteve the puppy!",
"icon_uri": "http://www.example.com/icons/reading-glassesflower",
} }</pre></div><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>PUT /host/com.photoz/user/ABCD001/action/print
Content-Type: application/json
...
{ "actions":
"action": {["http://photoz.example.com/dev/actions/view",
"name": "Print", "icon_uri": "http://wwwphotoz.example.com/iconsdev/actions/printerall"]
}
}</pre></div>
<p>When<p>Photoz Aliceuses indicatesthe she"create wantsresource toset protectdescription" hermethod puppy photo, Photoz prepares the followingof CopMonkey's standard UMA-based resource setregistration descriptionAPI, whichpresenting isits Alice-specific tohost Aliceaccess and her photo. The "name" parameter value is intendedtoken there, to beregister usedand byassign Alice in mapping authorization constraintsan identifier to specificthe resource setsset anddescription. actionsThe whenresource sheset visitsidentifier CopMonkey,path suchcomponent thatof Alicethe wouldURL seematches the string "Steve the puppy!", likely accompanied by"_id" parameter value in the referenced icon, when she visits there. The possible actions on this resource set are indicated with references to the identifiers of the action descriptions, as defined just above.
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{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":
{
"resource_setid": "112210f47de98100"
{ "name": "Steve the puppy!",
"icon_uri": "http://www.example.com/icons/flower",
"actions":
["view", "print"] } }</pre></div> <p>Photoz uses the "create resource set description" method of CopMonkey's resource registration API, presenting its Alice-specific host access token there, to register and assign an identifier to the resource set description. The "00001" path component assigns an identifier that does not reveal any of Alice's personal information to an outsider but allows Photoz to know that it is the "Steve the puppy!" photo being referred to. @@show token being used etc. in the method?
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>PUT /host/com.photoz/user/ABCD001/resource/00001
Content-Type: application/json
...
{
"resource_set":
{
"name": "Steve the puppy!",
"icon_uri": "http://www.example.com/icons/flower",
"actions": ["view", "print"]
}
}</pre></div>
<p>Once these descriptions have 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>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="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.4"></a><h3>4.
Action and Resource Set Descriptions</h3>
<p>The host registers resource information with an AM 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 information is of two types: action descriptions and resource set descriptions. The act of registering a description creates a unique identifier for it; see <a class='info' href='#reg-api'>Section 5<span> (</span><span class='info'>Resource Registration API</span><span>)</span></a> for more information.
</p>
<p>An action description is an object with the name "action" and with the following parameters:</p>
<blockquote class="text"><dl>
<dt>name</dt>
<dd>REQUIRED. A human-readable string describing the action. The AM SHOULD use the name ["http://photoz.example.com/dev/actions/view",
"http://photoz.example.com/dev/actions/all"]
}
}</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>
<dt>icon_uri</dt>
<dd>OPTIONAL. A URI for a graphic icon representing the action. If 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 </dl></blockquote>
<p>For example, this description characterizes an action that involves reading or viewing resources (vs., say, creating them or changingedit them in some fashion):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"action":
{
"_id": "view"
"name": "ReadingRead-only",
"icon_uri": "http://www.example.com/icons/reading-glasses"
}
}</pre></div>
<p>A<p>Action descriptions resourceMAY setcontain descriptionextension isparameters anthat objectare withnot thedefined name "resource_set" and with the following parameters:</p>
<blockquote class="text"><dl>
<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 and all of its contined photos) that can potentially be read, updated, or printed by those seeking access to it; the actions listed are citations to identifiers created during earlier registration of these action descriptions:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"resource_set":
{
"name": "Photo album",
"icon_uri": "http://www.example.com/icons/flower",
"actions": ["read", "update", "print"]
}
}</pre></div>
<p>Both action descriptions and resource set descriptions MAY contain extension parameters that are not defined in this specification. The names of extension parameters MUST begin with "x-".
</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.5"></a><h3>5.
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 and action 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: "{reguri}/host/{hostid}/user/{userid}/resource/{resourceid}"
</p>
<p>Individual action descriptions are managed at URIs with this structure: "{reguri}/host/{hostid}/user/{userid}/action/{actionid}"
</p>
<p>The components of these URIs are defined as follows:</p>
<blockquote class="text"><dl>
<dt>{reguri}</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>{hostid}</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>{userid}</dt>
<dd>The portion of the host's registration area at this AM that is specific to this user, assigned during registration of the first description for this user. The host MAY use any identifier scheme to represent each of its users uniquely, but for privacy, it is RECOMMENDED that the host assign an identifier that is both specific to this AM and obscured with respect to any identifier by which the user may be publicly known at this host. The host MAY change a user's identifier at any time by deleting registered resources under one identifier and re-registering them under another.
</dd>
<dt>{actionid}</dt>
<dd>An identifier for an action description, assigned during initial registration of this description. Without a specific action identifier path component, the URI applies to the set of action descriptions already registered. The identifier has meaning only to the host.
</dd>
<dt>{resourceid}</dt>
<dd>An identifier for a resource set description, assigned during initial registration of this description. 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. The host MAY use any identifier scheme to represent each resource set uniquely for each user, including using a URL-formatted string that corresponds directly to a URL that can be used by authorized parties to retrieve the resource. 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>The host MUST register at least action description and one resource set description (with a valid referenced {actionid}).
</p>
<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 action description: PUT /host/{hostid}/user/{userid}/action/{actionid}
</li>
<li>Read action description: GET /host/{hostid}/user/{userid}/action/{actionid}
</li>
<li>Update action description: PUT /host/{hostid}/user/{userid}/action/{actionid}
</li>
<li>Delete action description: DELETE /host/{hostid}/user/{userid}/action/{actionid}
</li>
<li>List action descriptions: GET /host/{hostid}user/{userid}/action/
</li>
<li>Create resource set description: PUT /host/{hostid}/user/{userid}/resource/{resourceid}
</li>
<li>Read resource set description: GET /host/{hostid}/user/{userid}/resource/{resourceid}
</li>
<li>Update resource set description: PUT /host/{hostid}/user/{userid}/resource/{resourceid}
</li>
<li>Delete resource set description: DELETE /host/{hostid}/user/{userid}/resource/{resourceid}
</li>
<li>List resource set descriptions: GET /host/{hostid}user/{userid}/resource/
</li>
</ul>
<p>The AM MUST respond to host requests using HTTP methods other than those listed with an HTTP 403 Forbidden error and 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="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.5.1"></a><h3>5.1.
Create Action Description</h3>
<p>Adds a new action 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 actions; the AM MUST treat them as opaque for the purpose of authorizing access.
</p>
<p>HTTP requestin 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":
{
"name": "Photo album",
"icon_uri": "http://www.example.com/icons/flower",
"actions":
["http://photoz.example.com/dev/actions/view",
"http://photoz.example.com/dev/actions/all"]
}
}</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: "{reguri}/host/{hostid}/resource_set/{resourcesetid}"
</p>
<p>The components of these URIs are defined as follows:</p>
<blockquote class="text"><dl>
<dt>{reguri}</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>{hostid}</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>{resourcesetid}</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/{hostid}/resource_set/{resourcesetid}
</li>
<li>Read resource set description: GET /host/{hostid}/resource_set/{resourcesetid}
</li>
<li>Update resource set description: PUT /host/{hostid}/resource_set/{resourcesetid}
</li>
<li>Delete resource set description: DELETE /host/{hostid}/resource_set/{resourcesetid}
</li>
<li>List resource set descriptions: GET /host/{hostid}/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>PUT /host/{hostid}/user/{userid}/action/{actionid}
Content-Type: application/json><pre>HTTP/1.1 403 Forbidden
...
(Body containsprovides theuser-readable JSONexplanation representation of the action description to be createderror.)</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 action, same as that which was PUT.)
...</pre></div>
<a name="anchor9"></a><br /<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.56.21"></a><h3>5a><h3>6.21.
ReadCreate Resource ActionSet Description</h3>
<p>Reads<p>Adds a previouslynew registeredresource actionset description using the GETPUT method. </p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>GET /host/{hostid}/user/{userid}/action/{actionid} 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 action artifact)
...
(Body contains JSON representation of action 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="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.5.3"></a><h3>5.3.
Update Action Description</h3>
<p>Updates a previously registered action description using the PUT method.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; 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/{hostid}/user/{userid}/actionresource/{actionidresourceid}
Content-Type: application/json
If-Match: (entity tag of the action if operation is to be
idempotent)
...
(Body contains JSON representation of actionresource set description to be updatedcreated.)</pre></div>
<p>HTTP response (success):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>PUT /host/{hostid}/user/{userid}/action/{actionid}><pre>HTTP/1.1 201 Created
Content-Type: application/json
If-MatchLocation: (entity tagURL of the created actionresource, ifsame operationas isthat towhich bewas idempotentPUT.)
...</pre></div>
(Body contains JSON representation of action description to be updated.)</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="anchor11<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.56.42"></a><h3>5a><h3>6.42.
Read DeleteResource ActionSet Description</h3>
<p>Deletes<p>Reads a previously registered resource actionset description using the DELETEGET method.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>DELETE><pre>GET /host/{hostid}/user/{userid}/actionresource/{actionidresourceid} If-Match: (entity tag of the action if operation is to be idempotent)
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 204 No content
... 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>TP><pre>HTTP/1.1 404 Not Found
...
(The bodyBody 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="anchor12"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td <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.56.53"></a><h3>5a><h3>6.53.
ListUpdate Resource ActionSet Descriptions<Description</h3>
<p>Lists<p>Updates alla previously registered actionresource descriptionsset fordescription this user using the GETPUT method.
The</p>
list<p>HTTP is in the form of a JSON array of {actionid} values.
</p>
<p>HTTP request:
</p><div style='display: tablerequest:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>GET><pre>PUT /host/{hostid}/user/{userid}/action/
...resource/{resourceid}
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 200204 OKNo Content-Type:
application/json
...</pre></div>
<p>HTTP response (Bodyentity containstag JSONdoes array of {actionid} values.)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="anchor13delete-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.56.64"></a><h3>5a><h3>6.64.
CreateDelete Resource Set Description</h3>
<p>Adds<p>Deletes a previously newregistered resource set description using the PUTDELETE method.
The</p>
host<p>HTTP 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. 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]. @@Specify error to produce if referenced actions are incorrect?
</p>
<p>HTTP requestrequest:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>DELETE /host/{hostid}/user/{userid}/resource/{resourceid}
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>PUT /host/{hostid}/user/{userid}/resource/{resourceid}
Content-Type: application/json
...
(Body contains JSON representation of resource set description to be created.)><pre>HTTP/1.1 412 Precondition failed
...</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="anchor14"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"><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.7"></a><h3>5a><h3>6.75.
ReadList Resource Set Description<Descriptions</h3>
<p>Reads<p>Lists aall previously registered resource set description identifiers for this user using the GET method. </p>The <p>HTTPlist request:
<is in the form of a JSON array of {resourcesetid} values.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>GET /host/{hostid}/user/{userid}/resource/{resourceid} HTTP/1.1_set/
...</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 representationarray of the resource set description{resourcesetid} values.)</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="anchor15"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align=<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.5.87"></a><h3>5.8a><h3>7.
UpdateSecurity ResourceConsiderations</h3>
Set
Description</h3><p>This specification <p>Updatesrelies amainly previouslyon registeredOAuth resourcesecurity setmechanisms descriptionfor usingprotecting the PUThost method.registration @@Specifyendpoint errorat tothe produceAM ifso referenced actions are incorrect?
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>PUT /host/{hostid}/user/{userid}/resource/{resourceid}
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="anchor16that 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.5.98"></a><h3>5a><h3>8.9.
Delete Resource Set Description<Privacy Considerations</h3>
<p>Deletes<p>The AM acomes previouslyto registeredbe resourcein setpossession descriptionof usinginformation the(such DELETEas method.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>DELETE /host/{hostid}/user/{userid}/resource/{resourceid}
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="anchor17names 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.5.109"></a><h3>5a><h3>9.10.
List Resource Set Descriptions</h3>
<p>Lists all previously registered resource set descriptions for this user using the GET method. The list is in the form of a JSON array of {resourceid} values.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>GET /host/{hostid}/user/{userid}/resource/
...</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 {resourceid} values.)</pre></div>
<a name="anchor18"></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.
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="anchor19
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 {hostid} 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.710"></a><h3>7a><h3>10.
Privacy Considerations<Acknowledgments</h3>
<p>The<p></p>
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 user identifiers and resource set identifiers in order to avoid leaking personally identifiable information to requesters through the "scope" mechanism.
</p>
<a name="anchor20"></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.
TODOs</h3>
<p></p>
<ul class="text">
<li>Consider the question of i18n of resource set and action "name" strings in addition to the extension-parameter mechanism.
</li>
<li>Would implementers expect the "list all" methods to return just a list of IDs, or the whole set of structures? If so, do this through a query parameter? E.g., "?mode={short|verbose}"
</li>
<li>Should resource set descriptions list action identifiers, as currently specified, or full action description URLs?
</li>
<li>Should it be possible for a host to tell an AM that it uses some standard set of actions, indicating them by reference, rather than providing descriptions of its supported actions by value?
</li>
<li>Reconsider the issue of including the ID in-band (possibly with the magic "_id" parameter) as well as out-of-band - given that the host creates these resources at the AM, can this be spec'd properly?
</li>
</ul>
<a name="anchor21"></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.
Acknowledgments</h3>
<p></p>
<ul class="text">
<li>[TBS]
</li>
</ul>
<a name="anchor22"></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.
Document History</h3><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", "{resourcesetid}, 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>11<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>
{html} |
Page Comparison
Manage space
Manage content
Integrations