Hypertext Transfer Protocol (HTTP): AuthenticationAdobe Systems Incorporated345 Park AveSan JoseCA95110USAfielding@gbiv.comhttp://roy.gbiv.com/greenbytes GmbHHafenweg 16MuensterNW48155Germanyjulian.reschke@greenbytes.dehttp://greenbytes.de/tech/webdav/
Applications and Real-Time
Hypertext Transfer ProtocolHTTPHTTP authentication
The Hypertext Transfer Protocol (HTTP) is a stateless application-level
protocol for distributed, collaborative, hypermedia information systems.
This document defines the HTTP Authentication framework.
This document obsoletes RFC 7235.
This note is to be removed before publishing as an RFC.This is a temporary document for the purpose of planning the revisions of RFCs 7230 to 7235. This is not yet
an official work item of the HTTP Working Group.
Discussion of this draft takes place on the HTTP working group
mailing list (ietf-http-wg@w3.org), which is archived at
.
Errata for RFC 7235 have been collected at
,
and an additional issues list lives at
.
The changes in this draft are summarized in .
HTTP provides a general framework for access control and authentication,
via an extensible set of challenge-response authentication schemes, which
can be used by a server to challenge a client request and by a client to
provide authentication information. This document defines HTTP/1.1
authentication in terms of the architecture defined in
"Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing"
.
The IANA Authentication Scheme Registry
() lists registered
authentication schemes and their corresponding specifications.
This specification obsoletes RFC 7235,
with the changes being summarized in .
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 .
Conformance criteria and considerations regarding error handling
are defined in Section 2.5 of .
This specification uses the Augmented Backus-Naur Form (ABNF) notation of
with a list extension, defined in
Section 7 of , that allows for compact definition of
comma-separated lists using a '#' operator (similar to how the '*' operator
indicates repetition).
describes rules imported from
other documents.
shows the collected grammar with all list
operators expanded to standard ABNF notation.
HTTP provides a simple challenge-response authentication framework
that can be used by a server to challenge a client request and by a
client to provide authentication information. It uses a case-insensitive
token as a means to identify the authentication scheme, followed
by additional information necessary for achieving authentication via that
scheme. The latter can be either a comma-separated list of parameters or a
single sequence of characters capable of holding base64-encoded
information.
Authentication parameters are name=value pairs, where the name token is
matched case-insensitively,
and each parameter name MUST only occur once per challenge.
The token68 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
().
A 401 (Unauthorized) response message is used by an origin
server to challenge the authorization of a user agent, including a
WWW-Authenticate header field containing at least one
challenge applicable to the requested resource.
A 407 (Proxy Authentication Required) response message is
used by a proxy to challenge the authorization of a client, including a
Proxy-Authenticate header field containing at least one
challenge applicable to the proxy for the requested resource.
Note: Many clients fail to parse a challenge that contains an unknown
scheme. 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) — can 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) — can do so by
including a Proxy-Authorization header field with the
request.
Both the Authorization field value and the
Proxy-Authorization field value contain the client's
credentials for the realm of the resource being requested, based upon a
challenge received in a response (possibly at some point in the past).
When creating their values, the user agent ought to do so by selecting the
challenge with what it considers to be the most secure auth-scheme that it
understands, obtaining credentials from the user as appropriate.
Transmission of credentials within header field values implies significant
security considerations regarding the confidentiality of the underlying
connection, as described in
.
Upon receipt of a request for a protected resource that omits credentials,
contains invalid credentials (e.g., a bad password) or partial credentials
(e.g., when the authentication scheme requires more than one round trip),
an origin server SHOULD send a 401 (Unauthorized) response
that contains a WWW-Authenticate header field with at least
one (possibly new) challenge applicable to the requested resource.
Likewise, upon receipt of a request that omits proxy credentials or
contains invalid or partial proxy credentials, a proxy that requires
authentication SHOULD generate a
407 (Proxy Authentication Required) response that contains
a Proxy-Authenticate header field with at least one
(possibly new) challenge applicable to the proxy.
A server that receives valid credentials that are not adequate to gain
access ought to respond with the 403 (Forbidden) status
code (Section 6.5.3 of ).
HTTP does not restrict applications to this simple challenge-response
framework for access authentication. Additional mechanisms can be used,
such as authentication 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.
The "realm" authentication parameter is reserved for use by
authentication schemes that wish to indicate a 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 5.5 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, that can have
additional semantics specific to the authentication scheme. Note that a
response can have multiple challenges with the same auth-scheme but
with different realms.
The protection space determines the domain over which credentials can
be automatically applied. If a prior request has been authorized, the
user agent MAY reuse the same credentials for all other requests within
that protection space for a period of time determined by the authentication
scheme, parameters, and/or user preferences (such as a configurable
inactivity timeout). Unless specifically allowed by the authentication
scheme, a single protection space cannot extend outside the scope of its
server.
For historical reasons, a sender MUST only generate 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 401 (Unauthorized) status code indicates that the
request has not been applied because it lacks valid authentication
credentials for the target resource.
The server generating a 401 response MUST send a
WWW-Authenticate header field
()
containing at least one challenge applicable to the target resource.
If the request included authentication credentials, then the 401 response
indicates that authorization has been refused for those credentials.
The user agent MAY repeat the request with a new or replaced
Authorization header field ().
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 agent SHOULD present the enclosed representation to the user, since
it usually contains relevant diagnostic information.
The 407 (Proxy Authentication Required) status code is
similar to 401 (Unauthorized), but it indicates that the client
needs to authenticate itself in order to use a proxy.
The proxy MUST send a Proxy-Authenticate header field
() containing a challenge
applicable to that proxy for the target resource. The client MAY repeat
the request with a new or replaced Proxy-Authorization
header field ().
This section defines the syntax and semantics of header fields related to
the HTTP authentication framework.
The "WWW-Authenticate" header field indicates the authentication scheme(s)
and parameters applicable to the target resource.
A server generating a 401 (Unauthorized) response
MUST send a WWW-Authenticate header field containing at least one
challenge. A server MAY generate a WWW-Authenticate header field
in other response messages to indicate that supplying credentials
(or different credentials) might affect the response.
A proxy forwarding a response MUST NOT modify any
WWW-Authenticate fields in that response.
User agents are advised to take special care in parsing the field value, as
it might contain more than one challenge, and each challenge can contain a
comma-separated list of authentication parameters. Furthermore, the header
field itself can occur multiple times.
Note: The challenge grammar production uses the list syntax as
well. Therefore, a sequence of comma, whitespace, and comma can be
considered either as applying to the preceding challenge, or to be an
empty entry in the list of challenges. In practice, this ambiguity
does not affect the semantics of the header field value and thus is
harmless.
The "Authorization" header field allows a user agent to authenticate itself
with an origin server — usually, but not necessarily, after receiving
a 401 (Unauthorized) response. Its value consists of
credentials containing the authentication 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
are presumed to 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).
A proxy forwarding a request MUST NOT modify any
Authorization fields in that request.
See Section 3.2 of for details of and requirements
pertaining to handling of the Authorization field by HTTP caches.
The "Proxy-Authenticate" header field consists of at least one
challenge that indicates the authentication scheme(s) and parameters
applicable to the proxy for this effective request URI
(Section 5.5 of ).
A proxy MUST send at least one Proxy-Authenticate header field in
each 407 (Proxy Authentication Required) response that it
generates.
Unlike WWW-Authenticate, the Proxy-Authenticate header field
applies only to the next outbound client on the response chain.
This is because only the client that chose a given proxy is likely to have
the credentials necessary for authentication. However, when multiple
proxies are used within the same administrative domain, such as office and
regional caching proxies within a large corporate network, it is common
for credentials to be generated by the user agent and passed through the
hierarchy until consumed. Hence, in such a configuration, it will appear
as if Proxy-Authenticate is being forwarded because each proxy will send
the same challenge set.
Note that the parsing considerations for WWW-Authenticate
apply to this header field as well; see
for details.
The "Proxy-Authorization" header field allows the client to
identify itself (or its user) to a proxy that requires
authentication. Its value consists of credentials containing the
authentication information of the client for the proxy and/or realm of the
resource being requested.
Unlike Authorization, the Proxy-Authorization header field
applies only to the next inbound 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
inbound 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 "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry" defines the namespace for the
authentication schemes in challenges and credentials. It has been created
and is now maintained at .
Registrations MUST include the following fields:
Authentication Scheme NamePointer to specification textNotes (optional)
Values to be added to this namespace require IETF Review
(see , Section 4.1).
There are certain aspects of the HTTP Authentication Framework that put
constraints on how new authentication schemes can work:
HTTP authentication is presumed to be stateless: all of the information
necessary to authenticate a request MUST be provided in the request,
rather than be dependent on the server remembering prior requests.
Authentication based on, or bound to, the underlying connection is
outside the scope of this specification and inherently flawed unless
steps are taken to ensure that the connection cannot be used by any
party other than the authenticated user
(see Section 2.3 of ).
The authentication parameter "realm" is reserved for defining protection
spaces as described in . New schemes
MUST NOT use it in a way incompatible with that definition.
The "token68" notation was introduced for compatibility with existing
authentication schemes and can only be used once per challenge or credential.
Thus, new schemes 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.
Definitions of new schemes ought to define the treatment of unknown
extension parameters. In general, a "must-ignore" rule is preferable
to a "must-understand" rule, because otherwise it will be hard to introduce
new parameters in the presence of legacy recipients. Furthermore,
it's good to describe the policy for defining new parameters (such
as "update the specification" or "use this registry").
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 (Section 5.2.2.6 of ),
within the scope of the request in which they appear.
Therefore, new authentication schemes that choose not to carry
credentials in the Authorization header field (e.g., using a newly defined
header field) will need to explicitly disallow caching, by mandating the use of
either Cache-Control request directives (e.g., "no-store",
Section 5.2.1.5 of ) or response directives (e.g., "private").
The "Hypertext Transfer Protocol (HTTP) Status Code Registry" located at
has been updated with the registrations below:
ValueDescriptionReference401Unauthorized407Proxy Authentication Required
HTTP header fields are registered within the "Message Headers" registry
maintained at
.
This document defines the following HTTP header fields, so the
"Permanent Message Header Field Names" registry has been updated
accordingly (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 developers, information providers, and
users of known security concerns specific to HTTP authentication.
More general security considerations are addressed in HTTP messaging
and semantics .
Everything about the topic of HTTP authentication is a security
consideration, so the list of considerations below is not exhaustive.
Furthermore, it is limited to security considerations regarding the
authentication framework, in general, rather than discussing all of the
potential considerations for specific authentication schemes (which ought
to be documented in the specifications that define those schemes).
Various organizations maintain topical information and links to current
research on Web application security (e.g., ),
including common pitfalls for implementing and using the authentication
schemes found in practice.
The HTTP authentication framework does not define a single mechanism for
maintaining the confidentiality of credentials; instead, each
authentication scheme defines how the credentials are encoded prior to
transmission. While this provides flexibility for the development of future
authentication schemes, it is inadequate for the protection of existing
schemes that provide no confidentiality on their own, or that do not
sufficiently protect against replay attacks. Furthermore, if the server
expects credentials that are specific to each individual user, the exchange
of those credentials will have the effect of identifying that user even if
the content within credentials remains confidential.
HTTP depends on the security properties of the underlying transport- or
session-level connection to provide confidential transmission of header
fields. In other words, if a server limits access to authenticated users
using this framework, the server needs to ensure that the connection is
properly secured in accordance with the nature of the authentication
scheme used. For example, services that depend on individual user
authentication often require a connection to be secured with TLS
("Transport Layer Security", ) prior to exchanging
any credentials.
Existing HTTP clients and user agents typically retain authentication
information indefinitely. HTTP does not provide a mechanism for the
origin server to direct clients to discard these cached credentials, since
the protocol has no awareness of how credentials are obtained or managed
by the user agent. The mechanisms for expiring or revoking credentials can
be specified as part of an authentication scheme definition.
Circumstances under which credential caching can interfere with the
application's security model include but are not limited to:
Clients that have been idle for an extended period, following
which the server might wish to cause the client to re-prompt the
user for credentials.Applications that 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.
User agents that cache credentials are encouraged to provide a readily
accessible mechanism for discarding cached credentials under user control.
Authentication schemes that solely rely on the "realm" mechanism for
establishing a protection space will expose credentials to all resources on
an origin server. Clients that have successfully made authenticated requests
with a resource can use the same authentication credentials for other
resources on the same origin server. This makes it possible for a different
resource to harvest authentication credentials for other resources.
This is of particular concern when an origin server hosts resources for multiple
parties under the same canonical root URI ().
Possible mitigation strategies include restricting direct access to
authentication credentials (i.e., not making the content of the
Authorization request header field available), and separating protection
spaces by using a different host name (or port number) for each party.
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and RoutingAdobe Systems Incorporatedfielding@gbiv.comgreenbytes GmbHjulian.reschke@greenbytes.deHypertext Transfer Protocol (HTTP): Semantics and ContentAdobe Systems Incorporatedfielding@gbiv.comgreenbytes GmbHjulian.reschke@greenbytes.deHypertext Transfer Protocol (HTTP): CachingAdobe Systems Incorporatedfielding@gbiv.comFastlymnot@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.netHTTP 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.comHypertext Transfer Protocol (HTTP/1.1): AuthenticationAdobe Systems Incorporatedfielding@gbiv.comgreenbytes GmbHjulian.reschke@greenbytes.deRegistration 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.noA Guide to Building Secure Web Applications and Web ServicesThe Transport Layer Security (TLS) Protocol Version 1.2RTFM, Inc.
None yet.
The following core rules are included by
reference, as defined in Appendix B.1 of :
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 rules below are defined in :
In the collected ABNF below, list rules are expanded as per Section 1.2 of .
This section is to be removed before publishing as an RFC.
The changes in this draft are purely editorial:
Change boilerplate and abstract to indicate the "draft" status, and update references to ancestor specifications.Remove version "1.1" from document title, indicating that this specification applies to all HTTP versions.Adjust historical notes.Update links to sibling specifications.Replace sections listing changes from RFC 2617 by new empty sections referring to RFC 723x.Remove acknowledgements specific to RFC 723x.Move "Acknowledgements" to the very end and make them unnumbered.
The previous specification took 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 Appendix "Acknowledgments" of for the Acknowledgments related to this document revision.