draft-uma-claim-profiles.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-catalano-oauth-umaclaim-00"
     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) Claim Profiles
    Framework</title>

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

      <address>
        <email>domenico.catalano@oracle.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>

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

    <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 policy. This specification
      defines a generic framework for building UMA claim profiles that can be
      used by client applications to obtain the necessary authorization to
      access protected resources. This revision of the specification is part
      of V0.9.</t>
    </abstract>
  </front>

  <middle>
    <section anchor="introduction" title="Introduction">
      <t>User-Managed Access <xref target="UMA"></xref> 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
      policy. This specification defines a generic framework for building UMA
      claim profiles that can be used by client applications to obtain the
      necessary authorization to access protected resources.</t>

      <t>Using the framework defined in this specification, UMA deployers can
      add new claim profiles to meet requirements of particular deployments of
      UMA. Profiles built on this framework will give both authorization
      servers and clients certain interoperability and ease of development
      properties. This specification also provides some sample profiles that
      build on the framework. Deployers can build on the framework directly or
      on these sample profiles, as they wish, in order to promote
      interoperability in their specific environments.</t>

      <t>The framework introduces different interaction patterns that the
      client and authorization server can use, and different roles they can
      play, in order to gather claims about the requesting party:<list
          style="symbols">
          <t>The <spanx style="bold">delivery</spanx> interaction pattern
          leverages a <spanx style="bold">claims-aware client</spanx> that is
          able to deliver claims about the requesting party (or information
          about how to get claims) directly to the authorization server. The
          information delivered can be an identity or claims token, data that
          aids in discovery of a claims endpoint, etc., depending on the
          client's role outside of UMA as a federated identity provider, a
          federated relying party, an application integrated with a native
          identity repository, etc. The authorization server then plays the
          role of a <spanx style="bold">claims receiver</spanx> (and/or
          activates a <spanx style="bold">claims connector</spanx> based on
          the information, for gathering claims itself without requesting
          party involvement).</t>

          <t>The <spanx style="bold">redirect</spanx> pattern assumes a <spanx
          style="bold">claims-unaware client</spanx> whose only option (other
          than failing entirely) is to redirect an end-user requesting party
          to the authorization server. On receiving the end user, the
          authorization server activates a <spanx style="bold">claims connector</spanx>
          for gathering the necessary claims with the user's involvement,
          using any method or combination of methods. In this role, the
          authorization server may be a relying party in a federated identity
          interaction, or it may connect to a directory or other user
          repository. After the claims-gathering process, the authorization
          server redirects the user back to the client.</t>
        </list></t>

      <t>The profiles defined based on both interaction patterns are as
      follows:<list style="symbols">
          <t>Delivery:<list style="symbols">
              <t>Client delivers a SAML assertion to the authorization
              server</t>

              <t>Client delivers OpenID Connect user claims to the
              authorization server</t>

              <t>Client delivers custom user claims to the authorization
              server</t>

              <t>Client delivers custom and OpenID Connect user claims to the
              authorization server</t>
            </list></t>

          <t>Redirect:<list style="symbols">
              <t>Client redirects end-user requesting party to the
              authorization server</t>
            </list></t>
        </list></t>

      <t>In all cases, it is assumed that the authorization server evaluates
      the resource owner's policy for a particular resource set based, at
      least in part, on the supplied claims. An authorization server MAY
      support any claim profiles defined in this specification, and SHOULD
      advertise its conformance to tbe profiles it supports in its
      configuration data.</t>

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

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

    <section anchor="framework" title="Generic Framework for Claim Profiles">
      <t>When a client asks an authorization server to associate authorization
      data with a requesting party token (RPT) so that the client can
      successfully access a resource on behalf of the requesting party
      operating it, the authorization can respond in three main ways: either
      it can deny the client's request outright, or it can accede to the
      request outright, or it can respond that it needs claims in order to
      assess whether suitability of adding the needed authorization data. The
      authorization server has an opportunity, when it returns a "need_claims"
      response, to provide further instructions and hints to the client in
      this response. This section defines extensions to <xref
      target="UMA"></xref> that support these instructions and hints.</t>

      <t>The authorization request endpoint in the authorization API presented
      by the authorization server is extended to accept JSON-encoded
      claims-related data in the body of the request. Along with the "rpt" and
      "ticket" properties that already need to be provided, a "claims"
      property appears in addition.</t>

      <t>Common message flow:</t>

      <figure>
        <preamble>1. The client sends the claims type and its claims directly
        to the AS</preamble>

        <artwork><![CDATA[POST /rpt_authorization HTTP/1.1
        Host: www.nuveam.com
        Authorization: Bearer jwfLG53^sad$#f
        ...
            
{
    "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
    "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de",
    "claims": [
        {
            "type": "CLAIM_TYPE_AS_STRING",
            "value": {SPECIFIC_SET_OF_CLAIMS_AS_JSON_OBJECT}
        }
    ]
}
        ]]></artwork>
      </figure>

      <t>Importantly, the claims MUST be an array of JSON objects. The type
      field MUST have a String value indicating the type of claims-related
      data, while the value field MUST be a JSON object specific to that type
      of claims-related data.</t>

      <figure>
        <preamble>2. The authorization server informs the client that
        authorization data has been added</preamble>

        <artwork><![CDATA[HTTP/1.1 201 Created
    Content-Type: application/json;charset=UTF-8
        
    {
        "rpt":"e6b09a4f434a6a47a65a198652df381a"
    }
    ]]></artwork>
      </figure>

      <figure>
        <preamble>3. The authorization server informs the client that further
        claims should be provided to the authorization request
        endpoint:</preamble>

        <artwork><![CDATA[HTTP/1.1 403 Forbidden
Content-Type: application/json
        
{
    "need_claims":[
    {
        "type":"CLAIM_TYPE_AS_STRING",
        "name":"",
        "value":""
    }]
}
    ]]></artwork>
      </figure>

      <figure>
        <preamble>4. The authorization server informs the client that further
        claims should be provided (the example below is for SAML
        assertion)</preamble>

        <artwork><![CDATA[HTTP/1.1 403 Forbidden
Content-Type: application/json
        
{
    "need_claims":[
    {
        "type":"claim-client-assertion-saml-1.0",
        "name":"",
        "value":""
    }
    ]
}
    ]]></artwork>
      </figure>

      <figure>
        <preamble>5. The authorization server informs the client that the
        authorization data cannot be added.</preamble>

        <artwork><![CDATA[HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
        
{
    "error":"not_authorized_permission",
    "error_description":"Authorization data cannot be added."
}
    ]]></artwork>
      </figure>

      <section anchor="client-pull-custom-attr"
               title="Client Provides Custom User Attributes">
        <t>TYPE = "custom"</t>

        <t>VALUE = {custom defined}</t>

        <t>In the most trivial setting where the AS and the Client are
        collocated and have an established trust relationship (in particular,
        the AS trusts information that it receives from the client), then the
        client can be preconfigured to provide the required information to the
        AS based on a custom schema. We provide the most trivial example
        below, where the client application provides a user's identifier (in
        this case email) to the AS and such identifier is used for policy
        evaluation.</t>

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

          <artwork><![CDATA[POST /rpt_authorization HTTP/1.1
Host: www.nuveam.com
Authorization: Bearer jwfLG53^sad$#f
...
           
{
    "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
    "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de",
    "claims": [
    {
        "type": "ci-nuveam-claims",
        "value": { "email": "bob@company.example.com" }
    }
    ]
}
       ]]></artwork>
        </figure>

        <t>Another example is where the client provides a richer set of
        attributes directly to the AS and these attributes are used for policy
        evaluation. Importantly, it is the AS that decides which attributes
        are used for policy evaluation and which are not.</t>

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

          <artwork><![CDATA[POST /rpt_authorization HTTP/1.1
Host: www.nuveam.com
Authorization: Bearer jwfLG53^sad$#f
...
        
{
    "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
    "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de",
    "claims": [
        {
        "type": "ci-nuveam-claims",
        "value": { "email": "bob@gmail.com", "roles": [ "manager", "admin" ] }
        }
    ]
    
}
    ]]></artwork>
        </figure>

        <t>We provide an example of a reply below (standard UMA reply):</t>

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

          <artwork><![CDATA[HTTP/1.1 201 Created
Content-Type: application/json
        
{
    "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv2"
}
    ]]></artwork>
        </figure>

        <t>In case of custom attributes, the client does not necessarily use
        any specific protocol for obtaining user attributes. It can use a
        pre-established relationship with the AS to provide the required set
        of attributes.</t>
      </section>

      <section anchor="claims-as-saml-conveyor"
               title="Client Acts as SAML Assertion Conveyor">
        <t>TYPE = "claim-client-assertion-saml-1.0"</t>

        <t>VALUE = {base64-encoded SAML assertion}</t>

        <t>In this setting the AS and the Client have a pre-established trust
        relationship. The client may provide the AS with a SAML assertion that
        can be used for policy evaluation. We provide an example of the
        request below.</t>

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

          <artwork><![CDATA[POST /rpt_authorization HTTP/1.1
Host: www.nuveam.com
Authorization: Bearer jwfLG53^sad$#f
...
            
{
    "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
    "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de",
    "claims": [
    {
        "type": "claim-client-assertion-saml-1.0",
        "value": {
        "saml_assertion": "PHNhbWxwOl...[omitted for brevity]...ZT"
        }
    }
    ]
    
}
        ]]></artwork>
        </figure>
      </section>

      <section anchor="claims-as-oidc-conveyor"
               title="Client Acts as OpenID Connect Claims Conveyor">
        <t>TYPE = "claim-client-claims-oidc-1.0"</t>

        <t>VALUE = {set of oidc reserved claims}</t>

        <t>In this setting the AS and the Client have a pre-established trust
        relationship. The client may provide the AS with a OpenID Connect user
        claims that can be used for policy evaluation. We provide an example
        of the request made by the client to the Authorization Server
        below.</t>

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

          <artwork><![CDATA[POST /rpt_authorization HTTP/1.1
Host: www.nuveam.com
Authorization: Bearer jwfLG53^sad$#f
...
            
{
    "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
    "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de",
    "claims": [
    {
        "type": "claim-client-claims-oidc-1.0",
        "value": {
        "sub": "248289761001"
        "name": "Jane Doe",
        "given_name": "Jane",
        "family_name": "Doe",
        "email": "joedoe@example.com"
        "email_verified": true,
        }
    }
    ]    
}
        ]]></artwork>
        </figure>
      </section>

      <section anchor="claims-as-custom-conveyor"
               title="Hybrid Approach: Client Acts as Custom Claims Conveyor and OpenID Connect Claims Conveyor">
        <t>TYPE = "custom"</t>

        <t>VALUE = {custom defined}</t>

        <t>TYPE = "claim-client-claims-oidc-1.0"</t>

        <t>VALUE = {set of oidc reserved claims}</t>

        <t>In this setting the AS and the Client have a pre-established trust
        relationship. The client may provide the AS with custom claims as well
        as with OpenID Connect user claims that can be used for policy
        evaluation. We provide an example of the request below.</t>

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

          <artwork><![CDATA[POST /rpt_authorization HTTP/1.1
Host: www.nuveam.com
Authorization: Bearer jwfLG53^sad$#f
...
{
    "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
    "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de",
    "claims": [
    {
        "type": "ci-nuveam-claims",
        "value": { "roles": ["manager", "admin" }
            },
    {
        "type": "claim-client-claims-oidc-1.0",
        "value": { "email": "bob@gmail.com" }
            }
    ]
}
    ]]></artwork>
        </figure>
      </section>

      <section anchor="claims-as-redirect"
               title="Client Redirects Requesting Party to AS">
        <t>TYPE = "claim-client-redirect-1.0"</t>

        <t>VALUE = {value of the scope at AS}</t>

        <t>The redirect UMA profile defines a Requesting Party Claims Endpoint
        that the Authorization Server has to support. This endpoint is
        advertised in the Authorisation Server Configuration Data as defined
        by the UMA specification <xref target="UMA"></xref>. The requesting
        party claims endpoint is used by the Authorization Server to interact
        with the requesting party and not with the client application. The
        authorization server can first verify the identity of the requesting
        party or it may engage the requesting party in claims gathering flow.
        For example, the AS may decide based on the authentication process
        that it has enough information to evaluate a policy or it may require
        the requesting party to provide further claims, e.g. using an existing
        identity federation protocol. For example, after landing at this
        endpoint the requesting party may be further redirected to the source
        of claims (e.g. SAML IDP or the OpenID Connect Identity Provider).</t>

        <section anchor="claims-as-redirect-endpoint"
                 title="Requesting Party Claims Endpoint">
          <t>In redirect UMA profile, the configuration data has to be
          extended with the following property.<list hangIndent="6"
              style="hanging">
              <t
              hangText="requesting_party_claims_endpoint"><vspace />REQUIRED.
              The endpoint URI at which the authorization server interacts
              with the end-user requesting party to obtain the necessary
              user-claims that will be used during policy evaluation
              process.</t>
            </list></t>

          <figure>
            <preamble>Example of authorization server configuration extended
            with requesting party claims endpoint:</preamble>

            <artwork><![CDATA[{
"version":"1.0",
"issuer":"https://example.com",
"pat_profiles_supported":["bearer"],
"aat_profiles_supported":["bearer"],
"rpt_profiles_supported":["bearer"],
"pat_grant_types_supported":["authorization_code"],
"aat_grant_types_supported":["authorization_code"],
"claim_profiles_supported":["openid"],
"dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri",
"token_endpoint":"https://as.example.com/token_uri",
"user_endpoint":"https://as.example.com/user_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",
"authorization_request_endpoint":"https://as.example.com/client/authz_uri",
"requesting_party_claims_endpoint":"https://as.example.com/rp/claims_uri"
}]]></artwork>
          </figure>
        </section>

        <section anchor="claims-as-redirect-flow" title="Message Flow">
          <t>Message flow:</t>

          <figure>
            <preamble>1. Client asks for new authorization data to be added to
            an existing RPT</preamble>

            <artwork><![CDATA[POST /rpt_authorization HTTP/1.1
        Host: www.nuveam.com
        Authorization: Bearer jwfLG53^sad$#f
        ...
                
        {
        "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
        "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
        }
            ]]></artwork>
          </figure>

          <figure>
            <preamble>2. AS tells the client to redirect the user to the
            Requesting Party Claims Endpoint and includes the scope parameter
            in the value of the response</preamble>

            <artwork><![CDATA[HTTP/1.1 403 Forbidden
    Content-Type: application/json
            
    {
      "need_claims":[
        {
          "type":"redirect_required",
          "name":"Redirect Required",
          "value":"699faf5bf2869838e992d57756bc6f"
        }
      ]
    }
        ]]></artwork>
          </figure>

          <figure>
            <preamble>3. Client redirects the user to the Requesting Party
            Claims Endpoint and includes the scope parameter in the
            request</preamble>

            <artwork><![CDATA[HTTP/1.1 302 Found
    Location: https://www.nuveam.com/uma/rp_claims?scope=699faf5bf2869838e992
    d57756bc6f&redirect_uri=http%3A%2F%2Fwww.umaapp.com%%2Fredirect&client_id=
    ca4453936fa5fda2110b9e589d61ab37&state=32455ddsafas
    ]]></artwork>
          </figure>

          <t>After the user is redirected to the AS, the claims for the user
          are gathered according to one of the defined protocols, such as
          SAML, OpenID Connect or any other protocol implemented by an
          UMA-compliant Authorisation Server. Furthermore, the AS is free to
          obtain the information from a local or remote LDAP, Active Directory
          or any other user datastore (e.g. SQL or NoSQL-based datastore).</t>

          <figure>
            <preamble>4. AS informs the client that new authorization can be
            added and the client is free to request a new RPT</preamble>

            <artwork><![CDATA[HTTP/1.1 302 Found
    Location: https://www.umaapp.com/redirect?access=granted&state=32455ddsafas
          ]]></artwork>
          </figure>

          <figure>
            <preamble>5. AS informs the client that authorization data cannot
            be added</preamble>

            <artwork><![CDATA[HTTP/1.1 302 Found
    Location: https://www.umaapp.com/redirect?access=denied&state=32455ddsafas
          ]]></artwork>
          </figure>
        </section>

        <section anchor="claims-as-redirect-examples" title="Examples">
          <t>In this section, we discuss three examples:<list style="numbers">
              <t>User is redirected to an OIDC Provider;</t>

              <t>User is redirected to a SAML IDP;</t>

              <t>User's authentication is sufficient for policy
              evalutation.</t>
            </list></t>

          <section anchor="claims-as-rp-oidc"
                   title="Authorization Server Acts as OpenID Connect Relying Party">
            <t>In this claim profile example, the Authorisation Server acts as
            an OIDC compliant RP. This flow is used in case the policies for a
            particular resource set use any of the existing reserved OIDC
            claims. Importantly, it is the AS that determines if OIDC claims
            should be used for policy evaluation. This information is not
            shared with the client application.</t>

            <t>During this flow the AS acts according to the OpenID Connect
            protocol and this is outside of the UMA specification.</t>
          </section>

          <section anchor="claims-as-rp-saml"
                   title="Authorization Server Acts as SAML Relying Party">
            <t>In this claim profile example, the Authorisation Server acts as
            an SAML compliant Service Provider. This flow is used in case the
            policies for a particular resource set require the use of the SAML
            protocol. Importantly, it is the AS that determines if the SAML
            protocol should be used for policy evaluation. This information is
            not shared with the client application.</t>

            <t>During this flow the AS acts according to the SAML protocol and
            this is outside of the UMA specification.</t>
          </section>

          <section anchor="claims-from-local-datastore"
                   title="Authorization Server pulls Claim from local user store">
            <t>In this claim profile example and after successful
            authentication of the RP, the AS can pull the required user
            attributes from a local user datastore (e.g. LDAP, Active
            Directory, and other SQL and NoSQL-datastores). This information
            can be used for policy evaluation.</t>
          </section>
        </section>
      </section>

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

      <section anchor="Acknowledgments" title="Acknowledgments">
        <t>The current editor of this specification is Domenico Catalano of
        Oracle. The following people are co-authors:<list style="symbols">
            <t>Maciej Machulak, Cloud Identity Ltd</t>

            <t>Thomas Hardjono, MIT</t>

            <t>Eve Maler, ForgeRock</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>

      <section title="Issues">
        <t>Issues are captured at the project's GitHub site (<eref
        target="https://github.com/xmlgrrl/UMA-Specifications/issues"></eref>).</t>
      </section>
    </section>
  </middle>

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

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

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

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

    <references title="Informative References">
      <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="July" year="2014" />
        </front>
      </reference>
    </references>

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

      <t>See <eref
      target="http://kantarainitiative.org/confluence/display/uma/UMA+1.0+Core+Protocol"></eref>
      for a list of code-breaking and other major changes made to this
      specification at various revision points.</t>
    </section>
  </back>
</rfc>