draft-ietf-oauth-introspection-04.txt   draft-ietf-oauth-introspection-05.txt 
OAuth Working Group J. Richer, Ed. OAuth Working Group J. Richer, Ed.
Internet-Draft The MITRE Corporation Internet-Draft
Intended status: Standards Track December 23, 2014 Intended status: Standards Track February 9, 2015
Expires: June 26, 2015 Expires: August 13, 2015
OAuth 2.0 Token Introspection OAuth 2.0 Token Introspection
draft-ietf-oauth-introspection-04 draft-ietf-oauth-introspection-05
Abstract Abstract
This specification defines a method for a protected resource to query This specification defines a method for a protected resource to query
an OAuth 2.0 authorization server to determine the active state of an an OAuth 2.0 authorization server to determine the active state of an
OAuth 2.0 token and to determine meta-information about this token. OAuth 2.0 token and to determine meta-information about this token.
OAuth 2.0 deployments can use this method to convey information about OAuth 2.0 deployments can use this method to convey information about
the authorization context of the token from the authorization server the authorization context of the token from the authorization server
to the protected resource. to the protected resource.
skipping to change at page 1, line 41 skipping to change at page 1, line 41
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 26, 2015. This Internet-Draft will expire on August 13, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 3 2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 3
2.1. Introspection Request . . . . . . . . . . . . . . . . . . 4 2.1. Introspection Request . . . . . . . . . . . . . . . . . . 4
2.2. Introspection Response . . . . . . . . . . . . . . . . . 5 2.2. Introspection Response . . . . . . . . . . . . . . . . . 5
2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 7
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 10 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 10
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1. Normative References . . . . . . . . . . . . . . . . . . 10 7.1. Normative References . . . . . . . . . . . . . . . . . . 10
7.2. Informative References . . . . . . . . . . . . . . . . . 11 7.2. Informative References . . . . . . . . . . . . . . . . . 11
Appendix A. Document History . . . . . . . . . . . . . . . . . . 11 Appendix A. Document History . . . . . . . . . . . . . . . . . . 11
Appendix B. Use with Proof of Posession Tokens . . . . . . . . . 12 Appendix B. Use with Proof of Posession Tokens . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13
skipping to change at page 4, line 25 skipping to change at page 4, line 25
authorization server in its response. authorization server in its response.
token REQUIRED. The string value of the token. For access tokens, token REQUIRED. The string value of the token. For access tokens,
this is the "access_token" value returned from the token endpoint this is the "access_token" value returned from the token endpoint
defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens, defined in OAuth 2.0 [RFC6749] section 5.1. For refresh tokens,
this is the "refresh_token" value returned from the token endpoint this is the "refresh_token" value returned from the token endpoint
as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types as defined in OAuth 2.0 [RFC6749] section 5.1. Other token types
are outside the scope of this specification. are outside the scope of this specification.
token_type_hint OPTIONAL. A hint about the type of the token token_type_hint OPTIONAL. A hint about the type of the token
submitted for introspection. The protected resource re MAY pass submitted for introspection. The protected resource MAY pass this
this parameter in order to help the authorization server to parameter in order to help the authorization server to optimize
optimize the token lookup. If the server is unable to locate the the token lookup. If the server is unable to locate the token
token using the given hint, it MUST extend its search across all using the given hint, it MUST extend its search across all of its
of its supported token types. An authorization server MAY ignore supported token types. An authorization server MAY ignore this
this parameter, particularly if it is able to detect the token parameter, particularly if it is able to detect the token type
type automatically. Values for this field are defined in OAuth automatically. Values for this field are defined in OAuth Token
Token Revocation [RFC7009]. Revocation [RFC7009].
The endpoint MAY allow other parameters to provide further context to The endpoint MAY allow other parameters to provide further context to
the query. For instance, an authorization service may need to know the query. For instance, an authorization service may need to know
the IP address of the client accessing the protected resource in the IP address of the client accessing the protected resource in
order to determine the appropriateness of the token being presented. order to determine the appropriateness of the token being presented.
To prevent unauthorized token scanning attacks, the endpoint MUST To prevent unauthorized token scanning attacks, the endpoint MUST
also require some form of authorization to access this endpoint, such also require some form of authorization to access this endpoint, such
as client authentication as described in OAuth 2.0 [RFC6749] or a as client authentication as described in OAuth 2.0 [RFC6749] or a
separate OAuth 2.0 access token such as the bearer token described in separate OAuth 2.0 access token such as the bearer token described in
OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and
validating these authentication credentials are out of scope of this validating these authentication credentials are out of scope of this
specification. specification.
For example, the following example shows a protected resource calling For example, the following example shows a protected resource calling
the token introspection endpoint to query about an OAuth 2.0 bearer. the token introspection endpoint to query about an OAuth 2.0 bearer.
The protected resource is using a separate OAuth 2.0 bearer token to The protected resource is using a separate OAuth 2.0 bearer token to
authorize this call. authorize this call.
Following is a non-normative example request (with line wraps for Following is a non-normative example request:
display purposes only):
POST /introspect HTTP/1.1 POST /introspect HTTP/1.1
Host: server.example.com Host: server.example.com
Accept: application/json Accept: application/json
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 23410913-abewfq.123483 Authorization: Bearer 23410913-abewfq.123483
token=2YotnFZFEjr1zCsicMWpAA token=2YotnFZFEjr1zCsicMWpAA
In this example, the protected resource uses a client identifier and In this example, the protected resource uses a client identifier and
client secret to authenticate itself to the introspection endpoint as client secret to authenticate itself to the introspection endpoint as
well as send a token type hint. well as send a token type hint.
Following is a non-normative example request (with line wraps for Following is a non-normative example request:
display purposes only):
POST /introspect HTTP/1.1 POST /introspect HTTP/1.1
Host: server.example.com Host: server.example.com
Accept: application/json Accept: application/json
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
token=mF_9.B5f-4.1JqM&token_type_hint=access_token token=mF_9.B5f-4.1JqM&token_type_hint=access_token
2.2. Introspection Response 2.2. Introspection Response
skipping to change at page 11, line 41 skipping to change at page 11, line 38
progress), July 2014. progress), July 2014.
[TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre, [TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of TLS and DTLS", November "Recommendations for Secure Use of TLS and DTLS", November
2014. 2014.
Appendix A. Document History Appendix A. Document History
[[ To be removed by the RFC Editor. ]] [[ To be removed by the RFC Editor. ]]
-05
o Typo fix.
o Updated author information.
o Removed extraneous "linewrap" note from examples.
- 04 - 04
o Removed "resource_id" from request. o Removed "resource_id" from request.
o Added examples. o Added examples.
- 03 - 03
o Updated HTML and HTTP references. o Updated HTML and HTTP references.
o Call for registration of parameters in the JWT registry. o Call for registration of parameters in the JWT registry.
- 02 - 02
o Removed SAML pointer. o Removed SAML pointer.
o Clarified what an "active" token could be. o Clarified what an "active" token could be.
skipping to change at page 13, line 8 skipping to change at page 13, line 8
request. The protected resource would be able to submit the token request. The protected resource would be able to submit the token
identifier to the authorization server's token endpoint in order to identifier to the authorization server's token endpoint in order to
obtain the necessary key information needed to validate the signature obtain the necessary key information needed to validate the signature
on the request. The details of this usage are outside the scope of on the request. The details of this usage are outside the scope of
this specification and should be defined in an extension to this this specification and should be defined in an extension to this
specification. specification.
Author's Address Author's Address
Justin Richer (editor) Justin Richer (editor)
The MITRE Corporation
Email: jricher@mitre.org Email: ietf@justin.richer.org
 End of changes. 12 change blocks. 
21 lines changed or deleted 25 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/