rec-uma-core-v1_0.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc PUBLIC "-//IETF//DTD RFC 2629//EN"
"http://xml.resource.org/authoring/rfc2629.dtd" [
<!ENTITY RFC2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2617 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2617.xml">
<!ENTITY UMA PUBLIC "" "http://kantarainitiative.org/confluence/display/uma/Home">
<!ENTITY UMAreqs PUBLIC "" "http://kantarainitiative.org/confluence/display/uma/UMA+Requirements">
<!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY RFC4627 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml">
]>
<rfc category="std" docName="draft-hardjono-oauth-umacore-13"
     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="UMA Core">User-Managed Access (UMA) Profile of OAuth
    2.0</title>

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

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

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

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

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

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

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

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

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

    <abstract>
      <t>User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how
      resource owners can control protected-resource access by clients
      operated by arbitrary requesting parties, where the resources reside on
      any number of resource servers, and where a centralized authorization
      server governs access based on resource owner policies.</t>
    </abstract>
  </front>

  <middle>
    <section anchor="introduction" title="Introduction">
      <t>User-Managed Access (UMA) is a profile of OAuth 2.0 <xref
      target="OAuth2"></xref>. UMA defines how resource owners can control
      protected-resource access by clients operated by arbitrary requesting
      parties, where the resources reside on any number of resource servers,
      and where a centralized authorization server governs access based on
      resource owner policies. Resource owners configure authorization servers
      with access policies that serve as asynchronous authorization
      grants.</t>

      <t>UMA serves numerous use cases where a resource owner uses a dedicated
      service to manage authorization for access to their resources,
      potentially even without the run-time presence of the resource owner. A
      typical example is the following: a web user (an end-user resource
      owner) can authorize a web or native app (a client) to gain one-time or
      ongoing access to a protected resource containing his home address
      stored at a "personal data store" service (a resource server), by
      telling the resource server to respect access entitlements issued by his
      chosen cloud-based authorization service (an authorization server). The
      requesting party operating the client might be the resource owner, where
      the app is run by an e-commerce company that needs to know where to ship
      a purchased item, or the requesting party might be resource owner's
      friend who is using an online address book service to collect contact
      information, or the requesting party might be a survey company that uses
      an autonomous web service to compile population demographics. A variety
      of use cases can be found in <xref target="UMA-usecases"></xref> and
      <xref target="UMA-casestudies"></xref>.</t>

      <t>Practical control of access among loosely coupled parties requires
      more than just messaging protocols. This specification defines only the
      "technical contract" between UMA-conforming entities; a companion
      specification, <xref target="UMA-obligations"></xref>, additionally
      discusses expected behaviors of parties operating and using these
      entities. Parties operating entities that claim to be UMA-conforming
      should provide documentation of any rights and obligations between and
      among them, especially as they pertain the concepts and clauses
      discussed in this companion specification.</t>

      <t>In enterprise settings, application access management sometimes
      involves letting back-office applications serve only as policy
      enforcement points (PEPs), depending entirely on access decisions coming
      from a central policy decision point (PDP) to govern the access they
      give to requesters. This separation eases auditing and allows policy
      administration to scale in several dimensions. UMA makes use of a
      separation similar to this, letting the resource owner serve as a policy
      administrator crafting authorization strategies for resources under
      their control.</t>

      <t>In order to increase interoperable communication among the
      authorization server, resource server, and client, UMA defines two
      purpose-built APIs related to the outsourcing of authorization,
      themselves protected by OAuth (or an OAuth-based authentication
      protocol) in embedded fashion.</t>

      <t>The UMA protocol has three broad phases, as shown in <xref
      target="UMA-phases"></xref>.</t>

      <figure align="center" anchor="UMA-phases">
        <preamble>The Three Phases of the UMA Profile of OAuth</preamble>

        <artwork><![CDATA[                                          +--------------+
                                           |   resource   |
          +---------manage (A)------------ |     owner    |
          |                                +--------------+
          |         Phase 1:                      |
          |         protect a                control (C)
          |         resource                      |
          v                                       v
   +------------+               +----------+--------------+
   |            |               |protection|              |
   |  resource  |               |   API    | authorization|
   |   server   |<-protect (B)--|  (needs  |    server    |
   |            |               |   PAT)   |              |
   +------------+               +----------+--------------+
   | protected  |                          | authorization|
   | resource   |                          |     API      |
   |(needs RPT) |                          |  (needs AAT) |
   +------------+                          +--------------+
          ^                                       |
          |         Phases 2 and 3:         authorize (D)
          |         get authorization,            |
          |         access a resource             v
          |                                +--------------+
          +---------access (E)-------------|    client    |
                                           +--------------+

                                           requesting party
]]></artwork>
      </figure>

      <t>The phases work as follows: <list style="hanging">
          <t hangText="Protect a resource">(Described in <xref
          target="protecting-a-resource"></xref>.) The resource owner, who
          manages online resources at the resource server ("A"), introduces it
          to the authorization server so that the latter can begin protecting
          the resources. To accomplish this, the authorization server presents
          a protection API ("B") to the resource server. This API is protected
          by OAuth (or an OAuth-based authentication protocol) and requires a
          protection API token (PAT) for access. Out of band, the resource
          owner configures the authorization server with policies associated
          with the resource sets ("C") that the resource registers for
          protection.</t>

          <t hangText="Get authorization">(Described in <xref
          target="getting-authz-accessing-resource"></xref>.) The client
          approaches the resource server seeking access to an UMA-protected
          resource. In order to access it successfully, the client must first
          use the authorization server's authorization API ("D") to obtain
          authorization data and a requesting party token (RPT) on behalf of
          its requesting party, and the requesting party may need to supply
          identity claims. The API is protected by OAuth (or an OAuth-based
          authentication protocol) and requires an authorization API token
          (AAT) for access.</t>

          <t hangText="Access a resource">(Described in <xref
          target="getting-authz-accessing-resource"></xref>.) The client
          successfully presents to the resource server an RPT that has
          sufficient authorization data associated with it, gaining access to
          the desired resource ("E"). Phase 3 is effectively the "success
          path" embedded within phase 2.</t>
        </list></t>

      <t>Implementers have the opportunity to develop profiles (see <xref
      target="profiles"></xref>) that specify and restrict various UMA
      protocol, RPT, and identity claim format options, according to
      deployment and usage conditions.</t>

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

        <t>Unless otherwise noted, all protocol properties and values are case
        sensitive. JSON <xref target="JSON"></xref> data structures defined by
        this specification MAY contain extension properties that are not
        defined in this specification. Any entity receiving or retrieving a
        JSON data structure SHOULD ignore extension properties it is unable to
        understand. Extension names that are unprotected from collisions are
        outside the scope of this specification.</t>
      </section>

      <section anchor="terminology" title="Terminology">
        <t>UMA introduces the following new terms and enhancements of OAuth
        term definitions.<list hangIndent="6" style="hanging">
            <t hangText="resource owner"><vspace />An OAuth resource owner
            that is the "user" in User-Managed Access. This is typically an
            end-user (a natural person) but it can also be a corporation or
            other legal person.</t>

            <t hangText="policy">The configuration parameters of an
            authorization server that effect resource access management.
            Authorization policies typically include elements similar to parts
            of speech; for example, "subjects" describe those seeking access
            (requesting parties and clients), "verbs" describe operational
            scopes of access, and "objects" describe targeted resource sets.
            Policy configuration takes place between the resource owner and
            the authorization server, and thus is out of band of UMA.</t>

            <t hangText="requesting party"><vspace />An end-user, or a
            corporation or other legal person, that uses a client to seek
            access to a protected resource. The requesting party may or may
            not be the same party as the resource owner.</t>

            <t hangText="client"><vspace />An application making protected
            resource requests with the resource owner's authorization and on
            the requesting party's behalf.</t>

            <t hangText="claim"><vspace />A statement of the value or values
            of one or more identity attributes of a requesting party. A
            requesting party may need to provide claims to an authorization
            server in order to gain permission for access to a protected
            resource.</t>

            <t hangText="resource set">One or more protected resources that a
            resource server manages as a set, abstractly. In authorization
            policy terminology, a resource set is the "object" being
            protected. This term derives from <xref
            target="OAuth-resource-reg"></xref>.</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"). UMA associates scopes with
            labeled resource sets.</t>

            <t hangText="authorization data">Data associated with an RPT that
            enables some combination of the authorization server and resource
            server to determine the correct extent of access to allow to a
            client. Authorization data is a key part of the definition of an
            RPT profile.</t>

            <t hangText="authorization server"><vspace />A server that issues
            authorization data and RPTs to a client and protects resources
            managed at a resource server.</t>

            <t hangText="permission">A scope of access over a particular
            resource set at a particular resource server that is being
            requested by, or granted to, a requesting party. In authorization
            policy terminology, a permission is an entitlement that includes a
            "subject" (requesting party), "verbs" (one or more scopes of
            access), and an "object" (resource set). A permission is one
            example of authorization data that an authorization server may add
            to a requesting party token.</t>

            <t hangText="permission ticket">A correlation handle that is
            conveyed from an authorization server to a resource server, from a
            resource server to a client, and ultimately from a client back to
            an authorization server, to enable the authorization server to
            assess the correct policies to apply to a request for
            authorization data.</t>

            <t hangText="token">A packaged collection of data meant to be
            transmitted to another entity. A token could be used for
            authorized access (an "access token" such as an UMA RPT, PAT, or
            AAT), or could be used to exchange information about a subject (a
            "claim token" such as one that is conveyed by a client to an
            authorization server while seeking authorization data).</t>
          </list></t>
      </section>

      <section anchor="endpoint-discussion"
               title="Achieving Distributed Access Control">
        <t>The software components that fill the roles of UMA authorization
        servers, resource servers, and clients respectively are intended to
        work in an interoperable fashion when each is operated by an
        independent party (for example, different organizations). For this
        reason, UMA specifies communications channels that the authorization
        server MUST implement as HTTP-based APIs that MUST use TLS and OAuth
        (or OAuth-based authentication protocol) protection, and that the
        resource server MUST implement as an HTTP-based interface. UMA's use
        of TLS is governed by Section 1.6 of <xref target="OAuth2"></xref>,
        which discusses deployment and adoption characteristics of different
        TLS versions.</t>

        <t>For those OAuth protection use cases where an identity token is
        desired in addition to an access token, it is RECOMMENDED that an
        OAuth-based authentication protocol such as OpenID Connect be
        used.</t>

        <t>It is also REQUIRED, in turn, for resource servers and clients on
        the requesting side of UMA interactions to use these channels, unless
        a profile is being used that enables API extensibility. The profiles
        that enable such alternatives are provided in <xref
        target="comms-profiles"></xref>.</t>

        <section anchor="protection-api" title="Protection API">
          <t>The authorization server MUST present an HTTP-based protection
          API, protected by TLS and OAuth (or an OAuth-based authentication
          protocol), for use by resource servers. The authorization server
          thus has an OAuth token endpoint and authorization endpoint. The
          authorization server MUST declare all of its protection API
          endpoints in its configuration data (see <xref
          target="am-endpoints"></xref>).</t>

          <t>The protection API consists of three endpoints:<list
              style="symbols">
              <t>Resource set registration endpoint as defined by <xref
              target="OAuth-resource-reg"></xref></t>

              <t>Permission registration endpoint as defined by <xref
              target="h-am-register-permission"></xref></t>

              <t>Token introspection endpoint as defined by <xref
              target="OAuth-introspection"></xref> and <xref
              target="token-introspection"></xref></t>
            </list></t>

          <t>An entity seeking protection API access MUST have the scope
          "uma_protection". An access token with at least this scope is called
          a protection API token (PAT) and an entity that can acquire an
          access token with this scope is by definition a resource server. A
          single entity can serve in both resource server and client roles if
          it has access tokens with the appropriate OAuth scopes. If a request
          to an endpoint fails due to an invalid, missing, or expired PAT, or
          requires higher privileges at this endpoint than provided by the
          PAT, the authorization server responds with an OAuth error.</t>

          <t>The authorization server MUST support the OAuth bearer token
          profile for PAT issuance, and MAY support other OAuth token
          profiles. It MUST declare all supported token profiles and grant
          types for PAT issuance in its configuration data. Any OAuth
          authorization grant type might be appropriate depending on
          circumstances; for example, the client credentials grant is useful
          in the case of an organization acting as a resource owner. <xref
          target="UMA-Impl"></xref> discusses grant options further.</t>

          <t>A PAT binds a resource owner, a resource server the owner uses
          for resource management, and an authorization server the owner uses
          for protection of resources at this resource server. It is not
          specific to any client or requesting party. The issuance of a PAT
          represents the approval of the resource owner for this resource
          server to use this authorization server for protecting some or all
          of the resources belonging to this resource owner.</t>
        </section>

        <section anchor="authorization-api" title="Authorization API">
          <t>The authorization server MUST present an HTTP-based authorization
          API, protected by TLS and OAuth (or an OAuth-based authentication
          protocol), for use by clients. The authorization server thus has an
          OAuth token endpoint and authorization endpoint. The authorization
          server MUST declare its authorization API endpoint in its
          configuration data (see <xref target="am-endpoints"></xref>).</t>

          <t>The authorization API consists of one endpoint:<list
              style="symbols">
              <t>RPT endpoint as defined in <xref
              target="authz-permission-token"></xref></t>
            </list></t>

          <t>An entity seeking authorization API access MUST have the scope
          "uma_authorization". An access token with at least this scope is
          called an authorization API token (AAT) and an entity that can
          acquire an access token with this scope is by definition a client. A
          single entity can serve in both resource server and client roles if
          it has access tokens with the appropriate OAuth scopes. If a request
          to an endpoint fails due to an invalid, missing, or expired AAT, or
          requires higher privileges at this endpoint than provided by the
          AAT, the authorization server responds with an OAuth error.</t>

          <t>The authorization server MUST support the OAuth bearer token
          profile for AAT issuance, and MAY support other OAuth token
          profiles. It MUST declare all supported token profiles and grant
          types for AAT issuance in its configuration data. Any OAuth
          authorization grant type might be appropriate depending on
          circumstances; for example, the client credentials grant is useful
          in the case of an organization acting as a requesting party. <xref
          target="UMA-Impl"></xref> discusses grant options further.</t>

          <t>An AAT binds a requesting party, a client being used by that
          party, and an authorization server that protects resources this
          client is seeking access to on this requesting party's behalf. It is
          not specific to any resource server or resource owner. The issuance
          of an AAT represents the approval of this requesting party for this
          client to engage with this authorization server to supply claims,
          ask for authorization, and perform any other tasks needed for
          obtaining authorization for access to resources at all resource
          servers that use this authorization server. The authorization server
          is able to manage future processes of authorization and
          claims-caching efficiently for this client/requesting party pair
          across all resource servers they try to access; however, these
          management processes are outside the scope of this
          specification.</t>
        </section>

        <section anchor="resource-api" title="Protected Resource Interface">
          <t>The resource server MAY present to clients whatever HTTP-based
          APIs or endpoints it wishes. To protect any of its resources
          available in this fashion using UMA, it MUST require a requesting
          party token (RPT) with sufficient authorization data for access.</t>

          <t>This specification defines one RPT profile, call "bearer" (see
          <xref target="uma-bearer-token-profile"></xref>), which the
          authorization server MUST support. It MAY support additional RPT
          profiles, and MUST declare all supported RPT profiles in its
          configuration data (see <xref target="am-endpoints"></xref>).</t>

          <t>An RPT binds a requesting party, the client being used by that
          party, the resource server at which protected resources of interest
          reside, and the authorization server that protects those resources.
          It is not specific to a single resource owner, though its internal
          components are likely to be bound in practice to individual resource
          owners, depending on the RPT profile in use.</t>
        </section>

        <section title="Time-to-Live Considerations">
          <t>The authorization server has the opportunity to manage the
          validity periods of access tokens that it issues, their
          corresponding refresh tokens where applicable, the individual
          authorization data components associated with RPTs where applicable,
          and even the client credentials that it issues. Different
          time-to-live strategies may be suitable for different resource sets
          and scopes of access, and the authorization server has the
          opportunity to give the resource owner control over lifetimes of
          tokens and authorization data issued on their behalf through policy.
          These options are all outside the scope of this specification.</t>
        </section>
      </section>

      <section anchor="am-endpoints"
               title="Authorization Server Configuration Data">
        <t>The authorization server MUST provide configuration data in a JSON
        document that resides in an /uma-configuration directory at its
        host-meta <xref target="hostmeta"></xref> location. The configuration
        data documents conformance options and endpoints supported by the
        authorization server.</t>

        <t>The configuration data has the following properties.<list
            hangIndent="6" style="hanging">
            <t hangText="version"><vspace />REQUIRED. The version of the UMA
            core protocol to which this authorization server conforms. The
            value MUST be the string "1.0".</t>

            <t hangText="issuer"><vspace />REQUIRED. A URI with no query or
            fragment component that the authorization server asserts as its
            issuer identifier. This value MUST be identical to the web
            location of the configuration data minus the host-meta [hostmeta]
            and /uma-configuration path components</t>

            <t hangText="pat_profiles_supported"><vspace />REQUIRED. OAuth
            access token types supported by this authorization server for PAT
            issuance. The property value is an array of string values, where
            each string value (which MAY be a URI) is a token type. Non-URI
            token type strings defined by OAuth token-defining specifications
            are privileged. For example, the type "bearer" stands for the
            OAuth bearer token type defined in <xref
            target="OAuth-bearer"></xref>. The authorization server is
            REQUIRED to support "bearer", and to supply this value explicitly.
            The authorization server MAY declare its support for additional
            PAT profiles.</t>

            <t hangText="aat_profiles_supported"><vspace />REQUIRED. OAuth
            access token types supported by this authorization server for AAT
            issuance. The property value is an array of string values, where
            each string value (which MAY be a URI) is a token type. Non-URI
            token type strings defined by OAuth token-defining specifications
            are privileged. For example, the type "bearer" stands for the
            OAuth bearer token type defined in <xref
            target="OAuth-bearer"></xref>. The authorization server is
            REQUIRED to support "bearer", and to supply this value explicitly.
            The authorization server MAY declare its support for additional
            AAT profiles.</t>

            <t hangText="rpt_profiles_supported"><vspace />REQUIRED. Profiles
            supported by this authorization server for RPT issuance. The
            property value is an array of string values, where each string
            value is a URI identifying an RPT profile. The authorization
            server is REQUIRED to support the "bearer" RPT profile defined in
            <xref target="uma-bearer-token-profile"></xref>, and to supply its
            identifying URI explicitly. The authorization server MAY declare
            its support for additional RPT profiles.</t>

            <t hangText="pat_grant_types_supported"><vspace />REQUIRED. OAuth
            grant types supported by this authorization server in issuing
            PATs. The property value is an array of string values, where each
            string value (which MAY be a URI) is a grant type. Non-URI token
            type strings defined by OAuth grant type-defining specifications
            are privileged. For example, the type "authorization_code" stands
            for the OAuth authorization code grant type defined in <xref
            target="OAuth2"></xref>.</t>

            <t hangText="aat_grant_types_supported"><vspace />REQUIRED. OAuth
            grant types supported by this authorization server in issuing
            AATs. The property value is an array of string values, where each
            string value (which MAY be a URI) is a grant type. Non-URI token
            type strings defined by OAuth grant type-defining specifications
            are privileged. For example, the type "authorization_code" stands
            for the OAuth authorization code grant type defined in <xref
            target="OAuth2"></xref>.</t>

            <t hangText="claim_token_profiles_supported"><vspace />OPTIONAL.
            Claim token format profiles supported by this authorization
            server. The property value is an array of string values, where
            each string value MAY be a URI.</t>

            <t hangText="uma_profiles_supported"><vspace />OPTIONAL. UMA
            profiles supported by this authorization server. The property
            value is an array of string values, where each string value is a
            URI identifying an UMA profile. Examples of UMA profiles are the
            API extensibility profiles defined in <xref
            target="comms-profiles"></xref>.</t>

            <t hangText="dynamic_client_endpoint"><vspace />OPTIONAL. The
            endpoint to use for performing dynamic client registration in the
            case of the use of <xref target="DynClientReg"></xref>, or
            alternatively the reserved string "openid" in the case of the use
            of <xref target="OIDCDynClientReg"></xref>. In the latter case, it
            is presumed that the resource server or client will discover the
            dynamic client registration endpoint from the authorization
            server's published OpenID Provider Configuration Information. The
            presence of this property indicates authorization server support
            for dynamic client registration feature; its absence indicates a
            lack of support.</t>

            <t hangText="token_endpoint"><vspace />REQUIRED. The endpoint URI
            at which the resource server or client asks the authorization
            server for a PAT or AAT. A requested scope of "uma_protection"
            results in a PAT. A requested scope of "uma_authorization" results
            in an AAT. Usage of this endpoint is defined by <xref
            target="OAuth2"></xref>.</t>

            <t hangText="authorization_endpoint"><vspace />REQUIRED. The
            endpoint URI at which the resource server gathers the consent of
            the end-user resource owner or the client gathers the consent of
            the end-user requesting party for issuance of a PAT or AAT
            respectively, if the "authorization_code" grant type is used.
            Usage of this endpoint is defined by <xref
            target="OAuth2"></xref>.</t>

            <t hangText="requesting_party_claims_endpoint"><vspace />OPTIONAL.
            The endpoint URI at which the authorization server interacts with
            the end-user requesting party to gather claims. If this property
            is absent, the authorization server does not interact with the
            end-user requesting party for claims gathering.</t>

            <t hangText="introspection_endpoint"><vspace />REQUIRED. The
            endpoint URI at which the resource server introspects an RPT
            presented to it by a client. Usage of this endpoint is defined by
            <xref target="OAuth-introspection"></xref> and <xref
            target="token-introspection"></xref>. A valid PAT MUST accompany
            requests to this protected endpoint.</t>

            <t
            hangText="resource_set_registration_endpoint"><vspace />REQUIRED.
            The endpoint URI at which the resource server registers resource
            sets to put them under authorization manager protection. Usage of
            this endpoint is defined by <xref
            target="OAuth-resource-reg"></xref> and <xref
            target="protecting-a-resource"></xref>. A valid PAT MUST accompany
            requests to this protected endpoint.</t>

            <t hangText="permission_registration_endpoint"><vspace />REQUIRED.
            The endpoint URI at which the resource server registers a
            requested permission that would suffice for a client's access
            attempt. Usage of this endpoint is defined by <xref
            target="h-am-register-permission"></xref>. A valid PAT MUST
            accompany requests to this protected endpoint.</t>

            <t hangText="rpt_endpoint"><vspace />REQUIRED. The endpoint URI at
            which the client asks for authorization data. Usage of this
            endpoint is defined in <xref
            target="r-am-obtain-permission"></xref>. A valid AAT and a
            permission ticket MUST, and an RPT MAY, accompany requests to this
            protected endpoint.</t>
          </list></t>

        <figure>
          <preamble>Example of authorization server configuration data that
          resides at https://example.com/.well-known/uma-configuration (note
          the use of https: for endpoints throughout):</preamble>

          <artwork><![CDATA[{
"version":"1.0",
"issuer":"https://example.com",
"pat_profiles_supported":["bearer"],
"aat_profiles_supported":["bearer"],
"rpt_profiles_supported":
["https://docs.kantarainitiative.org/uma/profiles/uma-token-bearer-1.0"],
"pat_grant_types_supported":["authorization_code"],
"aat_grant_types_supported":["authorization_code"],
"claim_token_profiles_supported":["https://example.com/claims/formats/token1"],
"dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri",
"token_endpoint":"https://as.example.com/token_uri",
"authorization_endpoint":"https://as.example.com/authz_uri",
"requesting_party_claims_endpoint":"https://as.example.com/rqp_claims_uri",
"resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri",
"introspection_endpoint":"https://as.example.com/rs/status_uri",
"permission_registration_endpoint":"https://as.example.com/rs/perm_uri",
"rpt_endpoint":"https://as.example.com/client/rpt_uri"
}]]></artwork>
        </figure>

        <t>Where this specification does not already require optional features
        to be documented, it is RECOMMENDED that authorization server
        deployers document any profiled or extended features explicitly and
        use configuration data to indicate their usage.</t>
      </section>
    </section>

    <section anchor="protecting-a-resource" title="Protecting a Resource">
      <t>The resource owner, resource server, and authorization server perform
      the following actions to put resources under protection. This list
      assumes that the resource server has discovered the authorization
      server's configuration data and endpoints as needed.<list
          style="numbers">
          <t>The authorization server issues client credentials to the
          resource server. It is OPTIONAL for the client credentials to be
          provided dynamically through <xref target="DynClientReg"></xref> or
          <xref target="OIDCDynClientReg"></xref>; alternatively, they MAY use
          a static process.</t>

          <t>The resource server acquires a PAT from the authorization server.
          It is OPTIONAL for the resource owner to introduce the resource
          server to the authorization server dynamically (for example, through
          a "NASCAR"-style user interface where the resource owner selects a
          chosen authorization server); alternatively, they MAY use a static
          process that may or may not directly involve the resource owner at
          introduction time.</t>

          <t>In an ongoing fashion, the resource server registers any resource
          sets with the authorization server for which it intends to outsource
          protection, using the resource set registration endpoint of the
          protection API (see <xref target="OAuth-resource-reg"></xref>).</t>
        </list></t>

      <t>Note: The resource server is free to offer the option to protect any
      subset of the resource owner's resources using different authorization
      servers or other means entirely, or to protect some resources and not
      others. Additionally, the choice of protection regimes can be made
      explicitly by the resource owner or implicitly by the resource server.
      Any such partitioning by the resource server or owner is outside the
      scope of this specification.</t>

      <t>Once a resource set has been placed under authorization server
      protection through the registration of a resource set description for
      it, and until such a description's deletion by the resource server, the
      resource server MUST limit access to corresponding resources, requiring
      sufficient authorization data associated with client-presented RPTs by
      the authorization server (see <xref
      target="client-presents-rpt"></xref>).</t>
    </section>

    <section anchor="getting-authz-accessing-resource"
             title="Getting Authorization and Accessing a Resource">
      <t>An authorization server orchestrates and controls clients' access (on
      their requesting parties' behalf) to a resource owner's protected
      resources at a resource server, under conditions dictated by that
      resource owner.</t>

      <t>The process of getting authorization and accessing a resource always
      begins with the client attempting access at a protected resource
      endpoint at the resource server. How the client came to learn about this
      endpoint is out of scope for this specification. The resource owner
      might, for example, have advertised its availability publicly on a blog
      or other website, listed it in a discovery service, or emailed a link to
      a particular intended requesting party.</t>

      <t>The resource server responds to the client's access request with
      whatever its application-specific resource interface defines as a
      success response, either immediately if the client has sufficient
      authorization, or having first performed one or more embedded
      interactions with the authorization server and client in the case of a
      failed access attempt.</t>

      <t>A high-level summary of the interactions is as follows. The recipient
      of each request message SHOULD respond unless it detects a security
      concern, such as a suspected denial of service attack that can be
      mitigated by rate limiting.<list style="symbols">
          <t>The client attempts to access a protected resource.<list
              style="symbols">
              <t>If the access attempt is unaccompanied by an RPT, the
              resource server registers a requested permission at the
              authorization server that would suffice for the access attempt,
              and then responds with an HTTP 403 (Forbidden) response, a
              permission ticket, and instructions on where to go to obtain an
              RPT and authorization data.</t>

              <t>If the access attempt is accompanied by an RPT, the resource
              server checks the RPT's status.<list style="symbols">
                  <t>If the RPT is invalid, or if the RPT is valid but has
                  insufficient authorization data, the resource server
                  registers a requested permission at the authorization server
                  that would suffice for the access attempt, and then responds
                  with an HTTP 403 (Forbidden) response, a permission ticket,
                  and instructions on where to go to obtain a valid RPT and
                  authorization data for it.</t>

                  <t>If the RPT is valid, and if the authorization data
                  associated with the token is sufficient for allowing access,
                  the resource server responds with an HTTP 2xx (Success)
                  response.</t>
                </list></t>
            </list></t>

          <t>If the client received a 403 response and a permission ticket, it
          asks the authorization server for authorization data that matches
          the ticket using the RPT endpoint of the authorization API. If the
          authorization server needs requesting party claims in order to
          assess this client's authorization, it engages in a claims-gathering
          flow.<list style="symbols">
              <t>If the client does not already have an AAT at the appropriate
              authorization server to be able to use its authorization API, it
              first obtains one.</t>
            </list></t>
        </list></t>

      <t>The interactions are described in detail in the following
      sections.</t>

      <section anchor="r-h-attempt-access"
               title="Client Attempts to Access Protected Resource">
        <t>This interaction assumes that the resource server has previously
        registered one or more resource sets that correspond to the resource
        the client is attempting to access.</t>

        <t>The client attempts to access a protected resource (for example,
        when an end-user requesting party clicks on a thumbnail representation
        of the resource to retrieve a larger version). It is expected to
        discover, or be provisioned or configured with, knowledge of the
        protected resource and its location out of band. Further, the client
        is expected to acquire its own knowledge about the
        application-specific methods made available by the resource server for
        operating on this protected resource (such as viewing it with a GET
        method, or transforming it with some complex API call).</t>

        <t>The access attempt either is or is not accompanied by an RPT.</t>

        <section anchor="no-rpt" title="Client Presents No RPT">
          <figure>
            <preamble>Example of a request carrying no RPT:</preamble>

            <artwork><![CDATA[
GET /album/photo.jpg HTTP/1.1
Host: photoz.example.com
...
]]></artwork>
          </figure>

          <t>If the client does not present an RPT with the request, the
          resource server uses the protection API to register a requested
          permission with the authorization server that would suffice for the
          access attempt (see <xref
          target="h-am-register-permission"></xref>), and receives a
          permission ticket back in response. It then responds to the client.
          It SHOULD respond with the HTTP 403 (Forbidden) status code,
          providing the authorization server's URI in an "as_uri" property in
          the header, along with the just-received permission ticket in the
          body in a JSON-encoded "ticket" property. Responses that use any
          code other than 403 are undefined by this specification; any common
          or best practices for returning other status codes will be
          documented in the <xref target="UMA-Impl"></xref>.</t>

          <figure>
            <preamble>For example:</preamble>

            <artwork><![CDATA[
HTTP/1.1 403 Forbidden
WWW-Authenticate: UMA realm="example",
  as_uri="https://as.example.com"

{
"ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
}
   ...
]]></artwork>
          </figure>
        </section>

        <section anchor="client-presents-rpt" title="Client Presents RPT">
          <figure>
            <preamble>Example of a request carrying an RPT using the UMA
            "bearer" RPT profile:</preamble>

            <artwork><![CDATA[
GET /album/photo.jpg HTTP/1.1
Authorization: Bearer vF9dft4qmT
Host: photoz.example.com
...
]]></artwork>
          </figure>

          <t>If the client presents an RPT with its request, the resource
          server MUST determine the RPT's status (see <xref
          target="h-am-rpt-status"></xref>) before responding.</t>

          <t>If the RPT is invalid, or if the RPT is valid but has
          insufficient authorization data for the type of access sought, the
          resource server uses the protection API to register a requested
          permission with the authorization server that would suffice for the
          access attempt (see <xref
          target="h-am-register-permission"></xref>), and receives a
          permission ticket back in response. It then responds to the client
          with the HTTP 403 (Forbidden) status code, providing the
          authorization server's URI in an "as_uri" property in the header,
          along with the just-received permission ticket in the body in a
          JSON-encoded "ticket" property.</t>

          <figure>
            <preamble>Example of the resource server's response after having
            registered a requested permission and received a
            ticket:</preamble>

            <artwork><![CDATA[
HTTP/1.1 403 Forbidden
WWW-Authenticate: UMA realm="example",
  as_uri="https://as.example.com"
  error="insufficient_scope"

{
"ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
}
]]></artwork>
          </figure>

          <t>If the RPT's status is associated with authorization data that is
          sufficient for the access sought by the client, the resource server
          MUST give access to the desired resource.</t>

          <figure>
            <preamble>Example of the resource server's response after having
            determined that the RPT is valid and associated with sufficient
            authorization data:</preamble>

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

/9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja
3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf
/bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo
KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb
]]></artwork>
          </figure>

          <t>The resource server MUST NOT give access where the token's status
          is not associated with sufficient authorization data for the
          attempted scope of access.</t>
        </section>
      </section>

      <section anchor="h-am-register-permission"
               title="Resource Server Registers Requested Permission With Authorization Server">
        <t>The resource server uses the protection API's permission
        registration endpoint to register a requested permission with the
        authorization server that would suffice for the client's access
        attempt. The authorization server returns a permission ticket for the
        resource server to give to the client in its response. The PAT
        provided in the API request implicitly identifies the resource owner
        ("subject") to which the permission applies.</t>

        <t>Note: The resource server is free to choose the extent of the
        requested permission that it registers, as long as it minimally
        suffices for the access attempted by the client. For example, it can
        choose to register a permission that covers several scopes or a
        resource set that is greater in extent than the specific resource that
        the client attempted to access. Likewise, the authorization server is
        ultimately free to choose to partially fulfill the elements of a
        permission request based on incomplete satisfaction of policy
        criteria, or not to fulfill the request.</t>

        <t>The resource server uses the POST method at the endpoint. The body
        of the HTTP request message contains a JSON object providing the
        requested permission, using a format derived from the scope
        description format specified in <xref
        target="OAuth-resource-reg"></xref>, as follows. The object has the
        following properties:<list style="hanging">
            <t hangText="resource_set_id">REQUIRED. The identifier for a
            resource set to which this client is seeking access. The
            identifier MUST correspond to a resource set that was previously
            registered.</t>

            <t hangText="scopes">REQUIRED. An array referencing one or more
            identifiers of scopes to which access is needed for this resource
            set. Each scope identifier MUST correspond to a scope that was
            registered by this resource server for the referenced resource
            set.</t>
          </list></t>

        <figure>
          <preamble>Example of an HTTP request that registers a requested
          permission at the authorization server's permission registration
          endpoint, with a PAT in the header:</preamble>

          <artwork><![CDATA[
POST /host/scope_reg_uri/photoz.example.com HTTP/1.1
Content-Type: application/json
Host: as.example.com
Authorization: Bearer 204c69636b6c69

{
  "resource_set_id": "112210f47de98100",
  "scopes": [
      "http://photoz.example.com/dev/actions/view",
      "http://photoz.example.com/dev/actions/all"
  ]
}
]]></artwork>
        </figure>

        <t>If the registration request is successful, the authorization server
        responds with an HTTP 201 (Created) status code and includes the
        "ticket" property in the JSON-formatted body.</t>

        <t>The permission ticket is a short-lived opaque structure whose form
        is determined by the authorization server. The ticket value MUST be
        securely random (for example, not merely part of a predictable
        sequential series), to avoid denial-of-service attacks. Since the
        ticket is an opaque structure from the point of view of the client,
        the authorization server is free to include information regarding
        expiration time or any other information within the opaque ticket for
        its own consumption. When the client subsequently uses the
        authorization API to ask the authorization server for authorization
        data to be associated with its RPT, it will submit this ticket to the
        authorization server.</t>

        <figure>
          <preamble>For example:</preamble>

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

{
"ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
}
]]></artwork>
        </figure>

        <t>If the registration request is authenticated properly but fails due
        to other reasons, the authorization server responds with an HTTP 400
        (Bad Request) status code and includes one of the following UMA error
        codes (see <xref target="uma-error-response"></xref>):<list
            style="hanging">
            <t hangText="invalid_resource_set_id">The provided resource set
            identifier was not found at the authorization server.</t>

            <t hangText="invalid_scope">At least one of the scopes included in
            the request was not registered previously by this resource
            server.</t>
          </list></t>
      </section>

      <section anchor="h-am-rpt-status"
               title="Resource Server Determines RPT's Status">
        <t>The resource server MUST determine a received RPT's status,
        including both whether it is active and, if so, its associated
        authorization data, before giving or refusing access to the client. An
        RPT is associated with a set of authorization data that governs
        whether the client is authorized for access. The token's nature and
        format are dictated by its profile; the profile might allow it to be
        self-contained, such that the resource server is able to determine its
        status locally, or might require or allow the resource server to make
        a run-time introspection request of the authorization server that
        issued the token.</t>

        <t>This specification makes one type of RPT REQUIRED for the
        authorization server to support: the UMA bearer token profile, as
        defined in <xref target="uma-bearer-token-profile"></xref>.
        Implementers MAY define and use other RPT profiles.</t>

        <section anchor="token-introspection" title="Token Introspection">
          <t>Within any RPT profile, when a resource server needs to
          introspect a token in a non-self-contained way to determine its
          status, it MAY require, allow, or prohibit use of the OAuth token
          introspection endpoint (defined by <xref
          target="OAuth-introspection"></xref>) that is part of the protection
          API, and MAY profile its usage. The resource server MUST use the
          POST method in interacting with the endpoint, not the GET method
          also defined by <xref target="OAuth-introspection"></xref>.</t>
        </section>

        <section anchor="uma-bearer-token-profile" title="RPT Profile: Bearer">
          <t>This section defines the UMA bearer token profile. Following is a
          summary:<list style="symbols">
              <t>Identifying URI:
              https://docs.kantarainitiative.org/uma/profiles/uma-token-bearer-1.0</t>

              <t>Profile author and contact information: Thomas Hardjono
              (hardjono@mit.edu)</t>

              <t>Updates or obsoletes: None; this profile is new.</t>

              <t>Keyword in HTTP Authorization header: "Bearer".</t>

              <t>Syntax and semantics of token data: As defined below; an
              opaque string value, resolving to an extended JSON Web Token
              (JWT) <xref target="JWT"></xref> format on introspection at the
              authorization server.</t>

              <t>Token data association: The on-the-wire token is opaque; it
              is introspected at run time by the resource server through
              profiled use of the OAuth token introspection endpoint <xref
              target="OAuth-introspection"></xref>, as defined below.</t>

              <t>Token data processing: As defined in this section and
              throughout <xref
              target="getting-authz-accessing-resource"></xref> of this
              specification.</t>

              <t>Grant type restrictions: None.</t>

              <t>Error states: As defined below.</t>

              <t>Security and privacy considerations: As defined in this
              section, throughout <xref
              target="getting-authz-accessing-resource"></xref>, and in <xref
              target="sec-consid"></xref>.</t>
            </list></t>

          <t>An example of a client making a request with an RPT using the
          "Bearer" scheme appears in <xref
          target="client-presents-rpt"></xref>.</t>

          <t>On receiving an RPT with the "Bearer" scheme in an authorization
          header from a client making an access attempt, the resource server
          introspects the token by using the token introspection endpoint of
          the protection API. The PAT used by the resource server to make the
          introspection request provides resource-owner context to the
          authorization server.</t>

          <t>The authorization server responds with a JSON object with the
          structure dictated by <xref target="OAuth-introspection"></xref>. If
          the "active" property has a Boolean value of true, then the JSON
          object MUST NOT contain a "scope" claim, and MUST contain an
          extension property with the name "permissions" that contains an
          array of zero or more values, each of which is an object consisting
          of these properties:<list style="hanging">
              <t hangText="resource_set_id">REQUIRED. A string that uniquely
              identifies the resource set, access to which has been granted to
              this client on behalf of this requesting party. The identifier
              MUST correspond to a resource set that was previously registered
              as protected.</t>

              <t hangText="scopes">REQUIRED. An array referencing one or more
              URIs of scopes to which access was granted for this resource
              set. Each scope MUST correspond to a scope that was registered
              by this resource server for the referenced resource set.</t>

              <t hangText="exp">OPTIONAL. Integer timestamp, measured in the
              number of seconds since January 1 1970 UTC, indicating when this
              permission will expire. If the property is absent, the
              permission does not expire. If the token-level "exp" value
              pre-dates a permission-level "exp" value, the former overrides
              the latter.</t>

              <t hangText="iat">OPTIONAL. Integer timestamp, measured in the
              number of seconds since January 1 1970 UTC, indicating when this
              permission was originally issued. If the token-level "iat" value
              post-dates a permission-level "iat" value, the former overrides
              the latter.</t>

              <t hangText="nbf">OPTIONAL. Integer timestamp, measured in the
              number of seconds since January 1 1970 UTC, indicating the time
              before which this permission is not valid. If the token-level
              "nbf" value post-dates a permission-level "nbf" value, the
              former overrides the latter.</t>
            </list></t>

          <figure>
            <preamble>Example:</preamble>

            <artwork><![CDATA[
HTTP/1.1 200 OK
   Content-Type: application/json
   Cache-Control: no-store

   {
    "active": true,
    "exp": 1256953732,
    "iat": 1256912345,
    "permissions": [
      {
        "resource_set_id": "112210f47de98100",
        "scopes": [
          "http://photoz.example.com/dev/actions/view",
          "http://photoz.example.com/dev/actions/all"
         ],
        "exp" : 1256953732
      }
    ]
   }
]]></artwork>
          </figure>
        </section>
      </section>

      <section anchor="r-am-obtain-permission"
               title="Client Seeks Authorization for Access">
        <t>In order to access a protected resource successfully, a client
        needs to present a valid RPT with sufficient authorization data for
        access. To get to this stage requires a number of previously
        successful steps:<list style="numbers">
            <t>The authorization server issues client credentials to the
            client. It is OPTIONAL for the client credentials to be provided
            dynamically through <xref target="DynClientReg"></xref> or <xref
            target="OIDCDynClientReg"></xref>; alternatively, they MAY use a
            static process.</t>

            <t>The client acquires an AAT.</t>

            <t>The client uses the authorization API to acquire an RPT and to
            ask for authorization data, providing the permission ticket it got
            from the resource server. The authorization server associates
            authorization data with the RPT based on the permission ticket,
            the resource owner's operative policies, and the results of any
            claims-gathering flows.</t>
          </list></t>

        <section anchor="authz-permission-token"
                 title="Client Requests Authorization Data">
          <t>Once in possession of a permission ticket and an AAT for this
          authorization server, the client asks the authorization server to
          give it authorization data corresponding to that permission ticket.
          It performs a POST on the RPT endpoint, supplying its own AAT in the
          header and a JSON object in the body with a "ticket" property
          containing the ticket as its value.</t>

          <t>If the client had included an RPT in its failed access attempt,
          It MAY also provide that RPT in an "rpt" property in its request to
          the authorization server.</t>

          <t>In circumstances where the client needs to provide requesting
          party claims to the authorization server, it MAY also include a
          "claim_tokens" property in its request; see <xref
          target="claim-push"></xref> for more information.</t>

          <figure>
            <preamble>Example of a request message containing an AAT, an RPT,
            and a permission ticket:</preamble>

            <artwork><![CDATA[POST /authz_request HTTP/1.1
Host: as.example.com
Authorization: Bearer jwfLG53^sad$#f
...

{
 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
}]]></artwork>
          </figure>

          <t>The authorization server uses the ticket to look up the details
          of the previously registered requested permission, maps the
          requested permission to operative resource owner policies based on
          the resource set identifier and scopes associated with it,
          potentially requests additional information, and ultimately responds
          positively or negatively to the request for authorization data.</t>

          <t>The authorization server bases the issuing of authorization data
          on resource owner policies. These policies thus amount to an
          asynchronous OAuth authorization grant. The authorization server is
          also free to enable the resource owner to set policies that require
          the owner to interact with the server in near-real time to provide
          consent subsequent to an access attempt. All such processes are
          outside the scope of this specification.</t>

          <t>Once the authorization server adds the requested authorization
          data, it returns an HTTP 200 (OK) status code with a response body
          containing the RPT with which it associates the requested
          authorization data. If the client did not present an RPT in the
          request for authorization data, the authorization server creates and
          returns a new RPT. If the client did present an RPT in the request,
          the authorization server returns the RPT with which it associated
          the requested authorization data, which MAY be either the RPT that
          was in the request or a new one. Note: It is entirely an
          implementation issue whether the returned RPT is the same one that
          appeared in the request or a new RPT, and it is also an
          implementation issue whether the AS chooses to invalidate or retain
          the validity of the original RPT or any authorization data that was
          previously added to that RPT; to assist in client interoperability
          and token caching expectations, it is RECOMMENDED that authorization
          servers document their practices. <xref target="UMA-Impl"></xref>
          discusses the implications.</t>

          <figure>
            <preamble>Example:</preamble>

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

{
  "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv"
}

]]></artwork>
          </figure>

          <t>If the authorization server does not add the requested
          authorization data, it responds using one of the following UMA error
          codes and corresponding HTTP status codes (see <xref
          target="uma-error-response"></xref>):<list style="hanging">
              <t hangText="invalid_ticket">The provided ticket was not found
              at the authorization server. The authorization server responds
              with the HTTP 400 (Bad Request) status code.</t>

              <t hangText="expired_ticket">The provided ticket has expired.
              The authorization server responds with the HTTP 400 (Bad
              Request) status code.</t>

              <t hangText="not_authorized">The client is not authorized to
              have this authorization data added. The authorization server
              responds with the HTTP 403 (Forbidden) status code.</t>

              <t hangText="need_info">The authorization server needs
              additional information in order to determine whether the client
              is authorized to have this authorization data. The authorization
              server responds with the HTTP 403 (Forbidden) status code. It
              MAY also respond with an "error_details" object that contains
              one or more sub-properties with hints about the nature of
              further required information. The client then has the
              opportunity to engage in follow-on flows to continue seeking
              authorization, in a process sometimes referred as "trust
              elevation". This specification defines two nonexclusive
              "error_details" sub-properties: "authentication_context",
              described in <xref target="authn-flows"></xref>, and
              "requesting_party_claims", described in <xref
              target="authz-flows"></xref>.</t>

              <t hangText="request_submitted">The authorization server
              requires intervention by the resource owner to determine whether
              the client is authorized to have this authorization data.
              Further immediate interaction between the client and
              authorization server is out of scope of this specification.</t>
            </list></t>

          <figure>
            <preamble>Example when the ticket has expired:</preamble>

            <artwork><![CDATA[
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
...

{
  "error": "expired_ticket"
}
]]></artwork>
          </figure>

          <figure>
            <preamble>Example of a "need_info" response with a full set of
            "error_details" hints:</preamble>

            <artwork><![CDATA[
HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-store
...

{
 "error": "need_info",
 "error_details": {
   "authentication_context": {
     "required_acr": ["https://example.com/acrs/LOA3.14159"]
   },
   "requesting_party_claims": {
     "required_claims": [
       {
         "name": "email23423453ou453",
         "friendly_name": "email",
         "claim_type": "urn:oid:0.9.2342.19200300.100.1.3",
         "claim_token_format": 
["http://openid.net/specs/openid-connect-core-1_0.html#HybridIDToken"],
         "issuer": ["https://example.com/idp"]
       }
     ],
     "redirect_user": true,
     "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
   }
 }
}
]]></artwork>
          </figure>

          <section anchor="authn-flows" title="Authentication Context Flows">
            <t>The "authentication_context" sub-property provides hints about
            additional requirements regarding the requesting party's
            authentication that underlies the issuance of the currently valid
            AAT. On receiving such hints, the client has the opportunity to
            redirect the requesting party to the authorization server to
            reauthenticate in a manner anticipated to be more successful for
            gaining access. Such an action is sometimes referred to as
            "step-up" authentication. The "authentication_context"
            sub-property contains the following parameter:<list
                style="hanging">
                <t hangText="required_acr">REQUIRED. An array of strings
                specifying a set of acceptable authentication context class
                reference values. Any one of the referenced authentication
                context classes (sets of authentication methods or procedures
                considered to be equivalent in a particular context) would
                satisfy the requesting party authentication requirements. Each
                string MAY be a URI, including one that has been registered
                through <xref target="RFC6711"></xref>.</t>
              </list></t>
          </section>

          <section anchor="authz-flows" title="Claims-Gathering Flows">
            <t>The "requesting_party_claims" sub-property provides hints about
            additional requirements regarding information the authorization
            server needs about the requesting party. On receiving such hints,
            the client has the opportunity to engage in claims-gathering flows
            of various types. The "requesting_party_claims" sub-property MAY
            contain the following parameters, where at least one of
            "required_claims" or "redirect_user" MUST be supplied:<list
                style="hanging">
                <t hangText="required_claims">An array containing objects that
                describe characteristics of the required claims, with the
                following properties:<list style="hanging">
                    <t hangText="name">OPTIONAL. A string (which MAY be a URI)
                    representing the name of the claim; the "key" in a
                    key-value pair.</t>

                    <t hangText="friendly_name">OPTIONAL. A string that
                    provides a more human-readable form of the attribute's
                    name, which may be useful as a "display name" for use in
                    user interfaces in cases where the actual name is complex
                    or opaque, such as an OID or a UUID.</t>

                    <t hangText="claim_type">OPTIONAL. A string, indicating
                    the expected interpretation of the provided claim value.
                    The string MAY be a URI.</t>

                    <t hangText="claim_token_format">OPTIONAL. An array of
                    strings specifying a set of acceptable formats for a token
                    pushed by the client containing this claim (see <xref
                    target="claim-push"></xref>). Any one of the referenced
                    formats would satisfy the authorization server's
                    requirements. Each string MAY be a URI.</t>

                    <t hangText="issuer">OPTIONAL. An array of strings
                    specifying a set of acceptable issuing authorities for the
                    claim. Any one of the referenced authorities would satisfy
                    the authorization server's requirements. Each string MAY
                    be a URI.</t>
                  </list></t>

                <t hangText="redirect_user">A Boolean value indicating whether
                the requesting party's presence at the authorization server is
                required for the process of claims gathering. For example, the
                authorization server may require the requesting party to fill
                out a CAPTCHA to help prove humanness. The default is false if
                this parameter is not present. See <xref
                target="am-endpoints"></xref> for how the authorization server
                declares the requesting party claims endpoint to which the
                client has the opportunity to redirect the requesting party.
                Note that the word "user" implies a human requesting party; if
                the requesting party is not an end-user, then no client action
                would be possible on receiving the hint.</t>

                <t hangText="ticket">The permission ticket that was in the
                client's request for authorization data. If the authorization
                server provides the "redirect_user" property, it MUST also
                provide the "ticket" property. This helps the client avoid
                maintaining this state information after the redirect.</t>
              </list></t>

            <t>An example of the use of these properties appears in <xref
            target="authz-permission-token"></xref>.</t>

            <t>The authorization server has many options for gathering
            requesting party claims. For example, it could interact with an
            end-user requesting party directly, or accept claims delivered by
            a client, or perform a lookup in some external system. The process
            is extensible and can have dependencies on the type of requesting
            party (for example, natural person or legal person) or client (for
            example, browser, native app, or autonomously running web
            service).</t>

            <t>The client and authorization server have two nonexclusive
            claims-gathering interaction patterns: push and redirect.</t>

            <section anchor="claim-push"
                     title="Client Pushes Claim Tokens to Authorization Server">
              <t>If the client is <spanx style="bold">claims-aware</spanx> and
              the authorization server can accept pushed claims (for example,
              as it might have indicated by providing
              "requesting_party_claims" hints described in <xref
              target="authz-permission-token"></xref>), the client has the
              option to <spanx>push</spanx> claim tokens to the RPT endpoint.
              The claim token can reflect the client's role as a federated
              identity provider, a federated relying party, or an application
              integrated with a native identity repository.</t>

              <t>If the client is aware of the authorization server's
              requirements for claims through an out-of-band relationship, the
              client MAY push claim tokens in an initial interaction with the
              RPT endpoint.</t>

              <t>The client supplies claim tokens in the body of the
              authorization data request message by providing, in addition to
              the "rpt" and "ticket" properties, the following property:<list
                  style="hanging">
                  <t hangText="claim_tokens">REQUIRED. An array of objects
                  with the following properties:<list style="hanging">
                      <t hangText="format">REQUIRED. A string specifying the
                      format of the accompanying claim tokens. The string MAY
                      be a URI.</t>

                      <t hangText="token">REQUIRED. A string containing the
                      claim information in the indicated format, base64url
                      encoded. If claim token format features are included
                      that require special interpretation, the client and
                      authorization server are assumed to have a prior
                      relationship that establishes how to interpret these
                      features. For example, if the referenced format equates
                      to SAML 2.0 assertions and the claim token contains
                      audience restrictions, it is the joint responsibility of
                      the client and authorization server to determine the
                      proper audience values that enable successful token
                      consumption.</t>
                    </list></t>
                </list></t>

              <figure>
                <preamble>Example:</preamble>

                <artwork><![CDATA[POST /rpt_authorization HTTP/1.1
Host: www.example.com
Authorization: Bearer jwfLG53^sad$#f
...
{
    "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
    "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de",
    "claim_tokens": [
      {
        "format":
"http://openid.net/specs/openid-connect-core-1_0.html#HybridIDToken",
        "token": "..."
      }
    ]
}
    ]]></artwork>
              </figure>

              <t>This specification provides a framework for extensibility
              through claim token format profiling. The authorization server
              MAY support any number of claim token profiles, and SHOULD
              document the claim token profiles it supports in its
              configuration data.</t>
            </section>

            <section anchor="claim-redirect"
                     title="Client Redirects Requesting Party to Authorization Server">
              <t>If the client is <spanx style="bold">claims-unaware</spanx>
              and the authorization server has declared a requesting party
              claims endpoint in its configuration data, or if the
              authorization server requires direct interaction with the
              requesting party as part of its claims-gathering process (for
              example, as it might have indicated through the "redirect_user"
              hint described in <xref
              target="authz-permission-token"></xref>), the client has the
              option to <spanx>redirect</spanx> an end-user requesting party
              to the requesting party claims endpoint. In this case, the
              authorization server might be a relying party in a federated
              identity interaction, or it might connect to a directory or
              other user repository, or even interact with the user in other
              ways, such as presenting a questionnaire in a web form. After
              this process completes, the authorization server redirects the
              end-user requesting party back to the client.</t>

              <t>The client constructs the request URI by adding the following
              parameters to the query component of the requesting party claims
              endpoint URI using the "application/x-www-form-urlencoded"
              format:<list style="hanging">
                  <t hangText="client_id">REQUIRED. The client's identifier
                  issued by the authorization server.</t>

                  <t hangText="redirect_uri">OPTIONAL. The URI to which the
                  client wishes the authorization server to direct the
                  requesting party's user agent after completing its
                  interaction. The URI MUST be absolute, MAY contain an
                  "application/x-www-form-urlencoded" formatted query
                  parameter component that MUST be retained when adding
                  addition parameters, and MUST NOT contain a fragment
                  component. The authorization server SHOULD require all
                  clients to register their redirection endpoint prior to
                  utilizing the authorization endpoint. If the URI is
                  pre-registered, this URI MUST exactly match one of the
                  pre-registered redirection URIs, with the matching performed
                  as described in Section 6.2.1 of <xref
                  target="RFC3986"></xref> (Simple String Comparison).</t>

                  <t hangText="ticket">REQUIRED. The permission ticket
                  associated with the client's current request for
                  authorization data for this requesting party. The
                  authorization server MUST return this parameter back to when
                  the authorization_state is need_info.</t>

                  <t hangText="state">OPTIONAL. An opaque value used by the
                  client to maintain state between the request and callback.
                  The authorization server includes this value when
                  redirecting the user agent back to the client. The use of
                  this parameter is STRONGLY RECOMMENDED for preventing
                  cross-site request forgery.</t>
                </list></t>

              <figure>
                <preamble>Example of a request issued by a client application
                (line breaks are shown only for display
                convenience):</preamble>

                <artwork><![CDATA[GET /rqp_claims?client_id=some_client_id&state=abc
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fredirect HTTP/1.1
Host: as.example.com]]></artwork>
              </figure>

              <t>At the conclusion of its interaction with the requesting
              party, the authorization server returns the user agent to the
              client adding the following parameters to the query component of
              the redirection URI using the
              "application/x-www-form-urlencoded" format:<list style="hanging">
                  <t hangText="authorization_state">REQUIRED. Indicates that
                  the authorization server completed its claims-gathering
                  interaction with the requesting party with the indicated
                  state:<list style="hanging">
                      <t hangText="claims_submitted">The client is free to
                      return to the RPT endpoint to seek authorization data
                      once again.</t>

                      <t hangText="not_authorized">The client is not
                      authorized to have the desired authorization data
                      added.</t>

                      <t hangText="need_info">The authorization server needs
                      additional information in order to determine whether the
                      client is authorized to have this authorization data.
                      This response directs the client to return to the RPT
                      endpoint, where it might be provided with error_details
                      hints about additional information needed.</t>

                      <t hangText="request_submitted">The authorization server
                      requires intervention by the resource owner to determine
                      whether authorization data can be added. Further
                      immediate interaction between the client, requesting
                      party, and authorization server is out of scope of this
                      specification.</t>
                    </list></t>

                  <t hangText="ticket">OPTIONAL. The same permission ticket
                  value that the client provided in the request. It MUST be
                  present if and only if the authorization_state is
                  need_info.</t>

                  <t hangText="state">OPTIONAL. The same state value that the
                  client provided in the request. It MUST be present if and
                  only if the client provided it.</t>
                </list></t>

              <t>The client MUST ignore unrecognized response parameters. If
              the request fails due to a missing, invalid, or mismatching
              redirection URI, or if the client identifier is missing or
              invalid, the authorization server SHOULD inform the resource
              owner of the error and MUST NOT automatically redirect the user
              agent to the invalid redirection URI. If the request fails for
              reasons other than a missing or invalid redirection URI, the
              authorization server informs the client by adding an "error"
              parameter to the query component of the redirection URI using
              the "application/x-www-form-urlencoded" format, containing one
              of the following ASCII error codes:<list style="hanging">
                  <t hangText="invalid_request">The request is missing a
                  required parameter, includes an invalid parameter value
                  (such as an invalid or expired ticket), includes a parameter
                  more than once, or is otherwise malformed.</t>

                  <t hangText="server_error">The authorization server
                  encountered an unexpected condition that prevented it from
                  fulfilling the request. (This error code is needed because
                  an HTTP 500 (Internal Server Error) status code cannot be
                  returned to the client via an HTTP redirect.)</t>

                  <t hangText="temporarily_unavailable">The authorization
                  server is currently unable to handle the request due to a
                  temporary overloading or maintenance of the server. (This
                  error code is needed because an HTTP 503 (Service
                  Unavailable) status code cannot be returned to the client
                  via an HTTP redirect.)</t>
                </list></t>
            </section>
          </section>
        </section>
      </section>
    </section>

    <section anchor="errors" title="Error Messages">
      <t>Ultimately the resource server is responsible for either granting the
      access the client attempted, or returning an error response to the
      client with a reason for the failure. <xref target="OAuth2"></xref>
      defines several error responses for a resource server to return. UMA
      makes use of these error responses, but requires the resource server to
      "outsource" the determination of some error conditions to the
      authorization server. This specification defines additional UMA-specific
      error responses that the authorization server may give to the resource
      server and client as they interact with it, and that the resource server
      may give to the client.</t>

      <section anchor="oauth-error-response" title="OAuth Error Responses">
        <t>When a resource server or client attempts to access one of the
        authorization server endpoints or a client attempts to access a
        protected resource at the resource server, it has to make an
        authenticated request by including an OAuth access token in the HTTP
        request as described in <xref target="OAuth2"></xref> Section 7.2.</t>

        <t>If the request failed authentication, the authorization server or
        the resource server responds with an OAuth error message as described
        in this specification in <xref
        target="getting-authz-accessing-resource"></xref>.</t>
      </section>

      <section anchor="uma-error-response" title="UMA Error Responses">
        <t>When a resource server or client attempts to access one of the
        authorization server endpoints or a client attempts to access a
        protected resource at the resource server, if the request is
        successfully authenticated by OAuth means, but is invalid for another
        reason, the authorization server or resource server responds with an
        UMA 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>

        <t>The following is a common error code that applies to several
        UMA-specified request messages: <list style="hanging">
            <t hangText="invalid_request">The request is missing a required
            parameter, includes an invalid parameter value, includes a
            parameter more than once, or is otherwise malformed. The
            authorization server MUST respond with the HTTP 400 (Bad Request)
            status code.</t>
          </list></t>

        <figure>
          <preamble>For example:</preamble>

          <artwork><![CDATA[
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
...

{
  "error": "invalid_request",
  "error_description": "There is already a resource with this identifier.",
  "error_uri": "https://as.example.com/errors/resource_exists"
}
]]></artwork>
        </figure>
      </section>
    </section>

    <section anchor="comms-profiles" title="Profiles for API Extensibility">
      <t>In some circumstances, it may be desirable to couple UMA roles
      tightly. For example, an authorization server application might also
      need to act as a client application in order to retrieve protected
      resources so that it can present to resource owners a dashboard-like
      user interface that accurately guides the setting of policy; it might
      need to access itself-as-authorization server for that purpose. For
      another example, the same organization might operate both an
      authorization server and a resource server that communicate only with
      each other behind a firewall, and it might seek more efficient
      communication methods between them.</t>

      <t>In other circumstances, it may be desirable to bind UMA flows to
      transport mechanisms other than HTTP even if entities remain loosely
      coupled. For example, in Internet of Things scenarios, Constrained
      Application Protocol (CoAP) may be preferred over HTTP.</t>

      <t>This section defines profiles that allow inter-role communications
      channels and methods to vary in these circumstances. This specification
      still REQUIRES authorization servers to issue PATs, AATs, and RPTs and
      associate authorization data with RPTs, and REQUIRES resource servers to
      give clients access only when RPTs are associated with sufficient
      authorization data. This is because, although tokens might not always
      appear on the wire in the normal fashion, the tokens may represent
      binding obligations that involve additional parties unable to take part
      in these optimization opportunities (see <xref
      target="UMA-obligations"></xref>).</t>

      <t>Where alternate communications channels are being used between
      independently implemented system entities, it is RECOMMENDED, for
      reasons of implementation interoperability, to define concrete extension
      profiles that build on these extensibility profiles (see <xref
      target="uma-profiles"></xref>).</t>

      <section anchor="alt-prot-profile"
               title="Protection API Extensibility Profile">
        <t>This section defines a profile for UMA where the authorization
        server and resource server roles either reside in the same system
        entity or otherwise have a privileged or specialized communications
        channel between them. Following is a summary:<list style="symbols">
            <t>Identifying URI:
            https://docs.kantarainitiative.org/uma/profiles/prot-ext-1.0</t>

            <t>Profile author and contact information: Mark Dobrinic
            (mdobrinic@cozmanova.com)</t>

            <t>Updates or obsoletes: None; this profile is new.</t>

            <t>Security considerations: See below.</t>

            <t>Privacy considerations: See below.</t>

            <t>Error states: None additional.</t>
          </list></t>

        <t>Using this profile, the resource server MAY use means other than
        the HTTP-based protection API that is protected by TLS and OAuth (or
        an OAuth-based authentication protocol) to communicate with the
        authorization server in all respects, including using software
        interfaces and methods rather than network interfaces and APIs. The
        authorization server MUST still issue PATs, AATs, and RPTs and
        associate authorization data with RPTs, and the resource server MUST
        still give clients access only when RPTs are associated with
        sufficient authorization data. Interactions with entities other than
        the authorization server or resource server MUST be preserved exactly
        as they would have if either of them were using standardized UMA APIs,
        unless other extensibility profiles are also in use.</t>

        <t>An authorization server using any of the opportunities afforded by
        this profile MUST declare use of this profile by supplying its
        identifying URI for one of its "uma_profiles_supported" values in its
        configuration data (see <xref target="am-endpoints"></xref>).</t>

        <t>Same-entity communication or a tight integration of entities has
        the opportunity to make deployments more secure by reducing possible
        attack vectors. However, if the entities do not use TLS but
        communicate across a transport layer, it is RECOMMENDED to use an
        alternate means of transport-layer security, for example, using DTLS
        in the case of a CoAP-based UMA profile.</t>

        <t>Same-entity communication or a tight integration of entities has
        the potential to compromise privacy by promoting the freer exchange of
        personal information within a deployment ecosystem. It is RECOMMENDED
        to account for privacy impacts in each deployment scenario.</t>
      </section>

      <section anchor="alt-authz-profile"
               title="Authorization API Extensibility Profile">
        <t>This section defines a profile for UMA where the authorization
        server and client roles either reside in the same system entity or
        otherwise have a privileged or specialized communications channel
        between them. Following is a summary:<list style="symbols">
            <t>Identifying URI:
            https://docs.kantarainitiative.org/uma/profiles/authz-ext-1.0</t>

            <t>Profile author and contact information: Mark Dobrinic
            (mdobrinic@cozmanova.com)</t>

            <t>Updates or obsoletes: None; this profile is new.</t>

            <t>Security considerations: See below.</t>

            <t>Privacy considerations: See below.</t>

            <t>Error states: None additional.</t>
          </list></t>

        <t>Using this profile, the client MAY use means other than the
        HTTP-based authorization API that is protected by TLS and OAuth (or an
        OAuth-based authentication protocol) to communicate with the
        authorization server in all respects, including using software
        interfaces and methods rather than network interfaces and APIs. The
        authorization server MUST still issue PATs, AATs, and RPTs and
        associate authorization data with RPTs, and the resource server MUST
        still give clients access only when RPTs are associated with
        sufficient authorization data. Interactions with entities other than
        the authorization server or client MUST be preserved exactly as they
        would have if either of them were using standardized UMA APIs, unless
        other extensibility profiles are also in use.</t>

        <t>An authorization server using any of the opportunities afforded by
        this profile MUST declare use of this profile by supplying its
        identifying URI for one of its "uma_profiles_supported" values in its
        configuration data (see <xref target="am-endpoints"></xref>).</t>

        <t>Same-entity communication or a tight integration of entities has
        the opportunity to make deployments more secure by reducing possible
        attack vectors. However, if the entities do not use TLS but
        communicate across a transport layer, it is RECOMMENDED to use an
        alternate means of transport-layer security, for example, using DTLS
        in the case of a CoAP-based UMA profile.</t>

        <t>Same-entity communication or a tight integration of entities has
        the potential to compromise privacy by promoting the freer exchange of
        personal information within a deployment ecosystem. It is RECOMMENDED
        to account for privacy impacts in each deployment scenario.</t>
      </section>

      <section anchor="alt-resource-profile"
               title="Resource Interface Extensibility Profile">
        <t>This section defines a profile for UMA where the resource server
        and client roles either reside in the same system entity or otherwise
        have a privileged or specialized communications channel between them.
        Following is a summary:<list style="symbols">
            <t>Identifying URI:
            https://docs.kantarainitiative.org/uma/profiles/rsrc-ext-1.0</t>

            <t>Profile author and contact information: Mark Dobrinic
            (mdobrinic@cozmanova.com)</t>

            <t>Updates or obsoletes: None; this profile is new.</t>

            <t>Security considerations: See below.</t>

            <t>Privacy considerations: See below.</t>

            <t>Error states: None additional.</t>
          </list></t>

        <t>Using this profile, the resource server MAY use means other than an
        HTTP-based resource interface to communicate with the authorization
        server in all respects, including using software interfaces and
        methods rather than network interfaces and APIs. The resource server
        MUST still give clients access only when RPTs are associated with
        sufficient authorization data. Interactions with entities other than
        the resource server or client MUST be preserved exactly as they would
        have if either of them were using standardized UMA APIs, unless other
        extensibility profiles are also in use.</t>

        <t>An authorization server involved in deployments where resource
        servers and clients are known to be using opportunities afforded by
        the resource interface extensibility profile MAY declare use of this
        profile by supplying its identifying URI for one of its
        "uma_profiles_supported" values in its configuration data (see <xref
        target="am-endpoints"></xref>).</t>

        <t>Same-entity communication or a tight integration of entities has
        the opportunity to make deployments more secure by reducing possible
        attack vectors. However, if the entities do not use TLS but
        communicate across a transport layer, it is RECOMMENDED to use an
        alternate means of transport-layer security, for example, using DTLS
        in the case of a CoAP-based UMA profile.</t>

        <t>Same-entity communication or a tight integration of entities has
        the potential to compromise privacy by promoting the freer exchange of
        personal information within a deployment ecosystem. It is RECOMMENDED
        to account for privacy impacts in each deployment scenario.</t>
      </section>
    </section>

    <section anchor="profiles" title="Specifying Additional Profiles">
      <t>This specification defines a protocol that has optional features. For
      implementation interoperability and to serve particular deployment
      scenarios, including sector-specific ones such as healthcare or
      e-government, third parties may want to define profiles of UMA that
      restrict these options.</t>

      <t>Further, this specification creates extensibility points for RPT
      profiles and claim token profiles, and third parties may likewise want
      to define their own. Different RPT profiles could be used, for example,
      to change the dividing line between authorization server and resource
      server responsibilities in controlling access. Different claim token
      profiles could be used to customize sector-specific or
      population-specific (such as individual vs. employee) claim types that
      drive the types of policies resource owners could set.</t>

      <t>It is not practical for this specification to standardize all desired
      profiles. However, to serve overall interoperability goals, this section
      provides guidelines for third parties that wish to specify UMA-related
      profiles. In all cases, it is RECOMMENDED that profiles document the
      following information:<list style="symbols">
          <t>Specify a URI that uniquely identifies the profile.</t>

          <t>Identify the responsible author and provide postal or electronic
          contact information.</t>

          <t>Supply references to any previously defined profiles that the
          profile updates or obsoletes.</t>

          <t>Define any additional or changed error states.</t>

          <t>Specify any conformance and interoperability considerations.</t>

          <t>Supply any additional security and privacy considerations.</t>
        </list></t>

      <section anchor="uma-profiles" title="Specifying Profiles of UMA">
        <t>It is RECOMMENDED that profiles of UMA additionally document the
        following information:</t>

        <t><list style="symbols">
            <t>Specify the set of interactions between endpoint entities
            involved in the profile, calling out any restrictions on ordinary
            UMA-conformant operations and any extension properties used in
            message formats.</t>
          </list></t>

        <t>See <xref target="comms-profiles"></xref> for examples.</t>
      </section>

      <section anchor="rpt-profiles" title="Specifying RPT Profiles">
        <t>It is RECOMMENDED that RPT profiles additionally document the
        following information:</t>

        <t><list style="symbols">
            <t>Specify the keyword to be used in HTTP Authorization headers
            with tokens conforming to this profile.</t>

            <t>Specify the syntax and semantics of the data that the
            authorization server associates with the token.</t>

            <t>Specify how the token data is associated with, contained
            within, and/or retrieved by means of, the on-the-wire token
            string.</t>

            <t>Specify processing rules for token data.</t>

            <t>Identify any restrictions on grant types to be used with the
            token profile.</t>
          </list></t>

        <t>See <xref target="uma-bearer-token-profile"></xref> for an
        example.</t>
      </section>

      <section anchor="claim-profiles"
               title="Specifying Claim Token Format Profiles">
        <t>It is RECOMMENDED that claim token format profiles additionally
        document the following information:<list style="symbols">
            <t>Specify any related or additional error_details hints.</t>

            <t>Specify any constraints on the claim token format vs. a
            standard definition for it in a specification.</t>

            <t>Specify any mutual interpretation details of claim token
            formats by authorization servers and clients.</t>
          </list></t>
      </section>
    </section>

    <section title="Compatibility Notes">
      <t>Implementers should heed the following compatibility notes.<list
          style="symbols">
          <t>This specification uses a specific draft of a specification that
          is not yet final: <xref target="OAuth-introspection"></xref> (draft
          04); the reference will be updated until this "UMA V1.0 candidate"
          specification is finalized. While every effort will be made to
          prevent breaking changes to this specification, should they occur,
          UMA implementations should continue to use the specifically
          referenced draft version in preference to the final versions, unless
          using a possible future UMA profile or specification that updates
          the relevant references.</t>

          <t>In cases where this specification is not prescriptive regarding
          conformance or interoperability, any common or best practices for
          implementation will be documented in the <xref
          target="UMA-Impl"></xref> over time.</t>
        </list></t>
    </section>

    <section anchor="sec-consid" title="Security Considerations">
      <t>As a profile of OAuth, this specification relies mainly on OAuth
      security mechanisms as well as transport-level encryption. Thus,
      implementers are strongly advised to read the security considerations in
      <xref target="OAuth2"></xref> (Section 10) and <xref
      target="OAuth-bearer"></xref> (Section 5) along with the security
      considerations of any other OAuth token-defining specifications in use,
      along with the entire <xref target="OAuth-threat"></xref> specification,
      and apply the countermeasures described therein. As well, since this
      specification builds on <xref target="OAuth-resource-reg"></xref>,
      implementers should also take into account the security considerations
      in that specification.</t>

      <t>The following sections describe additional security
      considerations.</t>

      <section title="Redirection and Impersonation Threats">
        <t>This section discusses threats related to UMA's nature as an
        protocol enabling autonomous (non-resource-owner) requesting parties
        to gain authorized access to sensitive resources, including through
        the process of claims-gathering redirection.</t>

        <t>Like ordinary OAuth redirection, UMA redirection for the purpose of
        gathering claims from an end-user requesting party (described in <xref
        target="claim-redirect"></xref>) creates the potential for cross-site
        request forgery (CSRF) through an open redirect if the authorization
        server does not force the client to pre-register its redirection
        endpoint, and server-side artifact tampering if the client does not
        avail itself of the state parameter. The client SHOULD check that the
        ticket value returned by an authorization server after a redirect is
        completed has not been maliciously changed, for example by a man in
        the browser (MITB), by using the state parameter. (See the <xref
        target="UMA-Impl"></xref> for advice on ways to accomplish this.)
        Sections 4.4.1.8, 4.4.2.5, and 5.3.5 of <xref
        target="OAuth-threat"></xref> are apropos for the UMA claims-gathering
        redirection flow as well.</t>

        <t>When a client redirects an end-user requesting party to the
        requesting party claims endpoint, the client provides no a priori
        context to the authorization server about which user is appearing at
        the endpoint, other than implicitly through the permission ticket.
        Since the authorization server is free to gather any claims it wishes,
        the effect is to "late-bind" them to the permission ticket and the
        state string provided by the client, with the effect of enabling the
        authorization server not to trust client-asserted claims. This is a
        desirable result and reflects one reason why the authorization server
        might choose to demand use of the redirect flow over the push flow.
        However, the client has the opportunity to switch end-users -- say,
        enabling malicious end-user Carlos to impersonate the original
        end-user Bob who approved the minting of of the AAT -- after the
        redirect completes and before it returns to the RPT endpoint to seek
        authorization data.</t>

        <t>Another issue concerns the exposure of the RPT to an autonomous
        requesting party, which could maliciously pass the token to an
        unauthorized party.</t>

        <t>To mitigate requesting-party switching and RPT exposure threats,
        consider the following strategies.<list style="symbols">
            <t>Require that the Requesting Party (as defined in <xref
            target="UMA-obligations"></xref>, meaning this party is able to
            take on legal obligations) legitimately represent the wielder of
            the bearer token. This solution is based on a legal or contractual
            approach, and therefore does not reduce the risk from the
            technical perspective.</t>

            <t>The authorization server, possibly with input from the resource
            owner, can implement tighter time-to-live strategies around the
            authorization data in RPTs. This is a classic approach with bearer
            tokens that helps to limit a malicious party's ability to
            intercept and use the bearer token. In the same vein, the
            authorization server could require claims to have a reasonable
            degree of freshness (which would require a custom claims
            profile).</t>

            <t>The strongest strategy is to disallow bearer-type RPTs within
            the UMA profile being deployed, by providing or requiring an RPT
            profile that requires use of a holder-of-key approach. In this
            way, the wielder of the token must engage in a live session for
            proof-of-possession. A less complex version of this strategy is to
            "elevate trust" in the requesting party by requiring a stronger
            authentication context, forcing step-up authentication by the
            requesting party at run time.</t>
          </list></t>
      </section>

      <section title="Client Authentication">
        <t>Along with TLS, UMA requires OAuth, or any OAuth-based
        authentication protocol, as the security mechanism for its
        standardized APIs. The UMA resource server acts in the role of an
        OAuth client at the authorization server's protection API, and the UMA
        client acts in the role of an OAuth client at the authorization
        server's authorization API. While it is possible to use any profile of
        OAuth for this protection, it is RECOMMENDED for the authorization
        server to use OpenID Connect, and to use its mechanisms for stronger
        client authentication at the token endpoint, in order to strengthen
        the authentication of OAuth clients. Section 16 of <xref
        target="OIDCCore"></xref> provides more information on OpenID Connect
        security considerations.</t>

        <t>Clients using the OAuth implicit grant type carry particular
        vulnerabilities in OAuth, and OpenID Connect doesn't help because of
        the nature of the implicit grant flow. UMA scenarios are vulnerable as
        well. For example, an "implicit client" might require the retrieval of
        AATs more frequently, for each browser on each platform. An attacker
        can initiate a spear phishing attack on the requesting party with a
        link to a malicious website, relying on the requesting party to
        authenticate to the authorization server through an email-based
        identity provider in order to receive the AAT. The site can
        impersonate the requesting party using the browser client's client ID
        in an OpenID Connect implicit request to the UMA authorization server.
        If the requesting party had previously given consent for an AAT to be
        issued, this attempt will likely succeed. The subsequently issued AAT
        and permission ticket for an attempted resource access could
        potentially be used for RPT retrieval and authorization data
        issuance.</t>

        <t>A number of mitigation strategies are possible.<list
            style="symbols">
            <t>The authorization server could penalize or disallow use of the
            implicit grant flow. This could be done at a variety of
            levels:<list style="symbols">
                <t>Enabling resource owners to define policies controlling the
                use of such clients</t>

                <t>Setting system-default policies controlling their use</t>

                <t>Participating in mutual agreements with other parties that
                admit only suitably secure client applications to interact
                with service operators</t>
              </list></t>

            <t>The authorization server could support dynamic client
            registration at the client instance level, such that each instance
            receives a unique client_id and secret. The client can then use
            the authorization code flow and have at least some form of client
            authentication. However, this is easier for a mobile app than for
            a browser-based HTML app.</t>
          </list></t>
      </section>

      <section title="JSON Usage">
        <t>This specification defines a number of data formats based on <xref
        target="JSON"></xref>. As a subset of the JavaScript scripting
        language, JSON data SHOULD be consumed through a process that does not
        dynamically execute it as code, to avoid malicious code execution. One
        way to achieve this is to use a JavaScript interpreter rather than the
        built-in JavaScript eval() function.</t>
      </section>

      <section title="Profiles, Binding Obligations, and Trust Establishment">
        <t>Parties operating and using UMA software entities have
        opportunities to establish agreements about mutual rights,
        responsibilities, and common interpretations of UMA constructs for
        consistent and expected software behavior. These agreements can be
        used to improve the parties' respective security postures, and written
        profiles are a key mechanism for conveying and enforcing these
        agreements. <xref target="profiles"></xref> discusses profiling. <xref
        target="comms-profiles"></xref> discusses profiling for extensibility.
        <xref target="UMA-obligations"></xref> discusses the development of
        binding obligations.</t>
      </section>
    </section>

    <section anchor="priv-consid" title="Privacy Considerations">
      <t>The authorization server comes to be in possession of resource set
      information that may reveal information about the resource owner, which
      the authorization server's trust relationship with the resource server
      is assumed to accommodate. However, the client is a less-trusted party
      -- in fact, entirely untrustworthy until authorization data is
      associated with its RPT. The more information about a resource set that
      is registered, the more risk of privacy compromise there is through a
      less-trusted authorization server.</t>

      <t>The primary privacy duty of UMA's design is to the resource owner.
      However, privacy considerations affect the requesting party as well.
      This can be seen in the issuance of an AAT, which represents the
      approval of a requesting party for a client to engage with an
      authorization server to perform tasks needed for obtaining
      authorization, possibly including pushing claim tokens.</t>

      <t>Parties operating and using UMA software entities have opportunities
      to establish agreements about mutual rights, responsibilities, and
      common interpretations of UMA constructs for consistent and expected
      software behavior. These agreements can be used to improve the parties'
      respective privacy postures. For information about the additional
      technical, operational, and legal elements of trust establishment, see
      <xref target="UMA-obligations"></xref>. Additional considerations
      related to Privacy by Design concepts are discussed in <xref
      target="UMA-PbD"></xref>.</t>
    </section>

    <section anchor="IANA" title="IANA Considerations">
      <t>This document makes the following requests of IANA.</t>

      <section title="JSON Web Token Claims Registration">
        <t>This specification registers the claim defined in <xref
        target="uma-bearer-token-profile"></xref>.</t>

        <section title="Registry Contents">
          <t><list style="symbols">
              <t>Claim name: permissions</t>

              <t>Claim description: Array of objects, each describing a set of
              scoped, time-limitable entitlements to a resource set</t>

              <t>Change controller: Kantara Initiative User-Managed Access
              Work Group - wg-uma@kantarainitiative.org</t>

              <t>Specification document: <xref
              target="uma-bearer-token-profile"></xref> in this document</t>
            </list></t>
        </section>
      </section>

      <section title="Well-Known URI Registration">
        <t>This specification registers the well-known URI defined in <xref
        target="am-endpoints"></xref>.</t>

        <section title="Registry Contents">
          <t><list style="symbols">
              <t>URI suffix: uma-configuration</t>

              <t>Change controller: Kantara Initiative User-Managed Access
              Work Group - wg-uma@kantarainitiative.org</t>

              <t>Specification document: <xref target="am-endpoints"></xref>
              in this document</t>
            </list></t>
        </section>
      </section>
    </section>

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

          <t>Mark Dobrinic, Cozmanova</t>

          <t>George Fletcher, AOL</t>

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

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

          <t>Mike Schwartz, Gluu</t>

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

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

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

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

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

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

      <reference anchor="OAuth-resource-reg"
                 target="https://tools.ietf.org/html/draft-hardjono-oauth-resource-reg">
        <front>
          <title>OAuth 2.0 Resource Set Registration</title>

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

          <date day="23" month="February" year="2015" />
        </front>
      </reference>

      <reference anchor="OAuth-introspection"
                 target="http://tools.ietf.org/html/draft-ietf-oauth-introspection-04">
        <front>
          <title>OAuth Token Introspection</title>

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

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

      <reference anchor="OAuth-bearer"
                 target="http://tools.ietf.org/html/rfc6750">
        <front>
          <title>The OAuth 2.0 Authorization Framework: Bearer Token
          Usage</title>

          <author fullname="M. Jones">
            <organization></organization>
          </author>

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

      <reference anchor="hostmeta" target="http://tools.ietf.org/html/rfc6415">
        <front>
          <title>Web Host Metadata</title>

          <author initials="E." surname="Hammer-Lahav">
            <organization>Yahoo!</organization>
          </author>

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

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

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

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

      <reference anchor="JWT"
                 target="http://datatracker.ietf.org/doc/draft-ietf-oauth-json-web-token/">
        <front>
          <title>JSON Web Token (JWT)</title>

          <author initials="M." surname="Jones">
            <organization>Microsoft</organization>
          </author>

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

      <reference anchor="DynClientReg"
                 target="http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg">
        <front>
          <title>OAuth 2.0 Core Dynamic Client Registration</title>

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

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

      <reference anchor="OIDCDynClientReg"
                 target="http://openid.net/specs/openid-connect-registration-1_0.html">
        <front>
          <title>OpenID Connect Dynamic Client Registration 1.0 incorporating
          errata set 1</title>

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

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

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

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

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

      <reference anchor="RFC3986" target="http://www.ietf.org/rfc/rfc3986.txt">
        <front>
          <title>Uniform Resource Identifier (URI): Generic Syntax</title>

          <author initials="T." surname="Berners-Lee">
            <organization>W3C/MIT</organization>
          </author>

          <date day="" month="January" year="2005" />
        </front>
      </reference>

      <reference anchor="OAuth-threat"
                 target="http://tools.ietf.org/html/rfc6819">
        <front>
          <title>OAuth 2.0 Threat Model and Security Considerations</title>

          <author initials="T." surname="Lodderstedt">
            <organization></organization>
          </author>

          <date day="" month="January" year="2013" />
        </front>
      </reference>

      <reference anchor="RFC6711" target="https://tools.ietf.org/html/rfc6711">
        <front>
          <title>An IANA Registry for Level of Assurance (LoA)
          Profiles</title>

          <author initials="L." surname="Johansson">
            <organization></organization>
          </author>

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

    <references title="Informative References">
      <reference anchor="UMA-usecases"
                 target="http://kantarainitiative.org/confluence/display/uma/UMA+Scenarios+and+Use+Cases">
        <front>
          <title>UMA Scenarios and Use Cases</title>

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

          <date month="October" year="2010" />
        </front>
      </reference>

      <reference anchor="UMA-obligations"
                 target="http://docs.kantarainitiative.org/uma/draft-uma-trust.html">
        <front>
          <title>Binding Obligations on UMA Participants</title>

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

          <date day="25" month="January" year="2013" />
        </front>
      </reference>

      <reference anchor="UMA-casestudies"
                 target="http://kantarainitiative.org/confluence/display/uma/Case+Studies">
        <front>
          <title>UMA Case Studies</title>

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

          <date day="29" month="April" year="2014" />
        </front>
      </reference>

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

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

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

      <reference anchor="UMA-PbD"
                 target="http://kantarainitiative.org/confluence/display/uma/Privacy+by+Design+Implications+of+UMA">
        <front>
          <title>Privacy by Design Implications of UMA</title>

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

          <date day="9" month="December" year="2013" />
        </front>
      </reference>

      <reference anchor="UMA-Impl"
                 target="http://kantarainitiative.org/confluence/display/uma/UMA+Implementer%27s+Guide">
        <front>
          <title>UMA Implementer's Guide</title>

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

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