One document matched: draft-reddy-tram-token-metadata-00.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-reddy-tram-token-metadata-00"
     ipr="trust200902">
  <front>
    <title abbrev="Metadata discovery for TURN session">Metadata discovery for
    third party authorized TURN session</title>

    <author fullname="Tirumaleswar Reddy" initials="T." surname="Reddy">
      <organization abbrev="Cisco">Cisco Systems, Inc.</organization>

      <address>
        <email>tireddy@cisco.com</email>
      </address>
    </author>

    <author fullname="Suhas Nandakumar" initials="S." surname="Nandakumar">
      <organization abbrev="Cisco">Cisco Systems, Inc.</organization>

      <address>
        <email>snandaku@cisco.com</email>
      </address>
    </author>

    <author fullname="Dan Wing" initials="D." surname="Wing">
      <organization abbrev="Cisco">Cisco Systems, Inc.</organization>

      <address>
        <postal>
          <street>170 West Tasman Drive</street>

          <city>San Jose</city>

          <region>California</region>

          <code>95134</code>

          <country>USA</country>
        </postal>

        <email>dwing@cisco.com</email>
      </address>
    </author>

    <author fullname="Brandon Williams" initials="B." surname="Williams">
      <organization>Akamai, Inc.</organization>

      <address>
        <postal>
          <street>8 Cambridge Center</street>

          <city>Cambridge, MA</city>

          <code>02142</code>

          <country>USA</country>
        </postal>

        <email>brandon.williams@akamai.com</email>
      </address>
    </author>

    <date />

    <workgroup>TRAM</workgroup>

    <abstract>
      <t>The operator of the TURN server might want to have fine grained
      control on the clients usage of the server resources for providing
      features such as limiting the bandwith usage, number of allocations and
      so on. This document proposes a generic mechanism for the operator to
      introspect the access token to retrieve any policy restrictions imposed
      by the authorization server on the TURN server resources assigned to the
      client.</t>
    </abstract>
  </front>

  <middle>
    <section anchor="introduction" title="Introduction">
      <t>The TURN protocol <xref target="RFC5766"></xref> is used to setup a
      relay service (via a TURN Server) to exchange traffic (real time media,
      data) between peers when direct peer-to-peer connection is not otherwise
      possible. Due to the costs associated with operating a relay service, it
      is important to constrain resource usage. For example, the operator
      might want to limit the number of allocations or bandwidth.</t>

      <t><xref target="I-D.ietf-tram-turn-third-party-authz"></xref> allows
      clients to obtain OAuth2.0 access token (of type
      ‘Assertion’) authorized by a Authorization Server to access
      a given TURN server. On receiving such a token, the TURN server
      validates the token to grant or reject access to the session resources.
      However, having a token doesn't provide any control for the operator of
      the TURN server restrict the server's resources. This specification
      proposes using the mechanism defined in <xref
      target="I-D.ietf-oauth-introspection"></xref> to query OAuth2.0
      authorization server to determine resource restrictions for this
      token.</t>

      <t>The rest of the document is organized as follows. <xref
      target="introspect_req"></xref> provides procedure for querying the
      OAuth2.0 introspection endpoint and <xref
      target="introspect_resp"></xref> shows the introspection response with
      the parameters identifying the policy controls associated with the
      access token.</t>
    </section>

    <section anchor="term" title="Terminology">
      <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>This document defines the following terms:</t>

      <t>Access Token: OAuth 2.0 access token.</t>

      <t>Token Introspection: The act of inquiring about the current state of
      an OAuth 2.0 token through use of the network protocol defined in this
      document.</t>

      <t>Introspection Endpoint: The OAuth 2.0 endpoint through which the
      token introspection operation is accomplished. The Introspection
      Endpoint could be a WebRTC server.</t>
    </section>

    <section anchor="introspect_req" title="Introspection Request">
      <t>For introspecting the meta-information associated with the access
      token, the TURN server shall execute the procedures defined in Section
      2.1 of <xref target="I-D.ietf-oauth-introspection"></xref>.</t>

      <figure>
        <artwork><![CDATA[
  POST {scheme}://{host}:{port}/.well-known/introspection
  Accept: application/json
  Content-Type: application/x-www-form-urlencoded

  {
      "token" : "string" 
      "token_type_hint" : "string"
  }
]]></artwork>
      </figure>

      <t><list hangIndent="5" style="hanging">
          <t>token REQUIRED. This parameter is defined in <xref
          target="I-D.ietf-oauth-introspection"></xref>. The access token is
          conveyed by the TURN client to the TURN server as discussed in
          Section 3.1 of <xref
          target="I-D.ietf-tram-turn-third-party-authz"></xref>.</t>

          <t>token_type_hint OPTIONAL. This parameter is defined in <xref
          target="I-D.ietf-oauth-introspection"></xref>. The token type MUST
          be set to ‘access_token’ defined in <xref
          target="RFC7009"></xref>. If the token type is not
          ‘access_token’, the server rejects the request with a
          400 (Bad Request) error.</t>
        </list></t>

      <t>Following is a non-normative example request showcasing the
      introspection request for a given access token.</t>

      <figure>
        <artwork><![CDATA[
  POST /introspect HTTP/1.1
  Host: server.example.com
  Accept: application/json
  Content-Type: application/x-www-form-urlencoded
  
  {

     "token" : "2YotnFZFEjr1zCsicMWpAA"
     "token_type_hint" : "access_token"

  }]]></artwork>
      </figure>
    </section>

    <section anchor="introspect_resp" title="Introspection Response">
      <t>The OAuth2.0 Introspection Endpoint on recognizing the token,
      responds with a JSON object <xref target="RFC7159"></xref> in
      “application/json” format with the following members.</t>

      <figure>
        <artwork><![CDATA[
  HTTP/1.1 200 OK
  Content-Type: application/json
 
  {
  "active" : "boolean",
  "scope" : "string",
  "max_upstream_bandwidth" : "unsigned integer",
  "max_downstream_bandwidth" : "unsigned integer",
  "max_allocations" : "unsigned integer",
  "lifetime" : "unsigned integer",
  }
]]></artwork>
      </figure>

      <t><list hangIndent="5" style="hanging">
          <t>active REQUIRED. This parameter is defined in <xref
          target="I-D.ietf-oauth-introspection"></xref>.</t>

          <t>scope OPTIONAL. This parameter is defined in <xref
          target="I-D.ietf-oauth-introspection"></xref>. For this
          specification, the scope MUST be 'stun'.</t>

          <t>max_upstream_bandwidth REQUIRED. The value of this parameter is
          an 64 bit unsigned integer that represents the maximum upstream
          bandwidth permitted for the token in kilobits per second (1 kilobit
          = 1024 bits).</t>

          <t>max_downstream bandwidth REQUIRED. The value of this parameter is
          an 64 bit unsigned integer that represents the maximum downstream
          bandwidth permitted for the token in kilobits per second (1 kilobit
          = 1024 bits).</t>

          <t>max_allocations: REQUIRED. 16 bit unsigned integer defining
          maximum number of allocations that is allowable for the given access
          token.</t>

          <t>lifetime: REQUIRED: The lifetime of the access token, in
          seconds.</t>
        </list></t>

      <t>NOTE: Future specifications are allowed to define further top-level
      members as mandated by the use-cases.</t>

      <t>Following is a non-normative example response:</t>

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

  {
  "active" : true,
  "scope" : "stun",
  "upstream-bandwidth" : 4096,
  "downstream-bandwidth" : 4096,
  "max-allocations" : 1,
  }
]]></artwork>
      </figure>
    </section>

    <section anchor="introspection_endpoint"
             title="INTROSPECTION_ENDPOINT Attribute">
      <t>This attribute is used by the TURN client to inform the TURN server
      the FQDN of Introspection Endpoint.</t>

      <t>The TURN server establishes an HTTPS connection with the indicated
      server and sends the above-described communications to that server. The
      INTROSPECTION_ENDPOINT attribute is a comprehension-optional attribute
      (see Section 15 from <xref target="RFC5389"></xref>).</t>

      <t>TBD: An alternate approach is to convey the FQDN in the token
      itself.</t>
    </section>

    <section anchor="revoke" title="Notifications from Introspection Endpoint">
      <t>Introspection Endpoint can send unsolicited responses to notify
      updates to the metadata associated with the token to the TURN server
      using HTTP/2 server push mechanism. Examples where such notifications
      are desired are:</t>

      <t><list style="symbols">
          <t>The Introspection Endpoint can signal the TURN server to revoke
          the access token after the call is terminated by setting lifetime to
          zero.</t>

          <t>When the call switches from audio to video, the Introspection
          Endpoint notifies the increased bandwidth to the TURN server.</t>
        </list></t>
    </section>

    <section anchor="alternate" title="Alternate approach">
      <t>TBD:</t>

      <t>Another approach, not discussed in this document, is a self-
      contained token where the metadata is contained within the token itself.
      This approach has the benefit of avoiding a protocol between the TURN
      server and the Introspection Endpoint. However, this approach has the
      following drawbacks:</t>

      <t><list style="symbols">
          <t>Needs a large TURN packet to accommodate the token.</t>

          <t>Token needs versioning for future enhancements, and the
          Introspection Endpoint needs a mechanism to learn the token version
          supported by the TURN server.</t>

          <t>Introspection Endpoint cannot notify changes to the metadata
          associated with the token to the TURN server.</t>
        </list></t>
    </section>

    <section anchor="security" title="Security Considerations">
      <t>The Security Considerations and Privacy Considerations of <xref
      target="I-D.ietf-oauth-introspection"></xref> apply to this
      document.</t>
    </section>

    <section anchor="iana" title="IANA Considerations">
      <section title="JSON Web Token Claims">
        <t>This specification requests IANA to register the following values
        into the IANA JSON Web Token Claims registry for JWT Claim Names.</t>

        <t><?rfc subcompact="yes"?><list style="symbols">
            <t>Claim Name: <spanx style="verb">max_upstream_bandwidth</spanx></t>

            <t>Claim Description: Maximum limit of upstream bandwidth</t>

            <t>Change Controller: IESG</t>

            <t>Specification Document(s): <xref
            target="introspect_resp"></xref> of [[ this document ]].</t>
          </list><list style="symbols">
            <t>Claim Name: <spanx style="verb">max_downstream_bandwidth</spanx></t>

            <t>Claim Description: Maximum limit of downstream bandwidth</t>

            <t>Change Controller: IESG</t>

            <t>Specification Document(s): <xref
            target="introspect_resp"></xref> of [[ this document ]].</t>
          </list><list style="symbols">
            <t>Claim Name: <spanx style="verb">max_allocations</spanx></t>

            <t>Claim Description: Maximum number of allocations</t>

            <t>Change Controller: IESG</t>

            <t>Specification Document(s): <xref
            target="introspect_resp"></xref> of [[ this document ]].</t>
          </list><?rfc subcompact="no"?></t>
      </section>

      <section title="Well-Known 'introspection' URI">
        <t>This memo registers the 'introspection' well-known URI in the
        Well-Known URIs registry as defined by <xref
        target="RFC5785"></xref>.</t>

        <t>URI suffix: introspection</t>

        <t>Change controller: IETF</t>

        <t>Specification document(s): This document</t>

        <t>Related information: None</t>
      </section>

      <section title="STUN attribute">
        <t>[Paragraphs below in braces should be removed by the RFC Editor
        upon publication]</t>

        <t>[IANA is requested to add the following attributes to the <xref
        target="iana-stun">STUN attribute registry</xref>, the
        INTROSPECTION_ENDPOINT attribute requires that IANA allocate a value
        in the "STUN attributes Registry" from the comprehension-optional
        range (0x8000-0xBFFF)].</t>

        <t>This document defines the INTROSPECTION_ENDPOINT attribute,
        described in <xref target="introspection_endpoint"></xref>. IANA has
        allocated the comprehension-optional codepoint TBD for this
        attribute.</t>
      </section>
    </section>

    <section title="Acknowledgements">
      <t>TODO</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include="reference.RFC.2119"?>

      <?rfc include="reference.RFC.5389"?>

      <?rfc include="reference.RFC.5766"?>

      <?rfc include='reference.I-D.ietf-tram-turn-third-party-authz'?>

      <?rfc include='reference.I-D.ietf-oauth-introspection' ?>

      <reference anchor="iana-stun"
                 target="http://www.iana.org/assignments/stun-parameters/stun-pa rameters.xml">
        <front>
          <title>IANA: STUN Attributes</title>

          <author fullname="IANA" surname="IANA">
            <organization></organization>
          </author>

          <date month="April" year="2011" />
        </front>
      </reference>
    </references>

    <references title="Informative References">
      <?rfc include="reference.RFC.7159"?>

      <?rfc include="reference.RFC.7009"?>

      <?rfc include="reference.RFC.5785"?>

      <!---->
    </references>
  </back>
</rfc>