draft-oauth-resource-reg-v1_0_1.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 RFC6749 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6749.xml">
<!ENTITY RFC7159 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7159.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-hardjono-oauth-resource-reg-07"
     id="kantara" ipr="kantara">
  <?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>Synergetics</organization>

      <address>
        <email>maciej@synergetics.be</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="" month="September" 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="RFC6749" /> resource server may need to communicate information
      about its protected resources to its authorization server:<list
          style="symbols">
          <t>In some deployments of OAuth 2.0, many resource servers share a
          single authorization server (a role often filled by a security token
          service (STS) component). Thus, whether or not the trust between
          these two is tightly bound, there is value in defining a singular
          standardized communications interface for resource protection
          between the authorization server and each of the resource
          servers.</t>

          <t>In some deployments of OpenID Connect <xref
          target="OpenIDConnect" />, 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 the third-party APs can
          register with a central OP, as well as ensuring that trust between
          the APs and OP is able to be established in a dynamic, loosely
          coupled fashion.</t>

          <t>In some deployments of User-Managed Access <xref target="UMA" />,
          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" />.</t>

        <t>Unless otherwise noted, all protocol properties and values are case
        sensitive. JSON <xref target="RFC7159" /> 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" />). For
            purposes of illustration in this specification, the resource set
            registration endpoint used in examples is <spanx
            style="verb">/rs</spanx>/.</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="RFC6749" /> 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>

      <t>Note: When a client attempts access to a presumptively protected
      resource without an access token, as occurs in <xref target="UMA" />,
      the resource server needs to derive the authorization server and
      resource set identifier associated with that resource from some other
      aspect of the client's request. This effectively means that the resource
      server&rsquo;s API needs to be structured in such a way that the
      client's request without an access token uniquely identifies the
      resource set. In practice, this information likely needs to be passed
      through the URI, headers, or body of the request.</t>

      <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. The authorization server MAY use
            this name in any user interface it presents to 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 MAY use this
            information in various ways to inform clients about a resource
            set's location. Note: When a client attempts access to a
            presumptively protected resource without an access token, the
            resource server needs to ascertain the authorization server and
            resource set identifier associated with that resource without any
            context to guide it. In practice, this likely means that the URI
            reference used by the client needs to be unique per 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. The authorization server MAY use this information
            in processing information about the resource set or displaying
            information about it in any user interface it presents to the
            resource owner.</t>

            <t hangText="scopes">REQUIRED. An array of strings indicating the
            available scopes for this resource set. Any of the strings MAY be
            either a plain string or a URI (see <xref
            target="scope-interpretation" />). If a scope is a URI, then it
            MUST resolve to a scope description document (see <xref
            target="action-desc" />).</t>

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

        <figure>
          <preamble>For example, this description characterizes a resource set
          (a photo album) that can potentially be viewed or printed; the scope
          URI points to a scope description as defined in <xref
          target="action-desc" />:</preamble>

          <artwork><![CDATA[
{
  "name" : "Photo Album",
  "icon_uri" : "http://www.example.com/icons/flower.png",
  "scopes" : [
    "view",
    "http://photoz.example.com/dev/scopes/print"
  ],
  "type" : "http://www.example.com/rsets/photoalbum"
}
]]></artwork>
        </figure>

        <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. The authorization server MAY use
              this name 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 authorization server MAY use the
              referenced icon 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" /> for a long-form
          example of scope descriptions used in resource set registration.</t>
        </section>

        <section anchor="scope-interpretation" title="Scope Interpretation">
          <t>If the resource server uses a plain string for a scope, then the
          resource server and authorization server are presumed to have
          negotiated any required interpretation of scope handling out of
          band.</t>

          <t>If the resource server uses a URI for a scope, the scope's
          published scope description 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 descriptions are accessible to authorization servers through
          GET calls to support any user interface requirements.</t>
        </section>
      </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>
          <spanx style="verb">{rsreguri}/resource_set</spanx>
        </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" />). 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. The <spanx
        style="verb">{_id}</spanx> is the authorization server-assigned
        identifier for the web resource corresponding to the resource set at
        the time it was created, included within the URL returned in the
        Location header.<list style="symbols">
            <t>Create resource set description: POST
            {rsreguri}/resource_set</t>

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

            <t>Update resource set description: PUT
            {rsreguri}/resource_set/{_id}</t>

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

            <t>List resource set descriptions: GET {rsreguri}/resource_set</t>
          </list></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 authorization server-defined identifier for
            the web resource corresponding to the resource set. Its appearance
            in the body makes it readily available as an object identifier for
            various resource set management tasks.</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" />):<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.</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 <spanx style="verb">_id</spanx>
          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 MHg3OUZEQkZBMjcx
...

{
  "name" : "Tweedl Social Service",
  "icon_uri" : "http://www.example.com/icons/sharesocial.png",
  "scopes" : [
    "read-public",
    "post-updates",
    "read-private",
    "http://www.example.com/scopes/all"
  ],
  "type" : "http://www.example.com/rsets/socialstream/140-compatible"
}
]]></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/KX3A-39WE
...

{
  "_id" : "KX3A-39WE",
  "user_access_policy_uri" : "http://as.example.com/rs/222/resource/KX3A-39WE/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 <spanx
          style="verb">_id</spanx> property.</t>

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

            <artwork><![CDATA[
GET /rs/resource_set/KX3A-39WE HTTP/1.1
Authorization: Bearer MHg3OUZEQkZBMjcx
...
]]></artwork>
          </figure>

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

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

{
  "_id" : "KX3A-39WE",
  "name" : "Tweedl Social Service",
  "icon_uri" : "http://www.example.com/icons/sharesocial.png",
  "scopes" : [
    "read-public",
    "post-updates",
    "read-private",
    "http://www.example.com/scopes/all"
  ],
  "type" : "http://www.example.com/rsets/socialstream/140-compatible"
}
]]></artwork>
          </figure>

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

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

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

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

{
  "name" : "Photo Album",
  "icon_uri" : "http://www.example.com/icons/sky.png",
  "scopes" : [
    "http://photoz.example.com/dev/scopes/view",
    "public-read"
  ],
  "type" : "http://www.example.com/rsets/photoalbum"
}
]]></artwork>
          </figure>

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

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

{
  "_id": "9UQU-DUWW"
}

]]></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/9UQU-DUWW
Authorization: Bearer 204c69636b6c69
...
]]></artwork>
          </figure>

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

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

          <t>If the referenced resource set does not exist, the authorization
          server MUST produce an error response with an error property value
          of <spanx style="verb">not_found</spanx>, as defined in <xref
          target="reg-api" />.</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 <spanx
          style="verb">{_id}</spanx> 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
...

[ "KX3A-39WE", "9UQU-DUWW" ]
]]></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. Values for this
          property are defined throughout this specification.</t>

          <t hangText="error_description">OPTIONAL. Human-readable text
          providing additional information.</t>

          <t hangText="error_uri">OPTIONAL. A URI identifying a human-readable
          web page with information about the error.</t>
        </list></t>
    </section>

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

      <t>Some form of trust relationship between the authorization server and
      resource server is presumed. However, where this pairwise trust
      relationship is weak or loosely coupled, for example, if dynamic client
      registration is supported for resource servers as OAuth clients of the
      resource set registration API, the authorization server must be
      extremely careful with any information supplied during resource set
      registration that may be displayed to the resource owner in a user
      interface or be used to drive authorization server-based workflows.</t>

      <t>For example, a rogue resource server could register a resource set or
      scope with a reference to a drive-by download in icons returned by the
      <spanx style="verb">icon_uri</spanx>, enticing the resource owner to
      click on the icon during the policy setting process. The authorization
      server SHOULD check to see if all URIs defined in the <spanx
      style="verb">icon_uri</spanx> and in the array of <spanx
      style="verb">redirect_uris</spanx> resolve to valid web pages. Since
      these are URI values that are intended to be displayed to the resource
      owner in a policy-setting interface, the authorization server SHOULD
      protect the resource owner from malicious content hosted at the URIs
      where possible.</t>

      <t>Additionally, a rogue resource server could supply misleading names
      for a resource set or scope, or mislabel the type of a resource set,
      leading a resource owner to set policy incorrectly.</t>

      <t>One approach to mitigating the threat of bad URIs is that, before
      presenting clickable icons, the authorization server could download the
      content hosted at the linked URIs, check the content against a malware
      scanner and blacklist filter, determine whether or not there is mixed
      secure and non-secure content at the URL, and other possible server-side
      mitigations. Note that the content in these URIs can change at any time
      and the authorization server cannot provide complete confidence in the
      safety of the URIs, but these practices could help. To further mitigate
      this kind of threat, the authorization server can also warn the user
      that the links have been provided by a third party, should be treated
      with caution, and are not hosted by the authorization server itself. For
      instance, instead of providing the links directly in an HTML anchor, the
      authorization server can direct the user to an interstitial warning page
      before allowing the user to continue to the target URI.</t>

      <t>An alternative approach may be available in deployment ecosystems
      where trust relationships with resource servers may be weak but APIs,
      resource set semantics, and scopes have been standardized. A resource
      server could potentially increase the likelihood of an authorization
      server trusting the URIs it registers by using well-known and
      third-party-standardized URIs. This may benefit resource set type values
      as well, if these are represented as URIs.</t>

      <t>In many ways, the resource server depends more heavily on elements of
      the pairwise trust relationship than does the authorization server.
      Since the resource server needs to outsource a variety of resource
      protection-related processes to the authorization server, a rogue or
      impersonated authorization server would present great risk. Using OAuth
      with its attendant channel security requirements for API authentication
      would mitigate the risk of impersonation.</t>

      <t>A small example of the risk posed by a rogue authorization server is
      the user_access_policy_uri property, which is the one case of a URI
      passed from authorization server to resource server rather than the
      reverse. The resource server, in taking advantage of this URI, could
      redirect a resource owner to a third-party web page infected with
      malware or similar. To mitigate this specific risk, the resource server
      could check that the URI is fully qualified and matches the host and
      scheme of the authorization server.</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 non-normative 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" />.</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>This example also does not contain any information regarding the
      mechanism that is used to authenticate the resource server at the
      authorization server, and mechanisms such as OAuth can be used for
      this purpose.</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>CopMonkey has a "default-deny" setup, so until such time as Alice
      maps some other more permissive policies to any resource sets registered
      by Photoz, the policy is not to share them. 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 has a publicly documented application-specific API that offers
      two dozen different methods that apply to single photos, such as <spanx
      style="verb">addTags</spanx> and <spanx style="verb">getSizes</spanx>,
      but rolls them up into two photo-related scopes of access: "view"
      (consisting of various read-only operations) and "print" (consisting of
      various 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>Photoz constructs scope description documents for the scopes in order
      to provide data that will help them be displayed in user interfaces.
      (This means that any scope strings it supplies in resource set
      registration descriptions will need to be URIs referring to these
      documents. The alternative would have been simple scope strings without
      the additional user interface data.)</t>

      <t>The "name" property values in the scope descriptions 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 "Print Photo",
      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 scope description document available at
      http://photoz.example.com/dev/scopes/print:</t>

      <figure>
        <artwork><![CDATA[
{
  "name" : "Print Photo",
  "icon_uri" : "http://www.example.com/icons/printer.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.png",
  "scopes" : [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/print"
  ]
}
]]></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[
POST /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/print"
  ]
}
]]></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",
  "user_access_policy_uri" : "http://as.example.com/rs/222/resource/112210f47de98100/policy"
}
]]></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 <spanx style="verb">_id</spanx>, 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" : "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/print"
  ]
}
]]></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. Note that the entire
      updated resource set description has to be included in the PUT
      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/print"
  ]
}
]]></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 such as photo
      resizing, 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>

          <t>Justin Richer</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" />.</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      &RFC2119;

      &RFC6749;

      &RFC7159;
    </references>

    <references title="Informative References">
      <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 />
          </author>

          <date day="8" month="November" year="2014" />
        </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</title>

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

          <date day="" month="September" year="2015" />
        </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="" year="2015" />
        </front>
      </reference>
    </references>
  </back>
</rfc>