draft-ietf-oauth-revocation.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!--
		This template is for creating an Internet Draft using xml2rfc, which
		is available here: http://xml.resource.org.
	-->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
     There has to be one entity for each item to be referenced. 
     An alternate method (rfc include) is described in the references. -->
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
<!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY I-D.narten-iana-considerations-rfc2434bis SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.narten-iana-considerations-rfc2434bis.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!--
		For a complete list and description of processing instructions (PIs),
		please see http://xml.resource.org/authoring/README.html.
	-->
<!--
		Below are generally applicable Processing Instructions (PIs) that most
		I-Ds might want to use. (Here they are set differently than their
		defaults in xml2rfc v1.32)
	-->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="4"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!--
		control vertical white space (using these PIs as follows is
		recommended by the RFC Editor)
	-->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="std" docName="draft-ietf-oauth-revocation-11" ipr="trust200902">
  <!--gran
		category values: std, bcp, info, exp, and historic ipr values:
		full3667, noModification3667, noDerivatives3667 you can add the
		attributes updates="NNNN" and obsoletes="NNNN" they will automatically
		be output with "(if approved)"
	-->

  <!-- ***** FRONT MATTER ***** -->

  <front>
    <!--
			The abbreviated title is used in the page header - it is only
			necessary if the full title is longer than 39 characters
		-->

    <title abbrev="Token Revocation">OAuth 2.0 Token Revocation</title>

    <author fullname="Torsten Lodderstedt" initials="T." role="editor"
            surname="Lodderstedt">
      <organization>Deutsche Telekom AG</organization>

      <address>
        <email>torsten@lodderstedt.net</email>
      </address>
    </author>

    <author fullname="Stefanie Dronia" initials="S." surname="Dronia">
      <address>
        <email>sdronia@gmx.de</email>
      </address>
    </author>

    <author fullname="Marius Scurtescu" initials="M." surname="Scurtescu ">
      <organization>Google</organization>

      <address>
        <email>mscurtescu@google.com</email>
      </address>
    </author>

    <date day="13" month="July" year="2013"/>

    <!-- Meta-data Declarations -->

    <area>Security Area</area>

    <workgroup>OAuth Working Group</workgroup>

    <!--
			WG name at the upperleft corner of the doc, IETF is fine for
			individual submissions. If this element is not present, the default
			is "Network Working Group", which is used by the RFC Editor as a nod
			to the history of the IETF.
		-->

    <keyword>token revocation</keyword>

    <keyword>oauth2</keyword>

    <!--
			Keywords will be incorporated into HTML output files in a meta tag
			but they have no effect on text or nroff output. If you submit your
			draft to the RFC Editor, the keywords will be used for the search
			engine.
		-->

    <abstract>
      <t>This document proposes an additional endpoint for OAuth authorization
      servers, which allows clients to notify the authorization server that a
      previously obtained refresh or access token is no longer needed. This
      allows the authorization server to cleanup security credentials. A
      revocation request will invalidate the actual token and, if applicable,
      other tokens based on the same authorization grant.</t>
    </abstract>

    <note title="Requirements Language">
      <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">RFC 2119</xref>.</t>
    </note>
  </front>

  <middle>
    <section anchor="Introduction" title="Introduction">
      <t>The OAuth 2.0 core specification <xref target="RFC6749"/> defines
      several ways for a client to obtain refresh and access tokens. This
      specification supplements the core specification with a mechanism to
      revoke both types of tokens. A token is a string representing an
      authorization grant issued by the resource owner to the client. A
      revocation request will invalidate the actual token and, if applicable,
      other tokens based on the same authorization grant and the authorization
      grant itself.</t>

      <t>From an end-user's perspective, OAuth is often used to log into a
      certain site or application. This revocation mechanism allows a client
      to invalidate its tokens if the end-user logs out, changes identity, or
      uninstalls the respective application. Notifying the authorization
      server that the token is no longer needed allows the authorization
      server to clean up data associated with that token (e.g. session data)
      and the underlying authorization grant. This behavior prevents a
      situation where there is still a valid authorization grant for a
      particular client which the end user is not aware of. This way, token
      revocation prevents abuse of abandoned tokens and facilitates a better
      end-user experience since invalidated authorization grants will no
      longer turn up in a list of authorization grants the authorization
      server might present to the end-user.</t>
    </section>

    <section anchor="Revocation" title="Token Revocation">
      <t>Implementations MUST support the revocation of refresh tokens and
      SHOULD support the revocation of access tokens (see <xref format="title"
      target="impl"/>).</t>

      <t>The client requests the revocation of a particular token by making an
      HTTP POST request to the token revocation endpoint URL. This URL MUST
      conform to the rules given in <xref target="RFC6749"/>, section 3.1.
      Clients MUST verify that the URL is an HTTPS URL.</t>

      <t>The means to obtain the location of the revocation endpoint is out of
      scope of this specification. For example, the client developer may
      consult the server's documentation or automatic discovery may be used.
      As this endpoint is handling security credentials, the endpoint location
      needs to be obtained from a trustworthy source.</t>

      <t>Since requests to the token revocation endpoint result in the
      transmission of plain text credentials in the HTTP request, URLs for
      token revocation endpoints MUST be HTTPS URLs. The authorization server
      MUST use Transport Layer Security (TLS) in a version compliant with
      <xref target="RFC6749"/>, section 1.6. Implementations MAY also support
      additional transport-layer security mechanisms that meet their security
      requirements.</t>

      <t>If the host of the token revocation endpoint can also be reached over
      HTTP, then the server SHOULD also offer a revocation service at the
      corresponding HTTP URI, but MUST NOT publish this URI as a token
      revocation endpoint. This ensures that tokens accidentally sent over
      HTTP will be revoked.</t>

      <section title="Revocation Request">
        <t>The client constructs the request by including the following
        parameters using the "application/x-www-form-urlencoded" format in the
        HTTP request entity-body:</t>

        <t><list hangIndent="8" style="hanging">
            <t hangText="token">REQUIRED. The token that the client wants to
            get revoked.</t>

            <t hangText="token_type_hint">OPTIONAL. A hint about the type of
            the token submitted for revocation. Clients MAY pass this
            parameter in order to help the authorization server to optimize
            the token lookup. If the server is unable to locate the token
            using the given hint, it MUST extend its search accross all of its
            supported token types. An authorization server MAY ignore this
            parameter, particularly if it is able to detect the token type
            automatically. This specification defines two such values:<list
                style="symbols">
                <t>access_token: An Access Token as defined in <xref
                target="RFC6749"/>, section 1.4</t>

                <t>refresh_token: A Refresh Token as defined in <xref
                target="RFC6749"/>, section 1.5</t>
              </list>Specific implementations, profiles, and extensions of
            this specification MAY define other values for this parameter
            using the registry defined in <xref target="hint-reg"/>.</t>
          </list></t>

        <t>The client also includes its authentication credentials as
        described in Section 2.3. of <xref target="RFC6749"/>.</t>

        <t>For example, a client may request the revocation of a refresh token
        with the following request:</t>

        <figure>
          <artwork><![CDATA[
  POST /revoke HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
     
  token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token]]></artwork>
        </figure>

        <t>The authorization server first validates the client credentials (in
        case of a confidential client) and then verifies whether the token was
        issued to the client making the revocation request. If this validation
        fails, the request is refused and the client is informed of the error
        by the authorization server as described below.</t>

        <t>In the next step, the authorization server invalidates the token.
        The invalidation takes place immediately, and the token can not be
        used again after the revocation. In practice there could be a
        propagation delay, for example, in which some servers know about the
        invalidation while others do not. Implementations should minimize that
        window, and clients must not try to use the token after receipt of an
        HTTP 200 response from the server.</t>

        <t>Depending on the authorization server's revocation policy, the
        revocation of a particular token may cause the revocation of related
        tokens and the underlying authorization grant. If the particular token
        is a refresh token and the authorization server supports the
        revocation of access tokens, then the authorization server SHOULD also
        invalidate all access tokens based on the same authorization grant
        (see <xref format="title" target="impl"/>). If the token passed to the
        request is an access token, the server MAY revoke the respective
        refresh token as well.</t>

        <t>Note: A client compliant with <xref target="RFC6749"/> must be
        prepared to handle unexpected token invalidation at any time.
        Independent of the revocation mechanism specified in this document,
        resource owners may revoke authorization grants or the authorization
        server may invalidate tokens in order to mitigate security threats.
        Thus having different server policies with respect to cascading the
        revocation of tokens should not pose interoperability problems.</t>
      </section>

      <section title="Revocation Response">
        <t>The authorization server responds with HTTP status code 200 if the
        token has been revoked sucessfully or if the client submitted an
        invalid token.</t>

        <t>Note: invalid tokens do not cause an error response since the
        client cannot handle such an error in a reasonable way. Moreover, the
        purpose of the revocation request, invalidating the particular token,
        is already achieved.</t>

        <t>The content of the response body is ignored by the client as all
        necessary information is conveyed in the response code.</t>

        <t>An invalid token type hint value is ignored by the authorization
        server and does not influence the revocation response.</t>

        <section title="Error Response">
          <t>The error presentation conforms to the definition in section 5.2
          of <xref target="RFC6749"/>. The following additional error code is
          defined for the token revocation endpoint: <list hangIndent="8"
              style="hanging">
              <t hangText="unsupported_token_type">The authorization server
              does not support the revocation of the presented token type.
              I.e. the client tried to revoke an access token on a server not
              supporting this feature.</t>
            </list></t>

          <t>If the server responds with HTTP status code 503, the client must
          assume the token still exists and may retry after a reasonable
          delay. The server may include a "Retry-After" header in the response
          to indicate how long the service is expected to be unavailable to
          the requesting client.</t>
        </section>
      </section>

      <section anchor="cross-orgin" title="Cross-Origin Support">
        <t>The revocation end-point MAY support <xref format="title"
        target="W3C.WD-cors-20120403">CORS</xref> if it is aimed at use in
        combination with user-agent-based applications.</t>

        <t>In addition, for interoperability with legacy user-agents, it MAY
        also offer <xref format="title" target="jsonp">JSONP</xref> by
        allowing GET requests with an additional parameter: <list
            hangIndent="8" style="hanging">
            <t hangText="callback">OPTIONAL. The qualified name of a
            JavaScript function.</t>
          </list></t>

        <t>For example, a client may request the revocation of an access token
        with the following request (line breaks are for display purposes
        only):</t>

        <figure>
          <artwork><![CDATA[
  https://example.com/revoke?token=agabcdefddddafdd&
  callback=package.myCallback
]]></artwork>
        </figure>

        <t>Successful response:</t>

        <figure>
          <artwork><![CDATA[
  package.myCallback();
]]></artwork>
        </figure>

        <t>Error response:</t>

        <figure>
          <artwork><![CDATA[
  package.myCallback({"error":"unsupported_token_type"});
]]></artwork>
        </figure>

        <t>Clients should be aware that when relying on JSONP, a malicious
        revocation end-point may attempt to inject malicious code into the
        client.</t>
      </section>
    </section>

    <section anchor="impl" title="Implementation Note">
      <t>OAuth 2.0 allows deployment flexibility with respect to the style of
      access tokens. The access tokens may be self-contained so that an
      resource server needs no further interaction with an authorization
      server issuing these tokens to perform an authorization decision of the
      client requesting access to a protected resource. A system design may,
      however, instead use access tokens that are handles referring to
      authorization data stored at the authorization server. This consequently
      requires a resource server to issue a request to the respective
      authorization server to retrieve the content of the access token every
      time a client presents an access token.</t>

      <t>While these are not the only options they illustrate the implications
      for revocation. In the latter case the authorization server is able to
      revoke an access token previously issued to a client when the resource
      server relays a received access token. In the former case some
      (currently non-standardized) backend interaction between the
      authorization server and the resource server may be used when immediate
      access token revocation is desired. Another design alternative is to
      issue short-lived access tokens, which can be refreshed at any time
      using the corresponding refresh tokens. This allows the authorization
      server to impose a limit on the time revoked access tokens are in
      use.</t>

      <t>Which approach of token revocation is chosen will depend on the
      overall system design and on the application service provider's risk
      analysis. The cost of revocation in terms of required state and
      communication overhead is ultimately the result of the desired security
      properties.</t>
    </section>

    <section anchor="IANA" title="IANA Considerations">
      <t>This specification registers an error value in the OAuth Extension
      Error registry and establishes the OAuth Token Type registry.</t>

      <section title="OAuth Extensions Error Registration">
        <t>This specification registers the following error values in the
        OAuth Extensions Error registry defined in <xref
        target="RFC6749"/>.</t>

        <section title="The &quot;unsupported_token_type&quot; Error Value">
          <t><list hangIndent="8" style="hanging">
              <t hangText="Error name">unsupported_token_type</t>

              <t hangText="Error usage location">revocation endpoint error
              response</t>

              <t hangText="Related protocol extension">Token Revocation
              Endpoint</t>

              <t hangText="Change controller">IETF</t>

              <t hangText="Specification document(s)">[this document]</t>
            </list></t>
        </section>

        <section anchor="hint-reg" title="OAuth Token Type Hint Registry">
          <t>This specification establishes the OAuth Token Type Hint
          registry. Possible values of the parameter "token_type_hint" (see
          Section 2.1) are registered with a Specification Required (<xref
          target="RFC5226"/>) after a two-week review period on the
          TBD@ietf.org mailing list, on the advice of one or more Designated
          Experts. However, to allow for the allocation of values prior to
          publication, the Designated Expert(s) may approve registration once
          they are satisfied that such a specification will be published.
          Registration requests must be sent to the TBD@ietf.org mailing list
          for review and comment, with an appropriate subject (e.g., "Request
          for parameter: example"). Within the review period, the Designated
          Expert(s) will either approve or deny the registration request,
          communicating this decision to the review list and IANA. Denials
          should include an explanation and, if applicable, suggestions as to
          how to make the request successful. IANA must only accept registry
          updates from the Designated Expert(s) and should direct all requests
          for registration to the review mailing list.</t>

          <section title="Registration Template">
            <t><list style="hanging">
                <t hangText="Hint Value:">The additional value, which can be
                used to indicate a certain token type to the authorization
                server.</t>

                <t hangText="Change controller:">For Standards Track RFCs,
                state "IETF". For others, give the name of the responsible
                party. Other details (e.g., postal address, email address,
                home page URI) may also be included.</t>

                <t hangText="Specification document(s):">Reference to the
                document(s) that specify the type, preferably including a URI
                that can be used to retrieve a copy of the document(s). An
                indication of the relevant sections may also be included but
                is not required.</t>
              </list></t>
          </section>

          <section title="Initial Registry Contents">
            <t>The OAuth Token Type Hint registry's initial contents are:</t>

            <t><list style="symbols">
                <t>Hint Value: access_token</t>

                <t>Change controller: IETF</t>

                <t>Specification document(s): [this document]</t>

                <t>Hint Value: refresh_token</t>

                <t>Change controller: IETF</t>

                <t>Specification document(s): [this document]</t>
              </list></t>
          </section>
        </section>
      </section>
    </section>

    <section anchor="Security" title="Security Considerations">
      <t>If the authorization server does not support access token revocation,
      access tokens will not be immediately invalidated when the corresponding
      refresh token is revoked. Deployments must take this into account when
      conducting their security risk analysis.</t>

      <t>Cleaning up tokens using revocation contributes to overall security
      and privacy since it reduces the likelihood for abuse of abandoned
      tokens. This specification in general does not intend to provide
      countermeasures against token theft and abuse. For a discussion of
      respective threats and countermeasures, consult the security
      considerations given in section 10 of the OAuth core specification <xref
      target="RFC6749"/> and the OAuth threat model document <xref
      target="RFC6819"/>.</t>

      <t>Malicious clients could attempt to use the new endpoint to launch
      denial of service attacks on the authorization server. Appropriate
      countermeasures, which should be in place for the token endpoint as
      well, MUST be applied to the revocation endpoint (see <xref
      target="RFC6819"/>, section 4.4.1.11). Specifically, invalid token type
      hints may misguide the authorization server and cause additional
      database lookups. Care MUST be taken to prevent malicious clients from
      exploiting this feature to launch denial of service attacks.</t>

      <t>A malicious client may attempt to guess valid tokens on this endpoint
      by making revocation requests against potential token strings. According
      to this specification, a client's request must contain a valid
      client_id, in the case of a public client, or valid client credentials,
      in the case of a confidential client. The token being revoked must also
      belong to the requesting client. If an attacker is able to successfully
      guess a public client's client_id and one of their tokens, or a private
      client's credentials and one of their tokens, they could do much worse
      damage by using the token elsewhere than by revoking it. If they chose
      to revoke the token, the legitimate client will lose its authorization
      grant and will need to prompt the user again. No further damage is done
      and the guessed token is now worthless.</t>

      <t>Since the revocation endpoint is handling security credentials,
      clients need to obtain its location from a trustworthy source only.
      Otherwise, an attacker could capture valid security tokens by utilizing
      a counterfeit revocation endpoint. Moreover in order to detect
      counterfeit revocation endpoints, clients MUST authenticate the
      revocation endpoint (certificate validation etc.).</t>
    </section>

    <section anchor="Acknowledgements" title="Acknowledgements">
      <t>We would like to thank Peter Mauritius, Amanda Anganes, Mark Wubben,
      Hannes Tschofenig, Michiel de Jong, Doug Foiles, Paul Madsen, George
      Fletcher, Sebastian Ebling, Christian St&uuml;bner, Brian Campbell, Igor
      Faynberg, Lukas Rosenstock, and Justin Richer for their valuable
      feedback.</t>
    </section>
  </middle>

  <!--  *****BACK MATTER ***** -->

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

      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2246.xml' ?>

      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml' ?>

      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5246.xml' ?>

      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.6749.xml' ?>
    </references>

    <references title="Informative References">
      <?rfc include='http://xml.resource.org/public/rfc/bibxml4/reference.W3C.WD-cors-20120403.xml' ?>

      <reference anchor="jsonp"
                 target="http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp">
        <front>
          <title>Remote JSON - JSONP</title>

          <author fullname="Bob Ippolito" initials="B." surname="Ippolito">
            <organization/>
          </author>

          <date day="5" month="December" year="2005"/>
        </front>

        <format target="http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp"
                type="HTML"/>
      </reference>

      <?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.6819.xml"?>
    </references>
  </back>
</rfc>