draft-uma-resource-reg.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc PUBLIC "-//IETF//DTD RFC 2629//EN"
"http://xml.resource.org/authoring/rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY UMA PUBLIC "" "http://kantarainitiative.org/confluence/display/uma/Home">
<!ENTITY UMAreqs PUBLIC "" "http://kantarainitiative.org/confluence/display/uma/UMA+Requirements">
]>
<rfc category="std" docName="draft-uma-resource-reg" ipr="trust200902">
  <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

  <?rfc toc='yes' ?>

  <?rfc tocdepth='3' ?>

  <?rfc symrefs='yes' ?>

  <?rfc sortrefs='yes' ?>

  <?rfc compact='yes' ?>

  <?rfc subcompact='no' ?>

  <?rfc strict='yes' ?>

  <front>
    <title abbrev="UMA Resource Registration">UMA Resource
    Registration</title>

    <author fullname="Christian Scholz" initials="C" role="editor"
            surname="Scholz">
      <organization>COM.lounge GmbH</organization>

      <address>
        <email>cs@comlounge.net</email>

        <uri>http://comlounge.net</uri>
      </address>
    </author>

    <author fullname="Maciej Machulak" initials="M" surname="Machulak">
      <organization>Newcastle University</organization>

      <address>
        <email>m.p.machulak@ncl.ac.uk</email>

        <uri>http://ncl.ac.uk/</uri>
      </address>
    </author>

    <author fullname="Eve Maler" initials="E" surname="Maler">
      <address>
        <email>eve@xmlgrrl.com</email>
      </address>
    </author>

    <author fullname="Paul Bryan" initials="P" surname="Bryan">
      <organization>ForgeRock</organization>

      <address>
        <email>email@pbryan.net</email>
      </address>
    </author>

    <date day="20" month="February" year="2011" />

    <abstract>
      <t>This specification defines the resource registration protocol for
      User-Managed Access (UMA). This protocol provides a method for a host to
      register, update, check, and delete resource-related information at an
      authorization manager (AM) so that the user's resources can be put under
      scoped protection.</t>
    </abstract>
  </front>

  <middle>
    <section title="Introduction">
      <t>This specification defines the resource registration protocol for
      User-Managed Access (<xref target="draft-uma-core">UMA</xref>). This
      protocol provides a method for a host to register, update, check, and
      delete resource-related information at an authorization manager (AM) so
      that the user's resources can be put under scoped protection.</t>

      <t>(Intellectual property notice: The User-Managed Access Work Group
      operates under <eref
      target="http://kantarainitiative.org/confluence/display/GI/Option+Patent+and+Copyright+%28RAND%29">Kantara
      IPR Policy - Option Patent &amp; Copyright: Reciprocal Royalty Free with
      Opt-Out to Reasonable And Non discriminatory (RAND)</eref> and the
      publication of this document is governed by the policies outlined in
      this option.)</t>

      <t>The host needs to register information about resources to be
      protected so that the AM can apply authorization constraints to them
      according to the user's wishes.</t>

      <t>The host determines (unilaterally or as instructed by the user) the
      universe of resources belonging to this user that are to be protected by
      the AM, and assigns a resource identifier to sets of these resources.
      Such a set might include a status update API endpoint (applying to the
      user's entire update stream), or an individual status update, or a photo
      album, or all photos with a particular user-assigned tag, or even the
      set of "all resources managed by this user at this host".</t>

      <t>The host also determines the universe of actions that is possible for
      requesting parties to perform on each resource set. Such actions might
      involve "viewing", "adding", "printing", or whatever other actions the
      application supports for that resource set. Typically each action covers
      a broad list of methods in the host's published API.</t>

      <t>Once the host has registered resource sets and their descriptive
      information with the AM, the AM (under the authorizing user's
      instructions) is able to map particular authorization constraints to a
      particular set of resources and a particular set of actions and to take
      part in the process of limiting (scoping) access to resource sets.</t>

      <t>Note that the host is free to offer the option to protect any subset
      of the user's resources using different AMs or other means entirely, or
      to protect some resources and not others; any such partitioning is
      outside the scope of this specification.</t>

      <section title="Notational Conventions">
        <t>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 <xref
        target="RFC2119"></xref>.</t>

        <t>Unless otherwise noted, all the protocol parameter names and values
        are case sensitive.</t>
      </section>

      <section title="Terminology">
        <t>See <xref target="draft-uma-core">UMA</xref> for additional term
        definitions.</t>

        <t><list hangIndent="6" style="hanging">
            <t hangText="registration endpoint"><vspace />A protected endpoint
            at the AM capable of receiving resource information from a
            host.</t>

            <t hangText="resource set description"><vspace />A JSON-formatted
            data structure that represents a set of one or more resources to
            be AM-protected and maps possible actions to them.</t>

            <t hangText="action description">A JSON-formatted data structure
            that represents a possible action on a resource set.</t>
          </list></t>
      </section>

      <section title="Requirements Analysis">
        <t>This specification, in combination with the UMA core protocol
        specification and the scoped-access specification, has been informed
        by the following resource registration requirements:<list
            style="symbols">
            <t>The authorizing user needs to be presented with a user
            interface at the AM that clearly indicates what resources and
            actions are available when they're setting and mapping
            authorization constraints. (User interface considerations are out
            of scope of UMA protocol specifications, but this requirement has
            protocol dependencies.)</t>

            <t>The AM therefore needs to acquire from the host some
            description of resources and actions to be protected, which
            includes enough information to display to the authorizing user.
            (Solved by this specification.)</t>

            <t>The requester and requesting party, prior to receiving an
            access token, should not be exposed to resource information that
            compromises the authorizing user's privacy. For example, a
            protected set of resources might usefully but embarrassingly be
            described as "racy photos from beach vacation". It is assumed that
            the host already has access to such a description and that the
            nature of the host-AM trust relationship forged by the authorizing
            user may qualify the AM to see this description as well. (Solved
            by this specification.)</t>

            <t>The AM needs to be told the relevant resource set, in
            host-described terms, that corresponds to the resource the
            requester is seeking access to so that it can assess the
            requesting party's request for an access token against the correct
            authorization constraints. (Solved by the scoped-access
            specification.)</t>

            <t>Therefore, when the requester attempts access at the host and
            fails, the host needs to convey enough information to the AM
            (whether through the requester directly or by other means) for the
            latter to do this job. For privacy reasons, if the host asks the
            requester to convey information directly, privacy considerations
            come into play. (Solved by the scoped-access specification.)</t>

            <t>"The host needs to be able to validate that a requester's
            access attempt in step 3, accompanied by an access token, matches
            a resource set and action associated with that access token.
            (Solved by the scoped-access specification.)</t>

            <t>The AM therefore needs to make an association between requester
            access tokens and resource sets/actions. (Solved by the core
            protocol specification. Currently it defines a run-time method for
            the host to ask the AM to confirm this match. An alternative
            solution that meets the requirement would be for the access token
            to securely contain this information.)</t>

            <t>The requester needs to know what actions are possible on the
            resource it is trying to access. (This requirement is considered
            out of scope for UMA; it is anticipated that host API
            documentation will pick up the slack.)</t>
          </list></t>
      </section>
    </section>

    <section title="Example">
      <t>The following example illustrates the intent and usage of the
      resource registration protocol.</t>

      <t>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".</t>

      <t>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.</t>

      <t>Alice has already introduced this host to her AM,
      CopMonkey.example.com, and thus Photoz has already obtained an OAuth
      client ID and an UMA host access token from CopMonkey. However, Alice
      has not previously instructed Photoz to use CopMonkey to protect any
      other photos of hers.</t>

      <t>Alice has previously visited CopMonkey to map a default "do not share
      with anyone" authorization constraint to any resource sets registered by
      Photoz, until such time as she maps some other less-draconian
      constraints to those resources. (User experience only. This may have
      been done at the time Alice introduced the host to the AM, and/or it
      could have been a global or host-specific preference setting. A
      different constraint or no constraint at all might be associated with
      newly protected resources.) Other kinds of constraints she may
      eventually map to particular photos or albums might be "Share only with
      husband@email.example.net" or "Share only with people in my 'family'
      group".</t>

      <t>Photoz itself has a publicly documented API that offers two dozen
      different methods that apply to single photos, such as "addTags" and
      "getSizes", but rolls them up into two photo-related actions: "viewing"
      (consisting of varous read-only operations) and "all" (consisting of
      various reading, editing, and printing operations). It defines two
      Web-accessible JSON-encoded documents called action descriptions that
      represent these actions, which it is able to reuse for all of its users
      (not just Alice). The "name" parameter values are intended to be seen by
      Alice when she maps authorization constraints to specific resource sets
      and actions while visiting CopMonkey, such that Alice would see the
      strings "View Photo and Related Info" and "All Actions", likely
      accompanied by the referenced icons, in the CopMonkey interface. (Other
      users of Photoz might similarly see the same labels at CopMonkey or
      whatever other AM they use.)</t>

      <figure>
        <artwork><![CDATA[{
        "action":
            {
            "_id": "view"
            "name": "View Photo and Related Info",
            "icon_uri": "http://www.example.com/icons/reading-glasses"
        }
}]]></artwork>
      </figure>

      <figure>
        <artwork><![CDATA[{
        "action":
            {
            "_id": "all"
            "name": "All Actions",
            "icon_uri": "http://www.example.com/icons/galaxy"
        }
}]]></artwork>
      </figure>

      <t>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).</t>

      <t>As a result, Photoz defines for itself a resource set that represents
      this photo (internal only; Photoz is the only application that knows how
      to map a particular photo to a particular resource set). Photoz also
      prepares the following resource set description, which is specific to
      Alice and her photo. The "name" parameter value is intended to be seen
      by Alice in mapping authorization constraints to specific resource sets
      and actions when she visits CopMonkey, such that Alice would see the
      string "Steve the puppy!", likely accompanied by the referenced icon, in
      the CopMonkey interface. The possible actions on this resource set are
      indicated with URI references to the action descriptions, as defined
      just above.</t>

      <figure>
        <artwork><![CDATA[{
        "resource_set":
            {
            "_id": "112210f47de98100"
            "name": "Steve the puppy!",
            "icon_uri": "http://www.example.com/icons/flower",
            "actions":
                        ["http://photoz.example.com/dev/actions/view",
                        "http://photoz.example.com/dev/actions/all"]
        }
}]]></artwork>
      </figure>

      <t>Photoz uses the "create resource set description" method of
      CopMonkey's standard UMA-based resource registration API, presenting its
      Alice-specific host access token there, to register and assign an
      identifier to the resource set description. The resource set identifier
      path component of the URL matches the "_id" parameter value in the
      description.</t>

      <figure>
        <artwork><![CDATA[PUT /host/photoz.example.com/resource/112210f47de98100
Content-Type: application/json
...

{
        "resource_set":
           {
           "_id": "112210f47de98100"
           "name": "Steve the puppy!",
           "icon_uri": "http://www.example.com/icons/flower",
           "actions":
                        ["http://photoz.example.com/dev/actions/view",
                        "http://photoz.example.com/dev/actions/all"]
         }
}]]></artwork>
      </figure>

      <t>Once this description has been successfully registered, Photoz is
      responsible for responding to requesters' attempts to access this photo
      in the manner described in <xref target="draft-uma-core">UMA</xref>,
      achieving protection of the resource by "outsourcing" this task to
      CopMonkey.</t>

      <t>At the time Alice indicates she would like this photo protected,
      Photoz can choose to redirect Alice to CopMonkey for further
      authorization constraint mapping, access auditing, and other AM-related
      tasks (user experience only).</t>

      <t>Over time, as Alice uploads other photos and creates and organizes
      photo albums, and as Photoz makes new action functionality available,
      Photoz can use additional methods of the resource registration API to
      ensure that CopMonkey's understanding of Alice's protected resources
      matches its own.</t>
    </section>

    <section title="Prerequisites">
      <t>In order for a host to be able to register resource information with
      an AM it needs to fulfill the following prerequisites:<list
          style="symbols">
          <t>The host has obtained a host access token from the AM as
          explained in UMA core protocol step 1.</t>

          <t>The host has obtained the URI of the registration API endpoint as
          part of the AM's metadata as described in UMA protocol step 1.</t>
        </list></t>
    </section>

    <section anchor="action-desc" title="Action Description">
      <t>The host defines an action that is available for use with resources
      it manages in an action description encoded in <xref format="default"
      target="RFC4627">JSON</xref> form and made publicly accessible through a
      URI reference (it MAY include a fragment identifier). The actions
      available for use at any one host MUST have unique URI references so
      that the host's action descriptions are distinguishable by URI
      reference. Action descriptions MAY reside anywhere; the host is not
      required to self-host action descriptions and may wish to point to
      standardized action descriptions residing elsewhere.</t>

      <t>An action description is an object with the name "action" and with
      the following parameters:<list style="hanging">
          <t hangText="_id">REQUIRED. A string that uniquely identifies the
          action across all actions available at this host.</t>

          <t hangText="name">REQUIRED. A human-readable string describing the
          action. The AM SHOULD use the name in its user interface to assist
          the user in mapping authorization constraints to resource sets with
          this permissible action.</t>

          <t hangText="icon_uri">OPTIONAL. A URI for a graphic icon
          representing the action. If this is provided, the AM SHOULD use the
          referenced icon in its user interface to assist the user in mapping
          authorization constraints to resource sets with this permissible
          action.</t>
        </list></t>

      <figure>
        <preamble>For example, this description characterizes an action that
        involves reading or viewing resources (vs. creating them or editing
        them in some fashion):</preamble>

        <artwork><![CDATA[{
        "action":
            {
            "_id": "view"
            "name": "Read-only",
            "icon_uri": "http://www.example.com/icons/reading-glasses"
        }
}]]></artwork>
      </figure>

      <t>Action descriptions MAY contain extension parameters that are not
      defined in this specification. The names of extension parameters MUST
      begin with "x-" or "X-".</t>
    </section>

    <section anchor="resource-set-desc" title="Resource Set Description">
      <t>The host defines a resource set that needs UMA protection in a
      resource set description encoded in <xref format="default"
      target="RFC4627">JSON</xref> form. The host registers the description
      and manages its lifecycle at the AM through the resource registration
      API.</t>

      <t>A resource set description is an object with the name "resource_set"
      and with the following parameters:<list style="hanging">
          <t hangText="_id">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 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 registration API; see <xref
          target="reg-api"></xref> for more information. (Typically this
          matching is achieved through automatically populating the parameter
          value on initial registration of the description.)</t>

          <t hangText="name">REQUIRED. A human-readable string describing a
          set of one or more resources. The AM SHOULD use the name in its user
          interface to assist the user in mapping authorization constraints to
          this resource set.</t>

          <t hangText="icon_uri">OPTIONAL. A URI for a graphic icon
          representing the resource set. If provided, the AM SHOULD use the
          referenced icon in its user interface to assist the user in mapping
          authorization constraints to this resource set.</t>

          <t hangText="actions">REQUIRED. An array referencing one or more
          identifiers of actions that are permissible on this resource set.
          Each action identifier MUST correspond to an action registered by
          this host for this user at this AM.</t>
        </list></t>

      <figure>
        <preamble>For example, this description characterizes a resource set
        (a photo album) that can potentially be only viewed, or alternatively
        to which full access can be granted; the URIs point to action
        descriptions, as dictated in <xref
        target="action-desc"></xref>:</preamble>

        <artwork><![CDATA[{
        "resource_set":
            {
            "name": "Photo album",
            "icon_uri": "http://www.example.com/icons/flower",
            "actions":
                        ["http://photoz.example.com/dev/actions/view",
                        "http://photoz.example.com/dev/actions/all"]
        }
}]]></artwork>
      </figure>

      <t>Resource set descriptions descriptions MAY contain extension
      parameters that are not defined in this specification. The names of
      extension parameters MUST begin with "x-" or "X-".</t>

      <t>When a host creates or updates a resource set description (see <xref
      target="reg-api"></xref>), the AM MUST attempt to retrieve the
      referenced action descriptions. It MAY cache such descriptions as long
      as indicated in the HTTP header for the action description resource
      unless the resource set description is subsequently updated within the
      validity period. At the beginning of an authorizing user's login session
      at the AM, the AM MUST attempt to re-retrieve action descriptions
      applying to that user whose cached versions have expired.</t>
    </section>

    <section anchor="reg-api" title="Resource Registration API">
      <t>The host uses a RESTful API at the AM's host_registration_uri to
      create, read, update, and delete resource set descriptions, along with
      listing groups of such descriptions. The host MUST use its valid host
      access token obtained previously in UMA protocol step 1 to gain access
      to the API.</t>

      <t>Individual resource set descriptions are managed at URIs with this
      structure: "{reguri}/host/{hostid}/resource_set/{resourcesetid}"</t>

      <t>The components of these URIs are defined as follows:<list
          style="hanging">
          <t hangText="{reguri}">The AM's host_registration_uri as advertised
          in its metadata. This endpoint, its security requirements, and its
          requirements around advertisement in metadata are defined in UMA
          protocol step 1 (see <xref target="draft-uma-core">UMA</xref>).</t>

          <t hangText="{hostid}">A registration area at the AM that is
          specific to this host. The host MUST use the OAuth client identifier
          it was assigned by this AM as its host identifier. If the host
          identifier does not match the host access token used at the host
          registration endpoint, the AM MUST report an HTTP 403 Forbidden
          error (see example below) and fail to act on the request.</t>

          <t hangText="{resourcesetid}">An identifier for a resource set
          description. The identifier MUST match the "_id" parameter value in
          the description itself.</t>
        </list></t>

      <t>Without a specific resource identifier path component, the URI
      applies to the set of resource set descriptions already registered.</t>

      <t>Following is a summary of the five registration API operations the AM
      is REQUIRED to support. Each is defined in its own section below. All
      other methods are unsupported.<list style="symbols">
          <t>Create resource set description: PUT
          /host/{hostid}/resource_set/{resourcesetid}</t>

          <t>Read resource set description: GET
          /host/{hostid}/resource_set/{resourcesetid}</t>

          <t>Update resource set description: PUT
          /host/{hostid}/resource_set/{resourcesetid}</t>

          <t>Delete resource set description: DELETE
          /host/{hostid}/resource_set/{resourcesetid}</t>

          <t>List resource set descriptions: GET
          /host/{hostid}/resource_set/</t>
        </list></t>

      <t>The AM MUST respond to host requests using unsupported HTTP methods
      with an HTTP 403 Forbidden error and MUST fail to act on the
      request.</t>

      <figure>
        <preamble>HTTP response (unsupported method or host ID not matching
        the presented host access token):</preamble>

        <artwork><![CDATA[HTTP/1.1 403 Forbidden
...

(Body provides user-readable explanation of the error.)]]></artwork>
      </figure>

      <section anchor="create-resource-set"
               title="Create Resource Set Description">
        <t>Adds a new resource set description using the PUT method. The host
        assigns a unique identifier to the action. The host is free to use its
        own methods of identifying and describing resource sets; the AM MUST
        treat them as opaque for the purpose of authorizing access, other than
        associating them with the authorizing user represented by the host
        access token used to access the API. On successfully registering a
        resource set, the host MUST use UMA mechanisms to limit access to any
        resources corresponding to this resource set, as defined in <xref
        target="draft-uma-core">UMA</xref>.</t>

        <figure>
          <preamble>HTTP request:</preamble>

          <artwork><![CDATA[PUT /host/{hostid}/user/{userid}/resource/{resourceid}
Content-Type: application/json
...

(Body contains JSON representation of resource set description to be created.)]]></artwork>
        </figure>

        <figure>
          <preamble>HTTP response (success):</preamble>

          <artwork><![CDATA[HTTP/1.1 201 Created
Content-Type: application/json
Location: (URL of the created resource, same as that which was PUT.)
...]]></artwork>
        </figure>
      </section>

      <section anchor="read-resource-set"
               title="Read Resource Set Description">
        <t>Reads a previously registered resource set description using the
        GET method.</t>

        <figure>
          <preamble>HTTP request:</preamble>

          <artwork><![CDATA[GET /host/{hostid}/user/{userid}/resource/{resourceid} HTTP/1.1
...]]></artwork>
        </figure>

        <figure>
          <preamble>HTTP response (success):</preamble>

          <artwork><![CDATA[HTTP/1.1 200 OK
Content-Type: application/json
ETag: (entity tag of the resource artifact)
...

(Body contains JSON representation of the resource set description.)]]></artwork>
        </figure>

        <figure>
          <preamble>HTTP response (not found):</preamble>

          <artwork><![CDATA[HTTP/1.1 404 Not Found
...

(Body provides user-readable explanation of the error.)]]></artwork>
        </figure>
      </section>

      <section anchor="update-resource-set"
               title="Update Resource Set Description">
        <t>Updates a previously registered resource set description using the
        PUT method.</t>

        <figure>
          <preamble>HTTP request:</preamble>

          <artwork><![CDATA[PUT /host/{hostid}/user/{userid}/resource/{resourceid}
Content-Type: application/json
If-Match: (entity tag of the resource if operation is to be idempotent)
...

(Body contains JSON representation of resource set description to be updated.)]]></artwork>
        </figure>

        <figure>
          <preamble>HTTP response (success):</preamble>

          <artwork><![CDATA[HTTP/1.1 204 No Content
...]]></artwork>
        </figure>

        <figure>
          <preamble>HTTP response (entity tag does not match):</preamble>

          <artwork><![CDATA[HTTP/1.1 412 Precondition failed
...]]></artwork>
        </figure>
      </section>

      <section anchor="delete-resource-set"
               title="Delete Resource Set Description">
        <t>Deletes a previously registered resource set description using the
        DELETE method.</t>

        <figure>
          <preamble>HTTP request:</preamble>

          <artwork><![CDATA[DELETE /host/{hostid}/user/{userid}/resource/{resourceid}
If-Match: (entity tag of the resource if operation to be idempotent)
...]]></artwork>
        </figure>

        <figure>
          <preamble>HTTP response (success):</preamble>

          <artwork><![CDATA[HTTP/1.1 204 No content
...]]></artwork>
        </figure>

        <figure>
          <preamble>HTTP response (not found):</preamble>

          <artwork><![CDATA[HTTP/1.1 404 Not Found
...

(Body provides user-readable explanation of the error.)]]></artwork>
        </figure>

        <figure>
          <preamble>HTTP response (entity tag does not match):</preamble>

          <artwork><![CDATA[HTTP/1.1 412 Precondition failed
...]]></artwork>
        </figure>
      </section>

      <section anchor="list-resource-sets"
               title="List Resource Set Descriptions">
        <t>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
        {resourcesetid} values.</t>

        <figure>
          <preamble>HTTP request:</preamble>

          <artwork><![CDATA[GET /host/{hostid}/resource_set/
...]]></artwork>
        </figure>

        <figure>
          <preamble>HTTP response:</preamble>

          <artwork><![CDATA[HTTP/1.1 200 OK
Content-Type: application/json
...

(Body contains JSON array of {resourcesetid} values.)]]></artwork>
        </figure>
      </section>
    </section>

    <section title="Security Considerations">
      <t>This specification relies mainly on OAuth security mechanisms for
      protecting the host registration endpoint at the AM so that only a
      properly authorized host can access it on behalf of the intended user.
      For example, the host needs to use a valid host access token issued
      through a user authorization process at the endpoint, and the
      interaction should take place over TLS. It is expected that the host
      will protect its client secret (if it was issued one) and will protect
      its host access token, particularly if used in "bearer token"
      fashion.</t>

      <t>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.</t>
    </section>

    <section title="Privacy Considerations">
      <t>The AM comes to be in possession of information (such as names and
      icons) that may reveal information about the user, which the AM's trust
      relationship with the host is assumed to accommodate. However, the
      requester is a less-trusted party (in fact, entirely untrustworthy until
      it acquires a requester access token in UMA protocol step 2). This
      specification recommends obscuring resource set identifiers in order to
      avoid leaking personally identifiable information to requesters through
      the "scope" mechanism.</t>
    </section>

    <section title="TODOs">
      <t><list style="symbols">
          <t>In <xref target="action-desc"></xref>, should the action
          description have an "_id" parameter or a normal "id" parameter so
          that the URI path component that must match the ID can be
          human-readable ("view") vs. machine-assigned gobbledygook?</t>

          <t>Should the {hostid} component instead be a pseudonym assigned by
          the AM (during or after OAuth client ID provisioning) to allow for
          hosts' client IDs to be a string like "anonymous"? Check this
          throughout the scoped-access spec progress.</t>

          <t>Give example of what a list of resource set IDs looks like in
          <xref target="list-resource-sets"></xref>.</t>

          <t>Consider the question of i18n of resource set and action "name"
          strings in addition to the extension-parameter mechanism.</t>
        </list></t>
    </section>

    <section title="Acknowledgments">
      <t><list style="symbols">
          <t>[TBS]</t>
        </list></t>
    </section>

    <section title="Document History">
      <t>Changes in 20 Feb 2011 version:<list style="symbols">
          <t>Cleaned up nits and minor wording revisions noted in comments
          sent to the mailing list on 13 Feb 2011 (<eref
          target="http://groups.google.com/group/kantara-initiative-uma-wg/browse_frm/thread/f498afdb5bfe7f60"></eref>).</t>

          <t>Revised the discussion of resource set identifier uniqueness and
          redistributed some information about this identifier between
          Sections 5 and 6.</t>

          <t>Switched the positions of the Example and Prerequisites
          sections.</t>

          <t>Revised TODOs accordingly.</t>
        </list></t>

      <t>Changes in 6 Jan 2011 version:<list style="symbols">
          <t>Removed action-related API methods.</t>

          <t>Revised Example section to take into account the new "passive"
          way of declaring actions.</t>

          <t>Added "_id" parameters.</t>

          <t>Changed "resource" to "resource set", "{resourcesetid}, or
          "resource_set" as appropriate throughout.</t>

          <t>Removed user-specific path component of the registration URI.</t>

          <t>Allowed "X-" in addition to "x-" for extension parameters.</t>

          <t>Broke out the two descriptions into their own sections.</t>

          <t>A bit of editorial cleanup all over.</t>
        </list></t>

      <t>Changes in 30 Dec 2010 version:<list style="symbols">
          <t>Unsupported HTTP methods in registration API return 403</t>

          <t>Folded error section in to API section and changed from UMA-level
          error to 403</t>

          <t>Changed name of "resource" parameter to "resource_set"</t>

          <t>Added TODO issue about referencing standard sets of actions and
          reconsidering in-band IDs, and cleaned up the TODO list
          generally</t>

          <t>Fleshed out citations and requirements analysis</t>

          <t>Added huge worked-example section at the beginning (which
          contains issues not yet captured in the TODO section)</t>
        </list></t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <reference anchor="RFC4627">
        <front>
          <title>The application/json Media Type for JavaScript Object
          Notation (JSON)</title>

          <author fullname="Douglas Crockford" initials="D"
                  surname="Crockford"></author>

          <date month="July" year="2006" />
        </front>

        <format target="http://tools.ietf.org/html/rfc4627" type="TXT" />
      </reference>

      <reference anchor="RFC2119">
        <front>
          <title>Key words for use in RFCs to Indicate Requirement
          Levels</title>

          <author fullname="S. Bradner" surname="Bradner"></author>

          <date month="March" year="1997" />
        </front>

        <format target="http://www.ietf.org/rfc/rfc2119.txt" type="TXT" />
      </reference>

      <reference anchor="draft-uma-core">
        <front>
          <title>UMA 1.0 Core Protocol</title>

          <author fullname="Christian Scholz" initials="C" surname="Scholz"></author>

          <date month="December" year="2010" />
        </front>

        <format target="http://mrtopf.clprojects.net/uma/draft-uma-core.html"
                type="HTML" />
      </reference>
    </references>
  </back>
</rfc>