HTTP/1.1, part 7: AuthenticationAdobe Systems Incorporated345 Park AveSan JoseCA95110USAfielding@gbiv.comhttp://roy.gbiv.com/Alcatel-Lucent Bell Labs21 Oak Knoll RoadCarlisleMA01741USAjg@freedesktop.orghttp://gettys.wordpress.com/Hewlett-Packard CompanyHP Labs, Large Scale Systems Group1501 Page Mill Road, MS 1177Palo AltoCA94304USAJeffMogul@acm.orgMicrosoft Corporation1 Microsoft WayRedmondWA98052USAhenrikn@microsoft.comAdobe Systems Incorporated345 Park AveSan JoseCA95110USALMM@acm.orghttp://larry.masinter.net/Microsoft Corporation1 Microsoft WayRedmondWA98052paulle@microsoft.comWorld Wide Web ConsortiumMIT Computer Science and Artificial Intelligence LaboratoryThe Stata Center, Building 3232 Vassar StreetCambridgeMA02139USAtimbl@w3.orghttp://www.w3.org/People/Berners-Lee/World Wide Web ConsortiumW3C / ERCIM2004, rte des LuciolesSophia-AntipolisAM06902Franceylafon@w3.orghttp://www.raubacapeu.net/people/yves/greenbytes GmbHHafenweg 16MuensterNW48155Germany+49 251 2807760+49 251 2807761julian.reschke@greenbytes.dehttp://greenbytes.de/tech/webdav/HTTPbis Working Group
The Hypertext Transfer Protocol (HTTP) is an application-level protocol for
distributed, collaborative, hypermedia information systems. HTTP has been in
use by the World Wide Web global information initiative since 1990. This
document is Part 7 of the seven-part specification that defines the protocol
referred to as "HTTP/1.1" and, taken together, obsoletes RFC 2616.
Part 7 defines the HTTP Authentication framework.
Discussion of this draft should take place on the HTTPBIS working group
mailing list (ietf-http-wg@w3.org), which is archived at
.
The current issues list is at
and related
documents (including fancy diffs) can be found at
.
The changes in this draft are summarized in .
This document defines HTTP/1.1 access control and authentication. It
includes the relevant parts of RFC 2616
with only minor changes, plus the general framework for HTTP authentication,
as previously defined in "HTTP Authentication: Basic and Digest Access
Authentication" ().
HTTP provides several OPTIONAL challenge-response authentication
mechanisms which can be used by a server to challenge a client request and
by a client to provide authentication information. The "basic" and "digest"
authentication schemes continue to be specified in
RFC 2617.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in .
This document defines conformance criteria for several roles in HTTP
communication, including Senders, Recipients, Clients, Servers, User-Agents,
Origin Servers, Intermediaries, Proxies and Gateways. See Section 2 of
for definitions of these terms.
An implementation is considered conformant if it complies with all of the
requirements associated with its role(s). Note that SHOULD-level requirements
are relevant here, unless one of the documented exceptions is applicable.
This document also uses ABNF to define valid protocol elements
(). In addition to the prose requirements placed
upon them, Senders MUST NOT generate protocol elements that are invalid.
Unless noted otherwise, Recipients MAY take steps to recover a usable
protocol element from an invalid construct. However, HTTP does not define
specific error handling mechanisms, except in cases where it has direct
impact on security. This is because different uses of the protocol require
different error handling strategies; for example, a Web browser may wish to
transparently recover from a response where the Location header field
doesn't parse according to the ABNF, whereby in a systems control protocol
using HTTP, this type of error recovery could lead to dangerous consequences.
This specification uses the ABNF syntax defined in Section 1.2 of (which
extends the syntax defined in with a list rule).
shows the collected ABNF, with the list
rule expanded.
The following core rules are included by
reference, as defined in , Appendix B.1:
ALPHA (letters), CR (carriage return), CRLF (CR LF), CTL (controls),
DIGIT (decimal 0-9), DQUOTE (double quote),
HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed),
OCTET (any 8-bit sequence of data), SP (space), and
VCHAR (any visible US-ASCII character).
The core rules below are defined in :
HTTP provides a simple challenge-response authentication mechanism
that can be used by a server to challenge a client request and by a
client to provide authentication information. It uses an extensible,
case-insensitive token to identify the authentication scheme, followed
by additional information necessary for achieving authentication via that
scheme. The latter can either be a comma-separated list of parameters or a
single sequence of characters capable of holding base64-encoded
information.
Parameters are name-value pairs where the name is matched case-insensitively,
and each parameter name MUST only occur once per challenge.
The "b64token" syntax allows the 66 unreserved URI characters (),
plus a few others, so that it can hold a base64, base64url (URL and filename
safe alphabet), base32, or base16 (hex) encoding, with or without padding, but
excluding whitespace ().
The 401 (Unauthorized) response message is used by an origin server
to challenge the authorization of a user agent. This response MUST
include a WWW-Authenticate header field containing at least one
challenge applicable to the requested resource.
The 407 (Proxy Authentication Required) response message is used by a proxy to
challenge the authorization of a client and MUST include a Proxy-Authenticate
header field containing at least one challenge
applicable to the proxy for the requested resource.
Note: User agents will need to take special care in parsing the
WWW-Authenticate and Proxy-Authenticate header field values because they
can contain more than one challenge, or if more than one of each is
provided, since the contents of a challenge can itself contain a
comma-separated list of authentication parameters.
Note: Many browsers fail to parse challenges containing unknown
schemes. A workaround for this problem is to list well-supported schemes
(such as "basic") first.
A user agent that wishes to authenticate itself with an origin server
— usually, but not necessarily, after receiving a 401 (Unauthorized)
— MAY do so by including an Authorization header field with the
request.
A client that wishes to authenticate itself with a proxy — usually,
but not necessarily, after receiving a 407 (Proxy Authentication Required)
— MAY do so by including a Proxy-Authorization header field with the
request.
Both the Authorization field value and the Proxy-Authorization field value
consist of credentials containing the authentication information of the
client for the realm of the resource being requested. The user agent MUST
choose to use one of the challenges with the strongest auth-scheme it
understands and request credentials from the user based upon that challenge.
If the origin server does not wish to accept the credentials sent
with a request, it SHOULD return a 401 (Unauthorized) response. The
response MUST include a WWW-Authenticate header field containing at
least one (possibly new) challenge applicable to the requested
resource.
If a proxy does not accept the credentials sent with a
request, it SHOULD return a 407 (Proxy Authentication Required). The
response MUST include a Proxy-Authenticate header field containing a
(possibly new) challenge applicable to the proxy for the requested
resource.
The HTTP protocol does not restrict applications to this simple
challenge-response mechanism for access authentication. Additional
mechanisms MAY be used, such as encryption at the transport level or
via message encapsulation, and with additional header fields
specifying authentication information. However, such additional
mechanisms are not defined by this specification.
Proxies MUST forward the WWW-Authenticate and Authorization headers
unmodified and follow the rules found in .
The authentication parameter realm is reserved for use by authentication
schemes that wish to indicate the scope of protection.
A protection space is defined by the canonical root URI (the
scheme and authority components of the effective request URI; see
Section 4.3 of ) of the
server being accessed, in combination with the realm value if present.
These realms allow the protected resources on a server to be
partitioned into a set of protection spaces, each with its own
authentication scheme and/or authorization database. The realm value
is a string, generally assigned by the origin server, which can have
additional semantics specific to the authentication scheme. Note that
there can be multiple challenges with the same auth-scheme but
different realms.
The protection space determines the domain over which credentials can
be automatically applied. If a prior request has been authorized, the
same credentials MAY be reused for all other requests within that
protection space for a period of time determined by the
authentication scheme, parameters, and/or user preference. Unless
otherwise defined by the authentication scheme, a single protection
space cannot extend outside the scope of its server.
For historical reasons, senders MUST only use the quoted-string syntax.
Recipients might have to support both token and quoted-string syntax for
maximum interoperability with existing clients that have been accepting both
notations for a long time.
The HTTP Authentication Scheme Registry defines the name space for the
authentication schemes in challenges and credentials.
Registrations MUST include the following fields:
Authentication Scheme NamePointer to specification textNotes (optional)
Values to be added to this name space are subject to IETF review
(, Section 4.1).
The registry itself is maintained at .
There are certain aspects of the HTTP Authentication Framework that put
constraints on how new authentication schemes can work:
Authentication schemes need to be compatible with the inherent
constraints of HTTP; for instance, that messages need to keep their
semantics when inspected in isolation, thus an authentication scheme
can not bind information to the TCP session over which the message
was received (see Section 2.2 of ).
The authentication parameter "realm" is reserved for defining Protection
Spaces as defined in . New schemes
MUST NOT use it in a way incompatible with that definition.
The "b64token" notation was introduced for compatibility with existing
authentication schemes and can only be used once per challenge/credentials.
New schemes thus ought to use the "auth-param" syntax instead, because
otherwise future extensions will be impossible.
The parsing of challenges and credentials is defined by this specification,
and cannot be modified by new authentication schemes. When the auth-param
syntax is used, all parameters ought to support both token and
quoted-string syntax, and syntactical constraints ought to be defined on
the field value after parsing (i.e., quoted-string processing). This is
necessary so that recipients can use a generic parser that applies to
all authentication schemes.
Note: the fact that the value syntax for the "realm" parameter
is restricted to quoted-string was a bad design choice not to be repeated
for new parameters.
Authentication schemes need to document whether they are usable in
origin-server authentication (i.e., using WWW-Authenticate), and/or
proxy authentication (i.e., using Proxy-Authenticate).
The credentials carried in an Authorization header field are specific to
the User Agent, and therefore have the same effect on HTTP caches as the
"private" Cache-Control response directive, within the scope of the
request they appear in.
Therefore, new authentication schemes which choose not to carry
credentials in the Authorization header (e.g., using a newly defined
header) will need to explicitly disallow caching, by mandating the use of
either Cache-Control request directives (e.g., "no-store") or response
directives (e.g., "private").
The request requires user authentication. The response MUST include a
WWW-Authenticate header field () containing a challenge
applicable to the target resource. The client MAY repeat the
request with a suitable Authorization header field (). If
the request already included Authorization credentials, then the 401
response indicates that authorization has been refused for those
credentials. If the 401 response contains the same challenge as the
prior response, and the user agent has already attempted
authentication at least once, then the user SHOULD be presented the
representation that was given in the response, since that representation might
include relevant diagnostic information.
This code is similar to 401 (Unauthorized), but indicates that the
client ought to first authenticate itself with the proxy. The proxy MUST
return a Proxy-Authenticate header field () containing a
challenge applicable to the proxy for the target resource. The
client MAY repeat the request with a suitable Proxy-Authorization
header field ().
This section defines the syntax and semantics of HTTP/1.1 header fields
related to authentication.
The "Authorization" header field allows a user agent to authenticate
itself with a server — usually, but not necessarily, after receiving a 401
(Unauthorized) response. Its value consists of credentials containing
information of the user agent for the realm of the resource being
requested.
If a request is
authenticated and a realm specified, the same credentials SHOULD
be valid for all other requests within this realm (assuming that
the authentication scheme itself does not require otherwise, such
as credentials that vary according to a challenge value or using
synchronized clocks).
When a shared cache (see Section 1.2 of ) receives a request
containing an Authorization field, it MUST NOT return the
corresponding response as a reply to any other request, unless one
of the following specific exceptions holds:
If the response includes the "s-maxage" cache-control
directive, the cache MAY use that response in replying to a
subsequent request. But (if the specified maximum age has
passed) a proxy cache MUST first revalidate it with the origin
server, using the header fields from the new request to allow
the origin server to authenticate the new request. (This is the
defined behavior for s-maxage.) If the response includes "s-maxage=0",
the proxy MUST always revalidate it before re-using
it.If the response includes the "must-revalidate" cache-control
directive, the cache MAY use that response in replying to a
subsequent request. But if the response is stale, all caches
MUST first revalidate it with the origin server, using the
header fields from the new request to allow the origin server
to authenticate the new request.If the response includes the "public" cache-control directive,
it MAY be returned in reply to any subsequent request.
The "Proxy-Authenticate" header field consists of a challenge that
indicates the authentication scheme and parameters applicable to the proxy
for this effective request URI (Section 4.3 of ). It MUST be included as part
of a 407 (Proxy Authentication Required) response.
Unlike WWW-Authenticate, the Proxy-Authenticate header field applies only to
the current connection and SHOULD NOT be passed on to downstream
clients. However, an intermediate proxy might need to obtain its own
credentials by requesting them from the downstream client, which in
some circumstances will appear as if the proxy is forwarding the
Proxy-Authenticate header field.
The "Proxy-Authorization" header field allows the client to
identify itself (or its user) to a proxy which requires
authentication. Its value consists of
credentials containing the authentication information of the user
agent for the proxy and/or realm of the resource being requested.
Unlike Authorization, the Proxy-Authorization header field applies only to
the next outbound proxy that demanded authentication using the Proxy-Authenticate
field. When multiple proxies are used in a chain, the
Proxy-Authorization header field is consumed by the first outbound
proxy that was expecting to receive credentials. A proxy MAY relay
the credentials from the client request to the next proxy if that is
the mechanism by which the proxies cooperatively authenticate a given
request.
The "WWW-Authenticate" header field consists of at least one
challenge that indicates the authentication scheme(s) and parameters
applicable to the effective request URI (Section 4.3 of ).
It MUST be included in 401 (Unauthorized) response messages and MAY be
included in other response messages to indicate that supplying credentials
(or different credentials) might affect the response.
User agents are advised to take special care in parsing the WWW-Authenticate
field value as it might contain more than one challenge,
or if more than one WWW-Authenticate header field is provided, the
contents of a challenge itself can contain a comma-separated list of
authentication parameters.
The registration procedure for HTTP Authentication Schemes is defined by
of this document.
The HTTP Method Authentication Scheme shall be created at .
The HTTP Status Code Registry located at
shall be updated with the registrations below:
ValueDescriptionReference401Unauthorized407Proxy Authentication Required
The Message Header Field Registry located at shall be updated
with the permanent registrations below (see ):
Header Field NameProtocolStatusReferenceAuthorizationhttpstandardProxy-AuthenticatehttpstandardProxy-AuthorizationhttpstandardWWW-Authenticatehttpstandard
The change controller is: "IETF (iesg@ietf.org) - Internet Engineering Task Force".
This section is meant to inform application developers, information
providers, and users of the security limitations in HTTP/1.1 as
described by this document. The discussion does not include
definitive solutions to the problems revealed, though it does make
some suggestions for reducing security risks.
Existing HTTP clients and user agents typically retain authentication
information indefinitely. HTTP/1.1 does not provide a method for a
server to direct clients to discard these cached credentials. This is
a significant defect that requires further extensions to HTTP.
Circumstances under which credential caching can interfere with the
application's security model include but are not limited to:
Clients which have been idle for an extended period following
which the server might wish to cause the client to reprompt the
user for credentials.Applications which include a session termination indication
(such as a "logout" or "commit" button on a page) after which
the server side of the application "knows" that there is no
further reason for the client to retain the credentials.
This is currently under separate study. There are a number of work-arounds
to parts of this problem, and we encourage the use of
password protection in screen savers, idle time-outs, and other
methods which mitigate the security problems inherent in this
problem. In particular, user agents which cache credentials are
encouraged to provide a readily accessible mechanism for discarding
cached credentials under user control.
This specification takes over the definition of the HTTP Authentication
Framework, previously defined in RFC 2617.
We thank John Franks, Phillip M. Hallam-Baker, Jeffery L. Hostetler, Scott D. Lawrence,
Paul J. Leach, Ari Luotonen, and Lawrence C. Stewart for their work
on that specification. See Section 6 of
for further acknowledgements.
See Section 11 of for the Acknowledgments related to this document revision.
HTTP/1.1, part 1: URIs, Connections, and Message ParsingAdobe Systems Incorporatedfielding@gbiv.comAlcatel-Lucent Bell Labsjg@freedesktop.orgHewlett-Packard CompanyJeffMogul@acm.orgMicrosoft Corporationhenrikn@microsoft.comAdobe Systems IncorporatedLMM@acm.orgMicrosoft Corporationpaulle@microsoft.comWorld Wide Web Consortiumtimbl@w3.orgWorld Wide Web Consortiumylafon@w3.orggreenbytes GmbHjulian.reschke@greenbytes.deHTTP/1.1, part 6: CachingAdobe Systems Incorporatedfielding@gbiv.comAlcatel-Lucent Bell Labsjg@freedesktop.orgHewlett-Packard CompanyJeffMogul@acm.orgMicrosoft Corporationhenrikn@microsoft.comAdobe Systems IncorporatedLMM@acm.orgMicrosoft Corporationpaulle@microsoft.comWorld Wide Web Consortiumtimbl@w3.orgWorld Wide Web Consortiumylafon@w3.orgRackspacemnot@mnot.netgreenbytes GmbHjulian.reschke@greenbytes.deKey words for use in RFCs to Indicate Requirement LevelsHarvard Universitysob@harvard.eduAugmented BNF for Syntax Specifications: ABNFBrandenburg InternetWorkingdcrocker@bbiw.netTHUS plc.paul.overell@thus.netHypertext Transfer Protocol -- HTTP/1.1University of California, Irvinefielding@ics.uci.eduW3Cjg@w3.orgCompaq Computer Corporationmogul@wrl.dec.comMIT Laboratory for Computer Sciencefrystyk@w3.orgXerox Corporationmasinter@parc.xerox.comMicrosoft Corporationpaulle@microsoft.comW3Ctimbl@w3.orgHTTP Authentication: Basic and Digest Access AuthenticationNorthwestern University, Department of Mathematicsjohn@math.nwu.eduVerisign Inc.pbaker@verisign.comAbiSource, Inc.jeff@AbiSource.comAgranat Systems, Inc.lawrence@agranat.comMicrosoft Corporationpaulle@microsoft.comNetscape Communications CorporationOpen Market, Inc.stewart@OpenMarket.comRegistration Procedures for Message Header FieldsNine by NineGK-IETF@ninebynine.orgBEA Systemsmnot@pobox.comHP LabsJeffMogul@acm.orgUniform Resource Identifier (URI): Generic SyntaxWorld Wide Web Consortiumtimbl@w3.orghttp://www.w3.org/People/Berners-Lee/Day Softwarefielding@gbiv.comhttp://roy.gbiv.com/Adobe Systems IncorporatedLMM@acm.orghttp://larry.masinter.net/The Base16, Base32, and Base64 Data EncodingsGuidelines for Writing an IANA Considerations Section in RFCsIBMnarten@us.ibm.comGoogleHarald@Alvestrand.no
The "realm" parameter isn't required anymore in general; consequently, the
ABNF allows challenges without any auth parameters.
()
The "b64token" alternative to auth-param lists has been added for consistency
with legacy authentication schemes such as "Basic".
()
Change ABNF productions for header fields to only define the field value.
()
Extracted relevant partitions from .
Closed issues:
:
"Normative and Informative references"
Ongoing work on ABNF conversion ():
Explicitly import BNF rules for "challenge" and "credentials" from RFC2617.
Add explicit references to BNF syntax and rules imported from other parts of the specification.
Ongoing work on IANA Message Header Field Registration ():
Reference RFC 3984, and update header field registrations for header fields defined
in this document.
None.
Ongoing work on ABNF conversion ():
Use "/" instead of "|" for alternatives.
Introduce new ABNF rules for "bad" whitespace ("BWS"), optional
whitespace ("OWS") and required whitespace ("RWS").
Rewrite ABNFs to spell out whitespace rules, factor out
header field value format definitions.
Final work on ABNF conversion ():
Add appendix containing collected and expanded ABNF, reorganize ABNF introduction.
None.
Closed issues:
:
"move IANA registrations for optional status codes"
No significant changes.
Partly resolved issues:
:
"Term for the requested resource's URI"
None.
Closed issues:
:
"introduction to part 7 is work-in-progress"
:
"auth-param syntax"
:
"Header Classification"
:
"absorbing the auth framework from 2617"
Partly resolved issues:
:
"should we have an auth scheme registry"
None.
Closed issues:
:
"untangle ABNFs for header fields"
None.
Closed issues:
:
"Relationship between 401, Authorization and WWW-Authenticate"
:
"Realm required on challenges"
:
"auth-param syntax"
:
"Considerations for new authentications schemes"
:
"LWS in auth-param ABNF"
:
"credentials ABNF missing SP (still using implied LWS?)"
Closed issues:
:
"Document HTTP's error-handling philosophy"
:
"add advice on defining auth scheme parameters"
Closed issues:
:
"allow unquoted realm parameters"
:
"Repeating auth-params"