| Wiki Markup |
|---|
{note}The canonical version of rev 00 of this IETF Internet-Draft (UMA group rev 15) is [here|http://tools.ietf.org/html/draft-hardjono-oauth-umacore-00]. A better-looking HTML version of that rev is [here|http://xmlgrrl.com/publications/draft-hardjono-oauth-umacore-00.html]. The latest I-D can always be found [here|http://tools.ietf.org/html/draft-hardjono-oauth-umacore]. ThisBelow is rev 1718. We planwill toshortly getbegin intoto a routine of submittingsubmit these new UMAWG group revs as I-D updates shortly, in the IIW 13 timeframe.{note}
{html}
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "-include:url=http://wwwdocs.w3kantarainitiative.org/TR/html4/loose.dtd">
<html lang="en"><head><title>User-Managed Access (UMA) Core Protocol</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="User-Managed Access (UMA) Core Protocol">
<meta name="generator" content="xml2rfc v1.36 (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">T. Hardjono, Ed.</td></tr>
<tr><td class="header">Internet-Draft</td><td class="header">MIT</td></tr>
<tr><td class="header">Intended status: Standards Track</td><td class="header">C. Scholz</td></tr>
<tr><td class="header">Expires: January 3, 2012</td><td class="header">COM.lounge GmbH</td></tr>
<tr><td class="header"> </td><td class="header">P. Bryan</td></tr>
<tr><td class="header"> </td><td class="header">pbryan.net</td></tr>
<tr><td class="header"> </td><td class="header">M. Machulak</td></tr>
<tr><td class="header"> </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">XMLgrrl.com</td></tr>
<tr><td class="header"> </td><td class="header">L. Moren</td></tr>
<tr><td class="header"> </td><td class="header">Newcastle University</td></tr>
<tr><td class="header"> </td><td class="header">July 2, 2011</td></tr>
</table></td></tr></table>
<h1><br />User-Managed Access (UMA) Core Protocol<br />draft-hardjono-oauth-umacore-00-rev17</h1>
<h3>Abstract</h3>
<p>This specification defines the User-Managed Access (UMA) core protocol. This protocol provides a method for users to control access to their protected resources, residing on any number of host sites, through an authorization manager that governs access decisions based on user policy.
</p>
<p>This document is an approved Report of the User-Managed Access Work Group of the Kantara Initiative. The User-Managed Access Work Group operates under Kantara IPR Policy - Option Patent and Copyright: Reciprocal Royalty Free with Opt-Out to Reasonable And Non discriminatory (RAND) and the publication of this document is governed by the policies outlined in this option.
</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 January 3, 2012.</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>
Endpoint Names<br />
<a href="#protecting-a-resource">2.</a>
Protecting a Resource<br />
<a href="#anchor5">2.1.</a>
Host Looks Up AM Metadata<br />
<a href="#am-endpoints">2.1.1.</a>
AM Endpoints<br />
<a href="#anchor6">2.1.2.</a>
Example AM Metadata<br />
<a href="#anchor7">2.2.</a>
Host Registers with AM<br />
<a href="#anchor8">2.3.</a>
Host Obtains Host Access Token<br />
<a href="#anchor9">2.4.</a>
Host Registers Sets of Resources to Be Protected<br />
<a href="#resource-reg-example">2.4.1.</a>
Example of Registering Resource Sets<br />
<a href="#action-desc">2.4.2.</a>
Scope Descriptions<br />
<a href="#resource-set-desc">2.4.3.</a>
Resource Set Descriptions<br />
<a href="#reg-api">2.4.4.</a>
Resource Set Registration API<br />
<a href="#getting-authz-accessing-resource">3.</a>
Getting Authorization and Accessing a Resource<br />
<a href="#r-h-attempt-access">3.1.</a>
Requester-Host: Attempt Access at Protected Resource<br />
<a href="#ambiguous-user">3.1.1.</a>
Requester's Request Is Ambiguous<br />
<a href="#no-token">3.1.2.</a>
Requester Presents No Access Token<br />
<a href="#anchor10">3.1.3.</a>
Requester Presents an Invalid Access Token<br />
<a href="#insufficient-scope">3.1.4.</a>
Requester's Token Has Insufficient Permission<br />
<a href="#sufficient-scope">3.1.5.</a>
Requester's Token Has Sufficient Permission<br />
<a href="#r-am-obtain-token">3.2.</a>
Requester-AM: Requester Obtains Access Token<br />
<a href="#h-am-token-validation">3.3.</a>
Host-AM: Ask for Requester's Presented Access Token Status<br />
<a href="#token-valid">3.3.1.</a>
AM Returns a Token Status Description<br />
<a href="#token-invalid">3.3.2.</a>
AM Returns a Token Invalid Response<br />
<a href="#h-am-register-scope">3.4.</a>
Host-AM: Register a Permission<br />
<a href="#h-am-register-scope-success-response">3.4.1.</a>
AM Returns a Permission Registration Success Response<br />
<a href="#h-am-register-scope-invalid-response">3.4.2.</a>
AM Returns a Permission Registration Error Response<br />
<a href="#r-am-authz-scope">3.5.</a>
Requester-AM: Request Authorization to Add Permission<br />
<a href="#trusted-claims-human-driven">3.5.1.</a>
Human Driven Requester Application Flow<br />
<a href="#trusted-claims-autonomously-driven">3.5.2.</a>
Autonomously Driven Requester Application Flow<br />
<a href="#r-am-add-permissions-success-response">3.5.3.</a>
AM Returns an Add Permission Success Response<br />
<a href="#r-am-add-permissions-invalid-response">3.5.4.</a>
AM Returns an Add Permission Error Response<br />
<a href="#anchor11">4.</a>
Error Messages<br />
<a href="#oauth-error-response">4.1.</a>
OAuth Error Responses<br />
<a href="#uma-error-response">4.2.</a>
UMA Error Responses<br />
<a href="#anchor12">5.</a>
Security Considerations<br />
<a href="#anchor13">6.</a>
Privacy Considerations<br />
<a href="#anchor14">7.</a>
Conformance<br />
<a href="#IANA">8.</a>
IANA Considerations<br />
<a href="#Acknowledgments">9.</a>
Acknowledgments<br />
<a href="#anchor15">10.</a>
Issues<br />
<a href="#rfc.references1">11.</a>
References<br />
<a href="#rfc.references1">11.1.</a>
Normative References<br />
<a href="#rfc.references2">11.2.</a>
Informative References<br />
<a href="#History">Appendix A.</a>
Document History<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>The User-Managed Access (UMA) core protocol provides a method based on <a class='info' href='#OAuth2'>[OAuth2]<span> (</span><span class='info'>Hammer-Lahav, E., “The OAuth 2.0 Protocol,” 2010.</span><span>)</span></a> (currently draft 16) for users to control access to their protected resources, residing on any number of host sites, through a single authorization manager (AM) that governs access decisions based on user policy.
</p>
<p>There are numerous use cases for UMA, where a resource owner nominates a third party to control access to these resources potentially without the real-time presence of the resource owner. A typical example is the following. A web user (authorizing user) can authorize a web app (requester) to gain one-time or ongoing access to a resource containing his home address stored at a "personal data store" service (host), by telling the host to act on access decisions made by his authorization decision-making service (authorization manager or AM). The requesting party might be an e-commerce company whose site is acting on behalf of the user himself to assist him/her in arranging for shipping a purchased item, or it might be his friend who is using an online address book service to collect addresses, or it might be a survey company that uses an online service to compile population demographics. Other scenarios and use cases for UMA usage can be found in <a class='info' href='#UMA-usecases'>[UMA‑usecases]<span> (</span><span class='info'>Maler, E., “UMA Scenarios and Use Cases,” October 2010.</span><span>)</span></a> and <a class='info' href='#UMA-userstories'>[UMA‑userstories]<span> (</span><span class='info'>Maler, E., “UMA User Stories,” November 2010.</span><span>)</span></a>.
</p>
<p>In enterprise settings, application access management often involves letting back-office applications serve only as policy enforcement points (PEPs), depending entirely on access decisions coming from a central policy decision point (PDP) to govern the access they give to requesters. This separation eases auditing and allows policy administration to scale in several dimensions. UMA makes use of a separation similar to this, letting the authorizing user serve as a policy administrator crafting authorization strategies on his or her own behalf.
</p>
<p>The UMA protocol profiles and extends <a class='info' href='#OAuth2'>[OAuth2]<span> (</span><span class='info'>Hammer-Lahav, E., “The OAuth 2.0 Protocol,” 2010.</span><span>)</span></a>. An AM serves as an enhanced OAuth authorization server; a host serves as an enhanced resource server; and a requester serves as an enhanced client, acquiring an access token and the requisite authorization to access a protected resource at the host.
</p>
<p>UMA defines an interoperable protection API between the AM and host, allowing them to reside in separate domains and allowing the host to establish mutual trust with an AM on behalf of a particular user. This API is itself OAuth-protected. Thus, the overall UMA flow has a second embedded OAuth-based interaction within it governing the host-AM relationship.
</p>
<p>The UMA protocol has three broad phases (see <a class='info' href='#UMA-phases'>Figure 1</a>).
</p><br /><hr class="insert" />
<a name="UMA-phases"></a>
<p style='text-align: center'>The Three Phases of the UMA Protocol
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +-----+----------------+
| UA | authorizing |
+-------Manage (A)--| | user |
| +-----+----------------+
| Phase 1: | UA |
| protect a +----------------+
| resource |
| Control (B)
| |
v v
+-----------+ +-----+----------------+
| host |<-Protect-(C)-|prot | authorization |
| | | API | manager (AM) |
+-----------+ +-----+----------------+
| protected | | authorization |
| resource | | API |
+-----------+ +----------------+
^ |
| Phases 2 and 3: Authorize (D)
| get authz and |
| access a resource v
| +----------------+
+-------Access (E)--------| requester |
+----------------+
(requesting party)</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 1 </b></font><br /></td></tr></table><hr class="insert" />
<p>The phases work as follows: </p>
<ol class="text">
<li>Protect a resource: This phase involves the authorizing user, host, and AM. The authorizing user has chosen to use a host for managing online resources ("A"), and introduces this host to an AM using an OAuth-mediated interaction that results in the AM giving the host an access token. The host uses AM's protection API to tell the AM what sets of resources to protect ("C"). Out of band of the UMA protocol, the authorizing user instructs the AM what policies to attach to the registered resource sets ("B"). This phase is described in <a class='info' href='#protecting-a-resource'>Section 2<span> (</span><span class='info'>Protecting a Resource</span><span>)</span></a>.
</li>
<li>Get authorization: This phase involves the requester, host, and AM. It may also involve synchronous involvement by the authorizing user if this person is synonymous with the requesting party. This phase is dominated by a loop of activity in which the requester approaches the host seeking access to a protected resource ("E"), is sent to obtain an access token from the AM if it does not have one, and then must demonstrate to the AM that it satisfies the user's authorization policy governing the sought-for resource and scope of access if the host discovers that it does not have the requisite authorization ("D"). This phase is described in <a class='info' href='#getting-authz-accessing-resource'>Section 3<span> (</span><span class='info'>Getting Authorization and Accessing a Resource</span><span>)</span></a>.
</li>
<li>Access a resource: This phase involves the requester successfully presenting an access token that has sufficient permission associated with it to the host in order to gain access to the desired resource ("E"). This phase is described along with Phase 2 in <a class='info' href='#getting-authz-accessing-resource'>Section 3<span> (</span><span class='info'>Getting Authorization and Accessing a Resource</span><span>)</span></a>.
</li>
</ol>
<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, S., “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>
<p>The usage in this document of URIs is temporary ony, awaiting final standardization in the eventual standards body to whom this document will be contributed and taken up as a work item.
</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></p>
<blockquote class="text"><dl>
<dt>authorizing user</dt>
<dd>An UMA-defined variant of an OAuth resource owner; a web user who configures an authorization manager with policies that control how it governs access decisions when a requester attempts to access a protected resource at a host.
</dd>
<dt>authorization manager (AM)</dt>
<dd>An UMA-defined variant of an OAuth authorization server that carries out an authorizing user's policies governing access to a protected resource.
</dd>
<dt>protected resource</dt>
<dd>An access-restricted resource at a host, which is being policy-protected by the AM.
</dd>
<dt>host</dt>
<dd>An UMA-defined variant of an OAuth resource server that enforces access to the protected resources it hosts, as governed by an authorization manager.
</dd>
<dt>host access token</dt>
<dd>An access token representing the authorizing user's consent for a host to trust a particular authorization manager for control over authorizations to access protected resources hosted there.
</dd>
<dt>claim</dt>
<dd>A statement of the value or values of one or more identity attributes of a requesting party. Claims are conveyed by a requester on behalf of a requesting party to an authorization manager in an attempt to satisfy an authorizing user's policy.
</dd>
<dt>requester</dt>
<dd>An UMA-defined variant of an OAuth client that seeks access to a protected resource.
</dd>
<dt>requester access token</dt>
<dd>An access token that can be associated with permissions to access particular resources at a host on behalf of a particular requesting party.
</dd>
<dt>requesting party</dt>
<dd>A web user, or a corporation or other legal person, that uses a requester to seek access to a protected resource. If the requesting party is a natural person, it may or may not be the same person as the authorizing user.
</dd>
<dt>resource set description</dt>
<dd>A JSON-formatted document that represents a set of one or more resources to be AM-protected and maps available scopes to them. The host registers a resource set by giving this document to the AM.
</dd>
<dt>scope description</dt>
<dd>A JSON-formatted document that represents a scope of access on a particular resource set. The host refers to this type of document from within resource set descriptions and permissions that it registers.
</dd>
<dt>token status description</dt>
<dd>A JSON-formatted document that represents the currently valid permissions for authorized access associated with a requester access token.
</dd>
<dt>permission</dt>
<dd>A scope of access over a particular resource set at a particular host that is being asked for by a requester or that has been granted by an AM.
</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.
Endpoint Names</h3>
<p></p>
<blockquote class="text"><dl>
<dt>host access token endpoint</dt>
<dd>Part of the protection API at the AM used by the host (and part of standard OAuth). The endpoint at the AM at which the host asks for a host access token on the authorizing user's behalf.
</dd>
<dt>host user authorization endpoint</dt>
<dd>Part of the protection API at the AM used by the host (and part of standard OAuth). The endpoint at the AM to which the host redirects the authorizing user to authorize the host to use this AM for protecting resources, if the authorization code grant type is being used.
</dd>
<dt>resource set registration endpoint</dt>
<dd>Part of the protection API at the AM used by the host. The endpoint at the AM at which the host registers resource sets which it wants the AM to protect.
</dd>
<dt>permission registration endpoint</dt>
<dd>Part of the protection API at the AM used by the host. The endpoint at the AM at which the host registers permissions that a requester will be asking for.
</dd>
<dt>token status endpoint</dt>
<dd>Part of the protection API at the AM used by the host. The endpoint at the AM at which the host submits requester access tokens to learn what currently valid permissions are associated with them.
</dd>
<dt>protected resource endpoint</dt>
<dd>An endpoint at the host at which a requester attempts to access resources. This can be a singular API endpoint, one of a set of API endpoints, a URI corresponding to an HTML document, or any other Web-accessible URI.
</dd>
<dt>requester access token endpoint</dt>
<dd>Part of the authorization API at the AM used by the requester (and part of standard OAuth). The endpoint at the AM at which the requester asks for a requester access token.
</dd>
<dt>permission endpoint</dt>
<dd>Part of the authorization API at the AM used by the requester. The endpoint at the AM at which the requester asks for authorization to have a new permission associated with its requester access token.
</dd>
</dl></blockquote>
<a name="protecting-a-resource"></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.
Protecting a Resource</h3>
<p>Phase 1 of UMA is protecting a resource. For a host to be able to delegate authorization of protected-resource access to an AM, the authorizing user must first introduce the host to the AM. This phase is concluded successfuly when: </p>
<ul class="text">
<li>The host has received metadata about the AM, such as endpoints it needs to use in interacting with the AM.
</li>
<li>The host has received an OAuth host access token that represents the authorizing user's approval for the host to work with the AM in protecting resources. This host access token is later used when the host makes other requests at the AM's protection API.
</li>
<li>The AM has acquired information about resource sets on the host it is supposed to protect on behalf of the authorizing user.
</li>
</ul>
<p>The user, host, and AM perform the following steps in order to successfully complete Phase 1: </p>
<ol class="text">
<li>The host looks up the AM's metadata and learns about its protection API endpoints and supported formats.
</li>
<li>If the host has not yet obtained a unique OAuth client identifier and optional secret from the AM, it registers with the AM as required. It MAY do this using the OAuth dynamic registration protocol (see <a class='info' href='#Dyn-Reg'>[Dyn‑Reg]<span> (</span><span class='info'>Scholz, C., “OAuth Dynamic Client Registration Protocol,” 2010.</span><span>)</span></a>) proposed by UMA WG participants, if the AM supports it.
</li>
<li>The host obtains a host access token from the AM with the authorizing user's consent, using either the authorization code grant type or the SAML bearer assertion grant type.
</li>
<li>The host registers any resource sets with the AM that are intended to be protected.
</li>
</ol>
<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.1"></a><h3>2.1.
Host Looks Up AM Metadata</h3>
<p>The host needs to learn the OAuth- and UMA-related endpoints of the AM before they can begin interacting. The authorizing user might provide the AM's location to get the host started in this process, for example by typing a URL into a web form field or clicking a button. Alternatively, the host might already be configured to work with a single AM without requiring any user input. The exact process is beyond the scope of this specification, and it is up to the host to choose a method to learn the AM's location.
</p>
<p>From the data provided, discovered, or configured, the host MUST retrieve the hostmeta document as described in Section 2 of <a class='info' href='#hostmeta'>hostmeta<span> (</span><span class='info'>Hammer-Lahav, E., “Web Host Metadata,” May 2011.</span><span>)</span></a> [hostmeta]. For example, if the user supplied "am.example.com" as the Authorization Manager's domain, the host creates the URL "https://am.example.com/.well-known/host-meta" and performs a GET request on it.
</p>
<a name="am-endpoints"></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.1.1"></a><h3>2.1.1.
AM Endpoints</h3>
<p>The AM MUST provide an XRD 1.0-formatted document at the hostmeta location, documenting the following: </p>
<ul class="text">
<li>A set of protection API endpoints for the host to use
</li>
<li>A set of authorization API endpoints for the requester to use
</li>
<li>At least one access token format the AM produces
</li>
<li>Any claim formats the AM supports
</li>
</ul>
<p>Property type values for access token and claim format information:</p>
<blockquote class="text"><dl>
<dt>http://docs.kantarainitiative.org/uma/1.0/token_formats</dt>
<dd>REQUIRED (one or more). Access token format produced by this AM. Currently the only option is "artifact".
</dd>
<dt>http://docs.kantarainitiative.org/uma/1.0/claim_formats</dt>
<dd>OPTIONAL (zero or more). Claim format supported by this AM. Currently the options are "openid-connect". If the AM is capable of requesting and accepting any claim formats at all, it MUST declare them.
</dd>
</dl></blockquote>
<p>Link relationship rel values for the protection API endpoints for the host to use: </p>
<blockquote class="text"><dl>
<dt>http://docs.kantarainitiative.org/uma/1.0/host_token_uri</dt>
<dd>REQUIRED. The host access token endpoint. Available HTTP methods are as defined by <a class='info' href='#OAuth2'>[OAuth2]<span> (</span><span class='info'>Hammer-Lahav, E., “The OAuth 2.0 Protocol,” 2010.</span><span>)</span></a> for a token endpoint. Supplies the endpoint the host uses to ask for a host access token.
</dd>
<dt>http://docs.kantarainitiative.org/uma/1.0/host_user_uri</dt>
<dd>REQUIRED. The host user authorization endpoint. Available HTTP methods are as defined by OAuth for an authorization endpoint. Supplies the endpoint the host uses to gather the consent of the authorizing user for a host-AM relationship if it is using the authorization code grant type. The AM MUST support the authorization code grant type method of obtaining the authorizing user's consent.
</dd>
<dt>http://docs.kantarainitiative.org/uma/1.0/host_resource_reg_uri</dt>
<dd>REQUIRED. The resource set registration endpoint. Requests to this endpoint require a host access token to be present. Supplies the endpoint the host uses for registering resource sets with the AM to be protected (see <a class='info' href='#reg-api'>Section 2.4.4<span> (</span><span class='info'>Resource Set Registration API</span><span>)</span></a>). This endpoint SHOULD require the use of a transport-layer security mechanism such as TLS.
</dd>
<dt>http://docs.kantarainitiative.org/uma/1.0/host_token_status_uri</dt>
<dd>REQUIRED. The token status endpoint. Requests to this endpoint require a host access token to be present. Supplies the endpoint the host uses to request the status of access tokens presented to them by requesters with respect to currently valid permissions. This endpoint SHOULD require the use of a transport-layer security mechanism such as TLS.
</dd>
<dt>http://docs.kantarainitiative.org/uma/1.0/host_perm_reg_uri</dt>
<dd>REQUIRED. The permission registration endpoint. Requests to this endpoint require a host access token to be present. Supplies the endpoint the host uses for registering permissions with the AM for which a requester will be seeking authorization (see <a class='info' href='#h-am-register-scope'>Section 3.4<span> (</span><span class='info'>Host-AM: Register a Permission</span><span>)</span></a>). This endpoint SHOULD require the use of a transport-layer security mechanism such as TLS.
</dd>
</dl></blockquote>
<p>Link relationship rel values for the authorization API endpoints for the requester to use: </p>
<blockquote class="text"><dl>
<dt>http://docs.kantarainitiative.org/uma/1.0/req_token_uri</dt>
<dd>REQUIRED. The requester access token endpoint. Available HTTP methods are as defined by <a class='info' href='#OAuth2'>[OAuth2]<span> (</span><span class='info'>Hammer-Lahav, E., “The OAuth 2.0 Protocol,” 2010.</span><span>)</span></a> for a token issuance endpoint. Supplies the endpoint the requester uses to ask for an access token. This endpoint SHOULD require the use of a transport-layer security mechanism such as TLS.
</dd>
<dt>http://docs.kantarainitiative.org/uma/1.0/req_perm_uri</dt>
<dd>REQUIRED. The permission endpoint. Supplies the endpoint the requester uses to ask for authorization to have a new permission associated with its existing requester access token, which MUST accompany the request. This endpoint SHOULD require the use of a transport-layer security mechanism such as TLS.
</dd>
</dl></blockquote>
<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.2.1.2"></a><h3>2.1.2.
Example AM Metadata</h3>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
<!-- Applies to both hosts and requesters -->
<Property
type="http://docs.kantarainitiative.org/uma/1.0/token_formats">artifact
</Property>
<Property
type="http://docs.kantarainitiative.org/uma/1.0/claim_formats">OpenID-UserInfo
</Property>
<!-- Host protection API -->
<!-- AM as authorization server to host-as-client -->
<Link
rel="http://docs.kantarainitiative.org/uma/1.0/host_token_uri"
href="https://am.example.com/host/token_uri">
</Link>
<Link
rel="http://docs.kantarainitiative.org/uma/1.0/host_user_uri"
href="https://am.example.com/host/user_uri">
</Link>
<!-- AM as resource server to host-as-client -->
<Link
rel="http://docs.kantarainitiative.org/uma/1.0/host_resource_reg_uri"
href="https://am.example.com/host/resource_details_uri">
</Link>
<Link
rel="http://docs.kantarainitiative.org/uma/1.0/host_token_status_uri"
href="https://am.example.com/host/token_validation_uri">
</Link>
<Link
rel="http://docs.kantarainitiative.org/uma/1.0/host_perm_reg_uri"
href="https://am.example.com/host/scope_reg_uri">
</Link>
<!-- Requester authorization API -->
<!-- AM as authorization server to requester-as-client -->
<Link
rel="http://docs.kantarainitiative.org/uma/1.0/req_token_uri"
href="https://am.example.com/requester/token_uri">
</Link>
<!-- AM as resource server to requester-as-client -->
<Link
rel="http://docs.kantarainitiative.org/uma/1.0/req_perm_uri"
href="https://am.example.com/requester/perm_uri">
</Link></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.2.2"></a><h3>2.2.
Host Registers with AM</h3>
<p>If the host has not already obtained a unique client identifier and optional secret from this AM, in this step it MUST do so in order to engage in OAuth-based interactions with the AM. It MAY do this using the OAuth dynamic registration protocol (see <a class='info' href='#Dyn-Reg'>[Dyn‑Reg]<span> (</span><span class='info'>Scholz, C., “OAuth Dynamic Client Registration Protocol,” 2010.</span><span>)</span></a>) proposed by UMA WG participants, if the AM supports it. The AM MUST issue a unique client identifier to every host. This is to ensure that individual hosts can be unambiguously identified in resource set registration, where the client identifier is used as a URI component.
</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.2.3"></a><h3>2.3.
Host Obtains Host Access Token</h3>
<p>In this step, the host acquires a host access token from the AM that represents the approval of the authorizing user for the host to trust the AM for protecting resources belonging to the user.
</p>
<p>The host MUST use the <a class='info' href='#OAuth2'>OAuth2<span> (</span><span class='info'>Hammer-Lahav, E., “The OAuth 2.0 Protocol,” 2010.</span><span>)</span></a> [OAuth2] authorization code grant type or the SAML bearer token grant type <a class='info' href='#OAuth-SAML'>[OAuth‑SAML]<span> (</span><span class='info'>Campbell, B., “SAML 2.0 Bearer Assertion Grant Type Profile for OAuth 2.0,” February 2011.</span><span>)</span></a>, utilizing the end-user authorization and token endpoints as appropriate. Here the host acts in the role of an OAuth client; the authorizing user acts in the role of an OAuth end-user resource owner; and the AM acts in the role of an OAuth authorization server. (Once the host has obtained an access token, it presents it to the AM at various protection API endpoints, at which point the AM acts in the role of a resource server.)
</p>
<p>The host has completed this step successfully when it possesses a host access token it can use at the AM's protection API.
</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.2.4"></a><h3>2.4.
Host Registers Sets of Resources to Be Protected</h3>
<p>Once the host has received a host access token, for any of the user's sets of resources that are to be protected by this AM, it MUST register these resource sets at the AM's registration endpoint.
</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. Additionally, the choice of protection regimes can be made explicitly by the user or implicitly by the host. Any such partitioning by the host or user is outside the scope of this specification.
</p>
<a name="resource-reg-example"></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.4.1"></a><h3>2.4.1.
Example of Registering Resource Sets</h3>
<p>The following example illustrates the intent and usage of resource set registration.
</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 a 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" policy to any resource sets registered by Photoz, until such time as she maps some other less-draconian policies 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 policies 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 scopes of access: "viewing" (consisting of various read-only operations) and "all" (consisting of various reading, editing, and printing operations). It defines two Web-accessible JSON-encoded documents called scope descriptions that represent these scopes, which it is able to reuse for all of its users (not just Alice).
</p>
<p>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. Photoz could distinguish natural-language labels per user if it wishes, by pointing to scopes with differently translated names.)
</p>
<p>Example of the "view" scope ,which description is a Web-accessible resource at http://photoz.example.com/dev/scopes/view:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"scope":
{
"_id": "view"
"name": "View Photo and Related Info",
"icon_uri": "http://www.example.com/icons/reading-glasses.png"
}
}</pre></div>
<p>Example of the "all" scope, which description is a Web-accessible resource at http://photoz.example.com/dev/scopes/all:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"scope":
{
"_id": "all"
"name": "All Actions",
"icon_uri": "http://www.example.com/icons/galaxy.png"
}
}</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 scopes of access on this resource set are indicated with URI references to the scope descriptions, as defined just above.
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"resource_set":
{
"_id": "112210f47de98100"
"name": "Steve the puppy!",
"icon_uri": "http://www.example.com/icons/flower",
"scopes":
["http://photoz.example.com/dev/scopes/view",
"http://photoz.example.com/dev/scopes/all"]
}
}</pre></div>
<p>Photoz uses the "create resource set description" method of CopMonkey's standard UMA resource set 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_set/112210f47de98100 HTTP/1.1
Content-Type: application/json
...
{
"resource_set":
{
"_id": "112210f47de98100"
"name": "Steve the puppy!",
"icon_uri": "http://www.example.com/icons/flower.png",
"scopes":
["http://photoz.example.com/dev/scopes/view",
"http://photoz.example.com/dev/scopes/all"]
}
}</pre></div>
<p>Once this description has been successfully registered, Photoz is responsible for responding correctly to requesters' attempts to access this photo, 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 policy setting, 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 set 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.2.4.2"></a><h3>2.4.2.
Scope Descriptions</h3>
<p>The host defines a scope of access that is available for use with resources it manages in a publicly Web-accessible document containing a scope description. The scopes available for use at any one host MUST have unique URI references so that the host's scope descriptions are distinguishable by URI reference; the URI reference MAY include a fragment identifier. Scope descriptions MAY reside anywhere; the host is not required to self-host scope descriptions and may wish to point to standardized scope descriptions residing elsewhere.
</p>
<p>A scope description is a <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] object with the name "scope" and with the following parameters:</p>
<blockquote class="text"><dl>
<dt>_id</dt>
<dd>REQUIRED. A string that uniquely identifies the scope across all scopes available at this host.
</dd>
<dt>name</dt>
<dd>REQUIRED. A human-readable string describing the scope of access. The AM SHOULD use the name in its user interface to assist the user in setting policies for protected resource sets that have this available scope.
</dd>
<dt>icon_uri</dt>
<dd>OPTIONAL. A URI for a graphic icon representing the scope. If this is provided, the AM SHOULD use the referenced icon in its user interface to assist the user in setting policies for protected resource sets that have this available scope.
</dd>
</dl></blockquote>
<p>For example, this description characterizes a scope that involves reading or viewing resources (vs. creating them or editing them in some fashion):
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"scope":
{
"_id": "view"
"name": "Read-only",
"icon_uri": "http://www.example.com/icons/reading-glasses"
}
}</pre></div>
<p>Scope 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.2.4.3"></a><h3>2.4.3.
Resource Set Descriptions</h3>
<p>The host defines a resource set that needs protection by registering a resource set description at the AM. The host registers the description and manages its lifecycle at the AM's host resource set registration endpoint by using the resource set registration API (see <a class='info' href='#reg-api'>Section 2.4.4<span> (</span><span class='info'>Resource Set Registration API</span><span>)</span></a>). The resource set description is a <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] 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. The resource set 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 set registration API. The host MAY use any identifier scheme to represent resource sets, for example, making its identifiers unique across all users of this host or allowing for the sharing of resource set identifiers among users. However, for privacy reasons, 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. Further, this identifier MUST match the resource set identifier path component of the URI used to manage this description in the resource set registration API; see <a class='info' href='#reg-api'>Section 2.4.4<span> (</span><span class='info'>Resource Set Registration API</span><span>)</span></a> for more information. (Typically this matching is achieved through automatically populating the parameter value on initial registration of the description.)
</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 setting policing for protecting 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 setting policies for protecting this resource set.
</dd>
<dt>scopes</dt>
<dd>REQUIRED. An array referencing one or more URI references of scope descriptions that are available for this resource set.
</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 scopes descriptions as defined in <a class='info' href='#action-desc'>Section 2.4.2<span> (</span><span class='info'>Scope Descriptions</span><span>)</span></a>:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{
"resource_set":
{
"_id": "112210f47de98100",
"name": "Photo album",
"icon_uri": "http://www.example.com/icons/flower.png",
"scopes":
["http://photoz.example.com/dev/scopes/view",
"http://photoz.example.com/dev/scopes/all"]
}
}</pre></div>
<p>Resource set 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 2.4.4<span> (</span><span class='info'>Resource Set Registration API</span><span>)</span></a>), the AM MUST attempt to retrieve the referenced scope descriptions. It MAY cache such descriptions as long as indicated in the HTTP header for the scope 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 scope 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.2.4.4"></a><h3>2.4.4.
Resource Set Registration API</h3>
<p>The host uses a RESTful API at the AM's resource set registration endpoint 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 to gain access to this endpoint.
</p>
<p>(Note carefully the similar but distinct senses in which the word "resource" is used in this section. UMA resource set descriptions are themselves managed as web resources at the AM through this API.)
</p>
<p>Individual resource set descriptions are managed at URIs with this structure: "{rsreguri}/host/{hostid}/resource_set/{rsid}"
</p>
<p>The components of these URIs are defined as follows:</p>
<blockquote class="text"><dl>
<dt>{rsreguri}</dt>
<dd>The AM's resource set registration endpoint as advertised in its metadata (see <a class='info' href='#am-endpoints'>Section 2.1.1<span> (</span><span class='info'>AM Endpoints</span><span>)</span></a>).
</dd>
<dt>{hostid}</dt>
<dd>A registration area at the AM that is specific to this host. The host MUST use the unique 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 and fail to act on the request.
</dd>
<dt>{rsid}</dt>
<dd>An identifier for a resource set description. The identifier MUST match the "_id" parameter value in the description itself.
</dd>
</dl></blockquote>
<p>Without a specific resource set identifier path component, the URI applies to the set of resource set descriptions already registered.
</p>
<p>Following is a summary of the five registration operations the AM is REQUIRED to support. 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/{rsid}
</li>
<li>Read resource set description: GET /host/{hostid}/resource_set/{rsid}
</li>
<li>Update resource set description: PUT /host/{hostid}/resource_set/{rsid}
</li>
<li>Delete resource set description: DELETE /host/{hostid}/resource_set/{rsid}
</li>
<li>List resource set descriptions: GET /host/{hostid}/resource_set/
</li>
</ul>
<p>If the request to the resource set registration endpoint is incorrect, then the AM responds with an error message (see <a class='info' href='#uma-error-response'>Section 4.2<span> (</span><span class='info'>UMA Error Responses</span><span>)</span></a>) by including one of the following error codes with the response: </p>
<blockquote class="text"><dl>
<dt>unsupported_method_type</dt>
<dd>The host request used an unsupported HTTP method. The AM MUST respond with the HTTP 403 (Forbidden) status code and MUST fail to act on the request.
</dd>
<dt>hostid_access_token_mismatch</dt>
<dd>The hostid does not match the presented host access token. The AM MUST respond with the HTTP 403 (Forbidden) status code.
</dd>
<dt>ambiguous_resource_set_id</dt>
<dd>The resourcesetid provided in the resource set description does not match the one provided in the URI. The AM MUST respond with the HTTP 400 (Bad Request) status code and MUST fail to act on the request.
</dd>
<dt>resource_set_not_found</dt>
<dd>The resource set requested from the AM cannot be found. The AM MUST respond with HTTP 404 (Not Found) status code.
</dd>
<dt>resource_set_mismatch</dt>
<dd>The resource set that was requested to be deleted or updated at the AM did not match the ETag value present in the request. The AM MUST respond with HTTP 412 (Precondition Failed) status code and MUST fail to act on the request.
</dd>
</dl></blockquote>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store
{
"error":"unsupported_method_type"
}
</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.2.4.4.1"></a><h3>2.4.4.1.
Create Resource Set Description</h3>
<p>Adds a new resource set description using the PUT method, thereby putting it under the AM's protection. 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, relying on the AM to supply currently valid permissions for authorized access.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>PUT /host/{hostid}/resource_set/{rsid} HTTP/1.1
Content-Type: application/json
...
(Body contains JSON representation of resource set description to be created)</pre></div>
<p>Example of an HTTP request that creates a resource set description at the AM:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>PUT /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1
Content-Type: application/json
Host: am.example.com
{
"resource_set":
{
"_id": "112210f47de98100",
"name": "Photo album",
"icon_uri": "http://www.example.com/icons/flower.png",
"scopes":
["http://photoz.example.com/dev/scopes/view",
"http://photoz.example.com/dev/scopes/all"]
}
}</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 created resource, same as in the PUT request)
ETag: (entity tag of resource artifact)
...
(Body contains JSON representation of created resource set description)</pre></div>
<p>Example of an HTTP response confirming the created resource set description:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 201 Created
Content-Type: application/json
Location: https://am.example.com/rsreg_uri/host/photoz.example.com/resource_set/112210f47de98100
ETag: "1234sdbdDX"
...
{
"resource_set":
{
"_id": "112210f47de98100",
"name": "Photo album",
"icon_uri": "http://www.example.com/icons/flower.png",
"scopes":
["http://photoz.example.com/dev/scopes/view",
"http://photoz.example.com/dev/scopes/all"]
}
}</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.2.4.4.2"></a><h3>2.4.4.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/{hostid}/resource_set/{rsid} HTTP/1.1
...</pre></div>
<p>Example of an HTTP request that reads a resource set description from the AM:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>GET /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1
Host: am.example.com
...</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 resource artifact)
...
(Body contains JSON representation of resource set description)</pre></div>
<p>Example of an HTTP response message containing a resource set description from the AM:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 200 OK
Content-Type: application/json
ETag: "1234sdbdDX"
...
{
"resource_set":
{
"_id": "112210f47de98100",
"name": "Photo album",
"icon_uri": "http://www.example.com/icons/flower.png",
"scopes":
["http://photoz.example.com/dev/scopes/view",
"http://photoz.example.com/dev/scopes/all"]
}</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
Content-Type: application/json
...
{
"error":"resource_set_not_found"
}</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.2.4.4.3"></a><h3>2.4.4.3.
Update Resource Set Description</h3>
<p>Updates a previously registered resource set description using the PUT method, thereby changing the resource set's protection characteristics.
</p>
<p>This operation is different from the operation to create a new resource set description (<a class='info' href='#create-resource-set'>Section 2.4.4.1<span> (</span><span class='info'>Create Resource Set Description</span><span>)</span></a>) because it assumes that prior registration of the resource set in question has occurred.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>PUT /host/{hostid}/resource_set/{rsid} HTTP/1.1
Content-Type: application/json
If-Match: (entity tag of resource if operation is to be idempotent)
...
(Body contains JSON representation of resource set description to be updated)</pre></div>
<p>Example of an HTTP request that updates a resource set description at AM:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>PUT /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1
Content-Type: application/json
Host: am.example.com
If-Match: "1234sdbdDX"
{
"resource_set":
{
"_id": "112210f47de98100",
"name": "Updated Photo album",
"icon_uri": "http://www.example.com/icons/sun.png",
"scopes":
["http://photoz.example.com/dev/scopes/view",
"http://photoz.example.com/dev/scopes/all"]
}
}</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
ETag: "54223dfda"
...</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
Content-Type: application/json
...
{
"error":"resource_set_mismatch"
}</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.2.4.4.4"></a><h3>2.4.4.4.
Delete Resource Set Description</h3>
<p>Deletes a previously registered resource set description using the DELETE method, thereby removing it from the AM's protection regime.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>DELETE /host/{hostid}/resource_set/{rsid}
If-Match: (entity tag of resource if operation is to be idempotent)
...</pre></div>
<p>Example of an HTTP request that deletes a resource set description from the AM:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>DELETE /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1
Host: am.example.com
If-Match: "1234sdbdDX"
</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
Content-Type: application/json
...
{
"error":"resource_set_not_found"
}</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
Content-Type: application/json
...
{
"error":"resource_set_mismatch"
}</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.2.4.4.5"></a><h3>2.4.4.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 {rsid} values.
</p>
<p>HTTP request:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>GET /host/{hostid}/resource_set HTTP/1.1
...</pre></div>
<p>Example of an HTTP request that lists registered resource set descriptions at the AM:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>GET /host/photoz.example.com/resource_set HTTP/1.1
Host: am.example.com
...</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 {rsid} values)</pre></div>
<p>Example of an HTTP response with the list of registered resource set identifiers:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 200 OK
Content-Type: application/json
...
{
"resource_set_id_list": [ "112210f47de98100", "34234df47eL95300" ]
}</pre></div>
<a name="getting-authz-accessing-resource"></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.
Getting Authorization and Accessing a Resource</h3>
<p>Phase 2 of UMA is getting authorization, and Phase 3 is accessing a resource. In these phases, an AM orchestrates and controls requesting parties' access to a user's protected resources at a host, under conditions dictated by that user.
</p>
<p>Phase 3 is merely the successful completion of a requester's access attempt (see <a class='info' href='#sufficient-scope'>Section 3.1.5<span> (</span><span class='info'>Requester's Token Has Sufficient Permission</span><span>)</span></a>) that initially involved several embedded interactions among the requester, AM, and host in Phase 2. Phase 2 always begins with the requester attempting access at a protected resource endpoint at the host. How the requester came to learn about this endpoint is out of scope for UMA; the authorizing user might, for example, have advertised its availability publicly on a blog or other website, listed it in a discovery service, or emailed a link to a particular intended requesting party.
</p>
<p>The host responds to the requester's access request in one of several ways depending on the circumstances of the request, either immediately or having first performed one or more embedded interactions with the AM. Depending on the nature of the host's response to an failed access attempt, the requester itself engages in embedded interactions with the AM before re-attempting access.
</p>
<p>The interactions are as follows. The interaction summarized in each top-level list item MAY be the last interaction engaged in, if the requester chooses not to continue pursuing access to the resource.</p>
<ul class="text">
<li>The requester attempts access at a particular protected resource at a host (see <a class='info' href='#r-h-attempt-access'>Section 3.1<span> (</span><span class='info'>Requester-Host: Attempt Access at Protected Resource</span><span>)</span></a>).
<ul class="text">
<li>If the user corresponding to the protected resource URI is ambiguous: host responds immediately with an error (see <a class='info' href='#ambiguous-user'>Section 3.1.1<span> (</span><span class='info'>Requester's Request Is Ambiguous</span><span>)</span></a>).
</li>
<li>If the user is unambiguous but the access attempt is unaccompanied by a requester access token: host responds immediately with instructions on where to go to obtain one (see <a class='info' href='#no-token'>Section 3.1.2<span> (</span><span class='info'>Requester Presents No Access Token</span><span>)</span></a>).
</li>
</ul>
</li>
<li>If the access attempt was accompanied by a requester access token, the host checks the token's status at the AM (see <a class='info' href='#h-am-token-validation'>Section 3.3<span> (</span><span class='info'>Host-AM: Ask for Requester's Presented Access Token Status</span><span>)</span></a>).
<ul class="text">
<li>If the AM reports that the requester access token is invalid (see <a class='info' href='#token-invalid'>Section 3.3.2<span> (</span><span class='info'>AM Returns a Token Invalid Response</span><span>)</span></a>), the host responds to the requester with instructions on where to go to obtain a token (see <a class='info' href='#no-token'>Section 3.1.2<span> (</span><span class='info'>Requester Presents No Access Token</span><span>)</span></a>).
</li>
</ul>
</li>
<li>If the AM supplies a token status description for a valid requester access token (see <a class='info' href='#token-valid'>Section 3.3.1<span> (</span><span class='info'>AM Returns a Token Status Description</span><span>)</span></a>) but none of the permissions associated with the token match the scope of attempted access, the host registers a suitable permission on the requester's behalf at the AM (see <a class='info' href='#h-am-register-scope'>Section 3.4<span> (</span><span class='info'>Host-AM: Register a Permission</span><span>)</span></a>) and then responds to the requester with instructions on where to go to request authorization to associate that permission with its token (see <a class='info' href='#insufficient-scope'>Section 3.1.4<span> (</span><span class='info'>Requester's Token Has Insufficient Permission</span><span>)</span></a>).
</li>
<li>If the requester received instructions on where to get a token, it requests a token from the appropriate AM (see <a class='info' href='#r-am-obtain-token'>Section 3.2<span> (</span><span class='info'>Requester-AM: Requester Obtains Access Token</span><span>)</span></a>).
</li>
<li>If the requester received instructions on where to get authorization for access permission, it requests permission from the appropriate AM (see <a class='info' href='#r-am-authz-scope'>Section 3.5<span> (</span><span class='info'>Requester-AM: Request Authorization to Add Permission</span><span>)</span></a>).
</li>
<li>If the AM gave status back on a valid requester access token, and at least one of the permissions associated with the token match the scope of attempted access, the host responds to the requester's access attempt with success (see <a class='info' href='#sufficient-scope'>Section 3.1.5<span> (</span><span class='info'>Requester's Token Has Sufficient Permission</span><span>)</span></a>).
</li>
</ul>
<p>This process extends OAuth in several notable ways:</p>
<ul class="text">
<li>The requester access token signifies only a binding of this requester, the requesting party on whose behalf it is acting, this host, this authorizing user, and this AM, to be reused for all permissions to access any of the user's protected resources at this host that are protected by this AM.
</li>
<li>Any real-time authorizing user (resource owner) consent required by policy is gathered at the time of claim requests, rather than at the time of token issuance; the flow does not distinguish between policies for "person-to-person" sharing and policies for "person-to-self" sharing.
</li>
<li>The process of seeking authorization does not just rely on the requester's ability to authenticate as the (or a) resource owner, but admits a wide-ranging set of policy options based on attributes of the requesting party. This model could be called claims-based authorization.
</li>
<li>The host is (for now) required to check with the AM in real time about the status of all tokens unseen before or whose cached status has expired. Eventually, this specification will define an interoperable way to use of structured tokens to allow AMs the opportunity to give out requester access tokens whose status hosts can check "locally".
</li>
</ul>
<p>The interactions are described in detail in the following sections.
</p>
<a name="r-h-attempt-access"></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.1"></a><h3>3.1.
Requester-Host: Attempt Access at Protected Resource</h3>
<p>This interaction assumes that the host has previously registered with an AM one or more resource sets that correspond to the resource to which access is being attempted, such that the host considers this resource to be protected by a particular AM.
</p>
<p>The requester typically attempts to access the desired resource at the host directly (for example, when a human operator of the requester software clicks on a thumbnail representation of the resource). The requester is expected to discover, or be provisioned with, knowledge of the protected resource and its location out of band. Further, the requester is expected to acquire its own knowledge about the methods made available by the host for operating on this resource (such as viewing it with a GET method, or transforming it with some complex API call) and the possible scopes of access.
</p>
<p>The host responds in one of five ways.
</p>
<a name="ambiguous-user"></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.1.1"></a><h3>3.1.1.
Requester's Request Is Ambiguous</h3>
<p>By the nature of the requester's request for access (for example, through a URI parameter specifying a username or other identifier), the host needs to be able to detect uniquely which one of its users has the operative control over access to this resource. Without this, the host will be unable to interact with the correct AM using the correct host access token in protecting the resource.
</p>
<p>If the requester's request is ambiguous with respect to the specific user at the host, the host immediately responds with an "ambiguous-user" error message (see <a class='info' href='#uma-error-response'>Section 4.2<span> (</span><span class='info'>UMA Error Responses</span><span>)</span></a>).
</p>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store
{
"error":"ambiguous-user"
}</pre></div>
<a name="no-token"></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.1.2"></a><h3>3.1.2.
Requester Presents No Access Token</h3>
<p>If the host is able to detect uniquely which one of its users has the operative control over access to the resource (see <a class='info' href='#ambiguous-user'>Section 3.1.1<span> (</span><span class='info'>Requester's Request Is Ambiguous</span><span>)</span></a>), but the requester does not present any access token with the request, the host MUST return an HTTP 400 (Bad Request) status code indicating it is an "invalid_request" (see Section 2.4.1 of <a class='info' href='#OAuth-bearer'>[OAuth‑bearer]<span> (</span><span class='info'>Jones, M., “The OAuth 2.0 Protocol: Bearer Tokens,” June 2011.</span><span>)</span></a>), along with providing the AM's URI. This error indicates to the requester that the request is missing a required parameter, includes an unsupported parameter or parameter value, repeats the same parameter, uses more than one method for including an access token, or is otherwise malformed.
</p>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 400 Bad Request
WWW-Authenticate: UMA realm="example"
host_id="photoz.example.com",
am_uri="http://am.example.com"</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.3.1.3"></a><h3>3.1.3.
Requester Presents an Invalid Access Token</h3>
<p>If the requester presents an access token with its request, the host asks the AM to give it the requester access token's status (see <a class='info' href='#h-am-token-validation'>Section 3.3<span> (</span><span class='info'>Host-AM: Ask for Requester's Presented Access Token Status</span><span>)</span></a>). If the AM reports that the token is invalid, the Host SHOULD return an HTTP 401 (Unauthorized) status code indicating it is an "invalid_token" (see Section 2.4.1 of <a class='info' href='#OAuth-bearer'>[OAuth‑bearer]<span> (</span><span class='info'>Jones, M., “The OAuth 2.0 Protocol: Bearer Tokens,” June 2011.</span><span>)</span></a>), along with providing the AM's URI. This error indicates to the requester that the access token provided is expired, revoked, malformed, or invalid for other reasons.
</p>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 401 Unauthorized
WWW-Authenticate: UMA realm="example"
host_id="photoz.example.com",
am_uri="http://am.example.com"</pre></div>
<a name="insufficient-scope"></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.1.4"></a><h3>3.1.4.
Requester's Token Has Insufficient Permission</h3>
<p>If the requester presents an access token with its request, the host asks the AM to give it the requester access token's status (see <a class='info' href='#h-am-token-validation'>Section 3.3<span> (</span><span class='info'>Host-AM: Ask for Requester's Presented Access Token Status</span><span>)</span></a>). If the AM supplies a token status description for a valid requester access token, the host examines the token status description. If the token status is not, in the host's judgment, associated with any currently valid permission that applies to the scope of access attempted by the requester, the Host SHOULD register the desired permission with the AM (see <a class='info' href='#h-am-register-scope'>Section 3.4<span> (</span><span class='info'>Host-AM: Register a Permission</span><span>)</span></a>) and then respond to the requester with the HTTP 403 (Forbidden) status code indicating that the token has "insufficient_scope" (see Section 2.4.1 of <a class='info' href='#OAuth-bearer'>[OAuth‑bearer]<span> (</span><span class='info'>Jones, M., “The OAuth 2.0 Protocol: Bearer Tokens,” June 2011.</span><span>)</span></a>), along with providing the AM's URI and the permission ticket it just received from the AM.
</p>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 403 Forbidden
WWW-Authenticate: UMA realm="example"
host_id="photoz.example.com"
am_uri="http://am.example.com",
ticket="5454345rdsaa4543"</pre></div>
<a name="sufficient-scope"></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.1.5"></a><h3>3.1.5.
Requester's Token Has Sufficient Permission</h3>
<p>If the requester presents an access token with its request, the host asks the AM to give it the requester access token's status (see <a class='info' href='#h-am-token-validation'>Section 3.3<span> (</span><span class='info'>Host-AM: Ask for Requester's Presented Access Token Status</span><span>)</span></a>) If the AM supplies a token status description for a valid requester access token, the host examines the token status description. If the token status, in the host's judgment, is associated with at least one currently valid permission that applies to the scope of access attempted by the requester, the host gives access to the desired resource.
</p>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 200 OK
Content-Type: image/jpeg
...
/9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja
3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf
/bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo
KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb</pre></div>
<p>This response constitutes the conclusion of Phase 3 of UMA.
</p>
<a name="r-am-obtain-token"></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.2"></a><h3>3.2.
Requester-AM: Requester Obtains Access Token</h3>
<p>When a requester does not possess a valid access token to access resources of a particular user at a particular host, it requests one from the AM's requester token endpoint.
</p>
<p>The requester learns about this endpoint by retrieving the AM's hostmeta document (see <a class='info' href='#am-endpoints'>Section 2.1.1<span> (</span><span class='info'>AM Endpoints</span><span>)</span></a>) based on the "am_uri" information that was provided by the host in its previous response, as described in Section 2 of <a class='info' href='#hostmeta'>hostmeta<span> (</span><span class='info'>Hammer-Lahav, E., “Web Host Metadata,” May 2011.</span><span>)</span></a> [hostmeta]. For example, if the "am_uri" is "am.example.com", the requester creates the URI "https://am.example.com/.well-known/host-meta" and performs a GET request on it.
</p>
<p>Each such token is unique per requester; requesting party on whose behalf the requester software is operating; authorizing user; AM; and host. It is not unique per protected resource or resource set; the token represents the set of permissions for that requesting party to access potentially a large set of different resource sets with a variety of scopes.
</p>
<p>The requester SHOULD use the OAuth 2.0 client credentials authorization grant type (see Section 4.4 of <a class='info' href='#OAuth2'>[OAuth2]<span> (</span><span class='info'>Hammer-Lahav, E., “The OAuth 2.0 Protocol,” 2010.</span><span>)</span></a>).
</p>
<p>In UMA, unlike in plain OAuth, obtaining an access token does not automatically convey permission for access to any protected resource. The token must first be associated with at least one suitable permission for scoped access in order for the requester to succeed in accessing the resource.
</p>
<p>If the requester does not yet have a client identifier and the AM demands requesters to have unique client identifiers, the requester MAY use the dynamic OAuth registration protocol (see <a class='info' href='#Dyn-Reg'>[Dyn‑Reg]<span> (</span><span class='info'>Scholz, C., “OAuth Dynamic Client Registration Protocol,” 2010.</span><span>)</span></a>) proposed by the UMA participants, if the AM supports it.
</p>
<a name="h-am-token-validation"></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.3"></a><h3>3.3.
Host-AM: Ask for Requester's Presented Access Token Status</h3>
<p>On receiving a requester access token in an access attempt, the host asks the AM for the token's status. If it has a cached token status description available that has not expired yet, it MAY use it instead.
</p>
<p>The host makes the request to the AM with a POST to the AM's token status endpoint. The body of the HTTP request message contains a JSON <a class='info' href='#RFC4627'>[RFC4627]<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> document providing the requester access token and the IP address of the requester's request. The host MAY, at its discretion, instead supply the originating IP address indicated in the requester's X-Forwarded-For: header value. The IP address or originating IP address is advisory only; the AM MAY ignore it for purposes of its own token validation process.
</p>
<p>The host gains access to the token status endpoint by presenting its own host access token in the request. The host access token also allows the host and AM to uniquely identify the user they have in common, and therefore allows the AM to look up the correct authorizing user's policies and settings.
</p>
<p>
</p>
<p>Example of a request to the token validation endpoint that provides the host access token in the header:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>POST /token_status HTTP/1.1
Host: am.example.com
Authorization: Bearer vF9dft4qmT
Content-Type: application/json
{
"token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv"
"resource_set_id":"112210f47de98100"
"host_id":"photoz.example.com"
"ipaddr":"192.168.1.1"
}</pre></div>
<a name="token-valid"></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.3.1"></a><h3>3.3.1.
AM Returns a Token Status Description</h3>
<p>If the the AM finds the requester's access token to be valid, it returns the token's status in an HTTP response using the 200 OK status code, containing a JSON <a class='info' href='#RFC4627'>[RFC4627]<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> document supplying the token status description. The token status description contains all of the permissions that are currently valid for this requester access token (and thus for the requesting party on whose behalf it is acting). The AM MAY set a cache period for the returned token status description that allows the host to reuse it over some period of time when it later sees the same requester access token.
</p>
<p>The token status description is a JSON object with the name "token_status" containing an array of zero or more permission objects, each with the following parameters:</p>
<blockquote class="text"><dl>
<dt>resource_set_id</dt>
<dd>REQUIRED. A string that uniquely identifies the resource set, access to which has been granted to this requester on behalf of this requesting party. The identifier MUST correspond to a resource set that was previously registered as protected.
</dd>
<dt>scopes</dt>
<dd>REQUIRED. An array referencing one or more URIs of scopes to which access was granted for this resource set. Each scope MUST correspond to a scope that was registered by this host for the referenced resource set.
</dd>
<dt>exp</dt>
<dd>REQUIRED. An integer representing the expiration time on or after which the permission MUST NOT be accepted for authorized access. The processing of the exp parameter requires that the current date/time MUST be before the expiration date/time listed in the exp claim. Host implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew.
</dd>
</dl></blockquote>
<p>Example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"token_status":
[
{
"resource_set_id": "112210f47de98100",
"scopes":
["http://photoz.example.com/dev/actions/view",
"http://photoz.example.com/dev/actions/all"],
"exp": 1300819380
}
]
}</pre></div>
<p>
</p>
<a name="token-invalid"></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.3.2"></a><h3>3.3.2.
AM Returns a Token Invalid Response</h3>
<p>If the the AM finds the requester's access token to be invalid, it returns an UMA error message.
</p>
<p>The AM includes one of the following error codes in the error response: (see <a class='info' href='#uma-error-response'>Section 4.2<span> (</span><span class='info'>UMA Error Responses</span><span>)</span></a>) and responds with the HTTP 400 status code: </p>
<blockquote class="text"><dl>
<dt>invalid_requester_token</dt>
<dd>AM determined that the requester access token was not valid.
</dd>
<dt>expired_requester_token</dt>
<dd>AM determined that the requester access token has expired.
</dd>
</dl></blockquote>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error":"invalid_requester_token"
}</pre></div>
<a name="h-am-register-scope"></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.4"></a><h3>3.4.
Host-AM: Register a Permission</h3>
<p>If, in the host's judgment, the permissions returned by the AM from a token status request are insufficient to allow this requester's access attempt, the host registers a permission with the AM that it believes would be sufficient for the type of access sought. As a result of the host registering a permission to the AM, the AM returns a permission ticket for the host to give to the requester in its response (see <a class='info' href='#insufficient-scope'>Section 3.1.4<span> (</span><span class='info'>Requester's Token Has Insufficient Permission</span><span>)</span></a>).
</p>
<p>The permissions ticket is a short-lived opaque structure whose contents is determined by the AM. Later when the requester asks the AM to add permissions to the requester's token (see <a class='info' href='#r-am-authz-scope'>Section 3.5<span> (</span><span class='info'>Requester-AM: Request Authorization to Add Permission</span><span>)</span></a> it will submit this ticket to the AM. It is therefore the task of the AM to perform binding of this ticket to the requester and its token.
</p>
<p>The host registers the permission using the POST method at the AM's permission registration endpoint, providing its host access token to get authorized access to this endpoint. The body of the HTTP request message contains a JSON <a class='info' href='#RFC4627'>[RFC4627]<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> document providing the requester's access token and the requested permission.
</p>
<p>The requested scope is an object with the name "requested_permission" and the following parameters:</p>
<blockquote class="text"><dl>
<dt>resource_set_id</dt>
<dd>REQUIRED. A string that uniquely identifies a resource set, access to which this requester is seeking access. The identifier MUST correspond to a resource set that was previously registered as protected.
</dd>
<dt>scopes</dt>
<dd>REQUIRED. An array referencing one or more identifiers of scopes to which access is needed for this resource set. Each scope identifier MUST correspond to a scope that was registered by this host for the referenced resource set.
</dd>
</dl></blockquote>
<p>Example of an HTTP request that registers a permission at the AM's permission registration endpoint:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>POST /host/scope_reg_uri/photoz.example.com HTTP/1.1
Content-Type: application/json
Host: am.example.com
{
"requested_permission":
{
"resource_set_id": "112210f47de98100",
"scopes": ["http://photoz.example.com/dev/actions/view",
"http://photoz.example.com/dev/actions/all"]
}
}</pre></div>
<p>On receiving the scope registration request from the Host, the AM issues a response message that has one of the possible following outputs:</p>
<ul class="text">
<li>A permission ticket and its expiration time (typically very short).
</li>
<li>Error message indicating a malformed scope registration request.
</li>
</ul>
<p>
</p>
<a name="h-am-register-scope-success-response"></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.4.1"></a><h3>3.4.1.
AM Returns a Permission Registration Success Response</h3>
<p>The AM responds with an HTTP 201 (Created) status code and includes the Location header in its response as well as the "ticket" parameter in the JSON-formatted body:
</p>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 201 Created
Content-Type: application/json
Location: https://am.example.com/permreg/host/photoz.example.com/5454345rdsaa4543
{
"ticket":"5454345rdsaa4543"
}</pre></div>
<a name="h-am-register-scope-invalid-response"></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.4.2"></a><h3>3.4.2.
AM Returns a Permission Registration Error Response</h3>
<p>The AM responds with an HTTP 400 (Bad Request) status code and includes one of the following error codes with the error response (see <a class='info' href='#uma-error-response'>Section 4.2<span> (</span><span class='info'>UMA Error Responses</span><span>)</span></a>): </p>
<blockquote class="text"><dl>
<dt>invalid_resource_set_id</dt>
<dd>The provided resource set identifier was not found at the AM.
</dd>
<dt>invalid_scope</dt>
<dd>At least one of the scopes included in the request was not registered previously by this host.
</dd>
<dt>invalid_requester_token</dt>
<dd>The requester access token was not recognized by the AM.
</dd>
<dt>expired_requester_token</dt>
<dd>The requester access token has expired.
</dd>
</dl></blockquote>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
...
{
"error":"invalid_resource_set_id"
}</pre></div>
<a name="r-am-authz-scope"></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.5"></a><h3>3.5.
Requester-AM: Request Authorization to Add Permission</h3>
<p>In this interaction, the requester asks the AM to grant authorization to associate a new permission to its access token for use at a particular host. It does this at the AM's permission endpoint by supplying the permission ticket it got from the host, along with its requester access token. The AM uses this information to look up the previously registered permission, confirm that the correct requester is asking for it, map the requested permission to operative user policies, and demand in turn that the requester convey any claims needed to support its request.
</p>
<p>The requester learns about this endpoint by retrieving the AM's hostmeta document (see <a class='info' href='#am-endpoints'>Section 2.1.1<span> (</span><span class='info'>AM Endpoints</span><span>)</span></a>) based on the "am_uri" information that was provided by the host in its previous response, as described in Section 2 of <a class='info' href='#hostmeta'>hostmeta<span> (</span><span class='info'>Hammer-Lahav, E., “Web Host Metadata,” May 2011.</span><span>)</span></a> [hostmeta]. For example, if the "am_uri" is "am.example.com", the requester creates the URI "https://am.example.com/.well-known/host-meta" and performs a GET request on it.
</p>
<p>The requester performs a GET on the permission endpoint, using the standard HTTP "Accept" header to express the acceptable media type(s) of any claims-requested response.
</p>
<p>The AM responds in one of three ways: </p>
<ul class="text">
<li>If the AM requires no claims (or no further claims) from the requester in order to grant authorization for the asked-for permission based on user policy, it gives a success response, indicating that the requested scope has been associated with the requester's token.
</li>
<li>If the requester is definitively not authorized for this permission according to user policy, the AM responds with a failure response and the authorization request phase ends.
</li>
<li>If user policy demands more information from the requester, the AM responds with a claims-requested response. The list SHOULD use the claim format media type that was indicated by the requester as acceptable.
</li>
</ul>
<p>The claims-requested list MAY contain internal logic that gives a choice or other variability around the sets of claims that will satisfy the request. This potentially allows the requester to select a subset of claims to supply in order to obtain the needed permission.
</p>
<p>If claims are requested and the requester wishes to provide them, it POSTs another permission request, providing one or more claims or references to one or more locations where the AM can go to retrieve claims.
</p>
<p>The AM responds with a successful or unsuccessful access token response, or with another claims-requested response. This loop can be run through as many times as necessary for the AM to request further claims and the requester to supply them, re-asking for authorization to get the needed permission at every juncture.
</p>
<p>If the content-type of the request is not recognized by the AM, the AM MUST reject the document.
</p>
<p>
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre></pre></div>
<p>This specification does not define the formats of claims-requested lists and appropriate responses. It may ultimately put minimum conformance requirements on requesters and AMs to handle particular claim formats defined in other specifications, as well as specifying requirements that claim formats seeking consideration for use in UMA must meet. Currently the claim formats that an AM can declare in its metadata (<a class='info' href='#am-endpoints'>Section 2.1.1<span> (</span><span class='info'>AM Endpoints</span><span>)</span></a>), are as follows:</p>
<ul class="text">
<li><a class='info' href='#OpenID-Connect-Fmwk'>[OpenID‑Connect‑Fmwk]<span> (</span><span class='info'>Sakimura, N., “OpenID Connect Framework 1.0,” June 2011.</span><span>)</span></a> (see <a class='info' href='#trusted-claims'>Section 3.5.1.1<span> (</span><span class='info'>AM as an OpenID Connect RP</span><span>)</span></a> below for further context).
</li>
</ul>
<a name="trusted-claims-human-driven"></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.5.1"></a><h3>3.5.1.
Human Driven Requester Application Flow</h3>
<p>
</p>
<a name="trusted-claims"></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.5.1.1"></a><h3>3.5.1.1.
AM as an OpenID Connect RP</h3>
<p>
</p>
<p>It is hoped that UMA can profile the emerging OpenID Connect protocol as a mechanism to support access control to enable specific use cases in which the decision to grant access is made based on trusted (often third-party-asserted) claims about the requesting party, such as name, age, email address, role, and location.
</p>
<p>OpenID Connect provides authentication, authorization, and attribute transmission capability. The integration approach would treat the claims-seeking UMA AM as an OpenID relying party and OpenID Connect claims client, leveraging OpenID Connect mechanisms to transmit claims from distributed sources.
</p>
<p>In this scenario, the relying party interface is responsible for authenticating the subject (the UMA requesting party) and initializing the OpenID Connect protocol. The claims client interface is responsible for requesting claims based on OpenID Connect protocol, in order to satisfy the UMA authorizing user's policy. The client interacts with the OpenID Connect authorization server to obtain a specific access token to access to the subject's (UMA requesting party’s) UserInfo endpoint (trusted claims provider).
</p>
<a name="trusted-claims-others"></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.5.1.2"></a><h3>3.5.1.2.
Other options of AM Claims Handling</h3>
<p>
</p>
<p>TBD
</p>
<a name="trusted-claims-autonomously-driven"></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.5.2"></a><h3>3.5.2.
Autonomously Driven Requester Application Flow</h3>
<p>
</p>
<p>(Text to follow TBD)
</p>
<a name="r-am-add-permissions-success-response"></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.5.3"></a><h3>3.5.3.
AM Returns an Add Permission Success Response</h3>
<p>The AM responds with an HTTP 201 (Created) status code and includes the updated token:
</p>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 201 Created
Content-Type: application/json
{
"token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv"
}</pre></div>
<a name="r-am-add-permissions-invalid-response"></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.5.4"></a><h3>3.5.4.
AM Returns an Add Permission Error Response</h3>
<p>The AM responds with an HTTP 400 (Bad Request) status code and includes one of the following error codes with the error response (see <a class='info' href='#uma-error-response'>Section 4.2<span> (</span><span class='info'>UMA Error Responses</span><span>)</span></a>): </p>
<blockquote class="text"><dl>
<dt>invalid_requester_ticket</dt>
<dd>The provided ticket was not found at the AM.
</dd>
<dt>expired_requester_ticket</dt>
<dd>At least one of the scopes included in the request was not registered previously by this host.
</dd>
<dt>invalid_requester_token</dt>
<dd>The requester access token was not recognized by the AM.
</dd>
<dt>expired_requester_token</dt>
<dd>The requester access token has expired.
</dd>
</dl></blockquote>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
...
{
"error":"expired_requester_ticket"
}</pre></div>
<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.4"></a><h3>4.
Error Messages</h3>
<p>Ultimately the host is responsible for either granting the access the requester attempted, or returning an error response to the requester with a reason for the failure. <a class='info' href='#OAuth2'>[OAuth2]<span> (</span><span class='info'>Hammer-Lahav, E., “The OAuth 2.0 Protocol,” 2010.</span><span>)</span></a> defines several error responses for a resource server to return. UMA makes use of these error responses, but requires the host to "outsource" the determination of some error conditions to the AM. UMA defines its own additional error responses that the AM may give to the host and requester as they interact with it, and that the host may give to the requester.
</p>
<a name="oauth-error-response"></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.1"></a><h3>4.1.
OAuth Error Responses</h3>
<p>When a client (host or requester) attempts to access one of the AM endpoints <a class='info' href='#am-endpoints'>Section 2.1.1<span> (</span><span class='info'>AM Endpoints</span><span>)</span></a> or a client (requester) attempts to access a protected resource at the host, it has to make an authenticated request by including an OAuth access token in the HTTP request as described in <a class='info' href='#OAuth2'>[OAuth2]<span> (</span><span class='info'>Hammer-Lahav, E., “The OAuth 2.0 Protocol,” 2010.</span><span>)</span></a> Section 7.
</p>
<p>If the client's request failed authentication, the AM or the host responds with an OAuth error message as described throughout <a class='info' href='#protecting-a-resource'>Section 2<span> (</span><span class='info'>Protecting a Resource</span><span>)</span></a> and <a class='info' href='#getting-authz-accessing-resource'>Section 3<span> (</span><span class='info'>Getting Authorization and Accessing a Resource</span><span>)</span></a>.
</p>
<a name="uma-error-response"></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.2"></a><h3>4.2.
UMA Error Responses</h3>
<p>When a client (host or requester) attempts to access one of the AM endpoints <a class='info' href='#am-endpoints'>Section 2.1.1<span> (</span><span class='info'>AM Endpoints</span><span>)</span></a> or a client (requester) attempts to access a protected resource at the host, if the client request is successfully authenticated by OAuth means, but is invalid for another reason, the AM or host responds with an UMA error response by adding the following parameters to the entity body of the HTTP response using the "application/json" media type: </p>
<blockquote class="text"><dl>
<dt>error</dt>
<dd>REQUIRED. A single error code. Value for this parameter is defined in the specific AM endpoint description.
</dd>
<dt>error_description</dt>
<dd>OPTIONAL. A human-readable text providing additional information, used to assist in the understanding and resolution of the error occurred.
</dd>
<dt>error_uri</dt>
<dd>OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the end-user with additional information about the error.
</dd>
</dl></blockquote>
<p>Common error codes: </p>
<blockquote class="text"><dl>
<dt>invalid_request</dt>
<dd>The request is missing a required parameter or is otherwise malformed. The AM MUST respond with the HTTP 400 (Bad Request) status code.
</dd>
</dl></blockquote>
<p>For example:
</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
...
{
"error":"invalid_request",
"error_description":"There is already a resource with this identifier.",
"error_uri":"http://am.example.com/errors/resource_exists"
}</pre></div>
<a name="anchor12"></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.
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 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>
<p>For information about the technical, operational, and legal elements of trust establishment between UMA entities and parties, which affects security considerations, see <a class='info' href='#UMA-trustmodel'>[UMA‑trustmodel]<span> (</span><span class='info'>Maler, E., “UMA Trust Model,” February 2011.</span><span>)</span></a>.
</p>
<p>
</p>
<a name="anchor13"></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.
Privacy Considerations</h3>
<p>The AM comes to be in possession of resource set 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>
<p>For information about the technical, operational, and legal elements of trust establishment between UMA entities and parties, which affects privacy considerations, see <a class='info' href='#UMA-trustmodel'>[UMA‑trustmodel]<span> (</span><span class='info'>Maler, E., “UMA Trust Model,” February 2011.</span><span>)</span></a>.
</p>
<a name="anchor14"></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.
Conformance</h3>
<p>This section outlines conformance requirements for various entities implementing UMA endpoints.
</p>
<p>This specification has dependencies on other specifications, as follows:</p>
<ul class="text">
<li>OAuth 2.0: AMs, hosts, and requesters MUST support OAuth 2.0 features named in this specification for conformance. For example, AMs MUST support the authorization code grant type for being introduced to hosts by authorizing users.
</li>
<li>hostmeta: AMs, hosts, and requesters MUST support the hostmeta features named in this specification for conformance.
</li>
</ul>
<p>
</p>
<a name="IANA"></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.
IANA Considerations</h3>
<p>TBD
</p>
<a name="Acknowledgments"></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>The contributors to this specification include the Kantara UMA Work Group participants, a list of whom can be found at <a class='info' href='#UMAnitarians'>[UMAnitarians]<span> (</span><span class='info'>Maler, E., “UMA Participant Roster,” 2011.</span><span>)</span></a>.
</p>
<a name="anchor15"></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.
Issues</h3>
<p>(All issues are now captured and addressed in GitHub).
</p>
<a name="rfc.references"></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.
References</h3>
<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.1. Normative References</h3>
<table width="99%" border="0">
<tr><td class="author-text" valign="top"><a name="Dyn-Reg">[Dyn-Reg]</a></td>
<td class="author-text">Scholz, C., “<a href="http://tools.ietf.org/html/draft-hardjono-oauth-dynreg-00.html">OAuth Dynamic Client Registration Protocol</a>,” 2010.</td></tr>
<tr><td class="author-text" valign="top"><a name="OAuth-SAML">[OAuth-SAML]</a></td>
<td class="author-text">Campbell, B., “<a href="http://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer-03">SAML 2.0 Bearer Assertion Grant Type Profile for OAuth 2.0</a>,” February 2011.</td></tr>
<tr><td class="author-text" valign="top"><a name="OAuth-bearer">[OAuth-bearer]</a></td>
<td class="author-text">Jones, M., “<a href="http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-06">The OAuth 2.0 Protocol: Bearer Tokens</a>,” June 2011.</td></tr>
<tr><td class="author-text" valign="top"><a name="OAuth2">[OAuth2]</a></td>
<td class="author-text">Hammer-Lahav, E., “<a href="http://tools.ietf.org/html/draft-ietf-oauth-v2-16">The OAuth 2.0 Protocol</a>,” 2010.</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
<td class="author-text"><a href="mailto:sob@harvard.edu">Bradner, S.</a>, “<a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>,” BCP 14, RFC 2119, March 1997 (<a href="http://www.rfc-editor.org/rfc/rfc2119.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2119.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2119.xml">XML</a>).</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>,” RFC 4627, July 2006 (<a href="http://www.rfc-editor.org/rfc/rfc4627.txt">TXT</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="hostmeta">[hostmeta]</a></td>
<td class="author-text">Hammer-Lahav, E., “<a href="http://tools.ietf.org/html/draft-hammer-hostmeta-16">Web Host Metadata</a>,” May 2011.</td></tr>
</table>
<a name="rfc.references2"></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.2. Informative References</h3>
<table width="99%" border="0">
<tr><td class="author-text" valign="top"><a name="Claims2.0">[Claims2.0]</a></td>
<td class="author-text">Maler, E., “<a href="http://kantarainitiative.org/confluence/display/uma/Claims+2.0">Claims 2.0</a>,” 2010.</td></tr>
<tr><td class="author-text" valign="top"><a name="OpenID-Connect-Fmwk">[OpenID-Connect-Fmwk]</a></td>
<td class="author-text">Sakimura, N., “<a href="http://openid.net/specs/openid-connect-framework-1_0.html">OpenID Connect Framework 1.0</a>,” June 2011.</td></tr>
<tr><td class="author-text" valign="top"><a name="SAAC">[SAAC]</a></td>
<td class="author-text">Maler, E., “<a href="http://kantarainitiative.org/confluence/display/uma/Simple+Access+Authorization+Claims">Simple Access Authorization Claims</a>,” April 2010.</td></tr>
<tr><td class="author-text" valign="top"><a name="UMA-trustmodel">[UMA-trustmodel]</a></td>
<td class="author-text">Maler, E., “<a href="http://kantarainitiative.org/confluence/display/uma/UMA+Trust+Model">UMA Trust Model</a>,” February 2011.</td></tr>
<tr><td class="author-text" valign="top"><a name="UMA-usecases">[UMA-usecases]</a></td>
<td class="author-text">Maler, E., “<a href="http://kantarainitiative.org/confluence/display/uma/UMA+Scenarios+and+Use+Cases">UMA Scenarios and Use Cases</a>,” October 2010.</td></tr>
<tr><td class="author-text" valign="top"><a name="UMA-userstories">[UMA-userstories]</a></td>
<td class="author-text">Maler, E., “<a href="http://kantarainitiative.org/confluence/display/uma/User+Stories">UMA User Stories</a>,” November 2010.</td></tr>
<tr><td class="author-text" valign="top"><a name="UMAnitarians">[UMAnitarians]</a></td>
<td class="author-text">Maler, E., “<a href="http://kantarainitiative.org/confluence/display/uma/Participant+Roster">UMA Participant Roster</a>,” 2011.</td></tr>
</table>
<a name="History"></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.A"></a><h3>Appendix A.
Document History</h3>
<p>NOTE: To be removed by RFC editor before publication as an RFC
</p>
<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">Thomas Hardjono (editor)</td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">MIT</td></tr>
<tr><td class="author" align="right">Email: </td>
<td class="author-text"><a href="mailto:hardjono@mit.edu">hardjono@mit.edu</a></td></tr>
<tr cellpadding="3"><td> </td><td> </td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">Christian Scholz</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">Paul Bryan</td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">pbryan.net</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>
<tr><td class="author" align="right">URI: </td>
<td class="author-text"><a href="http://pbryan.net">http://pbryan.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-text"> </td>
<td class="author-text">XMLgrrl.com</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><td class="author" align="right">URI: </td>
<td class="author-text"><a href="http://www.xmlgrrl.com/">http://www.xmlgrrl.com/</a></td></tr>
<tr cellpadding="3"><td> </td><td> </td></tr>
<tr><td class="author-text"> </td>
<td class="author-text">Lukasz</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:lukasz.moren@ncl.ac.uk">lukasz.moren@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>
</table>
</body></html>
{uma/draft-uma-core.html} |
Page Comparison
Manage space
Manage content
Integrations