draft-ietf-oauth-introspection-03.txt   draft-ietf-oauth-introspection-04.txt 
OAuth Working Group J. Richer, Ed. OAuth Working Group J. Richer, Ed.
Internet-Draft The MITRE Corporation Internet-Draft The MITRE Corporation
Intended status: Standards Track December 6, 2014 Intended status: Standards Track December 23, 2014
Expires: June 9, 2015 Expires: June 26, 2015
OAuth 2.0 Token Introspection OAuth 2.0 Token Introspection
draft-ietf-oauth-introspection-03 draft-ietf-oauth-introspection-04
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 9, 2015. This Internet-Draft will expire on June 26, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 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
skipping to change at page 2, line 19 skipping to change at page 2, line 19
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 . . . . . . . . . . . . . . . . . . . . . 6 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 8 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 10
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1. Normative References . . . . . . . . . . . . . . . . . . 8 7.1. Normative References . . . . . . . . . . . . . . . . . . 10
7.2. Informative References . . . . . . . . . . . . . . . . . 9 7.2. Informative References . . . . . . . . . . . . . . . . . 11
Appendix A. Document History . . . . . . . . . . . . . . . . . . 9 Appendix A. Document History . . . . . . . . . . . . . . . . . . 11
Appendix B. Non-normative Examples . . . . . . . . . . . . . . . 10 Appendix B. Use with Proof of Posession Tokens . . . . . . . . . 12
Appendix C. Use with Proof of Posession Tokens . . . . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12
1. Introduction 1. Introduction
In OAuth 2.0, the contents of tokens are opaque to clients. This In OAuth 2.0, the contents of tokens are opaque to clients. This
means that the client does not need to know anything about the means that the client does not need to know anything about the
content or structure of the token itself, if there is any. However, 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 there is still a large amount of metadata that may be attached to a
token, such as its current validity, approved scopes, and information token, such as its current validity, approved scopes, and information
about the context in which the token was issued. These pieces of about the context in which the token was issued. These pieces of
information are often vital to protected resources making information are often vital to protected resources making
skipping to change at page 4, line 24 skipping to change at page 4, line 24
additional context that is known by the protected resource to aid the additional context that is known by the protected resource to aid the
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.
resource_id OPTIONAL. A service-specific string identifying the
resource that the token is being used for. This value allows the
protected resource to convey to the authorization server the
context in which the token is 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 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 re MAY pass
this parameter in order to help the authorization server to this parameter in order to help the authorization server to
optimize the token lookup. If the server is unable to locate the optimize the token lookup. If the server is unable to locate the
token using the given hint, it MUST extend its search across all token using the given hint, it MUST extend its search across all
of its supported token types. An authorization server MAY ignore of its supported token types. An authorization server MAY ignore
this parameter, particularly if it is able to detect the token this parameter, particularly if it is able to detect the token
type automatically. Values for this field are defined in OAuth type automatically. Values for this field are defined in OAuth
Token Revocation [RFC7009]. Token Revocation [RFC7009].
skipping to change at page 5, line 5 skipping to change at page 4, line 47
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
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
authorize this call.
Following is a non-normative example request (with line wraps for
display purposes only):
POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 23410913-abewfq.123483
token=2YotnFZFEjr1zCsicMWpAA
In this example, the protected resource uses a client identifier and
client secret to authenticate itself to the introspection endpoint as
well as send a token type hint.
Following is a non-normative example request (with line wraps for
display purposes only):
POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
token=mF_9.B5f-4.1JqM&token_type_hint=access_token
2.2. Introspection Response 2.2. Introspection Response
The server responds with a JSON object [RFC7159] in "application/ The server responds with a JSON object [RFC7159] in "application/
json" format with the following top-level members. Several of these json" format with the following top-level members.
active REQUIRED. Boolean indicator of whether or not the presented active
token is currently active. The authorization server determines REQUIRED. Boolean indicator of whether or not the presented token
whether and when a given token is in an active state. is currently active. The authorization server determines whether
and when a given token is in an active state.
scope OPTIONAL. A space-separated list of strings representing the scope
OPTIONAL. A space-separated list of strings representing the
scopes associated with this token, in the format described in scopes associated with this token, in the format described in
section 3.3 of OAuth 2.0 [RFC6749]. section 3.3 of OAuth 2.0 [RFC6749].
client_id OPTIONAL. Client identifier for the OAuth 2.0 client that client_id
OPTIONAL. Client identifier for the OAuth 2.0 client that
requested this token. requested this token.
user_id OPTIONAL. Human-readable identifier for the user who user_id
authorized this token. OPTIONAL. Human-readable identifier for the user who authorized
this token.
token_type OPTIONAL. Type of the token as defined in section 5.1 of token_type
OAuth 2.0 [RFC6749]. OPTIONAL. Type of the token as defined in section 5.1 of OAuth
2.0 [RFC6749].
The response MAY include any claims defined as JWT [JWT] claim names The response MAY include any claims defined as JWT [JWT] claim names
and carry the same semantics and syntax, such as the following: and carry the same semantics and syntax, such as the following:
exp OPTIONAL. Integer timestamp, measured in the number of seconds exp
OPTIONAL. Integer timestamp, measured in the number of seconds
since January 1 1970 UTC, indicating when this token will expire. since January 1 1970 UTC, indicating when this token will expire.
iat OPTIONAL. Integer timestamp, measured in the number of seconds iat
OPTIONAL. Integer timestamp, measured in the number of seconds
since January 1 1970 UTC, indicating when this token was since January 1 1970 UTC, indicating when this token was
originally issued. originally issued.
nbf OPTIONAL. Integer timestamp, measured in the number of seconds nbf
OPTIONAL. Integer timestamp, measured in the number of seconds
since January 1 1970 UTC, indicating when this token is not to be since January 1 1970 UTC, indicating when this token is not to be
used before. used before.
sub OPTIONAL. Subject of the token. Usually a machine-readable sub
OPTIONAL. Subject of the token. Usually a machine-readable
identifier of the resource owner who authorized this token identifier of the resource owner who authorized this token
aud OPTIONAL. Service-specific string identifier or list of string aud
OPTIONAL. Service-specific string identifier or list of string
identifiers representing the intended audience for this token. identifiers representing the intended audience for this token.
iss OPTIONAL. String representing the issuer of this token. iss
OPTIONAL. String representing the issuer of this token.
jti OPTIONAL. String identifier for the token. jti
OPTIONAL. String identifier for the token.
Specific implementations MAY extend this structure with their own Specific implementations MAY extend this structure with their own
service-specific pieces of information. service-specific pieces of information as top-level members of this
JSON object.
The authorization server MAY respond differently to different
protected resources making the same request. For instance, an
authorization server MAY limit which scopes from a given token for
each protected resources in order to prevent protected resources from
learning more about the larger network than is necessary for their
function.
The response MAY be cached by the protected resource. The response MAY be cached by the protected resource.
The authorization server MAY respond differently to different For example, the following response contains a set of information
protected resources making the same request. about an active token:
Note that in order to avoid disclosing too much of the authorization Following is a non-normative example response:
server's state to a third party, the authorization server SHOULD NOT
include any additional information about an inactive token, including HTTP/1.1 200 OK
why the token is inactive. Content-Type: application/json
{
"active": true,
"client_id": "l238j323ds-23ij4",
"user_id": "jdoe",
"scope": "read write dolphin",
"sub": "Z5O3upPC88QrAjx00dis",
"aud": "https://protected.example.net/resource",
"iss": "https://server.example.com/",
"exp": 1419356238,
"iat": 1419350238,
"extension_field": "twenty-seven"
}
If the introspection call is properly authorized but the token is not
active, does not exist on this server, or the protected resource is
not allowed to introspect this particular token, the authorization
server MUST return an introspection response with the active field
set to 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, including why the token is inactive. For example,
the response for a token that has been revoked or is otherwise
invalid would look like the following:
Following is a non-normative example response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": false
}
2.3. Error Response 2.3. Error Response
If the protected resource uses OAuth 2.0 client credentials to If the protected resource uses OAuth 2.0 client credentials to
authenticate to the introspection endpoint and its credentials are authenticate to the introspection endpoint and its credentials are
invalid, the authorization server responds with an HTTP 401 invalid, the authorization server responds with an HTTP 401
(Unauthorized) as described in section 5.2 of OAuth 2.0 [RFC6749]. (Unauthorized) as described in section 5.2 of OAuth 2.0 [RFC6749].
If the protected resource uses an OAuth 2.0 bearer token to authorize If the protected resource uses an OAuth 2.0 bearer token to authorize
its call to the introspection endpoint and the token used for its call to the introspection endpoint and the token used for
authorization does not contain sufficient privileges or is otherwise authorization does not contain sufficient privileges or is otherwise
invalid for this request, the authorization server responds with an invalid for this request, the authorization server responds with an
HTTP 401 code as described in section 3 of OAuth 2.0 Bearer Token HTTP 401 code as described in section 3 of OAuth 2.0 Bearer Token
Usage [RFC6750]. Usage [RFC6750].
Note that a properly formed and authorized query for an inactive or
otherwise invalid token (or a token the protected resource is not
allowed to know about) is not considered an error response by this
specification. In these cases, the authorization server MUST instead
respond with an introspection response with the "active" field set to
"false" as described in Section 2.2.
3. IANA Considerations 3. IANA Considerations
This specification requests IANA to register the following values This specification requests IANA to register the following values
into the IANA JSON Web Token Claims registry for JWT Claim Names. into the IANA JSON Web Token Claims registry for JWT Claim Names.
o Claim Name: "active" o Claim Name: "active"
o Claim Description: Token active status o Claim Description: Token active status
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2.2 of [[ this document ]]. o Specification Document(s): Section 2.2 of [[ this document ]].
skipping to change at page 9, line 47 skipping to change at page 11, line 41
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. ]]
- 04
o Removed "resource_id" from request.
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.
skipping to change at page 10, line 34 skipping to change at page 12, line 34
o Clarified that authorization servers need to be able to understand o Clarified that authorization servers need to be able to understand
the token if they're to introspect it. the token if they're to introspect it.
o Various editorial cleanups. o Various editorial cleanups.
- 00 - 00
o Created initial IETF drafted based on draft-richer-oauth- o Created initial IETF drafted based on draft-richer-oauth-
introspection-06 with no normative changes. introspection-06 with no normative changes.
Appendix B. Non-normative Examples Appendix B. Use with Proof of Posession Tokens
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
In this non-normative example, the protected resource also sends a
resource identifier and token type hint to the authorization server
to aid the authorization server's response:
Following is a non-normative example request (with line wraps for
display purposes only):
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
&resource_id=rsid-2348e.2381k3
&token_type_hint=access_token
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
{
"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, it has expired,
or the protected resource is not allowed to ask about this particular
token) 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
{
"active": false
}
Appendix C. Use with Proof of Posession Tokens
With bearer tokens such as those defined by OAuth 2.0 Bearer Token With bearer tokens such as those defined by OAuth 2.0 Bearer Token
Usage [RFC6750], the protected resource will have in its possession Usage [RFC6750], the protected resource will have in its possession
the entire secret portion of the token for submission to the the entire secret portion of the token for submission to the
introspection service. However, for proof-of-possession style introspection service. However, for proof-of-possession style
tokens, the protected resource will have only a token identifier used tokens, the protected resource will have only a token identifier used
during the request, along with the cryptographic signature on the during the request, along with the cryptographic signature on the
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
 End of changes. 25 change blocks. 
125 lines changed or deleted 137 lines changed or added

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