draft-oauth-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 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-03"
     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 RReg">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>

    <date day="20" month="July" year="2014" />

    <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. This revision
      of the specification is part of UMA V0.9.</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 to its
      authorization server information about its protected resources:<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 "CloudOS" authorization
          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 the protocol properties and values are
        case sensitive.</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.</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 labeled 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 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, for example <xref
        target="OAuth-linktypes"></xref> or <xref target="OAuth-meta"></xref>,
        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 is a bounded extent of access that is possible to perform
        on a resource set. 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 its resource owner user interface for 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 its resource owner user interface for the
            resource owner.</t>
          </list></t>

        <figure>
          <preamble>For example, this 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>scope descriptions MAY contain extension properties that are not
        defined in this specification. Extension names that are unprotected
        from collisions are outside the scope of the current
        specification.</t>

        <t>A resource server MUST list a resource set's available scopes using
        URI references (as defined in <xref
        target="resource-set-desc"></xref>). The scopes available for use at
        any one resource server MUST have unique URI references so that the
        resource server's scope descriptions are uniquely distinguishable. A
        scope URI reference MAY include a fragment identifier. Scope
        descriptions MAY reside anywhere. The resource server is not required
        to self-host scope descriptions and may wish to point to standardized
        scope descriptions residing elsewhere. Scope description documents
        MUST be accessible to authorization servers through GET calls made to
        these URI references.</t>

        <t>See <xref target="resource-reg-example"></xref> for a long-form
        example of scopes 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="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>

            <t hangText="scopes">REQUIRED. An array providing the URI
            references of scope descriptions that are available for this
            resource set.</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>
          </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>

        <t>Resource set descriptions MAY contain extension properties that are
        not defined in this specification. Extension names that are
        unprotected from collisions are outside the scope of the current
        specification.</t>

        <t>When a resource server creates or updates a resource set
        description (see <xref target="reg-api"></xref>), the authorization
        server MUST attempt to retrieve the referenced scope descriptions so
        that it can present fresh data in any resource owner interactions.</t>
      </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/{rsid}</t>

        <t>The method of authentication that the resource server uses SHOULD
        sufficient context to distinguish between identical resource set
        identifiers assigned by different resource servers.</t>

        <t>The components of these URIs are defined as follows:<list
            style="hanging">
            <t hangText="{rsreguri}">The authorization server's resource set
            registration endpoint as advertised in its configuration data (see
            <xref target="am-endpoints"></xref>).</t>

            <t hangText="{rsid}">An identifier for a resource set description.
            It is RECOMMENDED to obscure resource set identifiers in order to
            avoid leaking personally identifiable information to clients that
            are exposed to scope information.</t>
          </list></t>

        <t>Following is a summary of the five registration operations the
        authorization server is REQUIRED to support. Each is defined in its
        own section below. All other methods are unsupported. This API uses
        ETag and If-Match to ensure the desired resource at the authorization
        server is targeted.<list style="symbols">
            <t>Create resource set description: PUT /resource_set/{rsid}</t>

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

            <t>Update resource set description: PUT /resource_set/{rsid} with
            If-Match</t>

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

            <t>List resource set descriptions: GET /resource_set/ with
            If-Match</t>
          </list></t>

        <t>If the request to the resource set registration endpoint is
        incorrect, then the authorization server 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>

            <t hangText="precondition_failed">The resource set that was
            requested to be deleted or updated at the authorization server did
            not match the If-Match value present in the request. The
            authorization server MUST respond with HTTP 412 (Precondition
            Failed) status code and MUST fail to act on the request.</t>
          </list></t>

        <section anchor="create-resource-set"
                 title="Create Resource Set Description">
          <t>Adds a new resource set description using the PUT method. If the
          request is successful, the authorization server MUST respond with a
          status message that includes an ETag header and _id and _rev
          properties for managing resource set description versioning.</t>

          <figure>
            <preamble>Form of a "create resource set description" HTTP
            request:</preamble>

            <artwork><![CDATA[
PUT /resource_set/{rsid} HTTP/1.1
Content-Type: application/json
...

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

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

            <artwork><![CDATA[
HTTP/1.1 201 Created
Content-Type: application/json
ETag: (matches "_rev" property in returned object)
...

{
  "status": "created",
  "_id": (id of created resource set),
  "_rev": (ETag of created resource set)
}
]]></artwork>
          </figure>

          <t>On successful registration, the authorization server MAY return a
          redirect policy URI to the resource server in a property with the
          name "policy_uri". This URI allows the resource server to redirect
          the resource owner to a specific user interface within the
          authorization server where the resource owner can immediately set or
          modify access policies for the resource set that was just
          registered.</t>

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

            <artwork><![CDATA[
HTTP/1.1 201 Created
Content-Type: application/json
ETag: (matches "_rev" property in returned object)
...

{
  "status": "created",
  "_id": (id of created resource set),
  "_rev": (ETag of created resource set)
  "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 an ETag header and
          _id and _rev properties for managing resource set description
          versioning.</t>

          <figure>
            <preamble>Form of a "read resource set description" HTTP
            request:</preamble>

            <artwork><![CDATA[
GET /resource_set/{rsid} HTTP/1.1
...
]]></artwork>
          </figure>

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

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

(body contains JSON resource set description, including _id and _rev)
]]></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>

          <t>On successful read, the authorization server MAY return a
          redirect policy URI to the resource server in a property with the
          name "policy_uri". This URI allows the resource server to redirect
          the resource owner to a specific user interface within the
          authorization server where the resource owner can immediately set or
          modify access policies for the resource set that was read.</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 ETag
          header and _id and _rev properties for managing resource set
          description versioning.</t>

          <figure>
            <preamble>Form of an "update resource set description" HTTP
            request:</preamble>

            <artwork><![CDATA[
PUT /resource_set/{rsid} HTTP/1.1
Content-Type: application/json
If-Match: (entity tag of resource)
...

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

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

            <artwork><![CDATA[
HTTP/1.1 204 No Content
ETag: "2"
...
]]></artwork>
          </figure>

          <t>If the entity tag does not match, the authorization server MUST
          produce an error response with an error property value of
          "precondition_failed", as defined in <xref
          target="reg-api"></xref>.</t>

          <t>On successful update, the authorization server MAY return a
          redirect policy URI to the resource server in a property with the
          name "policy_uri". This URI allows the resource server to redirect
          the user to a specific user interface within the authorization
          server where the user can immediately set or modify access policies
          for the resource set that was just updated.</t>
        </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 resource set description" HTTP
            request:</preamble>

            <artwork><![CDATA[
DELETE /resource_set/{rsid}
If-Match: (entity tag of resource)
...
]]></artwork>
          </figure>

          <figure>
            <preamble>Form of a successful HTTP 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", and if
          the entity tag does not match the authorization server MUST produce
          an error response with an error property value of
          "precondition_failed".</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} 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 resource set descriptions" HTTP
            request:</preamble>

            <artwork><![CDATA[
GET /resource_set HTTP/1.1
...
]]></artwork>
          </figure>

          <figure>
            <preamble>HTTP 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 relies on OAuth for API security and shares its
      security and vulnerability considerations.</t>
    </section>

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

    <section anchor="conformance" title="Conformance">
      <t>This specification makes optional normative reference to <xref
      target="OAuth2"></xref> for API protection. This specification is
      anticipated to be used as a module in higher-order specifications, where
      additional constraints and profiling may appear.</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 for the purposes 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 resource set description" 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 /resource_set/112210f47de98100 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
ETag: "1"
...

{
  "status": "created",
  "_id":  "112210f47de98100",
  "_rev": "1"
}
]]></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 /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 and its current _rev, 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
ETag: "1"
...

{
  "_id":  "112210f47de98100",
  "_rev": "1",
  "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 /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 resource set description" 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 /resource_set/112210f47de98100 HTTP/1.1
Content-Type: application/json
Host: as.example.com
If-Match: "1"
...

{
  "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
ETag: "2"
...

{
  "status": "updated",
  "_id":  "112210f47de98100",
  "_rev": "2"
}
]]></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 /resource_set/112210f47de98100 HTTP/1.1
Host: as.example.com
If-Match: "2"
...
]]></artwork>
      </figure>
    </section>

    <section anchor="Acknowledgments" title="Acknowledgments">
      <t>The current editor of this specification is Thomas Hardjono of MIT.
      The following people are co-authors:<list style="symbols">
          <t>Paul C. Bryan, ForgeRock US, Inc.</t>

          <t>Domenico Catalano, Oracle Corp.</t>

          <t>George Fletcher, AOL</t>

          <t>Maciej Machulak, Cloud Identity Ltd</t>

          <t>Eve Maler, ForgeRock</t>

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

          <t>Christian Scholz, COMlounge GmbH</t>

          <t>Nat Sakimura, NRI</t>

          <t>Jacek Szpot, Newcastle University</t>
        </list></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>
    </references>

    <references title="Informative References">
      <reference anchor="OAuth-linktypes"
                 target="http://tools.ietf.org/html/draft-wmills-oauth-lrdd">
        <front>
          <title>Link Type Registrations for OAuth 2</title>

          <author initials="J." surname="Richer">
            <organization></organization>
          </author>

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

      <reference anchor="OAuth-meta"
                 target="http://tools.ietf.org/html/draft-sakimura-oauth-meta">
        <front>
          <title>JSON Metadata for OAuth Responses</title>

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

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

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

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

          <date day="14" month="July" year="2014" />
        </front>
      </reference>

      <reference anchor="OpenIDConnect"
                 target="http://openid.net/specs/openid-connect-core-1_0.html">
        <front>
          <title>OpenID Connect Standard 1.0 - draft 07</title>

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

          <date day="23" month="December" year="2011" />
        </front>
      </reference>
    </references>

    <section anchor="History" title="Document History">
      <t>NOTE: To be removed by RFC editor before publication as an RFC.</t>

      <t>At I-D rev 00:<list style="symbols">
          <t>Broken out of draft-oauth-umacore (post-rev 05) I-D and made
          generic to apply to a variety of OAuth-based use cases.</t>
        </list></t>

      <t>From rev 00 to 01:<list style="symbols">
          <t>Made editorial changes based on comments from Amanda Anganes.</t>

          <t>Removed previously overlooked references to UMA-specific
          constructs in the normative section.</t>
        </list></t>
    </section>
  </back>
</rfc>