1. Access Authentication
1.1 Reliance on the HTTP/1.1 Specification
This specification is a companion to the HTTP/1.1 specification [2]. It uses the augmented BNF section 2.1 of that document, and relies on both the non-terminals defined in that document and on other aspects of the HTTP/1.1 specification.
1.2 Access Authentication Framework
HTTP provides a simple challenge-response authentication mechanism (Challenge-Response Authentication Mechanism) that a server MAY use to challenge a client request, and the client MAY use to provide authentication information. It uses an extensible, case-insensitive token (Token) to identify the authentication scheme (Authentication Scheme), followed by a comma-separated list of attribute-value pairs which carry the parameters necessary for achieving authentication via that scheme.
auth-scheme = token
auth-param = token "=" ( token | quoted-string )
The origin server (Origin Server) uses a 401 (Unauthorized) response message to challenge the user agent's authorization. This response MUST include a WWW-Authenticate header field containing at least one challenge applicable to the requested resource. A proxy (Proxy) uses a 407 (Proxy Authentication Required) response message to challenge the client's authorization, and MUST include a Proxy-Authenticate header field containing at least one challenge applicable to the requested resource.
challenge = auth-scheme 1*SP 1#auth-param
Note: If the WWW-Authenticate or Proxy-Authenticate header field value contains multiple challenges, or if multiple WWW-Authenticate header fields are provided, the user agent must take special care when parsing, as the content of the challenge itself may contain a comma-separated list of authentication parameters.
The authentication parameter realm is defined for all authentication schemes:
realm = "realm" "=" realm-value
realm-value = quoted-string
The realm directive (case-insensitive) is REQUIRED for all authentication schemes that issue a challenge. The realm value (case-sensitive), in combination with the canonical root URL (the absoluteURI for the server whose abs_path is empty; see section 5.1.2 of [2]) of the server being accessed, defines the protection space (Protection Space). 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 may have additional semantics specific to the authentication scheme. Please note that there may be multiple challenges with the same auth-scheme but different realms.
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 (Credentials), containing the authentication information of the client for the realm of the resource being requested. The user agent MUST choose to use the challenge with the strongest auth-scheme it understands and request credentials from the user based upon that challenge.
credentials = auth-scheme #auth-param
Note: Many browsers only recognize Basic authentication and require it to be the first auth-scheme presented. Servers should only include Basic authentication when it is the minimum acceptable standard.
The protection space determines the domain in which credentials can be automatically applied. If a previous 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 beyond its server.
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 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 transport layer encryption or via message encapsulation, and with additional header fields specifying authentication information. However, these additional mechanisms are not defined by this specification.
Proxies MUST be completely transparent regarding user agent authentication with the origin server. That is, they must forward the WWW-Authenticate and Authorization headers unchanged, and follow the rules in section 14.8 of [2]. Both Proxy-Authenticate and Proxy-Authorization header fields are hop-by-hop headers (Hop-by-Hop Headers) (see section 13.5.1 of [2]).