diff options
Diffstat (limited to 'doc/specs/draft-ietf-oauth-v2-bearer.htm')
| -rw-r--r-- | doc/specs/draft-ietf-oauth-v2-bearer.htm | 1748 |
1 files changed, 1748 insertions, 0 deletions
diff --git a/doc/specs/draft-ietf-oauth-v2-bearer.htm b/doc/specs/draft-ietf-oauth-v2-bearer.htm new file mode 100644 index 0000000..27c78be --- /dev/null +++ b/doc/specs/draft-ietf-oauth-v2-bearer.htm @@ -0,0 +1,1748 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html lang="en"><head><title>The OAuth 2.0 Authorization Protocol: Bearer Tokens</title> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<meta name="description" content="The OAuth 2.0 Authorization Protocol: Bearer Tokens"> +<meta name="generator" content="xml2rfc v1.36 (http://xml.resource.org/)"> +<style type='text/css'><!-- + body { + font-family: verdana, charcoal, helvetica, arial, sans-serif; + font-size: small; color: #000; background-color: #FFF; + margin: 2em; + } + h1, h2, h3, h4, h5, h6 { + font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif; + font-weight: bold; font-style: normal; + } + h1 { color: #900; background-color: transparent; text-align: right; } + h3 { color: #333; background-color: transparent; } + + td.RFCbug { + font-size: x-small; text-decoration: none; + width: 30px; height: 30px; padding-top: 2px; + text-align: justify; vertical-align: middle; + background-color: #000; + } + td.RFCbug span.RFC { + font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif; + font-weight: bold; color: #666; + } + td.RFCbug span.hotText { + font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif; + font-weight: normal; text-align: center; color: #FFF; + } + + table.TOCbug { width: 30px; height: 15px; } + td.TOCbug { + text-align: center; width: 30px; height: 15px; + color: #FFF; background-color: #900; + } + td.TOCbug a { + font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif; + font-weight: bold; font-size: x-small; text-decoration: none; + color: #FFF; background-color: transparent; + } + + td.header { + font-family: arial, helvetica, sans-serif; font-size: x-small; + vertical-align: top; width: 33%; + color: #FFF; background-color: #666; + } + td.author { font-weight: bold; font-size: x-small; margin-left: 4em; } + td.author-text { font-size: x-small; } + + /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */ + a.info { + /* This is the key. */ + position: relative; + z-index: 24; + text-decoration: none; + } + a.info:hover { + z-index: 25; + color: #FFF; background-color: #900; + } + a.info span { display: none; } + a.info:hover span.info { + /* The span will display just on :hover state. */ + display: block; + position: absolute; + font-size: smaller; + top: 2em; left: -5em; width: 15em; + padding: 2px; border: 1px solid #333; + color: #900; background-color: #EEE; + text-align: left; + } + + a { font-weight: bold; } + a:link { color: #900; background-color: transparent; } + a:visited { color: #633; background-color: transparent; } + a:active { color: #633; background-color: transparent; } + + p { margin-left: 2em; margin-right: 2em; } + p.copyright { font-size: x-small; } + p.toc { font-size: small; font-weight: bold; margin-left: 3em; } + table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; } + td.toc { font-size: small; font-weight: bold; vertical-align: text-top; } + + ol.text { margin-left: 2em; margin-right: 2em; } + ul.text { margin-left: 2em; margin-right: 2em; } + li { margin-left: 3em; } + + /* RFC-2629 <spanx>s and <artwork>s. */ + em { font-style: italic; } + strong { font-weight: bold; } + dfn { font-weight: bold; font-style: normal; } + cite { font-weight: normal; font-style: normal; } + tt { color: #036; } + tt, pre, pre dfn, pre em, pre cite, pre span { + font-family: "Courier New", Courier, monospace; font-size: small; + } + pre { + text-align: left; padding: 4px; + color: #000; background-color: #CCC; + } + pre dfn { color: #900; } + pre em { color: #66F; background-color: #FFC; font-weight: normal; } + pre .key { color: #33C; font-weight: bold; } + pre .id { color: #900; } + pre .str { color: #000; background-color: #CFF; } + pre .val { color: #066; } + pre .rep { color: #909; } + pre .oth { color: #000; background-color: #FCF; } + pre .err { background-color: #FCC; } + + /* RFC-2629 <texttable>s. */ + table.all, table.full, table.headers, table.none { + font-size: small; text-align: center; border-width: 2px; + vertical-align: top; border-collapse: collapse; + } + table.all, table.full { border-style: solid; border-color: black; } + table.headers, table.none { border-style: none; } + th { + font-weight: bold; border-color: black; + border-width: 2px 2px 3px 2px; + } + table.all th, table.full th { border-style: solid; } + table.headers th { border-style: none none solid none; } + table.none th { border-style: none; } + table.all td { + border-style: solid; border-color: #333; + border-width: 1px 2px; + } + table.full td, table.headers td, table.none td { border-style: none; } + + hr { height: 1px; } + hr.insert { + width: 80%; border-style: none; border-width: 0; + color: #CCC; background-color: #CCC; + } +--></style> +</head> +<body> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1"> +<tr><td class="header">OAuth Working Group</td><td class="header">M. Jones</td></tr> +<tr><td class="header">Internet-Draft</td><td class="header">Microsoft</td></tr> +<tr><td class="header">Intended status: Standards Track</td><td class="header">D. Hardt</td></tr> +<tr><td class="header">Expires: August 2, 2012</td><td class="header">independent</td></tr> +<tr><td class="header"> </td><td class="header">D. Recordon</td></tr> +<tr><td class="header"> </td><td class="header">Facebook</td></tr> +<tr><td class="header"> </td><td class="header">January 30, 2012</td></tr> +</table></td></tr></table> +<h1><br />The OAuth 2.0 Authorization Protocol: Bearer Tokens<br />draft-ietf-oauth-v2-bearer-16</h1> + +<h3>Abstract</h3> + +<p> + This specification describes how to use bearer tokens in HTTP + 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 the associated resources (without demonstrating possession + of a cryptographic key). To prevent misuse, bearer tokens + need to be protected from disclosure in storage and in transport. + +</p> +<h3>Status of this Memo</h3> +<p> +This Internet-Draft is submitted in full +conformance with the provisions of BCP 78 and BCP 79.</p> +<p> +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/.</p> +<p> +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.”</p> +<p> +This Internet-Draft will expire on August 2, 2012.</p> + +<h3>Copyright Notice</h3> +<p> +Copyright (c) 2012 IETF Trust and the persons identified as the +document authors. All rights reserved.</p> +<p> +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.</p> +<a name="toc"></a><br /><hr /> +<h3>Table of Contents</h3> +<p class="toc"> +<a href="#anchor1">1.</a> +Introduction<br /> + <a href="#anchor2">1.1.</a> +Notational Conventions<br /> + <a href="#anchor3">1.2.</a> +Terminology<br /> + <a href="#anchor4">1.3.</a> +Overview<br /> +<a href="#anchor5">2.</a> +Authenticated Requests<br /> + <a href="#authz-header">2.1.</a> +Authorization Request Header Field<br /> + <a href="#body-param">2.2.</a> +Form-Encoded Body Parameter<br /> + <a href="#query-param">2.3.</a> +URI Query Parameter<br /> +<a href="#authn-header">3.</a> +The WWW-Authenticate Response Header Field<br /> + <a href="#resource-error-codes">3.1.</a> +Error Codes<br /> +<a href="#sec-con">4.</a> +Security Considerations<br /> + <a href="#threats">4.1.</a> +Security Threats<br /> + <a href="#mitigation">4.2.</a> +Threat Mitigation<br /> + <a href="#anchor6">4.3.</a> +Summary of Recommendations<br /> +<a href="#anchor7">5.</a> +IANA Considerations<br /> + <a href="#anchor8">5.1.</a> +OAuth Access Token Type Registration<br /> + <a href="#anchor9">5.1.1.</a> +The "Bearer" OAuth Access Token Type<br /> + <a href="#anchor10">5.2.</a> +Authentication Scheme Registration<br /> + <a href="#anchor11">5.2.1.</a> +The "Bearer" Authentication Scheme<br /> +<a href="#rfc.references1">6.</a> +References<br /> + <a href="#rfc.references1">6.1.</a> +Normative References<br /> + <a href="#rfc.references2">6.2.</a> +Informative References<br /> +<a href="#anchor14">Appendix A.</a> +Acknowledgements<br /> +<a href="#anchor15">Appendix B.</a> +Document History<br /> +<a href="#rfc.authors">§</a> +Authors' Addresses<br /> +</p> +<br clear="all" /> + +<a name="anchor1"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.1"></a><h3>1. +Introduction</h3> + +<p> + OAuth enables clients to access protected resources by + obtaining an access token, which is defined in + OAuth 2.0 Authorization <a class='info' href='#I-D.ietf-oauth-v2'>[I‑D.ietf‑oauth‑v2]<span> (</span><span class='info'>Hammer, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” January 2012.</span><span>)</span></a> + as "a string representing an access + authorization issued to the client", rather than using the + resource owner's credentials directly. + +</p> +<p> + Tokens are issued to clients by an authorization server with the approval of + the resource owner. The client uses the access token to access the protected resources + hosted by the resource server. This specification describes how to make protected resource + requests when the OAuth access token is a bearer token. + +</p> +<p> + This specification defines the use of bearer tokens over + HTTP/1.1 <a class='info' href='#I-D.ietf-httpbis-p1-messaging'>[I‑D.ietf‑httpbis‑p1‑messaging]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 1: URIs, Connections, and Message Parsing,” January 2012.</span><span>)</span></a> + using + TLS <a class='info' href='#RFC5246'>[RFC5246]<span> (</span><span class='info'>Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.</span><span>)</span></a> to access protected resources. + TLS is mandatory to implement + and use with this specification; other specifications may + extend this specification for use with other transport + protocols. + While designed for use with access tokens resulting from + OAuth 2.0 Authorization <a class='info' href='#I-D.ietf-oauth-v2'>[I‑D.ietf‑oauth‑v2]<span> (</span><span class='info'>Hammer, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” January 2012.</span><span>)</span></a> + flows to access OAuth protected resources, this + specification actually defines a general HTTP authorization + method that can be used with bearer tokens from any source + to access any resources protected by those bearer tokens. + +</p> +<a name="anchor2"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.1.1"></a><h3>1.1. +Notational Conventions</h3> + +<p> + 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 + Key words for use in RFCs to Indicate Requirement Levels <a class='info' href='#RFC2119'>[RFC2119]<span> (</span><span class='info'>Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.</span><span>)</span></a>. + +</p> +<p> + This document uses the Augmented Backus-Naur Form (ABNF) + notation of + HTTP/1.1, Part 1 <a class='info' href='#I-D.ietf-httpbis-p1-messaging'>[I‑D.ietf‑httpbis‑p1‑messaging]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 1: URIs, Connections, and Message Parsing,” January 2012.</span><span>)</span></a>, + which is based upon the + Augmented Backus-Naur Form (ABNF) <a class='info' href='#RFC5234'>[RFC5234]<span> (</span><span class='info'>Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.</span><span>)</span></a> + notation. Additionally, the following rules are included from + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>: + auth-param, auth-scheme, and b64token; and from + Uniform Resource Identifier (URI) <a class='info' href='#RFC3986'>[RFC3986]<span> (</span><span class='info'>Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</span><span>)</span></a>: + URI-Reference. + +</p> +<p> + Unless otherwise noted, all the protocol parameter names and values are case sensitive. + +</p> +<a name="anchor3"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.1.2"></a><h3>1.2. +Terminology</h3> + +<p> + </p> +<blockquote class="text"><dl> +<dt>Bearer Token</dt> +<dd> + + 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 party in possession of it can. + Using a bearer token does not require a bearer to prove + possession of cryptographic key material + (proof-of-possession). + +</dd> +</dl></blockquote><p> + +</p> +<p> + All other terms are as defined in + OAuth 2.0 Authorization <a class='info' href='#I-D.ietf-oauth-v2'>[I‑D.ietf‑oauth‑v2]<span> (</span><span class='info'>Hammer, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” January 2012.</span><span>)</span></a>. + +</p> +<a name="anchor4"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.1.3"></a><h3>1.3. +Overview</h3> + +<p> + OAuth provides a method for clients to access a protected resource on behalf of a + resource owner. In the general case, + before a client can access a protected resource, it must first obtain + an authorization grant from the resource owner and then exchange the authorization grant for + an access token. + The access token represents the grant's scope, duration, and + other attributes granted by the authorization grant. The + client accesses the protected resource by presenting the + access token to the resource server. + In some cases, a client can directly present its own + credentials to an authorization server to obtain an access + token without having to first obtain an authorization grant from a + resource owner. + +</p> +<p> + The access token provides an abstraction, replacing different authorization + constructs (e.g. username and password, assertion) for a single token understood by the + resource server. This abstraction 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 + authentication schemes. + +</p><br /><hr class="insert" /> +<a name="Figure-1"></a> +<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> ++--------+ +---------------+ +| |--(A)- Authorization Request ->| Resource | +| | | Owner | +| |<-(B)-- Authorization Grant ---| | +| | +---------------+ +| | +| | Authorization Grant & +---------------+ +| |--(C)--- Client Credentials -->| Authorization | +| Client | | Server | +| |<-(D)----- Access Token -------| | +| | +---------------+ +| | +| | +---------------+ +| |--(E)----- Access Token ------>| Resource | +| | | Server | +| |<-(F)--- Protected Resource ---| | ++--------+ +---------------+ +</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 1: Abstract Protocol Flow </b></font><br /></td></tr></table><hr class="insert" /> + +<p> + The abstract flow illustrated in <a class='info' href='#Figure-1'>Figure 1<span> (</span><span class='info'>Abstract Protocol Flow</span><span>)</span></a> describes the overall + OAuth 2.0 protocol architecture. The following steps are specified within this + document: + + </p> +<blockquote class="text"> +<p> + E) The client makes a protected resource request to the resource server by presenting + the access token. + +</p> +<p> + F) The resource server validates the access token, and if valid, serves the request. + +</p> +</blockquote><p> + +</p> +<a name="anchor5"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2"></a><h3>2. +Authenticated Requests</h3> + +<p> + This section defines three + methods of sending bearer access tokens in resource requests + to resource servers. Clients MUST NOT use more than one + method to transmit the token in each request. + +</p> +<a name="authz-header"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2.1"></a><h3>2.1. +Authorization Request Header Field</h3> + +<p> + When sending the access token in the <tt>Authorization</tt> request header field + defined by + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>, + the + client uses the <tt>Bearer</tt> + authentication scheme to transmit the access token. + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +GET /resource HTTP/1.1 +Host: server.example.com +Authorization: Bearer vF9dft4qmT +</pre></div> +<p> + The <tt>Authorization</tt> header field uses the framework defined by + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a> + as follows: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +credentials = "Bearer" 1*SP b64token +</pre></div> +<p> + The b64token syntax was chosen over the alternative + #auth-param syntax also defined by + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a> + both for simplicity + and for compatibility with existing implementations. + If additional parameters are needed in the future, a + different scheme would need to be defined. + +</p> +<p> + Clients SHOULD make authenticated requests with a bearer + token using the <tt>Authorization</tt> + request header field with the <tt>Bearer</tt> HTTP authorization scheme. + Resource servers MUST support this method. + +</p> +<a name="body-param"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2.2"></a><h3>2.2. +Form-Encoded Body Parameter</h3> + +<p> + When sending the access token in the HTTP request + entity-body, the client adds the access token to the request + body using the <tt>access_token</tt> + parameter. The client MUST NOT use this method unless + all of the following conditions are met: + </p> +<ul class="text"> +<li> + The HTTP request entity-header includes the <tt>Content-Type</tt> + header field set to <tt>application/x-www-form-urlencoded</tt>. + +</li> +<li> + The entity-body follows the encoding requirements of the + <tt>application/x-www-form-urlencoded</tt> content-type as + defined by + HTML 4.01 <a class='info' href='#W3C.REC-html401-19991224'>[W3C.REC‑html401‑19991224]<span> (</span><span class='info'>Hors, A., Raggett, D., and I. Jacobs, “HTML 4.01 Specification,” December 1999.</span><span>)</span></a>. + +</li> +<li> + The HTTP request entity-body is single-part. + +</li> +<li> + The content to be encoded in the entity-body MUST + consist entirely of ASCII <a class='info' href='#USASCII'>[USASCII]<span> (</span><span class='info'>American National Standards Institute, “Coded Character Set -- 7-bit American Standard Code for Information Interchange,” 1986.</span><span>)</span></a> characters. + +</li> +<li> + The HTTP request method is one for which the request + body has defined semantics. In particular, + this means that the <tt>GET</tt> + method MUST NOT be used. + +</li> +</ul><p> + +</p> +<p> + The entity-body MAY include other request-specific + parameters, in which case, the <tt>access_token</tt> parameter MUST be properly + separated from the request-specific parameters using <tt>&</tt> character(s) (ASCII code 38). + +</p> +<p> + For example, the client makes the following HTTP request using transport-layer + security: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +POST /resource HTTP/1.1 +Host: server.example.com +Content-Type: application/x-www-form-urlencoded + +access_token=vF9dft4qmT +</pre></div> +<p> + The <tt>application/x-www-form-urlencoded</tt> + method SHOULD NOT be used except in application contexts + where participating browsers do not have access to the + <tt>Authorization</tt> request header + field. Resource servers MAY support this method. + +</p> +<a name="query-param"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2.3"></a><h3>2.3. +URI Query Parameter</h3> + +<p> + When sending the access token in the HTTP request URI, the client adds the access + token to the request URI query component as defined by + Uniform Resource Identifier (URI) <a class='info' href='#RFC3986'>[RFC3986]<span> (</span><span class='info'>Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</span><span>)</span></a> + using + the <tt>access_token</tt> parameter. + +</p> +<p> + For example, the client makes the following HTTP request using transport-layer + security: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +GET /resource?access_token=vF9dft4qmT HTTP/1.1 +Host: server.example.com +</pre></div> +<p> + The HTTP request URI query can include other + request-specific parameters, in which case, the <tt>access_token</tt> parameter MUST be properly + separated from the request-specific parameters using <tt>&</tt> character(s) (ASCII code 38). + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +https://server.example.com/resource?x=y&access_token=vF9dft4qmT&p=q +</pre></div> +<p> + Because of the security weaknesses associated with the URI + method (see <a class='info' href='#sec-con'>Section 4<span> (</span><span class='info'>Security Considerations</span><span>)</span></a>), including the high + likelihood that the URL containing the access token will be + logged, it SHOULD NOT be used unless it is impossible to + transport the access token in the <tt>Authorization</tt> request header field or + the HTTP request entity-body. Resource servers MAY support + this method. + +</p> +<a name="authn-header"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3"></a><h3>3. +The WWW-Authenticate Response Header Field</h3> + +<p> + If the protected resource request does not include + authentication credentials or does not contain an access + token that enables access to the protected resource, + the resource server MUST include the HTTP <tt>WWW-Authenticate</tt> response header field; + it MAY include it in response to other conditions as well. + The <tt>WWW-Authenticate</tt> header + field uses the framework defined by + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + +</p> +<p> + All challenges defined by this specification MUST use the + auth-scheme value <tt>Bearer</tt>. This + scheme MUST be followed by one or more auth-param values. The + auth-param attributes used or defined by this specification + are as follows. Other auth-param attributes MAY be used as + well. + +</p> +<p> + A <tt>realm</tt> attribute MAY be included + to indicate the scope of protection in the manner described in + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + The <tt>realm</tt> attribute MUST NOT appear more than once. + +</p> +<p> + The <tt>scope</tt> attribute is a space-delimited list of scope values + indicating the required scope of the access token for accessing the requested resource. + In some cases, the <tt>scope</tt> value + will be used when requesting a new access token with + sufficient scope of access to utilize the protected resource. + Use of the <tt>scope</tt> attribute is OPTIONAL. + The <tt>scope</tt> attribute MUST NOT appear more than once. + The <tt>scope</tt> value is intended for + programmatic use and is not meant to be displayed to + end users. + +</p> +<p> + If the protected resource request included an access token and failed authentication, the + resource server SHOULD include the <tt>error</tt> attribute to provide + the client with the reason why the access request was declined. The parameter value is + described in <a class='info' href='#resource-error-codes'>Section 3.1<span> (</span><span class='info'>Error Codes</span><span>)</span></a>. + In addition, the resource server MAY include the <tt>error_description</tt> attribute to provide + developers a human-readable explanation that is not meant + to be displayed to end users. + It also MAY include + the <tt>error_uri</tt> attribute with + an absolute URI identifying a human-readable web page explaining the error. + The <tt>error</tt>, <tt>error_description</tt>, and + <tt>error_uri</tt> attributes MUST NOT appear more than once. + +</p> +<p> + Values for the <tt>scope</tt> attribute MUST NOT include + characters outside the set %x21 / %x23-5B / %x5D-7E + for representing scope values and %x20 for delimiters between scope values. + Values for the <tt>error</tt> and <tt>error_description</tt> attributes MUST NOT include + characters outside the set %x20-21 / %x23-5B / %x5D-7E. + Values for the <tt>error_uri</tt> attribute + MUST conform to the URI-Reference syntax, and thus MUST NOT include + characters outside the set %x21 / %x23-5B / %x5D-7E. + +</p> +<p> + For example, in response to a protected resource request without authentication: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +HTTP/1.1 401 Unauthorized +WWW-Authenticate: Bearer realm="example" +</pre></div> +<p> + And in response to a protected resource request with an authentication attempt using an + expired access token: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +HTTP/1.1 401 Unauthorized +WWW-Authenticate: Bearer realm="example", + error="invalid_token", + error_description="The access token expired" +</pre></div> +<a name="resource-error-codes"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.1"></a><h3>3.1. +Error Codes</h3> + +<p> + When a request fails, the resource server responds using the appropriate HTTP status + code (typically, 400, 401, 403, or 405), + and includes one of the following error codes in + the response: + + </p> +<blockquote class="text"><dl> +<dt>invalid_request</dt> +<dd> + + The request is missing a required parameter, includes an unsupported parameter or + parameter value, repeats the same parameter, uses more than one method for + including an access token, or is otherwise malformed. The resource server SHOULD + respond with the HTTP 400 (Bad Request) status code. + +</dd> +<dt>invalid_token</dt> +<dd> + + The access token provided is expired, revoked, malformed, or invalid for other + reasons. The resource SHOULD respond with the HTTP 401 (Unauthorized) status + code. The client MAY request a new access token and retry the protected resource + request. + +</dd> +<dt>insufficient_scope</dt> +<dd> + + The request requires higher privileges than provided by the access token. The + resource server SHOULD respond with the HTTP 403 (Forbidden) status code and MAY + include the <tt>scope</tt> attribute with the scope necessary to + access the protected resource. + +</dd> +</dl></blockquote><p> + +</p> +<p> + If the request lacks any authentication information (i.e. the client was unaware + authentication is necessary or attempted using an unsupported authentication method), + the resource server SHOULD NOT include an error code or other error information. + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +HTTP/1.1 401 Unauthorized +WWW-Authenticate: Bearer realm="example" +</pre></div> +<a name="sec-con"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4"></a><h3>4. +Security Considerations</h3> + +<p> + This section describes the relevant security threats regarding + token handling when using bearer tokens and describes how to + mitigate these threats. + +</p> +<a name="threats"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4.1"></a><h3>4.1. +Security Threats</h3> + +<p> + The following list presents several common threats against + protocols utilizing some form of tokens. This list of + threats is based on + NIST Special Publication 800-63 <a class='info' href='#NIST800-63'>[NIST800‑63]<span> (</span><span class='info'>Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., and E. Nabbus, “NIST Special Publication 800-63-1, INFORMATION SECURITY,” December 2008.</span><span>)</span></a>. + Since this document builds on the + OAuth 2.0 specification, we exclude a discussion of threats + that are described there or in related documents. + +</p> +<p> + </p> +<blockquote class="text"><dl> +<dt>Token manufacture/modification:</dt> +<dd> + An attacker may generate a bogus token or modify the + token contents (such as the authentication or attribute + statements) of an existing token, causing the resource + server to grant inappropriate access to the client. + For example, an attacker may modify the token to extend + the validity period; a malicious client may modify the + assertion to gain access to information that they + should not be able to view. + +</dd> +<dt>Token disclosure:</dt> +<dd> + Tokens may contain authentication and attribute + statements that include sensitive information. + +</dd> +<dt>Token redirect:</dt> +<dd> + An attacker uses a token generated for consumption by + one resource server to gain access to a different + resource server that mistakenly believes the token to be + for it. + +</dd> +<dt>Token replay:</dt> +<dd> + An attacker attempts to use a token that has already + been used with that resource server in the past. + +</dd> +</dl></blockquote><p> + +</p> +<a name="mitigation"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4.2"></a><h3>4.2. +Threat Mitigation</h3> + +<p> + A large range of threats can be mitigated by protecting the + contents of the token by using a digital signature or a + Message Authentication Code (MAC). + Alternatively, a bearer token can contain a reference to + authorization information, rather than encoding the + information directly. Such references MUST be infeasible for + an attacker to guess; using a reference may require an extra + interaction between a server and the token issuer to resolve + the reference to the authorization information. + The mechanics of such an interaction are not defined by this + specification. + +</p> +<p> + This document does not specify the encoding or the contents + of the token; hence detailed recommendations about the means + of guaranteeing token integrity protection are outside the + scope of this document. The token integrity protection MUST + be sufficient to prevent the token from being modified. + +</p> +<p> + To deal with token redirect, it is important for the + authorization server to include the identity of the intended + recipients (the audience), typically a single resource + server (or a list of resource servers), in the token. + Restricting the use of the token to a specific scope is also + RECOMMENDED. + +</p> +<p> + The authorization server MUST implement TLS. + Which version(s) ought to be implemented will vary over + time, and depend on the widespread deployment and known + security vulnerabilities at the time of implementation. + At the time of this writing, + TLS version 1.2 <a class='info' href='#RFC5246'>[RFC5246]<span> (</span><span class='info'>Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.</span><span>)</span></a> + is the most recent version, but has very limited actual + deployment, and might not be readily available in + implementation toolkits. + TLS version 1.0 <a class='info' href='#RFC2246'>[RFC2246]<span> (</span><span class='info'>Dierks, T. and C. Allen, “The TLS Protocol Version 1.0,” January 1999.</span><span>)</span></a> + is the most widely deployed version, and will give the + broadest interoperability. + +</p> +<p> + To protect against token disclosure, confidentiality + protection MUST be applied using + TLS <a class='info' href='#RFC5246'>[RFC5246]<span> (</span><span class='info'>Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.</span><span>)</span></a> + with a ciphersuite that provides confidentiality and + integrity protection. This + requires that the communication interaction between the + client and the authorization server, as well as the + interaction between the client and the resource server, + utilize confidentiality and integrity protection. + Since TLS is mandatory to + implement and to use with this specification, it is the + preferred approach for preventing token disclosure via the + communication channel. For those cases where the client + is prevented from observing the contents of the token, token + encryption MUST be applied in addition to the usage of TLS + protection. + As a further defense against token disclosure, the client + MUST validate the TLS certificate chain when making requests + to protected resources. + +</p> +<p> + Cookies are typically transmitted in the clear. Thus, any + information contained in them is at risk of disclosure. + Therefore, bearer tokens MUST NOT be stored in cookies that + can be sent in the clear. + +</p> +<p> + In some deployments, including those utilizing load + balancers, the TLS connection to the resource server + terminates prior to the actual server that provides the + resource. This could leave the token unprotected between + the front end server where the TLS connection terminates and + the back end server that provides the resource. In such + deployments, sufficient measures MUST be employed to ensure + confidentiality of the token between the front end and + back end servers; encryption of the token is one possible + such measure. + +</p> +<p> + To deal with token capture and replay, + the following recommendations are + made: First, the lifetime of the token MUST be limited; + one means of achieving this is by + putting a validity time field inside the protected part of + the token. Note that using short-lived (one hour or less) + tokens reduces the impact of them being + leaked. Second, confidentiality protection of the exchanges + between the client and the authorization server and between + the client and the resource server MUST be applied. + As a + consequence, no eavesdropper along the communication path is + able to observe the token exchange. Consequently, such an + on-path adversary cannot replay the token. + Furthermore, when + presenting the token to a resource server, the client MUST + verify the identity of that resource server, as per + 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) + <a class='info' href='#RFC6125'>[RFC6125]<span> (</span><span class='info'>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),” March 2011.</span><span>)</span></a>. + Note that the + client MUST validate the TLS certificate chain when making + these requests to protected resources. Presenting the token + to an unauthenticated and unauthorized resource server or + failing to validate the certificate chain will allow + adversaries to steal the token and gain unauthorized access + to protected resources. + +</p> +<a name="anchor6"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4.3"></a><h3>4.3. +Summary of Recommendations</h3> + +<p> + </p> +<blockquote class="text"><dl> +<dt>Safeguard bearer tokens:</dt> +<dd> + Client implementations MUST ensure that bearer tokens + are not leaked to unintended parties, as they will be + able to use them to gain access to protected resources. + This is the primary security consideration when using + bearer tokens and underlies all the more + specific recommendations that follow. + +</dd> +<dt>Validate SSL certificate chains:</dt> +<dd> + The client MUST validate the TLS certificate chain when + making requests to protected resources. Failing to do + so may enable DNS hijacking attacks to steal the token + and gain unintended access. + +</dd> +<dt>Always use TLS (https):</dt> +<dd> + Clients MUST always use + TLS <a class='info' href='#RFC5246'>[RFC5246]<span> (</span><span class='info'>Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.</span><span>)</span></a> + (https) or equivalent transport security when making requests + with bearer tokens. Failing to do so exposes the token + to numerous attacks that could give attackers unintended + access. + +</dd> +<dt>Don't store bearer tokens in cookies:</dt> +<dd> + Implementations MUST NOT store bearer tokens within + cookies that can be sent in the clear (which is the + default transmission mode for cookies). + Implementations that do store bearer tokens in cookies + MUST take precautions against cross site request forgery. + +</dd> +<dt>Issue short-lived bearer tokens:</dt> +<dd> + Token servers SHOULD issue short-lived (one hour or + less) bearer tokens, particularly when issuing tokens to + clients that run within a web browser or other + environments where information leakage may occur. Using + short-lived bearer tokens can reduce the impact of them + being leaked. + +</dd> +<dt>Issue scoped bearer tokens:</dt> +<dd> + Token servers SHOULD issue bearer tokens that contain an audience + restriction, scoping their use to the intended relying + party or set of relying parties. + +</dd> +<dt>Don't pass bearer tokens in page URLs:</dt> +<dd> + Bearer tokens SHOULD NOT be passed in page URLs (for + example as query string parameters). Instead, bearer + tokens SHOULD be passed in HTTP message headers or + message bodies for which confidentiality measures are + taken. Browsers, web servers, and other software may not + adequately secure URLs in the browser history, web + server logs, and other data structures. If bearer tokens + are passed in page URLs, attackers might be able to + steal them from the history data, logs, or other + unsecured locations. + +</dd> +</dl></blockquote><p> + +</p> +<a name="anchor7"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5"></a><h3>5. +IANA Considerations</h3> + +<a name="anchor8"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.1"></a><h3>5.1. +OAuth Access Token Type Registration</h3> + +<p> + This specification registers the following access token type in the OAuth Access Token + Type Registry. + +</p> +<a name="anchor9"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.1.1"></a><h3>5.1.1. +The "Bearer" OAuth Access Token Type</h3> + +<p> + </p> +<blockquote class="text"><dl> +<dt>Type name:</dt> +<dd> + + Bearer + +</dd> +<dt>Additional Token Endpoint Response Parameters:</dt> +<dd> + + (none) + +</dd> +<dt>HTTP Authentication Scheme(s):</dt> +<dd> + + Bearer + +</dd> +<dt>Change controller:</dt> +<dd> + + IETF + +</dd> +<dt>Specification document(s):</dt> +<dd> + + [[ this document ]] + +</dd> +</dl></blockquote><p> + +</p> +<a name="anchor10"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.2"></a><h3>5.2. +Authentication Scheme Registration</h3> + +<p> + This specification registers the following authentication + scheme in the Authentication Scheme Registry defined in + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + +</p> +<a name="anchor11"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.2.1"></a><h3>5.2.1. +The "Bearer" Authentication Scheme</h3> + +<p> + </p> +<blockquote class="text"><dl> +<dt>Authentication Scheme Name:</dt> +<dd> + + Bearer + +</dd> +<dt>Pointer to specification text:</dt> +<dd> + + [[ this document ]] + +</dd> +<dt>Notes (optional):</dt> +<dd> + + (none) + +</dd> +</dl></blockquote><p> + +</p> +<a name="rfc.references"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.6"></a><h3>6. +References</h3> + +<a name="rfc.references1"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<h3>6.1. Normative References</h3> +<table width="99%" border="0"> +<tr><td class="author-text" valign="top"><a name="I-D.ietf-httpbis-p1-messaging">[I-D.ietf-httpbis-p1-messaging]</a></td> +<td class="author-text">Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “<a href="http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-18">HTTP/1.1, part 1: URIs, Connections, and Message Parsing</a>,” draft-ietf-httpbis-p1-messaging-18 (work in progress), January 2012 (<a href="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p1-messaging-18.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="I-D.ietf-httpbis-p7-auth">[I-D.ietf-httpbis-p7-auth]</a></td> +<td class="author-text">Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “<a href="http://tools.ietf.org/html/draft-ietf-httpbis-p7-auth-18">HTTP/1.1, part 7: Authentication</a>,” draft-ietf-httpbis-p7-auth-18 (work in progress), January 2012 (<a href="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p7-auth-18.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="I-D.ietf-oauth-v2">[I-D.ietf-oauth-v2]</a></td> +<td class="author-text">Hammer, E., Recordon, D., and D. Hardt, “<a href="http://tools.ietf.org/html/draft-ietf-oauth-v2-23">The OAuth 2.0 Authorization Protocol</a>,” draft-ietf-oauth-v2-23 (work in progress), January 2012 (<a href="http://www.ietf.org/internet-drafts/draft-ietf-oauth-v2-23.txt">TXT</a>, <a href="http://www.ietf.org/internet-drafts/draft-ietf-oauth-v2-23.pdf">PDF</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td> +<td class="author-text"><a href="mailto:sob@harvard.edu">Bradner, S.</a>, “<a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>,” BCP 14, RFC 2119, March 1997 (<a href="http://www.rfc-editor.org/rfc/rfc2119.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2119.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2119.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2246">[RFC2246]</a></td> +<td class="author-text"><a href="mailto:tdierks@certicom.com">Dierks, T.</a> and <a href="mailto:callen@certicom.com">C. Allen</a>, “<a href="http://tools.ietf.org/html/rfc2246">The TLS Protocol Version 1.0</a>,” RFC 2246, January 1999 (<a href="http://www.rfc-editor.org/rfc/rfc2246.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC3986">[RFC3986]</a></td> +<td class="author-text"><a href="mailto:timbl@w3.org">Berners-Lee, T.</a>, <a href="mailto:fielding@gbiv.com">Fielding, R.</a>, and <a href="mailto:LMM@acm.org">L. Masinter</a>, “<a href="http://tools.ietf.org/html/rfc3986">Uniform Resource Identifier (URI): Generic Syntax</a>,” STD 66, RFC 3986, January 2005 (<a href="http://www.rfc-editor.org/rfc/rfc3986.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc3986.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc3986.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC5234">[RFC5234]</a></td> +<td class="author-text">Crocker, D. and P. Overell, “<a href="http://tools.ietf.org/html/rfc5234">Augmented BNF for Syntax Specifications: ABNF</a>,” STD 68, RFC 5234, January 2008 (<a href="http://www.rfc-editor.org/rfc/rfc5234.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC5246">[RFC5246]</a></td> +<td class="author-text">Dierks, T. and E. Rescorla, “<a href="http://tools.ietf.org/html/rfc5246">The Transport Layer Security (TLS) Protocol Version 1.2</a>,” RFC 5246, August 2008 (<a href="http://www.rfc-editor.org/rfc/rfc5246.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC6125">[RFC6125]</a></td> +<td class="author-text">Saint-Andre, P. and J. Hodges, “<a href="http://tools.ietf.org/html/rfc6125">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)</a>,” RFC 6125, March 2011 (<a href="http://www.rfc-editor.org/rfc/rfc6125.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="USASCII">[USASCII]</a></td> +<td class="author-text">American National Standards Institute, “Coded Character Set -- 7-bit American Standard Code for Information Interchange,” ANSI X3.4, 1986.</td></tr> +<tr><td class="author-text" valign="top"><a name="W3C.REC-html401-19991224">[W3C.REC-html401-19991224]</a></td> +<td class="author-text">Hors, A., Raggett, D., and I. Jacobs, “<a href="http://www.w3.org/TR/1999/REC-html401-19991224">HTML 4.01 Specification</a>,” World Wide Web Consortium Recommendation REC-html401-19991224, December 1999 (<a href="http://www.w3.org/TR/1999/REC-html401-19991224">HTML</a>).</td></tr> +</table> + +<a name="rfc.references2"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<h3>6.2. Informative References</h3> +<table width="99%" border="0"> +<tr><td class="author-text" valign="top"><a name="NIST800-63">[NIST800-63]</a></td> +<td class="author-text">Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., and E. Nabbus, “<a href="http://csrc.nist.gov/publications/PubsDrafts.html#SP-800-63-Rev.%201">NIST Special Publication 800-63-1, INFORMATION SECURITY</a>,” December 2008.</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2616">[RFC2616]</a></td> +<td class="author-text"><a href="mailto:fielding@ics.uci.edu">Fielding, R.</a>, <a href="mailto:jg@w3.org">Gettys, J.</a>, <a href="mailto:mogul@wrl.dec.com">Mogul, J.</a>, <a href="mailto:frystyk@w3.org">Frystyk, H.</a>, <a href="mailto:masinter@parc.xerox.com">Masinter, L.</a>, <a href="mailto:paulle@microsoft.com">Leach, P.</a>, and <a href="mailto:timbl@w3.org">T. Berners-Lee</a>, “<a href="http://tools.ietf.org/html/rfc2616">Hypertext Transfer Protocol -- HTTP/1.1</a>,” RFC 2616, June 1999 (<a href="http://www.rfc-editor.org/rfc/rfc2616.txt">TXT</a>, <a href="http://www.rfc-editor.org/rfc/rfc2616.ps">PS</a>, <a href="http://www.rfc-editor.org/rfc/rfc2616.pdf">PDF</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2616.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2616.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2617">[RFC2617]</a></td> +<td class="author-text"><a href="mailto:john@math.nwu.edu">Franks, J.</a>, <a href="mailto:pbaker@verisign.com">Hallam-Baker, P.</a>, <a href="mailto:jeff@AbiSource.com">Hostetler, J.</a>, <a href="mailto:lawrence@agranat.com">Lawrence, S.</a>, <a href="mailto:paulle@microsoft.com">Leach, P.</a>, Luotonen, A., and <a href="mailto:stewart@OpenMarket.com">L. Stewart</a>, “<a href="http://tools.ietf.org/html/rfc2617">HTTP Authentication: Basic and Digest Access Authentication</a>,” RFC 2617, June 1999 (<a href="http://www.rfc-editor.org/rfc/rfc2617.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2617.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2617.xml">XML</a>).</td></tr> +</table> + +<a name="anchor14"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.A"></a><h3>Appendix A. +Acknowledgements</h3> + +<p> + The following people contributed to preliminary versions of this document: + Blaine Cook (BT), Brian Eaton (Google), Yaron Y. Goland (Microsoft), Brent Goldman (Facebook), + Raffi Krikorian (Twitter), Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and + concepts within are a product of the OAuth community, the WRAP community, and the OAuth Working + Group. + +</p> +<p> + The OAuth Working Group has dozens of very active contributors who proposed ideas and + wording for this document, including: + Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, + John Bradley, Brian Campbell, Leah Culver, Bill de hÓra, + Brian Ellin, Igor Faynberg, Stephen Farrell, George Fletcher, + Tim Freeman, Evan Gilbert, Yaron Y. Goland, Thomas Hardjono, + Justin Hart, Phil Hunt, John Kemp, Eran Hammer-Lahav, + Chasen Le Hara, Barry Leiba, Michael B. Jones, + Torsten Lodderstedt, Eve Maler, James Manger, Laurence Miao, + William J. Mills, Chuck Mortimore, Anthony Nadalin, + Julian Reschke, Justin Richer, Peter Saint-Andre, Nat Sakimura, + Rob Sayre, Marius Scurtescu, Naitik Shah, Justin Smith, + Jeremy Suriel, Christian Stübner, Paul Tarjan, + Hannes Tschofenig, Franklin Tse, and Shane Weeden. + +</p> +<a name="anchor15"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.B"></a><h3>Appendix B. +Document History</h3> + +<p> + [[ to be removed by the RFC editor before publication as an RFC ]] + +</p> +<p> + -16 + </p> +<ul class="text"> +<li> + Use the HTTPbis auth-param syntax for Bearer challenge + attributes. + +</li> +<li> + Dropped the sentence "The <tt>realm</tt> value is intended for + programmatic use and is not meant to be displayed to end + users". + +</li> +<li> + Reordered form-encoded body parameter description bullets + for better readability. + +</li> +<li> + Added <a class='info' href='#USASCII'>[USASCII]<span> (</span><span class='info'>American National Standards Institute, “Coded Character Set -- 7-bit American Standard Code for Information Interchange,” 1986.</span><span>)</span></a> reference. + +</li> +</ul><p> + +</p> +<p> + -15 + </p> +<ul class="text"> +<li> + Clarified that form-encoded content must consist entirely + of ASCII characters. + +</li> +<li> + Added TLS version requirements. + +</li> +<li> + Applied editorial improvements suggested by Mark + Nottingham during the APPS area review. + +</li> +</ul><p> + +</p> +<p> + -14 + </p> +<ul class="text"> +<li> + Changes made in response to review comments by Security + Area Director Stephen Farrell. Specifically: + +</li> +<li> + Strengthened warnings about passing an access token as a + query parameter and more precisely described the + limitations placed upon the use of this method. + +</li> +<li> + Clarified that the <tt>realm</tt> + attribute MAY included to indicate the scope of protection + in the manner described in + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + +</li> +<li> + Normatively stated that "the token integrity protection + MUST be sufficient to prevent the token from being + modified". + +</li> +<li> + Added statement that "TLS is mandatory to implement and + use with this specification" to the introduction. + +</li> +<li> + Stated that TLS MUST be used with "a ciphersuite that + provides confidentiality and integrity protection". + +</li> +<li> + Added "As a further defense against token disclosure, the + client MUST validate the TLS certificate chain when making + requests to protected resources" to the Threat Mitigation + section. + +</li> +<li> + Clarified that putting a validity time field inside the + protected part of the token is one means, but not the only + means, of limiting the lifetime of the token. + +</li> +<li> + Dropped the confusing phrase "for instance, through the + use of TLS" from the sentence about confidentiality + protection of the exchanges. + +</li> +<li> + Reference RFC 6125 for identity verification, rather than + RFC 2818. + +</li> +<li> + Stated that the token MUST be protected between front end + and back end servers when the TLS connection terminates at + a front end server that is distinct from the actual server + that provides the resource. + +</li> +<li> + Stated that bearer tokens MUST NOT be stored in cookies + that can be sent in the clear in the Threat Mitigation + section. + +</li> +<li> + Replaced sole remaining reference to <a class='info' href='#RFC2616'>[RFC2616]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.</span><span>)</span></a> with + HTTPbis <a class='info' href='#I-D.ietf-httpbis-p1-messaging'>[I‑D.ietf‑httpbis‑p1‑messaging]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 1: URIs, Connections, and Message Parsing,” January 2012.</span><span>)</span></a> + reference. + +</li> +<li> + Replaced all references where the reference is used as if + it were part of the sentence (such as "defined by + [I-D.whatever]") with ones where the specification name is + used, followed by the reference (such as "defined by + Whatever [I-D.whatever]"). + +</li> +<li> + Other on-normative editorial improvements. + +</li> +</ul><p> + +</p> +<p> + -13 + </p> +<ul class="text"> +<li> + At the request of Hannes Tschofenig, made ABNF changes to + make it clear that no special WWW-Authenticate response + header field parsers are needed. The <tt>scope</tt>, <tt>error-description</tt>, and <tt>error-uri</tt> parameters are all now + defined as quoted-string in the ABNF (as <tt>error</tt> already was). Restrictions on + these values that were formerly described in the ABNFs are + now described in normative text instead. + +</li> +</ul><p> + +</p> +<p> + -12 + </p> +<ul class="text"> +<li> + Made non-normative editorial changes that Hannes + Tschofenig requested be applied prior to forwarding the + specification to the IESG. + +</li> +<li> + Added rationale for the choice of the b64token syntax. + +</li> +<li> + Added rationale stating that receivers are free to parse + the <tt>scope</tt> attribute using a + standard quoted-string parser, since it will correctly + process all legal <tt>scope</tt> + values. + +</li> +<li> + Added additional active working group contributors to the + Acknowledgements section. + +</li> +</ul><p> + +</p> +<p> + -11 + </p> +<ul class="text"> +<li> + Replaced uses of <"> with DQUOTE to pass ABNF syntax check. + +</li> +</ul><p> + +</p> +<p> + -10 + </p> +<ul class="text"> +<li> + Removed the #auth-param option from Authorization header + syntax (leaving only the b64token syntax). + +</li> +<li> + Restricted the <tt>scope</tt> value + character set to %x21 / %x23-5B / %x5D-7E (printable ASCII + characters excluding double-quote and backslash). + Indicated that scope is intended for programmatic use and + is not meant to be displayed to end users. + +</li> +<li> + Restricted the character set for <tt>error_description</tt> strings to SP / + VCHAR and indicated that they are not meant to be + displayed to end users. + +</li> +<li> + Included more description in the Abstract, since Hannes + Tschofenig indicated that the RFC editor would require + this. + +</li> +<li> + Changed "Access Grant" to "Authorization Grant", as was + done in the core spec. + +</li> +<li> + Simplified the introduction to the Authenticated Requests + section. + +</li> +</ul><p> + +</p> +<p> + -09 + </p> +<ul class="text"> +<li> + Incorporated working group last call comments. Specific changes were: + +</li> +<li> + Use definitions from <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a> rather than <a class='info' href='#RFC2617'>[RFC2617]<span> (</span><span class='info'>Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</span><span>)</span></a>. + +</li> +<li> + Update credentials definition to conform to <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + +</li> +<li> + Further clarified that query parameters may occur in any order. + +</li> +<li> + Specify that error_description is UTF-8 encoded + (matching the core specification). + +</li> +<li> + Registered "Bearer" Authentication Scheme in + Authentication Scheme Registry defined by + <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + +</li> +<li> + Updated references to oauth-v2, httpbis-p1-messaging, and + httpbis-p7-auth drafts. + +</li> +<li> + Other wording improvements not introducing normative changes. + +</li> +</ul><p> + +</p> +<p> + -08 + </p> +<ul class="text"> +<li> + Updated references to oauth-v2 and HTTPbis drafts. + +</li> +</ul><p> + +</p> +<p> + -07 + </p> +<ul class="text"> +<li> + Added missing comma in error response example. + +</li> +</ul><p> + +</p> +<p> + -06 + </p> +<ul class="text"> +<li> + Changed parameter name <tt>bearer_token</tt> to <tt>access_token</tt>, per working group + consensus. + +</li> +<li> + Changed HTTP status code for <tt>invalid_request</tt> error code from HTTP + 401 (Unauthorized) back to HTTP 400 (Bad Request), per + input from HTTP working group experts. + +</li> +</ul><p> + +</p> +<p> + -05 + </p> +<ul class="text"> +<li> + Removed OAuth Errors Registry, per design team input. + +</li> +<li> + Changed HTTP status code for <tt>invalid_request</tt> error code from HTTP + 400 (Bad Request) to HTTP 401 (Unauthorized) to match HTTP + usage [[ change pending working group consensus ]]. + +</li> +<li> + Added missing quotation marks in error-uri definition. + +</li> +<li> + Added note to add language and encoding information to + error_description if the core specification does. + +</li> +<li> + Explicitly reference the Augmented Backus-Naur Form (ABNF) + defined in <a class='info' href='#RFC5234'>[RFC5234]<span> (</span><span class='info'>Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.</span><span>)</span></a>. + +</li> +<li> + Use auth-param instead of repeating its definition, which + is ( token "=" ( token / quoted-string ) ). + +</li> +<li> + Clarify security considerations about including an + audience restriction in the token and include a + recommendation to issue scoped bearer tokens in the + summary of recommendations. + +</li> +</ul><p> + +</p> +<p> + -04 + </p> +<ul class="text"> +<li> + Edits responding to working group last call feedback on + -03. Specific edits enumerated below. + +</li> +<li> + Added Bearer Token definition in Terminology section. + +</li> +<li> + Changed parameter name <tt>oauth_token</tt> to <tt>bearer_token</tt>. + +</li> +<li> + Added realm parameter to <tt>WWW-Authenticate</tt> response to comply + with <a class='info' href='#RFC2617'>[RFC2617]<span> (</span><span class='info'>Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</span><span>)</span></a>. + +</li> +<li> + Removed "[ RWS 1#auth-param ]" from <tt>credentials</tt> definition since it did + not comply with the ABNF in <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + +</li> +<li> + Removed restriction that the <tt>bearer_token</tt> (formerly <tt>oauth_token</tt>) parameter be the last + parameter in the entity-body and the HTTP request URI + query. + +</li> +<li> + Do not require WWW-Authenticate Response in a reply to a + malformed request, as an HTTP 400 Bad Request response + without a WWW-Authenticate header is likely the right + response in some cases of malformed requests. + +</li> +<li> + Removed OAuth Parameters registry extension. + +</li> +<li> + Numerous editorial improvements suggested by working group + members. + +</li> +</ul><p> + +</p> +<p> + -03 + </p> +<ul class="text"> +<li> + Restored the WWW-Authenticate response header + functionality deleted from the framework specification in + draft 12 based upon the specification text from draft 11. + +</li> +<li> + Augmented the OAuth Parameters registry by adding two + additional parameter usage locations: "resource request" + and "resource response". + +</li> +<li> + Registered the "oauth_token" OAuth parameter with usage + location "resource request". + +</li> +<li> + Registered the "error" OAuth parameter. + +</li> +<li> + Created the OAuth Error registry and registered errors. + +</li> +<li> + Changed the "OAuth2" OAuth access token type name to + "Bearer". + +</li> +</ul><p> + +</p> +<p> + -02 + </p> +<ul class="text"> +<li> + Incorporated feedback received on draft 01. Most changes + were to the security considerations section. No normative + changes were made. Specific changes included: + +</li> +<li> + Changed terminology from "token reuse" to "token capture + and replay". + +</li> +<li> + Removed sentence "Encrypting the token contents is another + alternative" from the security considerations since it was + redundant and potentially confusing. + +</li> +<li> + Corrected some references to "resource server" to be + "authorization server" in the security considerations. + +</li> +<li> + Generalized security considerations language about + obtaining consent of the resource owner. + +</li> +<li> + Broadened scope of security considerations description for + recommendation "Don't pass bearer tokens in page URLs". + +</li> +<li> + Removed unused reference to OAuth 1.0. + +</li> +<li> + Updated reference to framework specification and updated + David Recordon's e-mail address. + +</li> +<li> + Removed security considerations text on authenticating + clients. + +</li> +<li> + Registered the "OAuth2" OAuth access token type and + "oauth_token" parameter. + +</li> +</ul><p> + +</p> +<p> + -01 + </p> +<ul class="text"> +<li> + First public draft, which incorporates feedback received + on -00 including enhanced Security Considerations content. + This version is intended to accompany OAuth 2.0 draft 11. + +</li> +</ul><p> + +</p> +<p> + -00 + </p> +<ul class="text"> +<li> + Initial draft based on preliminary version of OAuth 2.0 draft 11. + +</li> +</ul><p> + +</p> +<a name="rfc.authors"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<h3>Authors' Addresses</h3> +<table width="99%" border="0" cellpadding="0" cellspacing="0"> +<tr><td class="author-text"> </td> +<td class="author-text">Michael B. Jones</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Microsoft</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:mbj@microsoft.com">mbj@microsoft.com</a></td></tr> +<tr><td class="author" align="right">URI: </td> +<td class="author-text"><a href="http://self-issued.info/">http://self-issued.info/</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Dick Hardt</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">independent</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:dick.hardt@gmail.com">dick.hardt@gmail.com</a></td></tr> +<tr><td class="author" align="right">URI: </td> +<td class="author-text"><a href="http://dickhardt.org/">http://dickhardt.org/</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">David Recordon</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Facebook</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:dr@fb.com">dr@fb.com</a></td></tr> +<tr><td class="author" align="right">URI: </td> +<td class="author-text"><a href="http://www.davidrecordon.com/">http://www.davidrecordon.com/</a></td></tr> +</table> +</body></html> |