draft-uma-scoped-access.xml

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

  <?rfc toc='yes' ?>

  <?rfc tocdepth='3' ?>

  <?rfc symrefs='yes' ?>

  <?rfc sortrefs='yes' ?>

  <?rfc compact='yes' ?>

  <?rfc subcompact='no' ?>

  <?rfc strict='yes' ?>

  <front>
    <title abbrev="UMA Resource Registration">UMA Scoped Access
    Proposal</title>

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

      <address>
        <email>eve@xmlgrrl.com</email>
      </address>
    </author>

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

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

    <date day="21" month="December" year="2010" />

    <abstract>
      <t>This specification proposes a method for achieving scoped access with
      User-Managed Access (UMA). This method assumes that, as currently
      specified in the UMA core protocol, a host must outsource the validation
      of requester access tokens to the authorization manager (AM) when access
      is attempted on a protected resource.</t>
    </abstract>
  </front>

  <middle>
    <section title="Introduction">
      <t>This specification proposes a method for achieving scoped access with
      User-Managed Access <xref target="draft-uma-core">UMA</xref>. This
      method assumes that, as currently specified in the UMA core protocol, a
      host must outsource the validation of requester access tokens to the
      authorization manager (AM) when access is attempted on a protected
      resource.</t>

      <t>After a host registers resource set identifiers and the identifiers
      of permissible actions on those resource sets, the authorization manager
      (AM) is responsible for following the authorizing user's instructions in
      mapping authorization constraints to particular combinations of these
      identifiers. The triple of a set of constraints, a resource set, and a
      list of actions can be considered a "policy", and its latter two-thirds,
      the resource set/actions portion, can be considered a "permission",
      granted by the AM on the user's behalf when the requesting party meets
      the constraints.</t>

      <t>In order to enable communication about scopes and permissions in the
      process of granting and controlling access, this specification defines a
      JSON-formatted data structure that describes a set of one or more
      permissions, called a scope description, and defines how to use a unique
      scope identifier that refers to this description.</t>

      <t>Following is the flow of scope communications.</t>

      <t>Prerequisites before the following steps take place:<list
          style="symbols">
          <t>The host has obtained a host access token from the AM as
          explained in <xref target="draft-uma-core">UMA</xref> step 1. It
          MUST use this token to use the registration API of the AM.</t>

          <t>The host has obtained the URI of the registration API endpoint as
          part of the AM's metadata as described in <xref
          target="draft-uma-core"></xref> step 1.</t>

          <t>The host has already registered resource set and action
          descriptions for this user.</t>
        </list></t>

      <t><list style="numbers">
          <t>Step 1:<list style="letters">
              <t>Host registers resource set descriptions and action
              descriptions with AM (described in <xref
              target="draft-uma-resource-reg"></xref>).</t>

              <t>AM maps authorization constraints to permissions according to
              the user's instructions (independently of the UMA protocol).</t>
            </list></t>

          <t>Step 2:<list style="letters">
              <t>Requester attempts to access protected resource at host,
              allowing host to infer the requester's desired resource set.</t>

              <t>Host tells requester the identifier of a resource set that
              would suffice for access to the resource, and redirects
              requester to AM (defined in this specification for now). It is
              assumed that the requester has out-of-band knowledge of possible
              actions on the resource to which it had attempted access through
              host API documentation.</t>

              <t>Requester asks AM for an access token, specifying the
              identifiers of the desired resource set and action(s) (defined
              in this specification for now). [ISSUE: How does the AM know
              unambiguously which host and user is meant?]</t>

              <t>AM looks up the authorization constraints associated with
              these identifiers and asks for claims as required to satisfy the
              constraints.</t>

              <t>Assuming the constraints are satisfied, AM issues an access
              token and optional refresh token to requester.</t>

              <t>AM registers, in the user-specific portion of the host
              registration area [ISSUE: Necessary to be in the user-specific
              portion, or can it be global to the host-specific portion?], a
              scope description that lists the permissions corresponding to
              the issued access token (defined in this specification for
              now).</t>
            </list></t>

          <t>Step 3:<list style="letters">
              <t>Requester attempts to access the resource again, this time
              presenting its requester access token.</t>

              <t>Host conveys token to AM for validation.</t>

              <t>AM responds saying if the token is still valid (not expired)
              and providing the token's scope identifier (defined in this
              specification for now).</t>

              <t>Host looks up scope description and confirms that the
              attempted access matches the permissions granted for this token
              (defined in this specification for now).</t>
            </list></t>
        </list></t>

      <section title="Notational Conventions">
        <t>The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
        'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
        document are to be interpreted as described in <xref
        target="RFC2119"></xref>.</t>

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

      <section title="Terminology">
        <t>See the core UMA protocol spec [[draft-uma-core]] and the UMA
        resource registration spec [[draft-uma-resource-reg]] for additional
        term definitions.</t>

        <t><list hangIndent="6" style="hanging">
            <t hangText="scope description"><vspace />A JSON-formatted data
            structure that represents a set of one or more permissions that
            have been granted to a requesting party.</t>

            <t hangText="scope identifier">A unique identifier representing a
            scope description. (The word "scope" may be used to represent
            either this identifier or the corresponding description, depending
            on context.)</t>

            <t hangText="permission"><vspace />A resource set identifier and a
            list of action identifiers, which together represent a range of
            access abilities that an authorizing user is willing to grant.</t>
          </list></t>
      </section>
    </section>

    <section title="Host tells requester resource set identifier">
      <t>TBS (see item 2b in flow list above)</t>
    </section>

    <section title="Requester supplies desired resource set and action(s) to AM">
      <t>TBS (see item 2c in flow list above)</t>
    </section>

    <section title="AM registers scope description">
      <t>(See item 2f in flow list above)</t>

      <t>The AM registers scope descriptions as a way to record the
      permissions associated with a requester access token in a persistent
      fashion. A scope description is in JSON [[cite]] form. It is an object
      with the following parameters:</t>

      <t>An action description is an object with the name "scope" and the
      following parameters:<list style="hanging">
          <t hangText="_id">REQUIRED. An identifier that MUST be identical to
          the {scopeid} path component of the scope description URI (see
          below). Some RESTful database technologies provide special features
          for populating this parameter automatically.</t>

          <t hangText="permissions">REQUIRED. Contains an array of at least
          one object that has "resource_set" and "actions" parameters:<list
              style="hanging">
              <t hangText="resource_set">REQUIRED. The identifier of a
              resource set. The identifier MUST correspond to a resource set
              registered by this host for this user at this AM.</t>

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

      <figure>
        <preamble>For example, this description characterizes a scope whose
        single permission involves reading and updating a resource set
        representing "all" resources being protected for this user at this
        host:</preamble>

        <artwork><![CDATA[{
   "scope": {
       "_id": 1234afbd,
       "permissions": [
           {
               "resource_set": "all",
               "actions": [ "read", "update" ]
           }, ...
       ]
   }
}]]></artwork>
      </figure>

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

    <section title="AM provides the token's scope identifier">
      <t>TBS (see item 3c in flow list above)</t>
    </section>

    <section title="Host looks up token's scope description">
      <t>(See item 3d in flow list above)</t>

      <t>The host uses a RESTful API at the AM's host_registration_uri to read
      scope descriptions at the time of token validation. The host MUST use
      its valid host access token obtained previously in UMA protocol step 1
      to gain access to the API.</t>

      <t>Individual scope descriptions are managed at URIs with this
      structure: "{reguri}/host/{hostid}/user/{userid}/scope/{scopeid}"</t>

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

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

          <t hangText="{userid}">The portion of the host's registration area
          at this AM that is specific to this user, assigned during
          registration of resource information for this user.</t>

          <t hangText="{scopeid}">An identifier for a scope description,
          assigned during initial registration of this description.</t>
        </list></t>

      <t>The only allowed scope lookup API operation is:<list style="symbols">
          <t>Read scope description: GET
          /host/{hostid}/user/{userid}/scope/{scopeid}</t>
        </list></t>

      <t>With this operation, a host reads a previously registered scope
      description at the AM using the GET method. If any other HTTP method is
      attempted, the AM MUST respond with a 403 Forbidden message and fail to
      take any other action.</t>

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

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

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

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

(Body contains JSON representation of scope description.)]]></artwork>
      </figure>

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

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

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

      <figure>
        <preamble>HTTP response to any method other than GET or to a {hostid}
        path component that does not match the presented host access token
        (forbidden):</preamble>

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

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

    <section title="Security Considerations">
      <t>TBS</t>
    </section>

    <section title="Privacy Considerations">
      <t>TBS</t>
    </section>

    <section title="TODOs">
      <t><list style="symbols">
          <t>How is the host and user established at the point when the
          requester approaches the AM and when the AM needs to register a
          scope description?</t>

          <t>Should the AM respond to a token validation request by returning
          the applicable scope structure rather than by pointing to it through
          a scope identifier? Alternatively, is the scope description
          mechanism needed at all? If the host were to supply candidate
          resource sets and actions when asking for validation, the AM could
          perform the lookup and matching operation itself, and return a
          simple "YES" or "NO". However, if we chose this option, the host
          could not cache the token/scope mapping, and the scope description
          mechanism would not be available for other uses (such as eventual
          token scope upgrading).</t>
        </list></t>
    </section>

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

    <section title="Document History">
      <t>[[ to be removed by RFC editor before publication as an RFC ]</t>
    </section>
  </middle>

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

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

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

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

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

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

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

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

      <reference anchor="draft-uma-resource-reg">
        <front>
          <title>UMA Resource Registration</title>

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

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

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