< draft-ietf-oauth-v2-bearer-21.txt   draft-ietf-oauth-v2-bearer-22.txt >
OAuth Working Group M. Jones OAuth Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track D. Hardt Intended status: Standards Track D. Hardt
Expires: December 21, 2012 independent Expires: January 13, 2013 independent
D. Recordon D. Recordon
Facebook Facebook
June 19, 2012 July 12, 2012
The OAuth 2.0 Authorization Framework: Bearer Token Usage The OAuth 2.0 Authorization Framework: Bearer Token Usage
draft-ietf-oauth-v2-bearer-21 draft-ietf-oauth-v2-bearer-22
Abstract Abstract
This specification describes how to use bearer tokens in HTTP This specification describes how to use bearer tokens in HTTP
requests to access OAuth 2.0 protected resources. Any party in requests to access OAuth 2.0 protected resources. Any party in
possession of a bearer token (a "bearer") can use it to get access to possession of a bearer token (a "bearer") can use it to get access to
the associated resources (without demonstrating possession of a the associated resources (without demonstrating possession of a
cryptographic key). To prevent misuse, bearer tokens need to be cryptographic key). To prevent misuse, bearer tokens need to be
protected from disclosure in storage and in transport. protected from disclosure in storage and in transport.
skipping to change at page 1, line 38 skipping to change at page 1, line 38
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 December 21, 2012. This Internet-Draft will expire on January 13, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 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 30 skipping to change at page 2, line 30
3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 9 3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 9
4. Example Access Token Response . . . . . . . . . . . . . . . . 10 4. Example Access Token Response . . . . . . . . . . . . . . . . 10
5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
5.1. Security Threats . . . . . . . . . . . . . . . . . . . . . 11 5.1. Security Threats . . . . . . . . . . . . . . . . . . . . . 11
5.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 11 5.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 11
5.3. Summary of Recommendations . . . . . . . . . . . . . . . . 13 5.3. Summary of Recommendations . . . . . . . . . . . . . . . . 13
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
6.1. OAuth Access Token Type Registration . . . . . . . . . . . 14 6.1. OAuth Access Token Type Registration . . . . . . . . . . . 14
6.1.1. The "Bearer" OAuth Access Token Type . . . . . . . . . 14 6.1.1. The "Bearer" OAuth Access Token Type . . . . . . . . . 14
6.2. OAuth Extensions Error Registration . . . . . . . . . . . 14 6.2. OAuth Extensions Error Registration . . . . . . . . . . . 14
6.2.1. The "invalid_request" Error Value . . . . . . . . . . 14 6.2.1. The "invalid_request" Error Value . . . . . . . . . . 15
6.2.2. The "invalid_token" Error Value . . . . . . . . . . . 15 6.2.2. The "invalid_token" Error Value . . . . . . . . . . . 15
6.2.3. The "insufficient_scope" Error Value . . . . . . . . . 15 6.2.3. The "insufficient_scope" Error Value . . . . . . . . . 15
6.3. Authentication Scheme Registration . . . . . . . . . . . . 16
6.3.1. The "Bearer" Authentication Scheme . . . . . . . . . . 16
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.1. Normative References . . . . . . . . . . . . . . . . . . . 16 7.1. Normative References . . . . . . . . . . . . . . . . . . . 16
7.2. Informative References . . . . . . . . . . . . . . . . . . 17 7.2. Informative References . . . . . . . . . . . . . . . . . . 17
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 18 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 17
Appendix B. Document History . . . . . . . . . . . . . . . . . . 18 Appendix B. Document History . . . . . . . . . . . . . . . . . . 18
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 26 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25
1. Introduction 1. Introduction
OAuth enables clients to access protected resources by obtaining an OAuth enables clients to access protected resources by obtaining an
access token, which is defined in OAuth 2.0 Authorization access token, which is defined in OAuth 2.0 Authorization
[I-D.ietf-oauth-v2] as "a string representing an access authorization [I-D.ietf-oauth-v2] as "a string representing an access authorization
issued to the client", rather than using the resource owner's issued to the client", rather than using the resource owner's
credentials directly. credentials directly.
Tokens are issued to clients by an authorization server with the Tokens are issued to clients by an authorization server with the
approval of the resource owner. The client uses the access token to approval of the resource owner. The client uses the access token to
access the protected resources hosted by the resource server. This access the protected resources hosted by the resource server. This
specification describes how to make protected resource requests when specification describes how to make protected resource requests when
the OAuth access token is a bearer token. the OAuth access token is a bearer token.
This specification defines the use of bearer tokens over HTTP/1.1 This specification defines the use of bearer tokens over HTTP/1.1
[I-D.ietf-httpbis-p1-messaging] using TLS [RFC5246] to access [RFC2616] using TLS [RFC5246] to access protected resources. TLS is
protected resources. TLS is mandatory to implement and use with this mandatory to implement and use with this specification; other
specification; other specifications may extend this specification for specifications may extend this specification for use with other
use with other protocols. While designed for use with access tokens protocols. While designed for use with access tokens resulting from
resulting from OAuth 2.0 Authorization [I-D.ietf-oauth-v2] flows to OAuth 2.0 Authorization [I-D.ietf-oauth-v2] flows to access OAuth
access OAuth protected resources, this specification actually defines protected resources, this specification actually defines a general
a general HTTP authorization method that can be used with bearer HTTP authorization method that can be used with bearer tokens from
tokens from any source to access any resources protected by those any source to access any resources protected by those bearer tokens.
bearer tokens. The Bearer authentication scheme is intended The Bearer authentication scheme is intended primarily for server
primarily for server authentication using the WWW-Authenticate and authentication using the WWW-Authenticate and Authorization HTTP
Authorization HTTP headers, but does not preclude its use for proxy headers, but does not preclude its use for proxy authentication.
authentication.
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in Key words for use in document are to be interpreted as described in Key words for use in
RFCs to Indicate Requirement Levels [RFC2119]. RFCs to Indicate Requirement Levels [RFC2119].
This document uses the Augmented Backus-Naur Form (ABNF) notation of This document uses the Augmented Backus-Naur Form (ABNF) notation of
[RFC5234]. Additionally, the following rules are included from [RFC5234]. Additionally, the following rules are included from
HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth]: auth-param, auth-scheme, HTTP/1.1 [RFC2617]: auth-param and auth-scheme; and from Uniform
and b64token; and from Uniform Resource Identifier (URI) [RFC3986]: Resource Identifier (URI) [RFC3986]: URI-Reference.
URI-Reference.
Unless otherwise noted, all the protocol parameter names and values Unless otherwise noted, all the protocol parameter names and values
are case sensitive. are case sensitive.
1.2. Terminology 1.2. Terminology
Bearer Token Bearer Token
A security token with the property that any party in possession of A security token with the property that any party in possession of
the token (a "bearer") can use the token in any way that any other the token (a "bearer") can use the token in any way that any other
party in possession of it can. Using a bearer token does not party in possession of it can. Using a bearer token does not
require a bearer to prove possession of cryptographic key material require a bearer to prove possession of cryptographic key material
skipping to change at page 5, line 5 skipping to change at page 5, line 5
obtain an access token without having to first obtain an obtain an access token without having to first obtain an
authorization grant from a resource owner. authorization grant from a resource owner.
The access token provides an abstraction, replacing different The access token provides an abstraction, replacing different
authorization constructs (e.g., username and password, assertion) for authorization constructs (e.g., username and password, assertion) for
a single token understood by the resource server. This abstraction a single token understood by the resource server. This abstraction
enables issuing access tokens valid for a short time period, as well enables issuing access tokens valid for a short time period, as well
as removing the resource server's need to understand a wide range of as removing the resource server's need to understand a wide range of
authentication schemes. authentication schemes.
+--------+ +---------------+ +--------+ +---------------+
| |--(A)- Authorization Request ->| Resource | | |--(A)- Authorization Request ->| Resource |
| | | Owner | | | | Owner |
| |<-(B)-- Authorization Grant ---| | | |<-(B)-- Authorization Grant ---| |
| | +---------------+ | | +---------------+
| | | |
| | Authorization Grant & +---------------+ | | +---------------+
| |--(C)--- Client Credentials -->| Authorization | | |--(C)-- Authorization Grant -->| Authorization |
| Client | | Server | | Client | | Server |
| |<-(D)----- Access Token -------| | | |<-(D)----- Access Token -------| |
| | +---------------+ | | +---------------+
| | | |
| | +---------------+ | | +---------------+
| |--(E)----- Access Token ------>| Resource | | |--(E)----- Access Token ------>| Resource |
| | | Server | | | | Server |
| |<-(F)--- Protected Resource ---| | | |<-(F)--- Protected Resource ---| |
+--------+ +---------------+ +--------+ +---------------+
Figure 1: Abstract Protocol Flow Figure 1: Abstract Protocol Flow
The abstract flow illustrated in Figure 1 describes the overall OAuth The abstract OAuth 2.0 flow illustrated in Figure 1 describes the
2.0 protocol architecture. The following steps are specified within interaction between the four roles. The following steps are
this document: specified within this document:
E) The client makes a protected resource request to the resource E) The client requests the protected resource from the resource
server by presenting the access token. server and authenticates by presenting the access token.
F) The resource server validates the access token, and if valid, F) The resource server validates the access token, and if valid,
serves the request. serves the request.
This document also imposes semantic requirements upon the access This document also imposes semantic requirements upon the access
token returned in Step D. token returned in Step D.
2. Authenticated Requests 2. Authenticated Requests
This section defines three methods of sending bearer access tokens in This section defines three methods of sending bearer access tokens in
resource requests to resource servers. Clients MUST NOT use more resource requests to resource servers. Clients MUST NOT use more
than one method to transmit the token in each request. than one method to transmit the token in each request.
2.1. Authorization Request Header Field 2.1. Authorization Request Header Field
When sending the access token in the "Authorization" request header When sending the access token in the "Authorization" request header
field defined by HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth], the field defined by HTTP/1.1 [RFC2617], the client uses the "Bearer"
client uses the "Bearer" authentication scheme to transmit the access authentication scheme to transmit the access token.
token.
For example: For example:
GET /resource HTTP/1.1
Host: server.example.com GET /resource HTTP/1.1
Authorization: Bearer mF_9.B5f-4.1JqM Host: server.example.com
Authorization: Bearer mF_9.B5f-4.1JqM
The "Authorization" header field uses the framework defined by The "Authorization" header field uses the framework defined by
HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth] as follows: HTTP/1.1 [RFC2617] as follows:
credentials = "Bearer" 1*SP b64token
The b64token syntax was chosen over the alternative #auth-param b64token = 1*( ALPHA / DIGIT /
syntax also defined by HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth] "-" / "." / "_" / "~" / "+" / "/" ) *"="
both for simplicity and for compatibility with existing credentials = "Bearer" 1*SP b64token
implementations. If additional parameters are needed in the future,
a different scheme would need to be defined.
Clients SHOULD make authenticated requests with a bearer token using Clients SHOULD make authenticated requests with a bearer token using
the "Authorization" request header field with the "Bearer" HTTP the "Authorization" request header field with the "Bearer" HTTP
authorization scheme. Resource servers MUST support this method. authorization scheme. Resource servers MUST support this method.
2.2. Form-Encoded Body Parameter 2.2. Form-Encoded Body Parameter
When sending the access token in the HTTP request entity-body, the When sending the access token in the HTTP request entity-body, the
client adds the access token to the request body using the client adds the access token to the request body using the
"access_token" parameter. The client MUST NOT use this method unless "access_token" parameter. The client MUST NOT use this method unless
skipping to change at page 7, line 7 skipping to change at page 7, line 7
defined semantics. In particular, this means that the "GET" defined semantics. In particular, this means that the "GET"
method MUST NOT be used. method MUST NOT be used.
The entity-body MAY include other request-specific parameters, in The entity-body MAY include other request-specific parameters, in
which case, the "access_token" parameter MUST be properly separated which case, the "access_token" parameter MUST be properly separated
from the request-specific parameters using "&" character(s) (ASCII from the request-specific parameters using "&" character(s) (ASCII
code 38). code 38).
For example, the client makes the following HTTP request using For example, the client makes the following HTTP request using
transport-layer security: transport-layer security:
POST /resource HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
access_token=mF_9.B5f-4.1JqM POST /resource HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
access_token=mF_9.B5f-4.1JqM
The "application/x-www-form-urlencoded" method SHOULD NOT be used The "application/x-www-form-urlencoded" method SHOULD NOT be used
except in application contexts where participating browsers do not except in application contexts where participating browsers do not
have access to the "Authorization" request header field. Resource have access to the "Authorization" request header field. Resource
servers MAY support this method. servers MAY support this method.
2.3. URI Query Parameter 2.3. URI Query Parameter
When sending the access token in the HTTP request URI, the client When sending the access token in the HTTP request URI, the client
adds the access token to the request URI query component as defined adds the access token to the request URI query component as defined
by Uniform Resource Identifier (URI) [RFC3986] using the by Uniform Resource Identifier (URI) [RFC3986] using the
"access_token" parameter. "access_token" parameter.
For example, the client makes the following HTTP request using For example, the client makes the following HTTP request using
transport-layer security: transport-layer security:
GET /resource?access_token=mF_9.B5f-4.1JqM HTTP/1.1
Host: server.example.com GET /resource?access_token=mF_9.B5f-4.1JqM HTTP/1.1
Host: server.example.com
The HTTP request URI query can include other request-specific The HTTP request URI query can include other request-specific
parameters, in which case, the "access_token" parameter MUST be parameters, in which case, the "access_token" parameter MUST be
properly separated from the request-specific parameters using "&" properly separated from the request-specific parameters using "&"
character(s) (ASCII code 38). character(s) (ASCII code 38).
For example: For example:
https://server.example.com/resource?x=y&access_token=mF_9.B5f-4.1JqM&p=q
https://server.example.com/resource?access_token=mF_9.B5f-4.1JqM&p=q
Clients using the URI Query Parameter method SHOULD also send a Clients using the URI Query Parameter method SHOULD also send a
Cache-Control header containing the "no-store" option. Server Cache-Control header containing the "no-store" option. Server
success (2XX status) responses to these requests SHOULD contain a success (2XX status) responses to these requests SHOULD contain a
Cache-Control header with the "private" option. Cache-Control header with the "private" option.
Because of the security weaknesses associated with the URI method Because of the security weaknesses associated with the URI method
(see Section 5), including the high likelihood that the URL (see Section 5), including the high likelihood that the URL
containing the access token will be logged, it SHOULD NOT be used containing the access token will be logged, it SHOULD NOT be used
unless it is impossible to transport the access token in the unless it is impossible to transport the access token in the
skipping to change at page 8, line 14 skipping to change at page 8, line 18
to URI namespace best practices, per the Architecture of the World to URI namespace best practices, per the Architecture of the World
Wide Web [W3C.REC-webarch-20041215]. Wide Web [W3C.REC-webarch-20041215].
3. The WWW-Authenticate Response Header Field 3. The WWW-Authenticate Response Header Field
If the protected resource request does not include authentication If the protected resource request does not include authentication
credentials or does not contain an access token that enables access credentials or does not contain an access token that enables access
to the protected resource, the resource server MUST include the HTTP to the protected resource, the resource server MUST include the HTTP
"WWW-Authenticate" response header field; it MAY include it in "WWW-Authenticate" response header field; it MAY include it in
response to other conditions as well. The "WWW-Authenticate" header response to other conditions as well. The "WWW-Authenticate" header
field uses the framework defined by HTTP/1.1, Part 7 field uses the framework defined by HTTP/1.1 [RFC2617].
[I-D.ietf-httpbis-p7-auth].
All challenges defined by this specification MUST use the auth-scheme All challenges defined by this specification MUST use the auth-scheme
value "Bearer". This scheme MUST be followed by one or more auth- value "Bearer". This scheme MUST be followed by one or more auth-
param values. The auth-param attributes used or defined by this param values. The auth-param attributes used or defined by this
specification are as follows. Other auth-param attributes MAY be specification are as follows. Other auth-param attributes MAY be
used as well. used as well.
A "realm" attribute MAY be included to indicate the scope of A "realm" attribute MAY be included to indicate the scope of
protection in the manner described in HTTP/1.1, Part 7 protection in the manner described in HTTP/1.1 [RFC2617]. The
[I-D.ietf-httpbis-p7-auth]. The "realm" attribute MUST NOT appear "realm" attribute MUST NOT appear more than once.
more than once.
The "scope" attribute is defined in Section 3.3 of OAuth 2.0 The "scope" attribute is defined in Section 3.3 of OAuth 2.0
Authorization [I-D.ietf-oauth-v2]. The "scope" attribute is a space- Authorization [I-D.ietf-oauth-v2]. The "scope" attribute is a space-
delimited list of case sensitive scope values indicating the required delimited list of case sensitive scope values indicating the required
scope of the access token for accessing the requested resource. scope of the access token for accessing the requested resource.
"scope" values are implementation defined; there is no centralized "scope" values are implementation defined; there is no centralized
registry for them; allowed values are defined by the authorization registry for them; allowed values are defined by the authorization
server. The order of "scope" values is not significant. In some server. The order of "scope" values is not significant. In some
cases, the "scope" value will be used when requesting a new access cases, the "scope" value will be used when requesting a new access
token with sufficient scope of access to utilize the protected token with sufficient scope of access to utilize the protected
resource. Use of the "scope" attribute is OPTIONAL. The "scope" resource. Use of the "scope" attribute is OPTIONAL. The "scope"
attribute MUST NOT appear more than once. The "scope" value is attribute MUST NOT appear more than once. The "scope" value is
intended for programmatic use and is not meant to be displayed to end intended for programmatic use and is not meant to be displayed to end
users. users.
Two example scope values follow; these are taken from the OpenID Two example scope values follow; these are taken from the OpenID
Connect [OpenID.Messages] and OATC Online Multimedia Authorization Connect [OpenID.Messages] and OATC Online Multimedia Authorization
Protocol [OMAP] OAuth 2.0 use cases, respectively: Protocol [OMAP] OAuth 2.0 use cases, respectively:
scope="openid profile email"
scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" scope="openid profile email"
scope="urn:example:channel=HBO&urn:example:rating=G,PG-13"
If the protected resource request included an access token and failed If the protected resource request included an access token and failed
authentication, the resource server SHOULD include the "error" authentication, the resource server SHOULD include the "error"
attribute to provide the client with the reason why the access attribute to provide the client with the reason why the access
request was declined. The parameter value is described in request was declined. The parameter value is described in
Section 3.1. In addition, the resource server MAY include the Section 3.1. In addition, the resource server MAY include the
"error_description" attribute to provide developers a human-readable "error_description" attribute to provide developers a human-readable
explanation that is not meant to be displayed to end users. It also explanation that is not meant to be displayed to end users. It also
MAY include the "error_uri" attribute with an absolute URI MAY include the "error_uri" attribute with an absolute URI
identifying a human-readable web page explaining the error. The identifying a human-readable web page explaining the error. The
skipping to change at page 9, line 26 skipping to change at page 9, line 28
and %x20 for delimiters between scope values. Values for the "error" and %x20 for delimiters between scope values. Values for the "error"
and "error_description" attributes MUST NOT include characters and "error_description" attributes MUST NOT include characters
outside the set %x20-21 / %x23-5B / %x5D-7E specified in Sections A.7 outside the set %x20-21 / %x23-5B / %x5D-7E specified in Sections A.7
and A.8 of OAuth 2.0 Authorization. Values for the "error_uri" and A.8 of OAuth 2.0 Authorization. Values for the "error_uri"
attribute MUST conform to the URI-Reference syntax, and thus MUST NOT attribute MUST conform to the URI-Reference syntax, and thus MUST NOT
include characters outside the set %x21 / %x23-5B / %x5D-7E specified include characters outside the set %x21 / %x23-5B / %x5D-7E specified
in Section A.9 of OAuth 2.0 Authorization. in Section A.9 of OAuth 2.0 Authorization.
For example, in response to a protected resource request without For example, in response to a protected resource request without
authentication: authentication:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example" HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example"
And in response to a protected resource request with an And in response to a protected resource request with an
authentication attempt using an expired access token: authentication attempt using an expired access token:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example", HTTP/1.1 401 Unauthorized
error="invalid_token", WWW-Authenticate: Bearer realm="example",
error_description="The access token expired" error="invalid_token",
error_description="The access token expired"
3.1. Error Codes 3.1. Error Codes
When a request fails, the resource server responds using the When a request fails, the resource server responds using the
appropriate HTTP status code (typically, 400, 401, 403, or 405), and appropriate HTTP status code (typically, 400, 401, 403, or 405), and
includes one of the following error codes in the response: includes one of the following error codes in the response:
invalid_request invalid_request
The request is missing a required parameter, includes an The request is missing a required parameter, includes an
unsupported parameter or parameter value, repeats the same unsupported parameter or parameter value, repeats the same
skipping to change at page 10, line 25 skipping to change at page 10, line 25
403 (Forbidden) status code and MAY include the "scope" 403 (Forbidden) status code and MAY include the "scope"
attribute with the scope necessary to access the protected attribute with the scope necessary to access the protected
resource. resource.
If the request lacks any authentication information (e.g., the client If the request lacks any authentication information (e.g., the client
was unaware authentication is necessary or attempted using an was unaware authentication is necessary or attempted using an
unsupported authentication method), the resource server SHOULD NOT unsupported authentication method), the resource server SHOULD NOT
include an error code or other error information. include an error code or other error information.
For example: For example:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example" HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example"
4. Example Access Token Response 4. Example Access Token Response
Typically a bearer token is returned to the client as part of an Typically a bearer token is returned to the client as part of an
OAuth 2.0 [I-D.ietf-oauth-v2] access token response. An example of OAuth 2.0 [I-D.ietf-oauth-v2] access token response. An example of
such a response is: such a response is:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{ HTTP/1.1 200 OK
"access_token":"mF_9.B5f-4.1JqM", Content-Type: application/json;charset=UTF-8
"token_type":"Bearer", Cache-Control: no-store
"expires_in":3600, Pragma: no-cache
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
} {
"access_token":"mF_9.B5f-4.1JqM",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}
5. Security Considerations 5. Security Considerations
This section describes the relevant security threats regarding token This section describes the relevant security threats regarding token
handling when using bearer tokens and describes how to mitigate these handling when using bearer tokens and describes how to mitigate these
threats. threats.
5.1. Security Threats 5.1. Security Threats
The following list presents several common threats against protocols The following list presents several common threats against protocols
skipping to change at page 16, line 8 skipping to change at page 16, line 11
Related protocol extension: Related protocol extension:
Bearer access token type Bearer access token type
Change controller: Change controller:
IETF IETF
Specification document(s): Specification document(s):
[[ this document ]] [[ this document ]]
6.3. Authentication Scheme Registration
This specification registers the following authentication scheme in
the Authentication Scheme Registry defined in HTTP/1.1, Part 7
[I-D.ietf-httpbis-p7-auth].
6.3.1. The "Bearer" Authentication Scheme
Authentication Scheme Name:
Bearer
Pointer to specification text:
[[ this document ]]
Notes (optional):
(none)
7. References 7. References
7.1. Normative References 7.1. Normative References
[I-D.ietf-httpbis-p1-messaging]
Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part
1: URIs, Connections, and Message Parsing",
draft-ietf-httpbis-p1-messaging-19 (work in progress),
March 2012.
[I-D.ietf-httpbis-p7-auth]
Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part
7: Authentication", draft-ietf-httpbis-p7-auth-19 (work in
progress), March 2012.
[I-D.ietf-oauth-v2] [I-D.ietf-oauth-v2]
Hammer, E., Recordon, D., and D. Hardt, "The OAuth 2.0 Hardt, D. and D. Recordon, "The OAuth 2.0 Authorization
Authorization Framework", draft-ietf-oauth-v2-28 (work in Framework", draft-ietf-oauth-v2-29 (work in progress),
progress), June 2012. July 2012.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
RFC 2246, January 1999. RFC 2246, January 1999.
[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.
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
Leach, P., Luotonen, A., and L. Stewart, "HTTP
Authentication: Basic and Digest Access Authentication",
RFC 2617, June 1999.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
skipping to change at page 18, line 6 skipping to change at page 17, line 40
[OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J.,
Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C.,
and B. Boyer, "Online Multimedia Authorization Protocol: and B. Boyer, "Online Multimedia Authorization Protocol:
An Industry Standard for Authorized Access to Internet An Industry Standard for Authorized Access to Internet
Multimedia Resources", April 2012. Multimedia Resources", April 2012.
[OpenID.Messages] [OpenID.Messages]
Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Sakimura, N., Bradley, J., Jones, M., de Medeiros, B.,
Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0",
May 2012. June 2012.
[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.
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
Leach, P., Luotonen, A., and L. Stewart, "HTTP
Authentication: Basic and Digest Access Authentication",
RFC 2617, June 1999.
Appendix A. Acknowledgements Appendix A. Acknowledgements
The following people contributed to preliminary versions of this The following people contributed to preliminary versions of this
document: Blaine Cook (BT), Brian Eaton (Google), Yaron Y. Goland document: Blaine Cook (BT), Brian Eaton (Google), Yaron Y. Goland
(Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter),
Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and
concepts within are a product of the OAuth community, the WRAP concepts within are a product of the OAuth community, the WRAP
community, and the OAuth Working Group. community, and the OAuth Working Group.
The OAuth Working Group has dozens of very active contributors who The OAuth Working Group has dozens of very active contributors who
proposed ideas and wording for this document, including: Michael proposed ideas and wording for this document, including: Michael
Adams, Amanda Anganes, Andrew Arnott, Derek Atkins, Dirk Balfanz, Adams, Amanda Anganes, Andrew Arnott, Derek Atkins, Dirk Balfanz,
John Bradley, Brian Campbell, Francisco Corella, Leah Culver, Bill de John Bradley, Brian Campbell, Francisco Corella, Leah Culver, Bill de
hOra, Breno de Medeiros, Brian Ellin, Igor Faynberg, Stephen Farrell, hOra, Breno de Medeiros, Brian Ellin, Stephen Farrell, Igor Faynberg,
Igor Faynberg, George Fletcher, Tim Freeman, Evan Gilbert, Yaron Y. George Fletcher, Tim Freeman, Evan Gilbert, Yaron Y. Goland, Thomas
Goland, Thomas Hardjono, Justin Hart, Phil Hunt, John Kemp, Eran Hardjono, Justin Hart, Phil Hunt, John Kemp, Eran Hammer, Chasen Le
Hammer, Chasen Le Hara, Dick Hardt, Barry Leiba, Amos Jeffries, Hara, Dick Hardt, Barry Leiba, Amos Jeffries, Michael B. Jones,
Michael B. Jones, Torsten Lodderstedt, Paul Madsen, Eve Maler, James Torsten Lodderstedt, Paul Madsen, Eve Maler, James Manger, Laurence
Manger, Laurence Miao, William J. Mills, Chuck Mortimore, Anthony Miao, William J. Mills, Chuck Mortimore, Anthony Nadalin, Axel
Nadalin, Axel Nennker, Mark Nottingham, David Recordon, Julian Nennker, Mark Nottingham, David Recordon, Julian Reschke, Rob
Reschke, Rob Richards, Justin Richer, Peter Saint-Andre, Nat Richards, Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre,
Sakimura, Rob Sayre, Marius Scurtescu, Naitik Shah, Justin Smith, Marius Scurtescu, Naitik Shah, Justin Smith, Jeremy Suriel, Christian
Jeremy Suriel, Christian Stuebner, Doug Tangren, Paul Tarjan, Hannes Stuebner, Doug Tangren, Paul Tarjan, Hannes Tschofenig, Franklin Tse,
Tschofenig, Franklin Tse, Sean Turner, Paul Walker, Shane Weeden, Sean Turner, Paul Walker, Shane Weeden, Skylar Woodward, and Zachary
Skylar Woodward, and Zachary Zeltsan. Zeltsan.
Appendix B. Document History Appendix B. Document History
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
-22
o Removed uses of HTTPbis in favor of RFC 2616 and RFC 2617, since
HTTPbis is not an approved standard.
o Match formatting of artwork elements with OAuth core
specification.
-21 -21
o Changed "NOT RECOMMENDED" to "not recommended" in caveat about the o Changed "NOT RECOMMENDED" to "not recommended" in caveat about the
URI Query Parameter method. URI Query Parameter method.
o Changed "other specifications may extend this specification for o Changed "other specifications may extend this specification for
use with other transport protocols" to "other specifications may use with other transport protocols" to "other specifications may
extend this specification for use with other protocols". extend this specification for use with other protocols".
o Changed Acknowledgements to use only ASCII characters, per the RFC o Changed Acknowledgements to use only ASCII characters, per the RFC
style guide. style guide.
skipping to change at page 23, line 15 skipping to change at page 22, line 46
o Simplified the introduction to the Authenticated Requests section. o Simplified the introduction to the Authenticated Requests section.
-09 -09
o Incorporated working group last call comments. Specific changes o Incorporated working group last call comments. Specific changes
were: were:
o Use definitions from [I-D.ietf-httpbis-p7-auth] rather than o Use definitions from [I-D.ietf-httpbis-p7-auth] rather than
[RFC2617]. [RFC2617].
o Update credentials definition to conform to o Update credentials definition to conform to [I-D.ietf-httpbis-p7-
[I-D.ietf-httpbis-p7-auth]. auth].
o Further clarified that query parameters may occur in any order. o Further clarified that query parameters may occur in any order.
o Specify that error_description is UTF-8 encoded (matching the core o Specify that error_description is UTF-8 encoded (matching the core
specification). specification).
o Registered "Bearer" Authentication Scheme in Authentication Scheme o Registered "Bearer" Authentication Scheme in Authentication Scheme
Registry defined by [I-D.ietf-httpbis-p7-auth]. Registry defined by [I-D.ietf-httpbis-p7-auth].
o Updated references to oauth-v2, httpbis-p1-messaging, and httpbis- o Updated references to oauth-v2, httpbis-p1-messaging, and httpbis-
 End of changes. 38 change blocks. 
146 lines changed or deleted 126 lines changed or added

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