OAuth Working Group                                       J. Richer, Ed.
Internet-Draft                                     The MITRE Corporation
Intended status: Standards Track                         August 22,                       November 30, 2014
Expires: February 23, June 3, 2015

                     OAuth 2.0 Token Introspection
                   draft-ietf-oauth-introspection-00
                   draft-ietf-oauth-introspection-01

Abstract

   This specification defines a method for a client or protected resource to query
   an OAuth 2.0 authorization server to validate determine the active state of an
   OAuth 2.0 token and to determine meta-information about an OAuth this token.
   OAuth 2.0 deployments can use this method to convey information about
   the authorization context of the token from the authorization server
   to the protected resource.

Requirements Language

   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 RFC 2119 [RFC2119].

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on February 23, June 3, 2015.

Copyright Notice

   Copyright (c) 2014 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Introspection Endpoint  . . . . . . . . . . . . . . . . . . .   2   3
     2.1.  Introspection Request . . . . . . . . . . . . . . . . . .   3
     2.2.  Introspection Response  . . . . . . . . . . . . . . . . .   3   4
     2.3.  Non-normative Example  Error Response  . . . . . . . . . . . . . . . . . .   4 . . .   5
   3.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   6   5
   5.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .   7
   6.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   6
   6.   7
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   7
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .   7
     7.2.  Informative References  . . . . . . . . . . . . . . . .   6 .   8
   Appendix A.  Document History . . . . . . . . . . . . . . . . . .   6   8
   Appendix B.  Non-normative Example  . . . . . . . . . . . . . . .   8
   Appendix C.  Use with Proof of Posession Tokens . . . . . . . . .  10
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   7  10

1.  Introduction

   In OAuth, OAuth 2.0, the contents of tokens are opaque to clients.  This
   means that the client does not need to know anything about the
   content or structure of the token itself, if there is any.  However,
   there is still a large amount of metadata that may be attached to a
   token, such as its current validity, approved scopes, and extra information
   about the authentication context in which the token was issued.  These pieces of
   information are often vital to Protected Resources protected resources making
   authorization decisions based on the tokens being presented.  Since OAuth2
   OAuth 2.0 [RFC6749] defines no direct relationship between the Authorization
   Server
   authorization server and the Protected Resource, protected resource, only that they must
   have an agreement on the tokens themselves, there have been many
   different approaches to bridging this gap.  These include using
   structured token formats such as JWT [JWT] or SAML [[ Editor's Note:
   Which SAML document should we reference here? ]] and proprietary
   inter-service communication mechanisms (such as shared databases and
   protected enterprise service buses) that convey token information.

   This specification defines an Introspection Endpoint interoperable web API that allows the
   holder of a token
   authorized protected resources to query the Authorization Server authorization server to discover
   determine the set of metadata for a token.  A Protected Resource may use the
   mechanism described in this draft given token that was presented to query
   them by an OAuth 2.0 client.  This metadata includes whether or not
   the token is currently active (or if it has expired or otherwise been
   revoked), what rights of access the token carries (usually conveyed
   through OAuth 2.0 scopes), and the Introspection Endpoint
   in a particular authorization decision context and ascertain in which the
   relevant metadata about
   token was granted (including who authorized the token in order to make this authorization
   decision appropriately.

2.  Introspection Endpoint

   The Introspection Endpoint and which
   client it was issued to).  Token introspection allows a protected
   resource to query this information regardless of whether or not it is an OAuth 2 Endpoint that responds
   carried in the token itself, allowing this method to
   HTTP POST requests (and optionally HTTP GET requests) from be used along
   with or independently of structured token
   holders, particularly including Resource Servers values.  Additionally, a
   protected resource can use the mechanism described in this
   specification to introspect the token in a particular authorization
   decision context and Clients. ascertain the relevant metadata about the token
   in order to make this authorization decision appropriately.

2.  Introspection Endpoint

   The introspection endpoint is an OAuth 2.0 endpoint that takes a single
   parameter representing the an OAuth 2.0 token (and
   optionally further authentication) and returns a JSON
   [RFC7159] document representing the meta information surrounding the
   token.

   The introspection endpoint MUST be protected by TLS of at least
   version 1.2 RFC 5246 [RFC5246] and MAY support additional transport-
   layer mechanisms meeting its security requirements.  When using TLS,
   the client or equivalent. protected resource MUST perform a TLS/SSL server
   certificate check, per RFC 6125 [RFC6125].  Implementation security
   considerations can be found in Recommendations for Secure Use of TLS
   and DTLS [TLS.BCP].

2.1.  Introspection Request

   The protected resource calls the introspection endpoint using an HTTP
   POST [RFC2616] request (or optionally an HTTP GET request).  The
   protected resource sends a parameter representing the token along
   with optional parameters representing additional context that is
   known by the protected resource to aid the authorization server in
   its response.

   token  REQUIRED.  The string value of the token.  For access tokens,
      this is the "access_token" value returned from the token endpoint
      defined in OAuth 2.0 [RFC6749] section 5.1.  For refresh tokens,
      this is the "refresh_token" value returned from the token endpoint
      as defined in OAuth 2.0 [RFC6749] section 5.1.  Other token types
      are outside the scope of this specification.

   resource_id  OPTIONAL.  A service-specific string identifying the
      resource that the client doing token is being used for.  This value allows the introspection
      protected resource to convey to the authorization server the
      context in which the token is asking about. being used at the protected
      resource, allowing the authorization server to tailor its response
      accordingly if desired.

   token_type_hint  OPTIONAL.  A hint about the type of the token
      submitted for introspection.  Clients  The protected resource re 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 across all
      of its supported token types.  An authorization server MAY ignore
      this parameter, particularly if it is able to detect the token
      type automatically.  Values for this field are defined in OAuth
      Token Revocation [RFC7009].

   The endpoint MAY allow other parameters to provide further context to
   the query.  For instance, an authorization service may need to know
   the IP address of the Client client accessing the protected resource in
   order to determine the appropriateness of the token being presented.

   The

   To prevent unauthorized token scanning attacks, the endpoint SHOULD
   also require some form of authentication authorization to access this endpoint, such
   as the Client Authentication client authentication as described in OAuth 2.0 [RFC6749] or a
   separate OAuth 2.0 Access Token such access token such as the Bearer bearer token described in
   OAuth 2.0 Bearer Token Usage [RFC6750].  The methods of managing and
   validating these authentication credentials are out of scope of this specification.
   specification, though it is RECOMMENDED that these credentials be
   distinct from those used at an authorization server's token endpoint.

2.2.  Introspection Response

   The server responds with a JSON object [RFC4627] [RFC7159] in "application/
   json" format with the following top-level members.  Specific
   implementations MAY extend this structure with their own service-
   specific pieces of information.

   active  REQUIRED.  Boolean indicator of whether or not the presented
      token is currently active.  The authorization server determines
      whether and when a given token is in an active state.

   exp  OPTIONAL.  Integer timestamp, measured in the number of seconds
      since January 1 1970 UTC, indicating when this token will expire.

   iat  OPTIONAL.  Integer timestamp, measured in the number of seconds
      since January 1 1970 UTC, indicating when this token was
      originally issued.

   scope  OPTIONAL.  A space-separated list of strings representing the
      scopes associated with this token, in the format described in
      Section
      section 3.3 of OAuth 2.0 [RFC6749].

   client_id  OPTIONAL.  Client Identifier identifier for the OAuth Client 2.0 client that
      requested this token.

   sub  OPTIONAL.  Machine-readable identifier local to the AS of the
      Resource Owner resource owner who
      authorized this token.

   user_id  OPTIONAL.  Human-readable identifier for the user who
      authorized this token.

   aud  OPTIONAL.  Service-specific string identifier or list of string
      identifiers representing the intended audience for this token.

   iss  OPTIONAL.  String representing the issuer of this token.

   token_type  OPTIONAL.  Type of the token as defined in section 5.1 of
      OAuth 2.0
      section 5.1. [RFC6749].

   The response MAY be cached according to by the protected resource, and the
   authorization server SHOULD communicate appropriate cache controls
   using applicable HTTP caching headers.

2.3.  Non-normative Example

   For example, a Protected Resource recieves a request from a Client
   carrying an OAuth2 Bearer Token.  In order to know how and whether to
   serve the request, the Protected Resource then makes the following
   request to the Introspection Endpoint of the Authorization Server.
   The Protected Resource is here authenticating with its own Client ID
   and Client Secret as per OAuth2 [RFC6749] Section 2.3.1.

   Following is a non-normative example request:

   POST /introspect HTTP/1.1
   Host: authserver.example.com
   Content-type: application/x-www-form-urlencoded
   Accept: application/json
   Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

   token=X3241Affw.4233-99JXJ
   The Authorization Server validates  Error Response

   If the protected resource uses OAuth 2.0 client credentials and looks
   up the information in the token.  If the token is currently active,
   it returns the following JSON document.

   Following is a non-normative example active token response (with line
   wraps for display purposes only):

   HTTP/1.1 200 OK
   Content-Type: application/json
   Cache-Control: no-store

   {
    "active": true,
    "client_id":"s6BhdRkqt3",
    "scope": "read write dolphin",
    "sub": "2309fj32kl",
    "user_id": "jdoe",
    "aud": "https://example.org/protected-resource/*",
    "iss": "https://authserver.example.com/"
   }

   If the token presented is not currently active (but the
   authentication presented during the request is valid), it returns the
   following JSON document.

   Following is a non-normative example response to an inactive or
   invalid token (with line wraps for display purposes only):

   HTTP/1.1 200 OK
   Content-Type: application/json
   Cache-Control: no-store

   {
    "active": false
   }

   If
   authenticate to the client introspection endpoint and its credentials are invalid or there is another error,
   invalid, the
   Authorization Server authorization server responds with an HTTP 400 (Bad
   Request) as described in OAuth 2.0 section 5.2 of OAuth 2.0 [RFC6749].

   If the protected resource uses an OAuth 2.0 bearer token to authorize
   its call to the introspection endpoint and the token used for
   authorization does not contain sufficient privileges or is otherwise
   invalid for this request, the authorization server responds with an
   HTTP 400 code as described in section 3 of OAuth 2.0 Bearer Token
   Usage [RFC6750].

3.  IANA Considerations

   This document makes no request of IANA.

4.  Security Considerations

   If left unprotected and un-throttled, the Introspection Endpoint introspection endpoint
   could present a means for an attacker to poll a series of possible
   token values, fishing for a valid token.  Therefore,  The specifics of this
   authentication credentials are out of scope of this specification,
   but commonly these credentials could take the
   Authorization Server form of any valid
   client authentication mechanism used with the token endpoint, an
   OAuth 2.0 access token, or other HTTP authorization or authentication
   mechanism.  The authorization server SHOULD issue special client credentials to any
   protected resources or clients that need to access the introspection
   endpoint.  These credentials may endpoint,
   SHOULD require protected resources to be used directly at specifically authorized to
   call the introspection endpoint, or
   they may be exchanged for an OAuth2 Access and SHOULD NOT allow a single piece
   of software acting as both a client and a protected resource to re-
   use the same credentials between the token scoped specifically
   for endpoint and the Introspection Endpoint.
   introspection endpoint.

   Since the introspection endpoint takes in OAuth 2 2.0 tokens as
   parameters, it the server MUST be protected by support TLS 1.2 RFC 5246 [RFC5246] and
   MAY support additional transport-layer mechanisms meeting its
   security requirements.  When using TLS, the client or equivalent. protected
   resource MUST perform a TLS/SSL server certificate check, per RFC
   6125 [RFC6125].  Implementation security considerations can be found
   in Recommendations for Secure Use of TLS and DTLS [TLS.BCP].

   In order to prevent the values of access tokens being introspected from leaking
   into server-side logs via query parameters, a an authorization server
   offering token introspection MAY disallow HTTP GET and instead
   require an HTTP POST method only to the introspection endpoint.

5.  Acknowledgements

   Thanks

   An authorization server offering token introspection MUST be able to
   understand the OAuth Working Group token values being presented to it during this call.
   The exact means by which this happens is an implementation detail and
   outside the UMA Working Group for
   feedback.

6.  Normative References

   [RFC2119]  Bradner, S., "Key words scope of this specification.  For unstructured tokens,
   this could take the form of a simple server-side database query
   against a data store containing the context information for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March the
   token.  For structured tokens, this could take the form of the server
   parsing the token, validating its signature or other protection
   mechanisms, and returning the information contained in the token back
   to the protected resource (allowing the protected resource to be
   unaware of the token's contents, much like the client).

   Note that for a token carrying encrypted information that is needed
   during the introspection process, the authorization server MUST be
   able to decrypt and validate the token in order to access this
   information.  In cases where the authorization server stores no
   information about the token and has no means of accessing information
   about the token, it can not likely offer an introspection service.

5.  Privacy Considerations

   The introspection response may contain privacy-sensitive information
   such as user identifiers for resource owners.  When this is the case,
   measures MUST be taken to prevent disclosure of this information to
   unintended parties.  One way to limit disclosure is to require
   authorization to call the introspection endpoint and to limit calls
   to only registered and trusted protected resource servers.  Another
   method is to transmit user identifiers as opaque service-specific
   strings, potentially returning different identifiers to each
   protected resource.  Omitting privacy-sensitive information from an
   introspection response is the simplest way of minimizing privacy
   issues.

6.  Acknowledgements

   Thanks to the OAuth Working Group and the UMA Working Group for
   feedback.

7.  References

7.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC4627]  Crockford, D.,

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

   [RFC5246]  Dierks, T. and E. Rescorla, "The application/json Media Type for
              JavaScript Object Notation (JSON)", Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 4627, July 2006. 5246, August 2008.

   [RFC6125]  Saint-Andre, P. and J. Hodges, "Representation and
              Verification of Domain-Based Application Service Identity
              within Internet Public Key Infrastructure Using X.509
              (PKIX) Certificates in the Context of Transport Layer
              Security (TLS)", RFC 6125, March 2011.

   [RFC6749]  Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
              6749, October 2012.

   [RFC6750]  Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
              Framework: Bearer Token Usage", RFC 6750, October 2012.

   [RFC7009]  Lodderstedt, T., Dronia, S., and M. Scurtescu, "OAuth 2.0
              Token Revocation", RFC 7009, August 2013.

   [RFC7159]  Bray, T., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, March 2014.

7.2.  Informative References

   [JWT]      Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", draft-ietf-oauth-json-web-token (work in
              progress), July 2014.

   [TLS.BCP]  Sheffer, Y., Holz, R., and P. Saint-Andre,
              "Recommendations for Secure Use of TLS and DTLS", November
              2014.

Appendix A.  Document History

   [[ To be removed by the RFC Editor. ]]

   - 01

   o  Fixed casing and consistent term usage.

   o  Incorporated working group comments.

   o  Clarified that authorization servers need to be able to understand
      the token if they're to introspect it.

   o  Various editorial cleanups.

   - 00

   o  Created initial IETF drafted based on draft-richer-oauth-
      introspection-06 with no normative changes.

Appendix B.  Non-normative Example

   In this non-normative example, a protected resource receives a
   request from a client carrying an OAuth 2.0 bearer token as defined
   in OAuth 2.0 Bearer Token Usage [RFC6750].  In order to know how and
   whether to serve the request given this token, the protected resource
   then makes the following request to the introspection endpoint of the
   authorization server.  The protected resource authenticates with its
   own credentials, here re-using the format of client identifier and
   client secret conveyed as HTTP Basic authentication as per OAuth 2.0
   [RFC6749] Section 2.3.1.

   Following is a non-normative example request:

   POST /introspect HTTP/1.1
   Host: authserver.example.com
   Content-type: application/x-www-form-urlencoded
   Accept: application/json
   Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

   token=X3241Affw.4233-99JXJ

   The authorization server validates the protected resource's
   credentials and looks up the information in the token.  If the token
   is currently active and the authenticated protected resource is
   authorized to know information about this token, the authorization
   server returns the following JSON document.

   Following is a non-normative example active token response (with line
   wraps for display purposes only):

   HTTP/1.1 200 OK
   Content-Type: application/json
   Cache-Control: no-store

   {
    "active": true,
    "client_id":"s6BhdRkqt3",
    "scope": "read write dolphin",
    "sub": "2309fj32kl",
    "user_id": "jdoe",
    "aud": "https://example.org/protected-resource/*",
    "iss": "https://authserver.example.com/"
   }

   If the token presented is not currently active for any reason (for
   instance, it has been revoked by the resource owner) but the
   authorization presented during the request is otherwise valid, the
   authorization server returns the following JSON document.

   Following is a non-normative example response to an inactive or
   invalid token (with line wraps for display purposes only):

   HTTP/1.1 200 OK
   Content-Type: application/json
   Cache-Control: no-store

   {
    "active": false
   }
   Note that in order to avoid disclosing too much of the authorization
   server's state to a third party, the authorization server SHOULD NOT
   include any additional information about an inactive token.

Appendix C.  Use with Proof of Posession Tokens

   With bearer tokens such as those defined by OAuth 2.0 Bearer Token
   Usage [RFC6750], the protected resource will have in its posession
   the entire secret portion of the token for submission to the
   introspection service.  However, for proof-of-posession style tokens,
   the protected resource will have only a token identifier used during
   the request, along with the cryptographic signature on the request.
   The protected resource would be able to submit the token identifier
   to the authoriation server's token endpoint in order to obtain the
   necessary key information needed to validate the signature on the
   request.  The details of this usage are outside the scope of this
   specification and should be defined in an extension to this
   specification.

Author's Address

   Justin Richer (editor)
   The MITRE Corporation

   Email: jricher@mitre.org