source: draft-ietf-httpbis/19/draft-ietf-httpbis-p7-auth-19.txt @ 1592

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

-19

  • Property svn:eol-style set to native
  • Property svn:executable set to *
File size: 42.7 KB
Line 
1
2
3
4HTTPbis Working Group                                   R. Fielding, Ed.
5Internet-Draft                                                     Adobe
6Obsoletes: 2616 (if approved)                              Y. Lafon, Ed.
7Updates: 2617 (if approved)                                          W3C
8Intended status: Standards Track                         J. Reschke, Ed.
9Expires: September 13, 2012                                   greenbytes
10                                                          March 12, 2012
11
12
13                    HTTP/1.1, part 7: Authentication
14                     draft-ietf-httpbis-p7-auth-19
15
16Abstract
17
18   The Hypertext Transfer Protocol (HTTP) is an application-level
19   protocol for distributed, collaborative, hypermedia information
20   systems.  HTTP has been in use by the World Wide Web global
21   information initiative since 1990.  This document is Part 7 of the
22   seven-part specification that defines the protocol referred to as
23   "HTTP/1.1" and, taken together, obsoletes RFC 2616.
24
25   Part 7 defines the HTTP Authentication framework.
26
27Editorial Note (To be removed by RFC Editor)
28
29   Discussion of this draft should take place on the HTTPBIS working
30   group mailing list (ietf-http-wg@w3.org), which is archived at
31   <http://lists.w3.org/Archives/Public/ietf-http-wg/>.
32
33   The current issues list is at
34   <http://tools.ietf.org/wg/httpbis/trac/report/3> and related
35   documents (including fancy diffs) can be found at
36   <http://tools.ietf.org/wg/httpbis/>.
37
38   The changes in this draft are summarized in Appendix C.20.
39
40Status of This Memo
41
42   This Internet-Draft is submitted in full conformance with the
43   provisions of BCP 78 and BCP 79.
44
45   Internet-Drafts are working documents of the Internet Engineering
46   Task Force (IETF).  Note that other groups may also distribute
47   working documents as Internet-Drafts.  The list of current Internet-
48   Drafts is at http://datatracker.ietf.org/drafts/current/.
49
50   Internet-Drafts are draft documents valid for a maximum of six months
51   and may be updated, replaced, or obsoleted by other documents at any
52
53
54
55Fielding, et al.       Expires September 13, 2012               [Page 1]
56
57Internet-Draft              HTTP/1.1, Part 7                  March 2012
58
59
60   time.  It is inappropriate to use Internet-Drafts as reference
61   material or to cite them other than as "work in progress."
62
63   This Internet-Draft will expire on September 13, 2012.
64
65Copyright Notice
66
67   Copyright (c) 2012 IETF Trust and the persons identified as the
68   document authors.  All rights reserved.
69
70   This document is subject to BCP 78 and the IETF Trust's Legal
71   Provisions Relating to IETF Documents
72   (http://trustee.ietf.org/license-info) in effect on the date of
73   publication of this document.  Please review these documents
74   carefully, as they describe your rights and restrictions with respect
75   to this document.  Code Components extracted from this document must
76   include Simplified BSD License text as described in Section 4.e of
77   the Trust Legal Provisions and are provided without warranty as
78   described in the Simplified BSD License.
79
80   This document may contain material from IETF Documents or IETF
81   Contributions published or made publicly available before November
82   10, 2008.  The person(s) controlling the copyright in some of this
83   material may not have granted the IETF Trust the right to allow
84   modifications of such material outside the IETF Standards Process.
85   Without obtaining an adequate license from the person(s) controlling
86   the copyright in such materials, this document may not be modified
87   outside the IETF Standards Process, and derivative works of it may
88   not be created outside the IETF Standards Process, except to format
89   it for publication as an RFC or to translate it into languages other
90   than English.
91
92Table of Contents
93
94   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
95     1.1.  Conformance and Error Handling . . . . . . . . . . . . . .  4
96     1.2.  Syntax Notation  . . . . . . . . . . . . . . . . . . . . .  4
97       1.2.1.  Core Rules . . . . . . . . . . . . . . . . . . . . . .  5
98   2.  Access Authentication Framework  . . . . . . . . . . . . . . .  5
99     2.1.  Challenge and Response . . . . . . . . . . . . . . . . . .  5
100     2.2.  Protection Space (Realm) . . . . . . . . . . . . . . . . .  7
101     2.3.  Authentication Scheme Registry . . . . . . . . . . . . . .  7
102       2.3.1.  Considerations for New Authentication Schemes  . . . .  8
103   3.  Status Code Definitions  . . . . . . . . . . . . . . . . . . .  9
104     3.1.  401 Unauthorized . . . . . . . . . . . . . . . . . . . . .  9
105     3.2.  407 Proxy Authentication Required  . . . . . . . . . . . .  9
106   4.  Header Field Definitions . . . . . . . . . . . . . . . . . . . 10
107     4.1.  Authorization  . . . . . . . . . . . . . . . . . . . . . . 10
108
109
110
111Fielding, et al.       Expires September 13, 2012               [Page 2]
112
113Internet-Draft              HTTP/1.1, Part 7                  March 2012
114
115
116     4.2.  Proxy-Authenticate . . . . . . . . . . . . . . . . . . . . 11
117     4.3.  Proxy-Authorization  . . . . . . . . . . . . . . . . . . . 11
118     4.4.  WWW-Authenticate . . . . . . . . . . . . . . . . . . . . . 11
119   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 12
120     5.1.  Authenticaton Scheme Registry  . . . . . . . . . . . . . . 12
121     5.2.  Status Code Registration . . . . . . . . . . . . . . . . . 12
122     5.3.  Header Field Registration  . . . . . . . . . . . . . . . . 13
123   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 13
124     6.1.  Authentication Credentials and Idle Clients  . . . . . . . 13
125   7.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 14
126   8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 14
127     8.1.  Normative References . . . . . . . . . . . . . . . . . . . 14
128     8.2.  Informative References . . . . . . . . . . . . . . . . . . 14
129   Appendix A.  Changes from RFCs 2616 and 2617 . . . . . . . . . . . 15
130   Appendix B.  Collected ABNF  . . . . . . . . . . . . . . . . . . . 16
131   Appendix C.  Change Log (to be removed by RFC Editor before
132                publication)  . . . . . . . . . . . . . . . . . . . . 16
133     C.1.  Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 16
134     C.2.  Since draft-ietf-httpbis-p7-auth-00  . . . . . . . . . . . 16
135     C.3.  Since draft-ietf-httpbis-p7-auth-01  . . . . . . . . . . . 17
136     C.4.  Since draft-ietf-httpbis-p7-auth-02  . . . . . . . . . . . 17
137     C.5.  Since draft-ietf-httpbis-p7-auth-03  . . . . . . . . . . . 17
138     C.6.  Since draft-ietf-httpbis-p7-auth-04  . . . . . . . . . . . 17
139     C.7.  Since draft-ietf-httpbis-p7-auth-05  . . . . . . . . . . . 17
140     C.8.  Since draft-ietf-httpbis-p7-auth-06  . . . . . . . . . . . 18
141     C.9.  Since draft-ietf-httpbis-p7-auth-07  . . . . . . . . . . . 18
142     C.10. Since draft-ietf-httpbis-p7-auth-08  . . . . . . . . . . . 18
143     C.11. Since draft-ietf-httpbis-p7-auth-09  . . . . . . . . . . . 18
144     C.12. Since draft-ietf-httpbis-p7-auth-10  . . . . . . . . . . . 18
145     C.13. Since draft-ietf-httpbis-p7-auth-11  . . . . . . . . . . . 18
146     C.14. Since draft-ietf-httpbis-p7-auth-12  . . . . . . . . . . . 19
147     C.15. Since draft-ietf-httpbis-p7-auth-13  . . . . . . . . . . . 19
148     C.16. Since draft-ietf-httpbis-p7-auth-14  . . . . . . . . . . . 19
149     C.17. Since draft-ietf-httpbis-p7-auth-15  . . . . . . . . . . . 19
150     C.18. Since draft-ietf-httpbis-p7-auth-16  . . . . . . . . . . . 19
151     C.19. Since draft-ietf-httpbis-p7-auth-17  . . . . . . . . . . . 20
152     C.20. Since draft-ietf-httpbis-p7-auth-18  . . . . . . . . . . . 20
153   Index  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
154
155
156
157
158
159
160
161
162
163
164
165
166
167Fielding, et al.       Expires September 13, 2012               [Page 3]
168
169Internet-Draft              HTTP/1.1, Part 7                  March 2012
170
171
1721.  Introduction
173
174   This document defines HTTP/1.1 access control and authentication.  It
175   includes the relevant parts of RFC 2616 with only minor changes, plus
176   the general framework for HTTP authentication, as previously defined
177   in "HTTP Authentication: Basic and Digest Access Authentication"
178   ([RFC2617]).
179
180   HTTP provides several OPTIONAL challenge-response authentication
181   mechanisms which can be used by a server to challenge a client
182   request and by a client to provide authentication information.  The
183   "basic" and "digest" authentication schemes continue to be specified
184   in RFC 2617.
185
1861.1.  Conformance and Error Handling
187
188   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
189   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
190   document are to be interpreted as described in [RFC2119].
191
192   This document defines conformance criteria for several roles in HTTP
193   communication, including Senders, Recipients, Clients, Servers, User-
194   Agents, Origin Servers, Intermediaries, Proxies and Gateways.  See
195   Section 2 of [Part1] for definitions of these terms.
196
197   An implementation is considered conformant if it complies with all of
198   the requirements associated with its role(s).  Note that SHOULD-level
199   requirements are relevant here, unless one of the documented
200   exceptions is applicable.
201
202   This document also uses ABNF to define valid protocol elements
203   (Section 1.2).  In addition to the prose requirements placed upon
204   them, Senders MUST NOT generate protocol elements that are invalid.
205
206   Unless noted otherwise, Recipients MAY take steps to recover a usable
207   protocol element from an invalid construct.  However, HTTP does not
208   define specific error handling mechanisms, except in cases where it
209   has direct impact on security.  This is because different uses of the
210   protocol require different error handling strategies; for example, a
211   Web browser may wish to transparently recover from a response where
212   the Location header field doesn't parse according to the ABNF,
213   whereby in a systems control protocol using HTTP, this type of error
214   recovery could lead to dangerous consequences.
215
2161.2.  Syntax Notation
217
218   This specification uses the Augmented Backus-Naur Form (ABNF)
219   notation of [RFC5234] with the list rule extension defined in Section
220
221
222
223Fielding, et al.       Expires September 13, 2012               [Page 4]
224
225Internet-Draft              HTTP/1.1, Part 7                  March 2012
226
227
228   1.2 of [Part1].  Appendix B shows the collected ABNF with the list
229   rule expanded.
230
231   The following core rules are included by reference, as defined in
232   [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF
233   (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote),
234   HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit
235   sequence of data), SP (space), and VCHAR (any visible US-ASCII
236   character).
237
2381.2.1.  Core Rules
239
240   The core rules below are defined in [Part1]:
241
242     BWS           = <BWS, defined in [Part1], Section 3.2.1>
243     OWS           = <OWS, defined in [Part1], Section 3.2.1>
244     quoted-string = <quoted-string, defined in [Part1], Section 3.2.4>
245     token         = <token, defined in [Part1], Section 3.2.4>
246
2472.  Access Authentication Framework
248
2492.1.  Challenge and Response
250
251   HTTP provides a simple challenge-response authentication mechanism
252   that can be used by a server to challenge a client request and by a
253   client to provide authentication information.  It uses an extensible,
254   case-insensitive token to identify the authentication scheme,
255   followed by additional information necessary for achieving
256   authentication via that scheme.  The latter can either be a comma-
257   separated list of parameters or a single sequence of characters
258   capable of holding base64-encoded information.
259
260   Parameters are name-value pairs where the name is matched case-
261   insensitively, and each parameter name MUST only occur once per
262   challenge.
263
264     auth-scheme    = token
265
266     auth-param     = token BWS "=" BWS ( token / quoted-string )
267
268     b64token       = 1*( ALPHA / DIGIT /
269                          "-" / "." / "_" / "~" / "+" / "/" ) *"="
270
271   The "b64token" syntax allows the 66 unreserved URI characters
272   ([RFC3986]), plus a few others, so that it can hold a base64,
273   base64url (URL and filename safe alphabet), base32, or base16 (hex)
274   encoding, with or without padding, but excluding whitespace
275   ([RFC4648]).
276
277
278
279Fielding, et al.       Expires September 13, 2012               [Page 5]
280
281Internet-Draft              HTTP/1.1, Part 7                  March 2012
282
283
284   The 401 (Unauthorized) response message is used by an origin server
285   to challenge the authorization of a user agent.  This response MUST
286   include a WWW-Authenticate header field containing at least one
287   challenge applicable to the requested resource.
288
289   The 407 (Proxy Authentication Required) response message is used by a
290   proxy to challenge the authorization of a client and MUST include a
291   Proxy-Authenticate header field containing at least one challenge
292   applicable to the proxy for the requested resource.
293
294     challenge   = auth-scheme [ 1*SP ( b64token / #auth-param ) ]
295
296      Note: User agents will need to take special care in parsing the
297      WWW-Authenticate and Proxy-Authenticate header field values
298      because they can contain more than one challenge, or if more than
299      one of each is provided, since the contents of a challenge can
300      itself contain a comma-separated list of authentication
301      parameters.
302
303      Note: Many browsers fail to parse challenges containing unknown
304      schemes.  A workaround for this problem is to list well-supported
305      schemes (such as "basic") first.
306
307   A user agent that wishes to authenticate itself with an origin server
308   -- usually, but not necessarily, after receiving a 401 (Unauthorized)
309   -- MAY do so by including an Authorization header field with the
310   request.
311
312   A client that wishes to authenticate itself with a proxy -- usually,
313   but not necessarily, after receiving a 407 (Proxy Authentication
314   Required) -- MAY do so by including a Proxy-Authorization header
315   field with the request.
316
317   Both the Authorization field value and the Proxy-Authorization field
318   value consist of credentials containing the authentication
319   information of the client for the realm of the resource being
320   requested.  The user agent MUST choose to use one of the challenges
321   with the strongest auth-scheme it understands and request credentials
322   from the user based upon that challenge.
323
324     credentials = auth-scheme [ 1*SP ( b64token / #auth-param ) ]
325
326   If the origin server does not wish to accept the credentials sent
327   with a request, it SHOULD return a 401 (Unauthorized) response.  The
328   response MUST include a WWW-Authenticate header field containing at
329   least one (possibly new) challenge applicable to the requested
330   resource.
331
332
333
334
335Fielding, et al.       Expires September 13, 2012               [Page 6]
336
337Internet-Draft              HTTP/1.1, Part 7                  March 2012
338
339
340   If a proxy does not accept the credentials sent with a request, it
341   SHOULD return a 407 (Proxy Authentication Required).  The response
342   MUST include a Proxy-Authenticate header field containing a (possibly
343   new) challenge applicable to the proxy for the requested resource.
344
345   The HTTP protocol does not restrict applications to this simple
346   challenge-response mechanism for access authentication.  Additional
347   mechanisms MAY be used, such as encryption at the transport level or
348   via message encapsulation, and with additional header fields
349   specifying authentication information.  However, such additional
350   mechanisms are not defined by this specification.
351
352   Proxies MUST forward the WWW-Authenticate and Authorization headers
353   unmodified and follow the rules found in Section 4.1.
354
3552.2.  Protection Space (Realm)
356
357   The authentication parameter realm is reserved for use by
358   authentication schemes that wish to indicate the scope of protection.
359
360   A protection space is defined by the canonical root URI (the scheme
361   and authority components of the effective request URI; see Section
362   5.5 of [Part1]) of the server being accessed, in combination with the
363   realm value if present.  These realms allow the protected resources
364   on a server to be partitioned into a set of protection spaces, each
365   with its own authentication scheme and/or authorization database.
366   The realm value is a string, generally assigned by the origin server,
367   which can have additional semantics specific to the authentication
368   scheme.  Note that there can be multiple challenges with the same
369   auth-scheme but different realms.
370
371   The protection space determines the domain over which credentials can
372   be automatically applied.  If a prior request has been authorized,
373   the same credentials MAY be reused for all other requests within that
374   protection space for a period of time determined by the
375   authentication scheme, parameters, and/or user preference.  Unless
376   otherwise defined by the authentication scheme, a single protection
377   space cannot extend outside the scope of its server.
378
379   For historical reasons, senders MUST only use the quoted-string
380   syntax.  Recipients might have to support both token and quoted-
381   string syntax for maximum interoperability with existing clients that
382   have been accepting both notations for a long time.
383
3842.3.  Authentication Scheme Registry
385
386   The HTTP Authentication Scheme Registry defines the name space for
387   the authentication schemes in challenges and credentials.
388
389
390
391Fielding, et al.       Expires September 13, 2012               [Page 7]
392
393Internet-Draft              HTTP/1.1, Part 7                  March 2012
394
395
396   Registrations MUST include the following fields:
397
398   o  Authentication Scheme Name
399
400   o  Pointer to specification text
401
402   o  Notes (optional)
403
404   Values to be added to this name space require IETF Review (see
405   [RFC5226], Section 4.1).
406
407   The registry itself is maintained at
408   <http://www.iana.org/assignments/http-authschemes>.
409
4102.3.1.  Considerations for New Authentication Schemes
411
412   There are certain aspects of the HTTP Authentication Framework that
413   put constraints on how new authentication schemes can work:
414
415   o  HTTP authentication is presumed to be stateless: all of the
416      information necessary to authenticate a request MUST be provided
417      in the request, rather than be dependent on the server remembering
418      prior requests.  Authentication based on, or bound to, the
419      underlying connection is outside the scope of this specification
420      and inherently flawed unless steps are taken to ensure that the
421      connection cannot be used by any party other than the
422      authenticated user (see Section 2.3 of [Part1]).
423
424   o  The authentication parameter "realm" is reserved for defining
425      Protection Spaces as defined in Section 2.2.  New schemes MUST NOT
426      use it in a way incompatible with that definition.
427
428   o  The "b64token" notation was introduced for compatibility with
429      existing authentication schemes and can only be used once per
430      challenge/credentials.  New schemes thus ought to use the "auth-
431      param" syntax instead, because otherwise future extensions will be
432      impossible.
433
434   o  The parsing of challenges and credentials is defined by this
435      specification, and cannot be modified by new authentication
436      schemes.  When the auth-param syntax is used, all parameters ought
437      to support both token and quoted-string syntax, and syntactical
438      constraints ought to be defined on the field value after parsing
439      (i.e., quoted-string processing).  This is necessary so that
440      recipients can use a generic parser that applies to all
441      authentication schemes.
442
443      Note: the fact that the value syntax for the "realm" parameter is
444
445
446
447Fielding, et al.       Expires September 13, 2012               [Page 8]
448
449Internet-Draft              HTTP/1.1, Part 7                  March 2012
450
451
452      restricted to quoted-string was a bad design choice not to be
453      repeated for new parameters.
454
455   o  Definitions of new schemes ought to define the treatment of
456      unknown extension parameters.  In general, a "must-ignore" rule is
457      preferable over "must-understand", because otherwise it will be
458      hard to introduce new parameters in the presence of legacy
459      recipients.  Furthermore, it's good to describe the policy for
460      defining new parameters (such as "update the specification", or
461      "use this registry").
462
463   o  Authentication schemes need to document whether they are usable in
464      origin-server authentication (i.e., using WWW-Authenticate),
465      and/or proxy authentication (i.e., using Proxy-Authenticate).
466
467   o  The credentials carried in an Authorization header field are
468      specific to the User Agent, and therefore have the same effect on
469      HTTP caches as the "private" Cache-Control response directive,
470      within the scope of the request they appear in.
471
472      Therefore, new authentication schemes which choose not to carry
473      credentials in the Authorization header (e.g., using a newly
474      defined header) will need to explicitly disallow caching, by
475      mandating the use of either Cache-Control request directives
476      (e.g., "no-store") or response directives (e.g., "private").
477
4783.  Status Code Definitions
479
4803.1.  401 Unauthorized
481
482   The request requires user authentication.  The response MUST include
483   a WWW-Authenticate header field (Section 4.4) containing a challenge
484   applicable to the target resource.  The client MAY repeat the request
485   with a suitable Authorization header field (Section 4.1).  If the
486   request already included Authorization credentials, then the 401
487   response indicates that authorization has been refused for those
488   credentials.  If the 401 response contains the same challenge as the
489   prior response, and the user agent has already attempted
490   authentication at least once, then the user SHOULD be presented the
491   representation that was given in the response, since that
492   representation might include relevant diagnostic information.
493
4943.2.  407 Proxy Authentication Required
495
496   This code is similar to 401 (Unauthorized), but indicates that the
497   client ought to first authenticate itself with the proxy.  The proxy
498   MUST return a Proxy-Authenticate header field (Section 4.2)
499   containing a challenge applicable to the proxy for the target
500
501
502
503Fielding, et al.       Expires September 13, 2012               [Page 9]
504
505Internet-Draft              HTTP/1.1, Part 7                  March 2012
506
507
508   resource.  The client MAY repeat the request with a suitable Proxy-
509   Authorization header field (Section 4.3).
510
5114.  Header Field Definitions
512
513   This section defines the syntax and semantics of HTTP/1.1 header
514   fields related to authentication.
515
5164.1.  Authorization
517
518   The "Authorization" header field allows a user agent to authenticate
519   itself with a server -- usually, but not necessarily, after receiving
520   a 401 (Unauthorized) response.  Its value consists of credentials
521   containing information of the user agent for the realm of the
522   resource being requested.
523
524     Authorization = credentials
525
526   If a request is authenticated and a realm specified, the same
527   credentials SHOULD be valid for all other requests within this realm
528   (assuming that the authentication scheme itself does not require
529   otherwise, such as credentials that vary according to a challenge
530   value or using synchronized clocks).
531
532   When a shared cache (see Section 1.2 of [Part6]) receives a request
533   containing an Authorization field, it MUST NOT return the
534   corresponding response as a reply to any other request, unless one of
535   the following specific exceptions holds:
536
537   1.  If the response includes the "s-maxage" cache-control directive,
538       the cache MAY use that response in replying to a subsequent
539       request.  But (if the specified maximum age has passed) a proxy
540       cache MUST first revalidate it with the origin server, using the
541       header fields from the new request to allow the origin server to
542       authenticate the new request.  (This is the defined behavior for
543       s-maxage.)  If the response includes "s-maxage=0", the proxy MUST
544       always revalidate it before re-using it.
545
546   2.  If the response includes the "must-revalidate" cache-control
547       directive, the cache MAY use that response in replying to a
548       subsequent request.  But if the response is stale, all caches
549       MUST first revalidate it with the origin server, using the header
550       fields from the new request to allow the origin server to
551       authenticate the new request.
552
553   3.  If the response includes the "public" cache-control directive, it
554       MAY be returned in reply to any subsequent request.
555
556
557
558
559Fielding, et al.       Expires September 13, 2012              [Page 10]
560
561Internet-Draft              HTTP/1.1, Part 7                  March 2012
562
563
5644.2.  Proxy-Authenticate
565
566   The "Proxy-Authenticate" header field consists of a challenge that
567   indicates the authentication scheme and parameters applicable to the
568   proxy for this effective request URI (Section 5.5 of [Part1]).  It
569   MUST be included as part of a 407 (Proxy Authentication Required)
570   response.
571
572     Proxy-Authenticate = 1#challenge
573
574   Unlike WWW-Authenticate, the Proxy-Authenticate header field applies
575   only to the current connection and SHOULD NOT be passed on to
576   downstream clients.  However, an intermediate proxy might need to
577   obtain its own credentials by requesting them from the downstream
578   client, which in some circumstances will appear as if the proxy is
579   forwarding the Proxy-Authenticate header field.
580
581   Note that the parsing considerations for WWW-Authenticate apply to
582   this header field as well; see Section 4.4 for details.
583
5844.3.  Proxy-Authorization
585
586   The "Proxy-Authorization" header field allows the client to identify
587   itself (or its user) to a proxy which requires authentication.  Its
588   value consists of credentials containing the authentication
589   information of the user agent for the proxy and/or realm of the
590   resource being requested.
591
592     Proxy-Authorization = credentials
593
594   Unlike Authorization, the Proxy-Authorization header field applies
595   only to the next outbound proxy that demanded authentication using
596   the Proxy-Authenticate field.  When multiple proxies are used in a
597   chain, the Proxy-Authorization header field is consumed by the first
598   outbound proxy that was expecting to receive credentials.  A proxy
599   MAY relay the credentials from the client request to the next proxy
600   if that is the mechanism by which the proxies cooperatively
601   authenticate a given request.
602
6034.4.  WWW-Authenticate
604
605   The "WWW-Authenticate" header field consists of at least one
606   challenge that indicates the authentication scheme(s) and parameters
607   applicable to the effective request URI (Section 5.5 of [Part1]).
608
609   It MUST be included in 401 (Unauthorized) response messages and MAY
610   be included in other response messages to indicate that supplying
611   credentials (or different credentials) might affect the response.
612
613
614
615Fielding, et al.       Expires September 13, 2012              [Page 11]
616
617Internet-Draft              HTTP/1.1, Part 7                  March 2012
618
619
620     WWW-Authenticate = 1#challenge
621
622   User agents are advised to take special care in parsing the WWW-
623   Authenticate field value as it might contain more than one challenge,
624   or if more than one WWW-Authenticate header field is provided, the
625   contents of a challenge itself can contain a comma-separated list of
626   authentication parameters.
627
628   For instance:
629
630     WWW-Authenticate: Newauth realm="apps", type=1,
631                       title="Login to \"apps\"", Basic realm="simple"
632
633   This header field contains two challenges; one for the "Newauth"
634   scheme with a realm value of "apps", and two additional parameters
635   "type" and "title", and another one for the "Basic" scheme with a
636   realm value of "simple".
637
638      Note: The challenge grammar production uses the list syntax as
639      well.  Therefore, a sequence of comma, whitespace, and comma can
640      be considered both as applying to the preceding challenge, or to
641      be an empty entry in the list of challenges.  In practice, this
642      ambiguity does not affect the semantics of the header field value
643      and thus is harmless.
644
6455.  IANA Considerations
646
6475.1.  Authenticaton Scheme Registry
648
649   The registration procedure for HTTP Authentication Schemes is defined
650   by Section 2.3 of this document.
651
652   The HTTP Method Authentication Scheme shall be created at
653   <http://www.iana.org/assignments/http-authschemes>.
654
6555.2.  Status Code Registration
656
657   The HTTP Status Code Registry located at
658   <http://www.iana.org/assignments/http-status-codes> shall be updated
659   with the registrations below:
660
661   +-------+-------------------------------+-------------+
662   | Value | Description                   | Reference   |
663   +-------+-------------------------------+-------------+
664   | 401   | Unauthorized                  | Section 3.1 |
665   | 407   | Proxy Authentication Required | Section 3.2 |
666   +-------+-------------------------------+-------------+
667
668
669
670
671Fielding, et al.       Expires September 13, 2012              [Page 12]
672
673Internet-Draft              HTTP/1.1, Part 7                  March 2012
674
675
6765.3.  Header Field Registration
677
678   The Message Header Field Registry located at <http://www.iana.org/
679   assignments/message-headers/message-header-index.html> shall be
680   updated with the permanent registrations below (see [RFC3864]):
681
682   +---------------------+----------+----------+-------------+
683   | Header Field Name   | Protocol | Status   | Reference   |
684   +---------------------+----------+----------+-------------+
685   | Authorization       | http     | standard | Section 4.1 |
686   | Proxy-Authenticate  | http     | standard | Section 4.2 |
687   | Proxy-Authorization | http     | standard | Section 4.3 |
688   | WWW-Authenticate    | http     | standard | Section 4.4 |
689   +---------------------+----------+----------+-------------+
690
691   The change controller is: "IETF (iesg@ietf.org) - Internet
692   Engineering Task Force".
693
6946.  Security Considerations
695
696   This section is meant to inform application developers, information
697   providers, and users of the security limitations in HTTP/1.1 as
698   described by this document.  The discussion does not include
699   definitive solutions to the problems revealed, though it does make
700   some suggestions for reducing security risks.
701
7026.1.  Authentication Credentials and Idle Clients
703
704   Existing HTTP clients and user agents typically retain authentication
705   information indefinitely.  HTTP/1.1 does not provide a method for a
706   server to direct clients to discard these cached credentials.  This
707   is a significant defect that requires further extensions to HTTP.
708   Circumstances under which credential caching can interfere with the
709   application's security model include but are not limited to:
710
711   o  Clients which have been idle for an extended period following
712      which the server might wish to cause the client to reprompt the
713      user for credentials.
714
715   o  Applications which include a session termination indication (such
716      as a "logout" or "commit" button on a page) after which the server
717      side of the application "knows" that there is no further reason
718      for the client to retain the credentials.
719
720   This is currently under separate study.  There are a number of work-
721   arounds to parts of this problem, and we encourage the use of
722   password protection in screen savers, idle time-outs, and other
723   methods which mitigate the security problems inherent in this
724
725
726
727Fielding, et al.       Expires September 13, 2012              [Page 13]
728
729Internet-Draft              HTTP/1.1, Part 7                  March 2012
730
731
732   problem.  In particular, user agents which cache credentials are
733   encouraged to provide a readily accessible mechanism for discarding
734   cached credentials under user control.
735
7367.  Acknowledgments
737
738   This specification takes over the definition of the HTTP
739   Authentication Framework, previously defined in RFC 2617.  We thank
740   John Franks, Phillip M. Hallam-Baker, Jeffery L. Hostetler, Scott D.
741   Lawrence, Paul J. Leach, Ari Luotonen, and Lawrence C. Stewart for
742   their work on that specification.  See Section 6 of [RFC2617] for
743   further acknowledgements.
744
745   See Section 9 of [Part1] for the Acknowledgments related to this
746   document revision.
747
7488.  References
749
7508.1.  Normative References
751
752   [Part1]    Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
753              "HTTP/1.1, part 1: URIs, Connections, and Message
754              Parsing", draft-ietf-httpbis-p1-messaging-19 (work in
755              progress), March 2012.
756
757   [Part6]    Fielding, R., Ed., Lafon, Y., Ed., Nottingham, M., Ed.,
758              and J. Reschke, Ed., "HTTP/1.1, part 6: Caching",
759              draft-ietf-httpbis-p6-cache-19 (work in progress),
760              March 2012.
761
762   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
763              Requirement Levels", BCP 14, RFC 2119, March 1997.
764
765   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
766              Specifications: ABNF", STD 68, RFC 5234, January 2008.
767
7688.2.  Informative References
769
770   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
771              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
772              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
773
774   [RFC2617]  Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
775              Leach, P., Luotonen, A., and L. Stewart, "HTTP
776              Authentication: Basic and Digest Access Authentication",
777              RFC 2617, June 1999.
778
779   [RFC3864]  Klyne, G., Nottingham, M., and J. Mogul, "Registration
780
781
782
783Fielding, et al.       Expires September 13, 2012              [Page 14]
784
785Internet-Draft              HTTP/1.1, Part 7                  March 2012
786
787
788              Procedures for Message Header Fields", BCP 90, RFC 3864,
789              September 2004.
790
791   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
792              Resource Identifier (URI): Generic Syntax", STD 66,
793              RFC 3986, January 2005.
794
795   [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
796              Encodings", RFC 4648, October 2006.
797
798   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
799              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
800              May 2008.
801
802Appendix A.  Changes from RFCs 2616 and 2617
803
804   The "realm" parameter isn't required anymore in general;
805   consequently, the ABNF allows challenges without any auth parameters.
806   (Section 2)
807
808   The "b64token" alternative to auth-param lists has been added for
809   consistency with legacy authentication schemes such as "Basic".
810   (Section 2)
811
812   Change ABNF productions for header fields to only define the field
813   value.  (Section 4)
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839Fielding, et al.       Expires September 13, 2012              [Page 15]
840
841Internet-Draft              HTTP/1.1, Part 7                  March 2012
842
843
844Appendix B.  Collected ABNF
845
846   Authorization = credentials
847
848   BWS = <BWS, defined in [Part1], Section 3.2.1>
849
850   OWS = <OWS, defined in [Part1], Section 3.2.1>
851
852   Proxy-Authenticate = *( "," OWS ) challenge *( OWS "," [ OWS
853    challenge ] )
854   Proxy-Authorization = credentials
855
856   WWW-Authenticate = *( "," OWS ) challenge *( OWS "," [ OWS challenge
857    ] )
858
859   auth-param = token BWS "=" BWS ( token / quoted-string )
860   auth-scheme = token
861
862   b64token = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" )
863    *"="
864
865   challenge = auth-scheme [ 1*SP ( b64token / [ ( "," / auth-param ) *(
866    OWS "," [ OWS auth-param ] ) ] ) ]
867   credentials = auth-scheme [ 1*SP ( b64token / [ ( "," / auth-param )
868    *( OWS "," [ OWS auth-param ] ) ] ) ]
869
870   quoted-string = <quoted-string, defined in [Part1], Section 3.2.4>
871
872   token = <token, defined in [Part1], Section 3.2.4>
873
874   ABNF diagnostics:
875
876   ; Authorization defined but not used
877   ; Proxy-Authenticate defined but not used
878   ; Proxy-Authorization defined but not used
879   ; WWW-Authenticate defined but not used
880
881Appendix C.  Change Log (to be removed by RFC Editor before publication)
882
883C.1.  Since RFC 2616
884
885   Extracted relevant partitions from [RFC2616].
886
887C.2.  Since draft-ietf-httpbis-p7-auth-00
888
889   Closed issues:
890
891
892
893
894
895Fielding, et al.       Expires September 13, 2012              [Page 16]
896
897Internet-Draft              HTTP/1.1, Part 7                  March 2012
898
899
900   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/35>: "Normative and
901      Informative references"
902
903C.3.  Since draft-ietf-httpbis-p7-auth-01
904
905   Ongoing work on ABNF conversion
906   (<http://tools.ietf.org/wg/httpbis/trac/ticket/36>):
907
908   o  Explicitly import BNF rules for "challenge" and "credentials" from
909      RFC2617.
910
911   o  Add explicit references to BNF syntax and rules imported from
912      other parts of the specification.
913
914C.4.  Since draft-ietf-httpbis-p7-auth-02
915
916   Ongoing work on IANA Message Header Field Registration
917   (<http://tools.ietf.org/wg/httpbis/trac/ticket/40>):
918
919   o  Reference RFC 3984, and update header field registrations for
920      header fields defined in this document.
921
922C.5.  Since draft-ietf-httpbis-p7-auth-03
923
924   None.
925
926C.6.  Since draft-ietf-httpbis-p7-auth-04
927
928   Ongoing work on ABNF conversion
929   (<http://tools.ietf.org/wg/httpbis/trac/ticket/36>):
930
931   o  Use "/" instead of "|" for alternatives.
932
933   o  Introduce new ABNF rules for "bad" whitespace ("BWS"), optional
934      whitespace ("OWS") and required whitespace ("RWS").
935
936   o  Rewrite ABNFs to spell out whitespace rules, factor out header
937      field value format definitions.
938
939C.7.  Since draft-ietf-httpbis-p7-auth-05
940
941   Final work on ABNF conversion
942   (<http://tools.ietf.org/wg/httpbis/trac/ticket/36>):
943
944   o  Add appendix containing collected and expanded ABNF, reorganize
945      ABNF introduction.
946
947
948
949
950
951Fielding, et al.       Expires September 13, 2012              [Page 17]
952
953Internet-Draft              HTTP/1.1, Part 7                  March 2012
954
955
956C.8.  Since draft-ietf-httpbis-p7-auth-06
957
958   None.
959
960C.9.  Since draft-ietf-httpbis-p7-auth-07
961
962   Closed issues:
963
964   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/198>: "move IANA
965      registrations for optional status codes"
966
967C.10.  Since draft-ietf-httpbis-p7-auth-08
968
969   No significant changes.
970
971C.11.  Since draft-ietf-httpbis-p7-auth-09
972
973   Partly resolved issues:
974
975   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/196>: "Term for the
976      requested resource's URI"
977
978C.12.  Since draft-ietf-httpbis-p7-auth-10
979
980   None.
981
982C.13.  Since draft-ietf-httpbis-p7-auth-11
983
984   Closed issues:
985
986   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/130>: "introduction
987      to part 7 is work-in-progress"
988
989   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/195>: "auth-param
990      syntax"
991
992   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/224>: "Header
993      Classification"
994
995   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/237>: "absorbing the
996      auth framework from 2617"
997
998   Partly resolved issues:
999
1000   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/141>: "should we
1001      have an auth scheme registry"
1002
1003
1004
1005
1006
1007Fielding, et al.       Expires September 13, 2012              [Page 18]
1008
1009Internet-Draft              HTTP/1.1, Part 7                  March 2012
1010
1011
1012C.14.  Since draft-ietf-httpbis-p7-auth-12
1013
1014   None.
1015
1016C.15.  Since draft-ietf-httpbis-p7-auth-13
1017
1018   Closed issues:
1019
1020   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/276>: "untangle
1021      ABNFs for header fields"
1022
1023C.16.  Since draft-ietf-httpbis-p7-auth-14
1024
1025   None.
1026
1027C.17.  Since draft-ietf-httpbis-p7-auth-15
1028
1029   Closed issues:
1030
1031   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/78>: "Relationship
1032      between 401, Authorization and WWW-Authenticate"
1033
1034   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/177>: "Realm
1035      required on challenges"
1036
1037   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/195>: "auth-param
1038      syntax"
1039
1040   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/257>:
1041      "Considerations for new authentications schemes"
1042
1043   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/287>: "LWS in auth-
1044      param ABNF"
1045
1046   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/309>: "credentials
1047      ABNF missing SP (still using implied LWS?)"
1048
1049C.18.  Since draft-ietf-httpbis-p7-auth-16
1050
1051   Closed issues:
1052
1053   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/186>: "Document
1054      HTTP's error-handling philosophy"
1055
1056   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/320>: "add advice on
1057      defining auth scheme parameters"
1058
1059
1060
1061
1062
1063Fielding, et al.       Expires September 13, 2012              [Page 19]
1064
1065Internet-Draft              HTTP/1.1, Part 7                  March 2012
1066
1067
1068C.19.  Since draft-ietf-httpbis-p7-auth-17
1069
1070   Closed issues:
1071
1072   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/314>: "allow
1073      unquoted realm parameters"
1074
1075   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/321>: "Repeating
1076      auth-params"
1077
1078C.20.  Since draft-ietf-httpbis-p7-auth-18
1079
1080   Closed issues:
1081
1082   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/334>: "recipient
1083      behavior for new auth parameters"
1084
1085   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/342>: "WWW-
1086      Authenticate ABNF slightly ambiguous"
1087
1088Index
1089
1090   4
1091      401 Unauthorized (status code)  9
1092      407 Proxy Authentication Required (status code)  9
1093
1094   A
1095      auth-param  5
1096      auth-scheme  5
1097      Authorization header field  10
1098
1099   B
1100      b64token  5
1101
1102   C
1103      challenge  6
1104      credentials  6
1105
1106   G
1107      Grammar
1108         auth-param  5
1109         auth-scheme  5
1110         Authorization  10
1111         b64token  5
1112         challenge  6
1113         credentials  6
1114         Proxy-Authenticate  11
1115         Proxy-Authorization  11
1116
1117
1118
1119Fielding, et al.       Expires September 13, 2012              [Page 20]
1120
1121Internet-Draft              HTTP/1.1, Part 7                  March 2012
1122
1123
1124         WWW-Authenticate  12
1125
1126   H
1127      Header Fields
1128         Authorization  10
1129         Proxy-Authenticate  11
1130         Proxy-Authorization  11
1131         WWW-Authenticate  11
1132
1133   P
1134      Protection Space  7
1135      Proxy-Authenticate header field  11
1136      Proxy-Authorization header field  11
1137
1138   R
1139      Realm  7
1140
1141   S
1142      Status Codes
1143         401 Unauthorized  9
1144         407 Proxy Authentication Required  9
1145
1146   W
1147      WWW-Authenticate header field  11
1148
1149Authors' Addresses
1150
1151   Roy T. Fielding (editor)
1152   Adobe Systems Incorporated
1153   345 Park Ave
1154   San Jose, CA  95110
1155   USA
1156
1157   EMail: fielding@gbiv.com
1158   URI:   http://roy.gbiv.com/
1159
1160
1161   Yves Lafon (editor)
1162   World Wide Web Consortium
1163   W3C / ERCIM
1164   2004, rte des Lucioles
1165   Sophia-Antipolis, AM  06902
1166   France
1167
1168   EMail: ylafon@w3.org
1169   URI:   http://www.raubacapeu.net/people/yves/
1170
1171
1172
1173
1174
1175Fielding, et al.       Expires September 13, 2012              [Page 21]
1176
1177Internet-Draft              HTTP/1.1, Part 7                  March 2012
1178
1179
1180   Julian F. Reschke (editor)
1181   greenbytes GmbH
1182   Hafenweg 16
1183   Muenster, NW  48155
1184   Germany
1185
1186   Phone: +49 251 2807760
1187   Fax:   +49 251 2807761
1188   EMail: julian.reschke@greenbytes.de
1189   URI:   http://greenbytes.de/tech/webdav/
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231Fielding, et al.       Expires September 13, 2012              [Page 22]
1232
Note: See TracBrowser for help on using the repository browser.