rec-oauth-resource-reg-v1_0.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 RFC2617 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2617.xml">
<!ENTITY UMA PUBLIC "" "http://kantarainitiative.org/confluence/display/uma/Home">
<!ENTITY UMAreqs PUBLIC "" "http://kantarainitiative.org/confluence/display/uma/UMA+Requirements">
<!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY RFC4627 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml">
]>
<rfc category="std" docName="draft-hardjono-oauth-resource-reg-06"
     ipr="trust200902">
  <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

  <?rfc toc='yes' ?>

  <?rfc tocdepth='4' ?>

  <?rfc symrefs='yes' ?>

  <?rfc sortrefs='yes' ?>

  <?rfc compact='yes' ?>

  <?rfc subcompact='no' ?>

  <front>
    <title abbrev="OAuth RSR">OAuth 2.0 Resource Set Registration</title>

    <author fullname="Thomas Hardjono" initials="T" role="editor"
            surname="Hardjono">
      <organization>MIT</organization>

      <address>
        <email>hardjono@mit.edu</email>
      </address>
    </author>

    <author fullname="Eve Maler" initials="E" surname="Maler">
      <organization>ForgeRock</organization>

      <address>
        <email>eve.maler@forgerock.com</email>
      </address>
    </author>

    <author fullname="Maciej Machulak" initials="M" surname="Machulak">
      <organization>Cloud Identity</organization>

      <address>
        <email>maciej.machulak@cloudidentity.co.uk</email>
      </address>
    </author>

    <author fullname="Domenico Catalano" initials="D" surname="Catalano">
      <organization>Oracle</organization>

      <address>
        <email>domenico.catalano@oracle.com</email>
      </address>
    </author>

    <date day="2" month="April" year="2015" />

    <abstract>
      <t>This specification defines a resource set registration mechanism
      between an OAuth 2.0 authorization server and resource server. The
      resource server registers information about the semantics and discovery
      properties of its resources with the authorization server.</t>
    </abstract>
  </front>

  <middle>
    <section anchor="introduction" title="Introduction">
      <t>There are various circumstances under which an OAuth 2.0 <xref
      target="OAuth2"></xref> resource server may need to communicate
      information about its protected resources to its authorization
      server:<list style="symbols">
          <t>In some OAuth 2.0 deployments, the resource server and
          authorization server are operated by the same organization and
          deployed in the same domain, but many resource servers share a
          single authorization server (a security token service (STS)
          component). Thus, even though the trust between these two is
          typically tightly bound, there is value in defining a singular
          standardized resource protection communications interface between
          the authorization server and each of the resource servers.</t>

          <t>In some deployments of OpenID Connect <xref
          target="OpenIDConnect"></xref>, which has a dependency on OAuth 2.0,
          the OpenID Provider (OP) component is a specialized version of an
          OAuth authorization server that brokers availability of user
          attributes by dealing with an ecosystem of attribute providers
          (APs). These APs effectively function as third-party resource
          servers. Thus, there is value in defining a mechanism by which all
          of the third-party APs can communicate with a central OP, as well as
          ensuring that trust between the authorization server and resource
          servers is able to be established in a dynamic, loosely coupled
          fashion.</t>

          <t>In some deployments of User-Managed Access <xref
          target="UMA"></xref>, which has a dependency on OAuth 2.0, an
          end-user resource owner (the "user" in UMA) may choose their own
          authorization server as an independent cloud-based service, along
          with using any number of resource servers that make up their
          "personal cloud". Thus, there is value in defining a mechanism by
          which all of the third-party resource servers can outsource resource
          protection (and potentially discovery) to a central authorization
          server, as well as ensuring that trust between the authorization
          server and resource servers is able to be established by the
          resource owner in a dynamic, loosely coupled fashion.</t>
        </list></t>

      <t>This specification defines an API through which the resource server
      can register information about resource sets with the authorization
      server.</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 protocol properties and values are case
        sensitive. JSON <xref target="JSON"></xref> data structures defined by
        this specification MAY contain extension properties that are not
        defined in this specification. Any entity receiving or retrieving a
        JSON data structure SHOULD ignore extension properties it is unable to
        understand. Extension names that are unprotected from collisions are
        outside the scope of this specification.</t>
      </section>

      <section anchor="terminology" title="Terminology">
        <t>This specification introduces the following new terms and
        enhancements of OAuth term definitions.<list hangIndent="6"
            style="hanging">
            <t hangText="resource set">One or more resources that the resource
            server manages as a set, abstractly. A resource set may be a
            single API endpoint, a set of API endpoints, a classic web
            resource such as an HTML page, and so on. Defining this concept
            enables registering data about it, including, most importantly,
            scopes but also other data.</t>

            <t hangText="scope">A bounded extent of access that is possible to
            perform on a resource set. In authorization policy terminology, a
            scope is one of the potentially many "verbs" that can logically
            apply to a resource set ("object"). This specification enhances
            the OAuth concept of a "scope" by defining scopes as applying to
            particular registered resource sets, rather than leaving the
            relevant resources (such as API endpoints or URIs) implicit. A
            resource set can have any number of scopes, which together
            describe the universe of actions that <spanx>can be</spanx> taken
            on this protected resource set. For example, a resource set
            representing a status update API might have scopes that include
            adding an update or reading updates. A resource set representing a
            photo album might have scopes that include viewing a slideshow or
            printing the album. The resource server registers resource sets
            and their scopes when there is not yet any particular client in
            the picture.</t>

            <t hangText="resource set registration endpoint">The endpoint
            defined by this specification at which the resource server
            registers resource sets it wants the authorization server to know
            about. The operations available at this endpoint constitute a
            resource set registration API (see <xref
            target="reg-api"></xref>).</t>
          </list></t>
      </section>

      <section anchor="am-endpoints"
               title="Authorization Server Configuration Data">
        <t>If the authorization server declares its endpoints and any other
        configuration data in a machine-readable form, it SHOULD convey its
        resource set registration endpoint in this fashion as well.</t>
      </section>
    </section>

    <section anchor="protecting-a-resource" title="Resource Set Registration">
      <t>This specification defines a resource set registration API. The
      endpoint for this API SHOULD also require some form of authentication to
      access this endpoint, such as Client Authentication as described in
      <xref target="OAuth2"></xref> or a separate OAuth access token. The
      methods of managing and validating these authentication credentials are
      out of scope of this specification.</t>

      <t>For any of the resource owner's sets of resources this authorization
      server needs to be aware of, the resource server MUST register these
      resource sets at the authorization server's registration endpoint.</t>

      <section anchor="action-desc" title="Scope Descriptions">
        <t>A scope description is a JSON document with the following
        properties:<list style="hanging">
            <t hangText="name">REQUIRED. A human-readable string describing
            some scope (extent) of access. This name MAY be used by the
            authorization server in any user interface it presents to the
            resource owner.</t>

            <t hangText="icon_uri">OPTIONAL. A URI for a graphic icon
            representing the scope. The referenced icon MAY be used by the
            authorization server in any user interface it presents to the
            resource owner.</t>
          </list></t>

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

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

        <t>See <xref target="resource-reg-example"></xref> for a long-form
        example of scope descriptions used in resource set registration.</t>
      </section>

      <section anchor="resource-set-desc" title="Resource Set Descriptions">
        <t>The resource server defines a resource set that the authorization
        server needs to be aware of by registering a resource set description
        at the authorization server. This registration process results in a
        unique identifier for the resource set that the resource server can
        later use for managing its description.</t>

        <t>The resource server is free to use its own methods of describing
        resource sets. A resource set description is a JSON document with the
        following properties:<list style="hanging">
            <t hangText="name">REQUIRED. A human-readable string describing a
            set of one or more resources. This name MAY be used by the
            authorization server in its resource owner user interface for the
            resource owner.</t>

            <t hangText="uri">OPTIONAL. A URI that provides the network
            location for the resource set being registered. For example, if
            the resource set corresponds to a digital photo, the value of this
            property could be an HTTP-based URI identifying the location of
            the photo on the web. The authorization server can use this
            information in various ways to inform clients about a resource
            set's location.</t>

            <t hangText="type">OPTIONAL. A string uniquely identifying the
            semantics of the resource set. For example, if the resource set
            consists of a single resource that is an identity claim that
            leverages standardized claim semantics for "verified email
            address", the value of this property could be an identifying URI
            for this claim.</t>

            <t hangText="scopes">REQUIRED. An array of strings, any of which
            MAY be a URI, indicating the available scopes for this resource
            set. URIs MUST resolve to scope descriptions as defined in <xref
            target="action-desc"></xref>. Published scope descriptions MAY
            reside anywhere on the web; a resource server is not required to
            self-host scope descriptions and may wish to point to standardized
            scope descriptions residing elsewhere. It is the resource server's
            responsibility to ensure that scope description documents are
            accessible to authorization servers through GET calls to support
            any user interface requirements. The resource server and
            authorization server are presumed to have separately negotiated
            any required interpretation of scope handling not conveyed through
            scope descriptions.</t>

            <t hangText="icon_uri">OPTIONAL. A URI for a graphic icon
            representing the resource set. The referenced icon MAY be used by
            the authorization server in its resource owner user interface for
            the resource owner.</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
          scope descriptions as defined in <xref
          target="action-desc"></xref>:</preamble>

          <artwork><![CDATA[
{
  "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"
  ],
  "type" : "http://www.example.com/rsets/photoalbum"
}
]]></artwork>
        </figure>
      </section>

      <section anchor="reg-api" title="Resource Set Registration API">
        <t>The resource server uses the RESTful API at the authorization
        server's resource set registration endpoint to create, read, update,
        and delete resource set descriptions, along with retrieving lists of
        such descriptions.</t>

        <t>(Note carefully the similar but distinct senses in which the word
        "resource" is used in this section. The resource set descriptions are
        themselves managed as web resources at the authorization server
        through this API.)</t>

        <t>The authorization server MUST present an API for registering
        resource set descriptions at a set of URIs with the following
        structure:</t>

        <t>{rsreguri}/resource_set</t>

        <t>The {rsreguri} component is the authorization server's resource set
        registration endpoint as advertised in its configuration data (see
        <xref target="am-endpoints"></xref>). Following is a summary of the
        five registration operations the authorization server is REQUIRED to
        support, where the ellipsis represents whatever path segments might
        appear before the required path structure. Each is defined in its own
        section below. All other methods are unsupported. <list
            style="symbols">
            <t>Create resource set description: POST .../resource_set</t>

            <t>Read resource set description: GET .../resource_set/{rsid}</t>

            <t>Update resource set description: PUT
            .../resource_set/{rsid}</t>

            <t>Delete resource set description: DELETE
            .../resource_set/{rsid}</t>

            <t>List resource set descriptions: GET .../resource_set</t>
          </list></t>

        <t>The {rsid} is the authorization server-assigned identifier for the
        web resource corresponding to the resource set as returned in the
        Location header.</t>

        <t>Within the JSON body of a successful response, the authorization
        server includes common properties, possibly in addition to
        method-specific properties, as follows:<list style="hanging">
            <t hangText="_id">REQUIRED (except for the List method). A string
            value repeating the {rsid} as appearing in the Location header.
            Its appearance in both locations allows specialized header and
            body client software to avoid extra parsing.</t>

            <t hangText="user_access_policy_uri">OPTIONAL. A URI that allows
            the resource server to redirect an end-user resource owner to a
            specific user interface within the authorization server where the
            resource owner can immediately set or modify access policies
            subsequent to the resource set registration action just completed.
            The authorization server is free to choose the targeted user
            interface, for example, in the case of a deletion action, enabling
            the resource server to direct the end-user to a policy-setting
            interface for an overall "folder" of resource sets where the
            deleted resource set once resided.</t>
          </list></t>

        <t>If the request to the resource set registration endpoint is
        incorrect, then the authorization server instead responds with an
        error message by including one of the following error codes with the
        response (see <xref target="errors"></xref>):<list style="hanging">
            <t hangText="unsupported_method_type">The resource server request
            used an unsupported HTTP method. The authorization server MUST
            respond with the HTTP 405 (Method Not Allowed) status code and
            MUST fail to act on the request.</t>

            <t hangText="not_found">The resource set requested from the
            authorization server cannot be found. The authorization server
            MUST respond with HTTP 404 (Not Found) status code.</t>
          </list></t>

        <section anchor="create-resource-set"
                 title="Create Resource Set Description">
          <t>Adds a new resource set description using the POST method. If the
          request is successful, the authorization server MUST respond with a
          status message that includes an _id property.</t>

          <figure>
            <preamble>Form of a create request, with an access token in the
            header:</preamble>

            <artwork><![CDATA[
POST /rs/resource_set HTTP/1.1
Content-Type: application/json
Authorization: Bearer 204c69636b6c69
...

(body contains JSON resource set description to be created)
]]></artwork>
          </figure>

          <figure>
            <preamble>Form of a successful response:</preamble>

            <artwork><![CDATA[
HTTP/1.1 201 Created
Content-Type: application/json
Location: /rs/resource_set/12345
...

{
  "_id" : 12345,
  "user_access_policy_uri" : "http://as.example.com/rs/222/resource/333/policy"
}
]]></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. If the request is successful, the authorization server
          MUST respond with a status message that includes a body containing
          the referenced resource set description, along with an "_id"
          property.</t>

          <figure>
            <preamble>Form of a read request, with an access token in the
            header:</preamble>

            <artwork><![CDATA[
GET /rs/resource_set/12345 HTTP/1.1
Authorization: Bearer 204c69636b6c69
...
]]></artwork>
          </figure>

          <figure>
            <preamble>Form of a successful response:</preamble>

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

(body contains _id and resource set description)
]]></artwork>
          </figure>

          <t>If the referenced resource does not exist, the authorization
          server MUST produce an error response with an error property value
          of "not_found", as defined in <xref target="reg-api"></xref>.</t>
        </section>

        <section anchor="update-resource-set"
                 title="Update Resource Set Description">
          <t>Updates a previously registered resource set description using
          the PUT method. If the request is successful, the authorization
          server MUST respond with a status message that includes an "_id"
          property.</t>

          <figure>
            <preamble>Form of an update request, with an access token in the
            header:</preamble>

            <artwork><![CDATA[
PUT /rs/resource_set/12345 HTTP/1.1
Content-Type: application/json
Authorization: Bearer 204c69636b6c69
...

(body contains JSON resource set description to be updated)
]]></artwork>
          </figure>

          <figure>
            <preamble>Form of a successful response:</preamble>

            <artwork><![CDATA[
HTTP/1.1 200 OK
...

{
_"id": "12345"
}

]]></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, thereby removing it from the authorization
          server's protection regime.</t>

          <figure>
            <preamble>Form of a delete request, with an access token in the
            header:</preamble>

            <artwork><![CDATA[
DELETE /rs/resource_set/12345
Authorization: Bearer 204c69636b6c69
...
]]></artwork>
          </figure>

          <figure>
            <preamble>Form of a successful response:</preamble>

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

          <t>As defined in <xref target="reg-api"></xref>, if the referenced
          resource does not exist the authorization server MUST produce an
          error response with an error property value of "not_found".</t>
        </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 authorization server MUST return the
          list in the form of a JSON array of {rsid} string values.</t>

          <t>The resource server uses this method as a first step in checking
          whether its understanding of protected resources is in full
          synchronization with the authorization server's understanding.</t>

          <figure>
            <preamble>Form of a list request, with an access token in the
            header:</preamble>

            <artwork><![CDATA[
GET /rs/resource_set HTTP/1.1
Authorization: Bearer 204c69636b6c69
...
]]></artwork>
          </figure>

          <figure>
            <preamble>Form of a successful response:</preamble>

            <artwork><![CDATA[
HTTP/1.1 200 OK
...

(body contains JSON array of {rsid} values)
]]></artwork>
          </figure>
        </section>
      </section>
    </section>

    <section anchor="errors" title="Error Messages">
      <t>When a resource server attempts to access the resource set
      registration endpoint at the authorization server, if the request is
      successfully authenticated by OAuth means, but is invalid for another
      reason, the authorization server produces an error response by adding
      the following properties to the entity body of the HTTP response:<list
          style="hanging">
          <t hangText="error">REQUIRED. A single error code, as noted in the
          API definition. Value for this property is defined in the specific
          authorization server endpoint description.</t>

          <t hangText="error_description">OPTIONAL. A human-readable text
          providing additional information, used to assist in the
          understanding and resolution of the error occurred.</t>

          <t hangText="error_uri">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.</t>
        </list></t>
    </section>

    <section title="Security Considerations">
      <t>This specification largely relies on OAuth for API security and
      shares its security and vulnerability considerations.</t>

      <t>The resource server itself is presumed to have a trust relationship
      with the authorization server in question, and it registers resource
      sets in the context of a particular resource owner. A malicious resource
      server could register a bad icon URI at an authorization server,
      "infecting" the authorization server either when the icon is retrieved
      or by confusing a human resource owner about the nature of the resource
      set being protected. To accomplish this, the resource server would
      likely have to deceive a resource owner into authorizing it to, first,
      dynamically registering for client credentials at the authorization
      server, and second, outsourcing protection to the authorization
      server.</t>

      <t>An authorization server could mitigate this threat by not displaying
      scope or resource set icons of a dynamically registered resource server
      until such time as it establishes sufficient trust. A less-trusted
      resource server could increase the likelihood of an authorization server
      displaying its icons by choosing icons that are well-known and
      standardized by third parties.</t>
    </section>

    <section title="Privacy Considerations">
      <t>The communication between the authorization server and resource
      server may expose personally identifiable information of a resource
      owner. The context in which this API is used SHOULD account for its own
      unique privacy considerations.</t>
    </section>

    <section anchor="IANA" title="IANA Considerations">
      <t>This document makes no request of IANA.</t>
    </section>

    <section anchor="resource-reg-example"
             title="Example of Registering Resource Sets">
      <t>The following example illustrates the intent and usage of resource
      set descriptions and scope descriptions as part of resource set
      registration in the context of <xref target="UMA"></xref>.</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>A resource owner, Alice Adams, has just uploaded a photo of her new
      puppy to a resource server, Photoz.example.com, and wants to ensure that
      this specific photo is not publicly accessible.</t>

      <t>Alice has already introduced this resource server to her
      authorization server, CopMonkey.example.com. However, Alice has not
      previously instructed Photoz to use CopMonkey to protect any photos of
      hers.</t>

      <t>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 more permissive policies to those
      resources. (User experience only. This may have been done at the time
      Alice introduced the resource server to the authorization server, and/or
      it could have been a global or resource server-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".</t>

      <t>Photoz itself has a publicly documented application-specific 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: "view" (consisting of various read-only operations)
      and "all" (consisting of various reading, editing, and printing
      operations). It defines two scope descriptions that represent these
      scopes, which it is able to reuse for all of its users (not just Alice),
      and ensures that these scope description documents are available through
      HTTP GET requests that may be made by authorization servers.</t>

      <t>The "name" property 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
      authorization server they use. Photoz could distinguish natural-language
      labels per user if it wishes, by pointing to scopes with differently
      translated names.)</t>

      <t>Example of the viewing-related scope description document available
      at http://photoz.example.com/dev/scopes/view:</t>

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

      <t>Example of the broader scope description document available at
      http://photoz.example.com/dev/scopes/all:</t>

      <figure>
        <artwork><![CDATA[
{
  "name" : "All Actions",
  "icon_uri" : "http://www.example.com/icons/galaxy.png"
}
]]></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" property value is intended to be seen by
      Alice in mapping authorization policies to specific resource sets and
      actions when she visits CopMonkey. 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 shown just
      above.</t>

      <figure>
        <artwork><![CDATA[
{
  "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"
  ]
}
]]></artwork>
      </figure>

      <t>Photoz uses the Create method of CopMonkey's standard OAuth resource
      set registration API, presenting its Alice-specific access token to use
      the API to register and assign an identifier to the resource set
      description.</t>

      <figure>
        <artwork><![CDATA[
PUT /rs/resource_set HTTP/1.1
Content-Type: application/json
...

{
  "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"
  ]
}
]]></artwork>
      </figure>

      <t>If the registration attempt succeeds, CopMonkey responds in the
      following fashion.</t>

      <figure>
        <artwork><![CDATA[
HTTP/1.1 201 Created
Content-Type: application/json
...

{
  "_id" : "112210f47de98100"
}
]]></artwork>
      </figure>

      <t>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 authorization server-related tasks
      (user experience only).</t>

      <t>Once it has successfully registered this description, Photoz is
      responsible for outsourcing protection to CopMonkey for access attempts
      made to this photo.</t>

      <t>Over time, as Alice uploads other photos and creates and organizes
      photo albums, 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.</t>

      <t>For example, if Photoz suspects that somehow its understanding of the
      resource set has gotten out of sync with CopMonkey's, it can ask to read
      the resource set description as follows.</t>

      <figure>
        <artwork><![CDATA[
GET /rs/resource_set/112210f47de98100 HTTP/1.1
Host: as.example.com
...
]]></artwork>
      </figure>

      <t>CopMonkey responds with the full content of the resource set
      description, including its _id, as follows:</t>

      <figure>
        <preamble>Example of an HTTP response to a "read resource set
        description" request, containing a resource set description from the
        authorization server:</preamble>

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

{
  "_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"
  ]
}
]]></artwork>
      </figure>

      <t>If for some reason Photoz and CopMonkey have gotten dramatically out
      of sync, Photoz can ask for the list of resource set identifiers
      CopMonkey currently knows about:</t>

      <figure>
        <artwork><![CDATA[
GET /rs/resource_set HTTP/1.1
Host: as.example.com
...
]]></artwork>
      </figure>

      <t>CopMonkey's response might look as follows:</t>

      <figure>
        <artwork><![CDATA[
HTTP/1.1 200 OK
...

[ "112210f47de98100", "34234df47eL95300" ]
]]></artwork>
      </figure>

      <t>If Alice later changes the photo's title (user experience only) on
      Photoz from "Steve the puppy!" to "Steve on October 14, 2011", Photoz
      would use the Update method to ensure that Alice's experience of
      policy-setting at CopMonkey remains consistent with what she sees at
      Photoz. Following is an example of this request.</t>

      <figure>
        <artwork><![CDATA[
PUT /rs/resource_set/112210f47de98100 HTTP/1.1
Content-Type: application/json
Host: as.example.com
...

{
  "name" : "Steve on October 14, 2011",
  "icon_uri" : "http://www.example.com/icons/flower.png",
  "scopes" : [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/all"
  ]
}
]]></artwork>
      </figure>

      <t>CopMonkey would respond as follows.</t>

      <figure>
        <artwork><![CDATA[
HTTP/1.1 201 Created
Content-Type: application/json
...

{
  "_id" : "112210f47de98100"
}
]]></artwork>
      </figure>

      <t>There are other reasons Photoz might want to update resource set
      descriptions, having nothing to do with Alice's actions or wishes. For
      example, it might extend its API to include new features, and want to
      add new scopes to all of Alice's and other users' resource set
      descriptions.</t>

      <t>if Alice later decides to entirely remove sharing protection (user
      experience only) on this photo while visiting Photoz, ensuring that the
      public can get access without any protection, Photoz is responsible for
      deleting the relevant resource set registration, as follows:</t>

      <figure>
        <artwork><![CDATA[
DELETE /rs/resource_set/112210f47de98100 HTTP/1.1
Host: as.example.com
...
]]></artwork>
      </figure>
    </section>

    <section anchor="Acknowledgments" title="Acknowledgments">
      <t>The following people made significant text contributions to the
      specification:<list style="symbols">
          <t>Paul C. Bryan, ForgeRock US, Inc. (former editor)</t>

          <t>Mark Dobrinic, Cozmanova</t>

          <t>George Fletcher, AOL</t>

          <t>Lukasz Moren, Cloud Identity Ltd</t>

          <t>Christian Scholz, COMlounge GmbH (former editor)</t>

          <t>Mike Schwartz, Gluu</t>

          <t>Jacek Szpot, Newcastle University</t>
        </list></t>

      <t>Additional contributors to this specification include the Kantara UMA
      Work Group participants, a list of whom can be found at <xref
      target="UMAnitarians"></xref>.</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>

      <reference anchor="OAuth2" target="http://tools.ietf.org/html/rfc6749">
        <front>
          <title>The OAuth 2.0 Authorization Framework</title>

          <author initials="D." surname="Hardt">
            <organization>IETF</organization>
          </author>

          <date day="" month="October" year="2012" />
        </front>
      </reference>

      <reference anchor="JSON" target="https://tools.ietf.org/html/rfc7159">
        <front>
          <title>The JavaScript Object Notation (JSON) Data Interchange
          Format</title>

          <author initials="T." surname="Bray">
            <organization>Google, Inc.</organization>
          </author>

          <date day="" month="March" year="2014" />
        </front>
      </reference>
    </references>

    <references title="Informative References">
      <reference anchor="UMA"
                 target="http://docs.kantarainitiative.org/uma/draft-uma-core.html">
        <front>
          <title>User-Managed Access (UMA) Profile of OAuth 2.0</title>

          <author initials="T." surname="Hardjono">
            <organization>MIT</organization>
          </author>

          <date day="20" month="December" year="2014" />
        </front>
      </reference>

      <reference anchor="OpenIDConnect"
                 target="http://openid.net/specs/openid-connect-core-1_0.html">
        <front>
          <title>OpenID Connect Core 1.0 incorporating errata set 1</title>

          <author initials="N." surname="Sakimura">
            <organization></organization>
          </author>

          <date day="8" month="November" year="2014" />
        </front>
      </reference>

      <reference anchor="UMAnitarians"
                 target="http://kantarainitiative.org/confluence/display/uma/Participant+Roster">
        <front>
          <title>UMA Participant Roster</title>

          <author initials="E." surname="Maler">
            <organization>Maler</organization>
          </author>

          <date day="" month="December" year="2014" />
        </front>
      </reference>
    </references>
  </back>
</rfc>