source: draft-ietf-httpbis/20/draft-ietf-httpbis-p7-auth-20.xml @ 1809

Last change on this file since 1809 was 1809, checked in by julian.reschke@…, 8 years ago

Remove mentions of "seven" parts.

  • Property svn:eol-style set to native
  • Property svn:mime-type set to text/xml
File size: 48.2 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3    This XML document is the output of clean-for-DTD.xslt; a tool that strips
4    extensions to RFC2629(bis) from documents for processing with xml2rfc.
5-->
6<?xml-stylesheet type='text/xsl' href='../myxml2rfc.xslt'?>
7<?rfc toc="yes" ?>
8<?rfc symrefs="yes" ?>
9<?rfc sortrefs="yes" ?>
10<?rfc compact="yes"?>
11<?rfc subcompact="no" ?>
12<?rfc linkmailto="no" ?>
13<?rfc editing="no" ?>
14<?rfc comments="yes"?>
15<?rfc inline="yes"?>
16<?rfc rfcedstyle="yes"?>
17<!DOCTYPE rfc
18  PUBLIC "" "rfc2629.dtd">
19<rfc obsoletes="2616" updates="2617" category="std" ipr="pre5378Trust200902" docName="draft-ietf-httpbis-p7-auth-20">
20
21
22<front>
23
24  <title abbrev="HTTP/1.1, Part 7">HTTP/1.1, part 7: Authentication</title>
25
26  <author initials="R." surname="Fielding" fullname="Roy T. Fielding" role="editor">
27    <organization abbrev="Adobe">Adobe Systems Incorporated</organization>
28    <address>
29      <postal>
30        <street>345 Park Ave</street>
31        <city>San Jose</city>
32        <region>CA</region>
33        <code>95110</code>
34        <country>USA</country>
35      </postal>
36      <email>fielding@gbiv.com</email>
37      <uri>http://roy.gbiv.com/</uri>
38    </address>
39  </author>
40
41  <author initials="Y." surname="Lafon" fullname="Yves Lafon" role="editor">
42    <organization abbrev="W3C">World Wide Web Consortium</organization>
43    <address>
44      <postal>
45        <street>W3C / ERCIM</street>
46        <street>2004, rte des Lucioles</street>
47        <city>Sophia-Antipolis</city>
48        <region>AM</region>
49        <code>06902</code>
50        <country>France</country>
51      </postal>
52      <email>ylafon@w3.org</email>
53      <uri>http://www.raubacapeu.net/people/yves/</uri>
54    </address>
55  </author>
56
57  <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke" role="editor">
58    <organization abbrev="greenbytes">greenbytes GmbH</organization>
59    <address>
60      <postal>
61        <street>Hafenweg 16</street>
62        <city>Muenster</city><region>NW</region><code>48155</code>
63        <country>Germany</country>
64      </postal>
65      <email>julian.reschke@greenbytes.de</email>
66      <uri>http://greenbytes.de/tech/webdav/</uri>
67    </address>
68  </author>
69
70  <date month="July" year="2012" day="16"/>
71  <workgroup>HTTPbis Working Group</workgroup>
72
73<abstract>
74<t>
75   The Hypertext Transfer Protocol (HTTP) is an application-level protocol for
76   distributed, collaborative, hypermedia information systems. This document
77   defines the HTTP Authentication framework.
78</t>
79</abstract>
80
81<note title="Editorial Note (To be removed by RFC Editor)">
82  <t>
83    Discussion of this draft takes place on the HTTPBIS working group
84    mailing list (ietf-http-wg@w3.org), which is archived at
85    <eref target="http://lists.w3.org/Archives/Public/ietf-http-wg/"/>.
86  </t>
87  <t>
88    The current issues list is at
89    <eref target="http://tools.ietf.org/wg/httpbis/trac/report/3"/> and related
90    documents (including fancy diffs) can be found at
91    <eref target="http://tools.ietf.org/wg/httpbis/"/>.
92  </t>
93  <t>
94    The changes in this draft are summarized in <xref target="changes.since.19"/>.
95  </t>
96</note>
97</front>
98<middle>
99<section title="Introduction" anchor="introduction">
100<t>
101   This document defines HTTP/1.1 access control and authentication. It
102   includes the relevant parts of RFC 2616
103   with only minor changes (<xref target="RFC2616"/>), plus the general framework for HTTP authentication,
104   as previously defined in "HTTP Authentication: Basic and Digest Access
105   Authentication" (<xref target="RFC2617"/>).
106</t>
107<t>
108   HTTP provides several OPTIONAL challenge-response authentication
109   mechanisms which can be used by a server to challenge a client request and
110   by a client to provide authentication information. The "basic" and "digest"
111   authentication schemes continue to be specified in
112   RFC 2617.
113</t>
114
115<section title="Conformance and Error Handling" anchor="intro.conformance.and.error.handling">
116<t>
117   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
118   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
119   document are to be interpreted as described in <xref target="RFC2119"/>.
120</t>
121<t>
122   This specification targets conformance criteria according to the role of
123   a participant in HTTP communication.  Hence, HTTP requirements are placed
124   on senders, recipients, clients, servers, user agents, intermediaries,
125   origin servers, proxies, gateways, or caches, depending on what behavior
126   is being constrained by the requirement. See Section 2 of <xref target="Part1"/> for definitions
127   of these terms.
128</t>
129<t>
130   The verb "generate" is used instead of "send" where a requirement
131   differentiates between creating a protocol element and merely forwarding a
132   received element downstream.
133</t>
134<t>
135   An implementation is considered conformant if it complies with all of the
136   requirements associated with the roles it partakes in HTTP. Note that
137   SHOULD-level requirements are relevant here, unless one of the documented
138   exceptions is applicable.
139</t>
140<t>
141   This document also uses ABNF to define valid protocol elements
142   (<xref target="notation"/>).
143   In addition to the prose requirements placed upon them, senders MUST NOT
144   generate protocol elements that do not match the grammar defined by the
145   ABNF rules for those protocol elements that are applicable to the sender's
146   role. If a received protocol element is processed, the recipient MUST be
147   able to parse any value that would match the ABNF rules for that protocol
148   element, excluding only those rules not applicable to the recipient's role.
149</t>
150<t>
151   Unless noted otherwise, a recipient MAY attempt to recover a usable
152   protocol element from an invalid construct.  HTTP does not define
153   specific error handling mechanisms except when they have a direct impact
154   on security, since different applications of the protocol require
155   different error handling strategies.  For example, a Web browser might
156   wish to transparently recover from a response where the
157   Location header field doesn't parse according to the ABNF,
158   whereas a systems control client might consider any form of error recovery
159   to be dangerous.
160</t>
161</section>
162
163<section title="Syntax Notation" anchor="notation">
164<t>
165   This specification uses the Augmented Backus-Naur Form (ABNF) notation
166   of <xref target="RFC5234"/> with the list rule extension defined in
167   Section 1.2 of <xref target="Part1"/>. <xref target="imported.abnf"/> describes rules imported from
168   other documents. <xref target="collected.abnf"/> shows the collected ABNF
169   with the list rule expanded.
170</t>
171</section>
172</section>
173
174<section title="Access Authentication Framework" anchor="access.authentication.framework">
175
176<section title="Challenge and Response" anchor="challenge.and.response">
177 
178 
179 
180 
181 
182<t>
183   HTTP provides a simple challenge-response authentication mechanism
184   that can be used by a server to challenge a client request and by a
185   client to provide authentication information. It uses an extensible,
186   case-insensitive token to identify the authentication scheme, followed
187   by additional information necessary for achieving authentication via that
188   scheme. The latter can either be a comma-separated list of parameters or a
189   single sequence of characters capable of holding base64-encoded
190   information.
191</t>
192<t>
193   Parameters are name-value pairs where the name is matched case-insensitively,
194   and each parameter name MUST only occur once per challenge.
195</t>
196<figure><iref item="auth-scheme" primary="true"/><iref item="auth-param" primary="true"/><iref primary="true" item="Grammar" subitem="auth-scheme"/><iref primary="true" item="Grammar" subitem="auth-param"/><iref item="b64token" primary="true"/><iref primary="true" item="Grammar" subitem="b64token"/><artwork type="abnf2616"><![CDATA[
197  auth-scheme    = token
198 
199  auth-param     = token BWS "=" BWS ( token / quoted-string )
200
201  b64token       = 1*( ALPHA / DIGIT /
202                       "-" / "." / "_" / "~" / "+" / "/" ) *"="
203]]></artwork></figure>
204<t>
205   The "b64token" syntax allows the 66 unreserved URI characters (<xref target="RFC3986"/>),
206   plus a few others, so that it can hold a base64, base64url (URL and filename
207   safe alphabet), base32, or base16 (hex) encoding, with or without padding, but
208   excluding whitespace (<xref target="RFC4648"/>).
209</t>
210<t>
211   The <xref target="status.401" format="none">401 (Unauthorized)</xref> response message is used by an origin server
212   to challenge the authorization of a user agent. This response MUST
213   include a <xref target="header.www-authenticate" format="none">WWW-Authenticate</xref> header field containing at least one
214   challenge applicable to the requested resource.
215</t>
216<t>  
217   The <xref target="status.407" format="none">407 (Proxy Authentication Required)</xref> response message is
218   used by a proxy to challenge the authorization of a client and MUST
219   include a <xref target="header.proxy-authenticate" format="none">Proxy-Authenticate</xref> header field containing at least
220   one challenge applicable to the proxy for the requested resource.
221</t>
222<figure><iref item="challenge" primary="true"/><iref primary="true" item="Grammar" subitem="challenge"/><artwork type="abnf2616"><![CDATA[
223  challenge   = auth-scheme [ 1*SP ( b64token / #auth-param ) ]
224]]></artwork></figure>
225<t><list>
226  <t>
227     Note: User agents will need to take special care in parsing the
228     <xref target="header.www-authenticate" format="none">WWW-Authenticate</xref> and <xref target="header.proxy-authenticate" format="none">Proxy-Authenticate</xref>
229     header field values because they can contain more than one challenge, or
230     if more than one of each is provided, since the contents of a challenge
231     can itself contain a comma-separated list of authentication parameters.
232  </t>
233</list></t>
234<t><list>
235  <t>
236     Note: Many clients fail to parse challenges containing unknown
237     schemes. A workaround for this problem is to list well-supported schemes
238     (such as "basic") first.<!-- see http://greenbytes.de/tech/tc/httpauth/#multibasicunknown2 -->
239  </t>
240</list></t>
241<t>
242   A user agent that wishes to authenticate itself with an origin server
243   — usually, but not necessarily, after receiving a <xref target="status.401" format="none">401 (Unauthorized)</xref>
244   — can do so by including an <xref target="header.authorization" format="none">Authorization</xref> header field with the
245   request.
246</t>
247<t>  
248   A client that wishes to authenticate itself with a proxy — usually,
249   but not necessarily, after receiving a <xref target="status.407" format="none">407 (Proxy Authentication Required)</xref>
250   — can do so by including a <xref target="header.proxy-authorization" format="none">Proxy-Authorization</xref> header field with the
251   request.
252</t>
253<t>
254   Both the <xref target="header.authorization" format="none">Authorization</xref> field value and the <xref target="header.proxy-authorization" format="none">Proxy-Authorization</xref> field value
255   contain the client's credentials for the realm of the resource being
256   requested, based upon a challenge received from the server (possibly at
257   some point in the past). When creating their values, the user agent ought to
258   do so by selecting the challenge with what it considers to be the most
259   secure auth-scheme that it understands, obtaining credentials from the user
260   as appropriate.
261</t>
262<figure><iref item="credentials" primary="true"/><iref primary="true" item="Grammar" subitem="credentials"/><artwork type="abnf2616"><![CDATA[
263  credentials = auth-scheme [ 1*SP ( b64token / #auth-param ) ]
264]]></artwork></figure>
265<t>
266   Upon a request for a protected resource that omits credentials, contains
267   invalid credentials (e.g., a bad password) or partial credentials (e.g.,
268   when the authentication scheme requires more than one round trip), an origin
269   server SHOULD return a <xref target="status.401" format="none">401 (Unauthorized)</xref> response. Such
270   responses MUST include a <xref target="header.www-authenticate" format="none">WWW-Authenticate</xref> header field
271   containing at least one (possibly new) challenge applicable to the
272   requested resource.
273</t>
274<t>
275   Likewise, upon a request that requires authentication by proxies that omit
276   credentials or contain invalid or partial credentials, a proxy SHOULD
277   return a <xref target="status.407" format="none">407 (Proxy Authentication Required)</xref> response. Such responses
278   MUST include a <xref target="header.proxy-authenticate" format="none">Proxy-Authenticate</xref> header field containing a (possibly
279   new) challenge applicable to the proxy.
280</t>
281<t>
282   A server receiving credentials that are valid, but not adequate to gain
283   access, ought to respond with the 403 (Forbidden) status code (Section 4.6.3 of <xref target="Part2"/>).
284</t>
285<t>
286   The HTTP protocol does not restrict applications to this simple
287   challenge-response mechanism for access authentication. Additional
288   mechanisms MAY be used, such as encryption at the transport level or
289   via message encapsulation, and with additional header fields
290   specifying authentication information. However, such additional
291   mechanisms are not defined by this specification.
292</t>
293<t>
294   Proxies MUST forward the <xref target="header.www-authenticate" format="none">WWW-Authenticate</xref> and
295   <xref target="header.authorization" format="none">Authorization</xref> header fields unmodified and follow the rules
296   found in <xref target="header.authorization"/>.
297</t>
298</section>
299
300<section title="Protection Space (Realm)" anchor="protection.space">
301  <iref item="Protection Space"/>
302  <iref item="Realm"/>
303  <iref item="Canonical Root URI"/>
304<t>
305   The authentication parameter realm is reserved for use by authentication
306   schemes that wish to indicate the scope of protection.
307</t>
308<t>
309   A protection space is defined by the canonical root URI (the
310   scheme and authority components of the effective request URI; see
311   Section 5.5 of <xref target="Part1"/>) of the
312   server being accessed, in combination with the realm value if present.
313   These realms allow the protected resources on a server to be
314   partitioned into a set of protection spaces, each with its own
315   authentication scheme and/or authorization database. The realm value
316   is a string, generally assigned by the origin server, which can have
317   additional semantics specific to the authentication scheme. Note that
318   there can be multiple challenges with the same auth-scheme but
319   different realms.
320</t>
321<t>
322   The protection space determines the domain over which credentials can
323   be automatically applied. If a prior request has been authorized, the
324   same credentials MAY be reused for all other requests within that
325   protection space for a period of time determined by the
326   authentication scheme, parameters, and/or user preference. Unless
327   otherwise defined by the authentication scheme, a single protection
328   space cannot extend outside the scope of its server.
329</t>
330<t>
331   For historical reasons, senders MUST only use the quoted-string syntax.
332   Recipients might have to support both token and quoted-string syntax for
333   maximum interoperability with existing clients that have been accepting both
334   notations for a long time.
335</t>
336</section>
337
338<section title="Authentication Scheme Registry" anchor="authentication.scheme.registry">
339<t>
340  The HTTP Authentication Scheme Registry defines the name space for the
341  authentication schemes in challenges and credentials.
342</t>
343<t>
344  Registrations MUST include the following fields:
345  <list style="symbols">
346    <t>Authentication Scheme Name</t>
347    <t>Pointer to specification text</t>
348    <t>Notes (optional)</t>
349  </list>
350</t>
351<t>
352  Values to be added to this name space require IETF Review
353  (see <xref target="RFC5226"/>, Section 4.1).
354</t>
355<t>
356  The registry itself is maintained at <eref target="http://www.iana.org/assignments/http-authschemes"/>.
357</t>
358
359<section title="Considerations for New Authentication Schemes" anchor="considerations.for.new.authentication.schemes">
360<t>
361  There are certain aspects of the HTTP Authentication Framework that put
362  constraints on how new authentication schemes can work:
363</t>
364<t>
365  <list style="symbols">
366    <t>
367      HTTP authentication is presumed to be stateless: all of the information
368      necessary to authenticate a request MUST be provided in the request,
369      rather than be dependent on the server remembering prior requests.
370      Authentication based on, or bound to, the underlying connection is
371      outside the scope of this specification and inherently flawed unless
372      steps are taken to ensure that the connection cannot be used by any
373      party other than the authenticated user
374      (see Section 2.4 of <xref target="Part1"/>).
375    </t>
376    <t>
377      The authentication parameter "realm" is reserved for defining Protection
378      Spaces as defined in <xref target="protection.space"/>. New schemes
379      MUST NOT use it in a way incompatible with that definition.
380    </t>
381    <t>
382      The "b64token" notation was introduced for compatibility with existing
383      authentication schemes and can only be used once per challenge/credentials.
384      New schemes thus ought to use the "auth-param" syntax instead, because
385      otherwise future extensions will be impossible.
386    </t>
387    <t>
388      The parsing of challenges and credentials is defined by this specification,
389      and cannot be modified by new authentication schemes. When the auth-param
390      syntax is used, all parameters ought to support both token and
391      quoted-string syntax, and syntactical constraints ought to be defined on
392      the field value after parsing (i.e., quoted-string processing). This is
393      necessary so that recipients can use a generic parser that applies to
394      all authentication schemes.
395    <vspace blankLines="1"/>
396      Note: The fact that the value syntax for the "realm" parameter
397      is restricted to quoted-string was a bad design choice not to be repeated
398      for new parameters.
399    </t>
400    <t>
401      Definitions of new schemes ought to define the treatment of unknown
402      extension parameters. In general, a "must-ignore" rule is preferable
403      over "must-understand", because otherwise it will be hard to introduce
404      new parameters in the presence of legacy recipients. Furthermore,
405      it's good to describe the policy for defining new parameters (such
406      as "update the specification", or "use this registry").
407    </t>
408    <t>
409      Authentication schemes need to document whether they are usable in
410      origin-server authentication (i.e., using <xref target="header.www-authenticate" format="none">WWW-Authenticate</xref>),
411      and/or proxy authentication (i.e., using <xref target="header.proxy-authenticate" format="none">Proxy-Authenticate</xref>).
412    </t>
413    <t>
414      The credentials carried in an <xref target="header.authorization" format="none">Authorization</xref> header field are specific to
415      the User Agent, and therefore have the same effect on HTTP caches as the
416      "private" Cache-Control response directive, within the scope of the
417      request they appear in.
418    <vspace blankLines="1"/>
419      Therefore, new authentication schemes which choose not to carry
420      credentials in the <xref target="header.authorization" format="none">Authorization</xref> header field (e.g., using a newly defined
421      header field) will need to explicitly disallow caching, by mandating the use of
422      either Cache-Control request directives (e.g., "no-store") or response
423      directives (e.g., "private").
424    </t>
425  </list>
426</t>
427</section>
428
429</section>
430
431</section>
432
433<section title="Status Code Definitions" anchor="status.code.definitions">
434<section title="401 Unauthorized" anchor="status.401">
435  <iref primary="true" item="401 Unauthorized (status code)"/>
436  <iref primary="true" item="Status Codes" subitem="401 Unauthorized"/>
437 
438<t>
439   The request requires user authentication. The response MUST include a
440   <xref target="header.www-authenticate" format="none">WWW-Authenticate</xref> header field (<xref target="header.www-authenticate"/>)
441   containing a challenge applicable to the target resource. The client MAY
442   repeat the request with a suitable <xref target="header.authorization" format="none">Authorization</xref> header field
443   (<xref target="header.authorization"/>). If the request already included
444   Authorization credentials, then the 401 response indicates that authorization
445   has been refused for those credentials. If the 401 response contains the
446   same challenge as the prior response, and the user agent has already attempted
447   authentication at least once, then the user SHOULD be presented the
448   representation that was given in the response, since that representation might
449   include relevant diagnostic information.
450</t>
451</section>
452<section title="407 Proxy Authentication Required" anchor="status.407">
453  <iref primary="true" item="407 Proxy Authentication Required (status code)"/>
454  <iref primary="true" item="Status Codes" subitem="407 Proxy Authentication Required"/>
455 
456<t>
457   This code is similar to <xref target="status.401" format="none">401 (Unauthorized)</xref>, but indicates that the
458   client ought to first authenticate itself with the proxy. The proxy MUST
459   return a <xref target="header.proxy-authenticate" format="none">Proxy-Authenticate</xref> header field (<xref target="header.proxy-authenticate"/>) containing a
460   challenge applicable to the proxy for the target resource. The
461   client MAY repeat the request with a suitable <xref target="header.proxy-authorization" format="none">Proxy-Authorization</xref>
462   header field (<xref target="header.proxy-authorization"/>).
463</t>
464</section>
465</section>
466
467<section title="Header Field Definitions" anchor="header.field.definitions">
468<t>
469   This section defines the syntax and semantics of HTTP/1.1 header fields
470   related to authentication.
471</t>
472
473<section title="Authorization" anchor="header.authorization">
474  <iref primary="true" item="Authorization header field"/>
475  <iref primary="true" item="Header Fields" subitem="Authorization"/>
476 
477<t>
478   The "Authorization" header field allows a user agent to authenticate
479   itself with a server — usually, but not necessarily, after receiving a <xref target="status.401" format="none">401
480   (Unauthorized)</xref> response. Its value consists of credentials containing
481   information of the user agent for the realm of the resource being
482   requested.
483</t>
484<figure><iref primary="true" item="Grammar" subitem="Authorization"/><artwork type="abnf2616"><![CDATA[
485  Authorization = credentials
486]]></artwork></figure>
487<t>
488   If a request is
489   authenticated and a realm specified, the same credentials SHOULD
490   be valid for all other requests within this realm (assuming that
491   the authentication scheme itself does not require otherwise, such
492   as credentials that vary according to a challenge value or using
493   synchronized clocks).
494</t>
495<t>
496      When a shared cache (see Section 1.2 of <xref target="Part6"/>) receives a request
497      containing an Authorization field, it MUST NOT return the
498      corresponding response as a reply to any other request, unless one
499      of the following specific exceptions holds:
500</t>
501<t>
502  <list style="numbers">
503      <t>If the response includes the "s-maxage" cache-control
504         directive, the cache MAY use that response in replying to a
505         subsequent request. But (if the specified maximum age has
506         passed) a proxy cache MUST first revalidate it with the origin
507         server, using the header fields from the new request to allow
508         the origin server to authenticate the new request. (This is the
509         defined behavior for s-maxage.) If the response includes "s-maxage=0",
510         the proxy MUST always revalidate it before re-using
511         it.</t>
512
513      <t>If the response includes the "must-revalidate" cache-control
514         directive, the cache MAY use that response in replying to a
515         subsequent request. But if the response is stale, all caches
516         MUST first revalidate it with the origin server, using the
517         header fields from the new request to allow the origin server
518         to authenticate the new request.</t>
519
520      <t>If the response includes the "public" cache-control directive,
521         it MAY be returned in reply to any subsequent request.</t>
522  </list>
523</t>
524</section>
525
526<section title="Proxy-Authenticate" anchor="header.proxy-authenticate">
527  <iref primary="true" item="Proxy-Authenticate header field"/>
528  <iref primary="true" item="Header Fields" subitem="Proxy-Authenticate"/>
529 
530<t>
531   The "Proxy-Authenticate" header field consists of at least one
532   challenge that indicates the authentication scheme(s) and parameters
533   applicable to the proxy for this effective request URI (Section 5.5 of <xref target="Part1"/>).
534   It MUST be included as part of a <xref target="status.407" format="none">407 (Proxy Authentication Required)</xref> response.
535</t>
536<figure><iref primary="true" item="Grammar" subitem="Proxy-Authenticate"/><artwork type="abnf2616"><![CDATA[
537  Proxy-Authenticate = 1#challenge
538]]></artwork></figure>
539<t>
540   Unlike <xref target="header.www-authenticate" format="none">WWW-Authenticate</xref>, the Proxy-Authenticate header field
541   applies only to the current connection, and intermediaries SHOULD NOT
542   forward it to downstream clients. However, an intermediate proxy might need
543   to obtain its own credentials by requesting them from the downstream client,
544   which in some circumstances will appear as if the proxy is forwarding the
545   Proxy-Authenticate header field.
546</t>
547<t>
548   Note that the parsing considerations for <xref target="header.www-authenticate" format="none">WWW-Authenticate</xref>
549   apply to this header field as well; see <xref target="header.www-authenticate"/>
550   for details.
551</t>
552</section>
553
554<section title="Proxy-Authorization" anchor="header.proxy-authorization">
555  <iref primary="true" item="Proxy-Authorization header field"/>
556  <iref primary="true" item="Header Fields" subitem="Proxy-Authorization"/>
557 
558<t>
559   The "Proxy-Authorization" header field allows the client to
560   identify itself (or its user) to a proxy which requires
561   authentication. Its value consists of
562   credentials containing the authentication information of the user
563   agent for the proxy and/or realm of the resource being requested.
564</t>
565<figure><iref primary="true" item="Grammar" subitem="Proxy-Authorization"/><artwork type="abnf2616"><![CDATA[
566  Proxy-Authorization = credentials
567]]></artwork></figure>
568<t>
569   Unlike <xref target="header.authorization" format="none">Authorization</xref>, the Proxy-Authorization header field applies only to
570   the next outbound proxy that demanded authentication using the <xref target="header.proxy-authenticate" format="none">Proxy-Authenticate</xref>
571   field. When multiple proxies are used in a chain, the
572   Proxy-Authorization header field is consumed by the first outbound
573   proxy that was expecting to receive credentials. A proxy MAY relay
574   the credentials from the client request to the next proxy if that is
575   the mechanism by which the proxies cooperatively authenticate a given
576   request.
577</t>
578</section>
579
580<section title="WWW-Authenticate" anchor="header.www-authenticate">
581  <iref primary="true" item="WWW-Authenticate header field"/>
582  <iref primary="true" item="Header Fields" subitem="WWW-Authenticate"/>
583 
584<t>
585   The "WWW-Authenticate" header field consists of at least one
586   challenge that indicates the authentication scheme(s) and parameters
587   applicable to the effective request URI (Section 5.5 of <xref target="Part1"/>).
588</t>
589<t>  
590   It MUST be included in <xref target="status.401" format="none">401 (Unauthorized)</xref> response messages and MAY be
591   included in other response messages to indicate that supplying credentials
592   (or different credentials) might affect the response.
593</t>
594<figure><iref primary="true" item="Grammar" subitem="WWW-Authenticate"/><artwork type="abnf2616"><![CDATA[
595  WWW-Authenticate = 1#challenge
596]]></artwork></figure>
597<t>
598   User agents are advised to take special care in parsing the WWW-Authenticate
599   field value as it might contain more than one challenge,
600   or if more than one WWW-Authenticate header field is provided, the
601   contents of a challenge itself can contain a comma-separated list of
602   authentication parameters.
603</t>
604<figure>
605  <preamble>For instance:</preamble>
606  <artwork type="example"><![CDATA[
607  WWW-Authenticate: Newauth realm="apps", type=1,
608                    title="Login to \"apps\"", Basic realm="simple"
609]]></artwork>
610  <postamble>
611  This header field contains two challenges; one for the "Newauth" scheme
612  with a realm value of "apps", and two additional parameters "type" and
613  "title", and another one for the "Basic" scheme with a realm value of
614  "simple".
615</postamble></figure>
616<t><list>
617  <t>
618    Note: The challenge grammar production uses the list syntax as
619    well. Therefore, a sequence of comma, whitespace, and comma can be
620    considered both as applying to the preceding challenge, or to be an
621    empty entry in the list of challenges. In practice, this ambiguity
622    does not affect the semantics of the header field value and thus is
623    harmless.
624  </t>
625</list></t>
626</section>
627
628</section>
629
630<section title="IANA Considerations" anchor="IANA.considerations">
631
632<section title="Authentication Scheme Registry" anchor="authentication.scheme.registration">
633<t>
634  The registration procedure for HTTP Authentication Schemes is defined by
635  <xref target="authentication.scheme.registry"/> of this document.
636</t>
637<t>
638   The HTTP Method Authentication Scheme shall be created at <eref target="http://www.iana.org/assignments/http-authschemes"/>.
639</t>
640</section>
641
642<section title="Status Code Registration" anchor="status.code.registration">
643<t>
644   The HTTP Status Code Registry located at <eref target="http://www.iana.org/assignments/http-status-codes"/>
645   shall be updated with the registrations below:
646</t>
647
648<!--AUTOGENERATED FROM extract-status-code-defs.xslt, do not edit manually-->
649<texttable align="left" suppress-title="true" anchor="iana.status.code.registration.table">
650   <ttcol>Value</ttcol>
651   <ttcol>Description</ttcol>
652   <ttcol>Reference</ttcol>
653   <c>401</c>
654   <c>Unauthorized</c>
655   <c>
656      <xref target="status.401"/>
657   </c>
658   <c>407</c>
659   <c>Proxy Authentication Required</c>
660   <c>
661      <xref target="status.407"/>
662   </c>
663</texttable>
664<!--(END)-->
665
666</section>
667
668<section title="Header Field Registration" anchor="header.field.registration">
669<t>
670   The Message Header Field Registry located at <eref target="http://www.iana.org/assignments/message-headers/message-header-index.html"/> shall be updated
671   with the permanent registrations below (see <xref target="RFC3864"/>):
672</t>
673
674<!--AUTOGENERATED FROM extract-header-defs.xslt, do not edit manually-->
675<texttable align="left" suppress-title="true" anchor="iana.header.registration.table">
676   <ttcol>Header Field Name</ttcol>
677   <ttcol>Protocol</ttcol>
678   <ttcol>Status</ttcol>
679   <ttcol>Reference</ttcol>
680
681   <c>Authorization</c>
682   <c>http</c>
683   <c>standard</c>
684   <c>
685      <xref target="header.authorization"/>
686   </c>
687   <c>Proxy-Authenticate</c>
688   <c>http</c>
689   <c>standard</c>
690   <c>
691      <xref target="header.proxy-authenticate"/>
692   </c>
693   <c>Proxy-Authorization</c>
694   <c>http</c>
695   <c>standard</c>
696   <c>
697      <xref target="header.proxy-authorization"/>
698   </c>
699   <c>WWW-Authenticate</c>
700   <c>http</c>
701   <c>standard</c>
702   <c>
703      <xref target="header.www-authenticate"/>
704   </c>
705</texttable>
706<!--(END)-->
707
708<t>
709   The change controller is: "IETF (iesg@ietf.org) - Internet Engineering Task Force".
710</t>
711</section>
712</section>
713
714<section title="Security Considerations" anchor="security.considerations">
715<t>
716   This section is meant to inform application developers, information
717   providers, and users of the security limitations in HTTP/1.1 as
718   described by this document. The discussion does not include
719   definitive solutions to the problems revealed, though it does make
720   some suggestions for reducing security risks.
721</t>
722
723<section title="Authentication Credentials and Idle Clients" anchor="auth.credentials.and.idle.clients">
724<t>
725   Existing HTTP clients and user agents typically retain authentication
726   information indefinitely. HTTP/1.1 does not provide a method for a
727   server to direct clients to discard these cached credentials. This is
728   a significant defect that requires further extensions to HTTP.
729   Circumstances under which credential caching can interfere with the
730   application's security model include but are not limited to:
731  <list style="symbols">
732     <t>Clients which have been idle for an extended period following
733        which the server might wish to cause the client to reprompt the
734        user for credentials.</t>
735
736     <t>Applications which include a session termination indication
737        (such as a "logout" or "commit" button on a page) after which
738        the server side of the application "knows" that there is no
739        further reason for the client to retain the credentials.</t>
740  </list>
741</t>
742<t>
743   This is currently under separate study. There are a number of work-arounds
744   to parts of this problem, and we encourage the use of
745   password protection in screen savers, idle time-outs, and other
746   methods which mitigate the security problems inherent in this
747   problem. In particular, user agents which cache credentials are
748   encouraged to provide a readily accessible mechanism for discarding
749   cached credentials under user control.
750</t>
751</section>
752
753<section title="Protection Spaces" anchor="protection.spaces">
754<t>
755  Authentication schemes that solely rely on the "realm" mechanism for
756  establishing a protection space will expose credentials to all resources on a
757  server. Clients that have successfully made authenticated requests with a
758  resource can use the same authentication credentials for other resources on
759  the same server. This makes it possible for a different resource to harvest
760  authentication credentials for other resources.
761</t>
762<t>
763  This is of particular concern when a server hosts resources for multiple
764  parties under the same canonical root URI (<xref target="protection.space"/>).
765  Possible mitigation strategies include restricting direct access to
766  authentication credentials (i.e., not making the content of the
767  <xref target="header.authorization" format="none">Authorization</xref> request header field available), and separating protection
768  spaces by using a different host name for each party.
769</t>
770</section>
771</section>
772
773<section title="Acknowledgments" anchor="acks">
774<t>
775  This specification takes over the definition of the HTTP Authentication
776  Framework, previously defined in RFC 2617.
777  We thank John Franks, Phillip M. Hallam-Baker, Jeffery L. Hostetler, Scott D. Lawrence,
778  Paul J. Leach, Ari Luotonen, and Lawrence C. Stewart for their work
779  on that specification. See Section 6 of <xref target="RFC2617"/>
780  for further acknowledgements. 
781</t>
782<t>
783  See Section 9 of <xref target="Part1"/> for the Acknowledgments related to this document revision.
784</t>
785</section>
786</middle>
787
788<back>
789
790<references title="Normative References">
791
792<reference anchor="Part1">
793  <front>
794    <title>HTTP/1.1, part 1: Message Routing and Syntax"</title>
795    <author initials="R." surname="Fielding" fullname="Roy T. Fielding" role="editor">
796      <organization abbrev="Adobe">Adobe Systems Incorporated</organization>
797      <address><email>fielding@gbiv.com</email></address>
798    </author>
799    <author initials="Y." surname="Lafon" fullname="Yves Lafon" role="editor">
800      <organization abbrev="W3C">World Wide Web Consortium</organization>
801      <address><email>ylafon@w3.org</email></address>
802    </author>
803    <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke" role="editor">
804      <organization abbrev="greenbytes">greenbytes GmbH</organization>
805      <address><email>julian.reschke@greenbytes.de</email></address>
806    </author>
807    <date month="July" year="2012"/>
808  </front>
809  <seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-p1-messaging-20"/>
810 
811</reference>
812
813<reference anchor="Part2">
814  <front>
815    <title>HTTP/1.1, part 2: Semantics and Payloads</title>
816    <author fullname="Roy T. Fielding" initials="R." role="editor" surname="Fielding">
817      <organization abbrev="Adobe">Adobe Systems Incorporated</organization>
818      <address><email>fielding@gbiv.com</email></address>
819    </author>
820    <author fullname="Yves Lafon" initials="Y." role="editor" surname="Lafon">
821      <organization abbrev="W3C">World Wide Web Consortium</organization>
822      <address><email>ylafon@w3.org</email></address>
823    </author>
824    <author fullname="Julian F. Reschke" initials="J. F." role="editor" surname="Reschke">
825      <organization abbrev="greenbytes">greenbytes GmbH</organization>
826      <address><email>julian.reschke@greenbytes.de</email></address>
827    </author>
828    <date month="July" year="2012"/>
829  </front>
830  <seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-p2-semantics-20"/>
831 
832</reference>
833
834<reference anchor="Part6">
835  <front>
836    <title>HTTP/1.1, part 6: Caching</title>
837    <author initials="R." surname="Fielding" fullname="Roy T. Fielding" role="editor">
838      <organization abbrev="Adobe">Adobe Systems Incorporated</organization>
839      <address><email>fielding@gbiv.com</email></address>
840    </author>
841    <author initials="Y." surname="Lafon" fullname="Yves Lafon" role="editor">
842      <organization abbrev="W3C">World Wide Web Consortium</organization>
843      <address><email>ylafon@w3.org</email></address>
844    </author>
845    <author initials="M." surname="Nottingham" fullname="Mark Nottingham" role="editor">
846      <organization>Rackspace</organization>
847      <address><email>mnot@mnot.net</email></address>
848    </author>
849    <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke" role="editor">
850      <organization abbrev="greenbytes">greenbytes GmbH</organization>
851      <address><email>julian.reschke@greenbytes.de</email></address>
852    </author>
853    <date month="July" year="2012"/>
854  </front>
855  <seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-p6-cache-20"/>
856 
857</reference>
858
859<reference anchor="RFC2119">
860  <front>
861    <title>Key words for use in RFCs to Indicate Requirement Levels</title>
862    <author initials="S." surname="Bradner" fullname="Scott Bradner">
863      <organization>Harvard University</organization>
864      <address><email>sob@harvard.edu</email></address>
865    </author>
866    <date month="March" year="1997"/>
867  </front>
868  <seriesInfo name="BCP" value="14"/>
869  <seriesInfo name="RFC" value="2119"/>
870</reference>
871
872<reference anchor="RFC5234">
873  <front>
874    <title abbrev="ABNF for Syntax Specifications">Augmented BNF for Syntax Specifications: ABNF</title>
875    <author initials="D." surname="Crocker" fullname="Dave Crocker" role="editor">
876      <organization>Brandenburg InternetWorking</organization>
877      <address>
878        <email>dcrocker@bbiw.net</email>
879      </address> 
880    </author>
881    <author initials="P." surname="Overell" fullname="Paul Overell">
882      <organization>THUS plc.</organization>
883      <address>
884        <email>paul.overell@thus.net</email>
885      </address>
886    </author>
887    <date month="January" year="2008"/>
888  </front>
889  <seriesInfo name="STD" value="68"/>
890  <seriesInfo name="RFC" value="5234"/>
891</reference>
892
893</references>
894
895<references title="Informative References">
896
897<reference anchor="RFC2616">
898  <front>
899    <title>Hypertext Transfer Protocol -- HTTP/1.1</title>
900    <author initials="R." surname="Fielding" fullname="R. Fielding">
901      <organization>University of California, Irvine</organization>
902      <address><email>fielding@ics.uci.edu</email></address>
903    </author>
904    <author initials="J." surname="Gettys" fullname="J. Gettys">
905      <organization>W3C</organization>
906      <address><email>jg@w3.org</email></address>
907    </author>
908    <author initials="J." surname="Mogul" fullname="J. Mogul">
909      <organization>Compaq Computer Corporation</organization>
910      <address><email>mogul@wrl.dec.com</email></address>
911    </author>
912    <author initials="H." surname="Frystyk" fullname="H. Frystyk">
913      <organization>MIT Laboratory for Computer Science</organization>
914      <address><email>frystyk@w3.org</email></address>
915    </author>
916    <author initials="L." surname="Masinter" fullname="L. Masinter">
917      <organization>Xerox Corporation</organization>
918      <address><email>masinter@parc.xerox.com</email></address>
919    </author>
920    <author initials="P." surname="Leach" fullname="P. Leach">
921      <organization>Microsoft Corporation</organization>
922      <address><email>paulle@microsoft.com</email></address>
923    </author>
924    <author initials="T." surname="Berners-Lee" fullname="T. Berners-Lee">
925      <organization>W3C</organization>
926      <address><email>timbl@w3.org</email></address>
927    </author>
928    <date month="June" year="1999"/>
929  </front>
930  <seriesInfo name="RFC" value="2616"/>
931</reference>
932
933<reference anchor="RFC2617">
934  <front>
935    <title abbrev="HTTP Authentication">HTTP Authentication: Basic and Digest Access Authentication</title>
936    <author initials="J." surname="Franks" fullname="John Franks">
937      <organization>Northwestern University, Department of Mathematics</organization>
938      <address><email>john@math.nwu.edu</email></address>
939    </author>
940    <author initials="P.M." surname="Hallam-Baker" fullname="Phillip M. Hallam-Baker">
941      <organization>Verisign Inc.</organization>
942      <address><email>pbaker@verisign.com</email></address>
943    </author>
944    <author initials="J.L." surname="Hostetler" fullname="Jeffery L. Hostetler">
945      <organization>AbiSource, Inc.</organization>
946      <address><email>jeff@AbiSource.com</email></address>
947    </author>
948    <author initials="S.D." surname="Lawrence" fullname="Scott D. Lawrence">
949      <organization>Agranat Systems, Inc.</organization>
950      <address><email>lawrence@agranat.com</email></address>
951    </author>
952    <author initials="P.J." surname="Leach" fullname="Paul J. Leach">
953      <organization>Microsoft Corporation</organization>
954      <address><email>paulle@microsoft.com</email></address>
955    </author>
956    <author initials="A." surname="Luotonen" fullname="Ari Luotonen">
957      <organization>Netscape Communications Corporation</organization>
958    </author>
959    <author initials="L." surname="Stewart" fullname="Lawrence C. Stewart">
960      <organization>Open Market, Inc.</organization>
961      <address><email>stewart@OpenMarket.com</email></address>
962    </author>
963    <date month="June" year="1999"/>
964  </front>
965  <seriesInfo name="RFC" value="2617"/>
966</reference>
967
968<reference anchor="RFC3864">
969  <front>
970    <title>Registration Procedures for Message Header Fields</title>
971    <author initials="G." surname="Klyne" fullname="G. Klyne">
972      <organization>Nine by Nine</organization>
973      <address><email>GK-IETF@ninebynine.org</email></address>
974    </author>
975    <author initials="M." surname="Nottingham" fullname="M. Nottingham">
976      <organization>BEA Systems</organization>
977      <address><email>mnot@pobox.com</email></address>
978    </author>
979    <author initials="J." surname="Mogul" fullname="J. Mogul">
980      <organization>HP Labs</organization>
981      <address><email>JeffMogul@acm.org</email></address>
982    </author>
983    <date year="2004" month="September"/>
984  </front>
985  <seriesInfo name="BCP" value="90"/>
986  <seriesInfo name="RFC" value="3864"/>
987</reference>
988
989<reference anchor="RFC3986">
990 <front>
991  <title abbrev="URI Generic Syntax">Uniform Resource Identifier (URI): Generic Syntax</title>
992  <author initials="T." surname="Berners-Lee" fullname="Tim Berners-Lee">
993    <organization abbrev="W3C/MIT">World Wide Web Consortium</organization>
994    <address>
995       <email>timbl@w3.org</email>
996       <uri>http://www.w3.org/People/Berners-Lee/</uri>
997    </address>
998  </author>
999  <author initials="R." surname="Fielding" fullname="Roy T. Fielding">
1000    <organization abbrev="Day Software">Day Software</organization>
1001    <address>
1002      <email>fielding@gbiv.com</email>
1003      <uri>http://roy.gbiv.com/</uri>
1004    </address>
1005  </author>
1006  <author initials="L." surname="Masinter" fullname="Larry Masinter">
1007    <organization abbrev="Adobe Systems">Adobe Systems Incorporated</organization>
1008    <address>
1009      <email>LMM@acm.org</email>
1010      <uri>http://larry.masinter.net/</uri>
1011    </address>
1012  </author>
1013  <date month="January" year="2005"/>
1014 </front>
1015 <seriesInfo name="STD" value="66"/>
1016 <seriesInfo name="RFC" value="3986"/>
1017</reference>
1018
1019<reference anchor="RFC4648">
1020  <front>
1021    <title>The Base16, Base32, and Base64 Data Encodings</title>
1022    <author fullname="S. Josefsson" initials="S." surname="Josefsson"/>
1023    <date year="2006" month="October"/>
1024  </front>
1025  <seriesInfo value="4648" name="RFC"/>
1026</reference>
1027
1028<reference anchor="RFC5226">
1029  <front>
1030    <title>Guidelines for Writing an IANA Considerations Section in RFCs</title>
1031    <author initials="T." surname="Narten" fullname="T. Narten">
1032      <organization>IBM</organization>
1033      <address><email>narten@us.ibm.com</email></address>
1034    </author>
1035    <author initials="H." surname="Alvestrand" fullname="H. Alvestrand">
1036      <organization>Google</organization>
1037      <address><email>Harald@Alvestrand.no</email></address>
1038    </author>
1039    <date year="2008" month="May"/>
1040  </front>
1041  <seriesInfo name="BCP" value="26"/>
1042  <seriesInfo name="RFC" value="5226"/>
1043</reference>
1044
1045</references>
1046
1047<section title="Changes from RFCs 2616 and 2617" anchor="changes.from.rfc.2616">
1048<t>
1049  The "realm" parameter isn't required anymore in general; consequently, the
1050  ABNF allows challenges without any auth parameters.
1051  (<xref target="access.authentication.framework"/>)
1052</t>
1053<t>
1054  The "b64token" alternative to auth-param lists has been added for consistency
1055  with legacy authentication schemes such as "Basic".
1056  (<xref target="access.authentication.framework"/>)
1057</t>
1058<t>
1059  Introduce Authentication Scheme Registry.
1060  (<xref target="authentication.scheme.registry"/>)
1061</t>
1062<t>
1063  Change ABNF productions for header fields to only define the field value.
1064  (<xref target="header.field.definitions"/>)
1065</t>
1066</section>
1067 
1068<section title="Imported ABNF" anchor="imported.abnf">
1069 
1070 
1071 
1072 
1073 
1074 
1075 
1076 
1077 
1078 
1079 
1080<t>
1081  The following core rules are included by
1082  reference, as defined in Appendix B.1 of <xref target="RFC5234"/>:
1083  ALPHA (letters), CR (carriage return), CRLF (CR LF), CTL (controls),
1084  DIGIT (decimal 0-9), DQUOTE (double quote),
1085  HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed),
1086  OCTET (any 8-bit sequence of data), SP (space), and
1087  VCHAR (any visible US-ASCII character).
1088</t>
1089<t>
1090   The rules below are defined in <xref target="Part1"/>:
1091</t>
1092<figure><artwork type="abnf2616"><![CDATA[
1093  BWS           = <BWS, defined in [Part1], Section 3.2.1>
1094  OWS           = <OWS, defined in [Part1], Section 3.2.1>
1095  quoted-string = <quoted-string, defined in [Part1], Section 3.2.4>
1096  token         = <token, defined in [Part1], Section 3.2.4>
1097]]></artwork></figure>
1098</section>
1099
1100
1101<section title="Collected ABNF" anchor="collected.abnf">
1102<figure>
1103<artwork type="abnf" name="p7-auth.parsed-abnf"><![CDATA[
1104Authorization = credentials
1105
1106BWS = <BWS, defined in [Part1], Section 3.2.1>
1107
1108OWS = <OWS, defined in [Part1], Section 3.2.1>
1109
1110Proxy-Authenticate = *( "," OWS ) challenge *( OWS "," [ OWS
1111 challenge ] )
1112Proxy-Authorization = credentials
1113
1114WWW-Authenticate = *( "," OWS ) challenge *( OWS "," [ OWS challenge
1115 ] )
1116
1117auth-param = token BWS "=" BWS ( token / quoted-string )
1118auth-scheme = token
1119
1120b64token = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" )
1121 *"="
1122
1123challenge = auth-scheme [ 1*SP ( b64token / [ ( "," / auth-param ) *(
1124 OWS "," [ OWS auth-param ] ) ] ) ]
1125credentials = auth-scheme [ 1*SP ( b64token / [ ( "," / auth-param )
1126 *( OWS "," [ OWS auth-param ] ) ] ) ]
1127
1128quoted-string = <quoted-string, defined in [Part1], Section 3.2.4>
1129
1130token = <token, defined in [Part1], Section 3.2.4>
1131]]></artwork>
1132</figure>
1133</section>
1134
1135
1136<section title="Change Log (to be removed by RFC Editor before publication)" anchor="change.log">
1137<t>
1138  Changes up to the first Working Group Last Call draft are summarized
1139  in <eref target="http://trac.tools.ietf.org/html/draft-ietf-httpbis-p7-auth-19#appendix-C"/>.
1140</t>
1141
1142<section title="Since draft-ietf-httpbis-p7-auth-19" anchor="changes.since.19">
1143<t>
1144  Closed issues:
1145  <list style="symbols">
1146    <t>
1147      <eref target="http://tools.ietf.org/wg/httpbis/trac/ticket/348"/>:
1148      "Realms and scope"
1149    </t>
1150    <t>
1151      <eref target="http://tools.ietf.org/wg/httpbis/trac/ticket/349"/>:
1152      "Strength"
1153    </t>
1154    <t>
1155      <eref target="http://tools.ietf.org/wg/httpbis/trac/ticket/357"/>:
1156      "Authentication exchanges"
1157    </t>
1158    <t>
1159      <eref target="http://tools.ietf.org/wg/httpbis/trac/ticket/361"/>:
1160      "ABNF requirements for recipients"
1161    </t>
1162    <t>
1163      <eref target="http://tools.ietf.org/wg/httpbis/trac/ticket/368"/>:
1164      "note introduction of new IANA registries as normative changes"
1165    </t>
1166  </list>
1167</t>
1168</section>
1169
1170</section>
1171
1172</back>
1173</rfc>
Note: See TracBrowser for help on using the repository browser.