Hypertext Transfer Protocol (HTTP/1.1): Authentication
Extracted elements (28)
New authentication scheme definitions should prefer a "must-ignore" rule over a "must-understand" rule for unknown extension parameters, because otherwise it will be hard to introduce new parameters in the presence of legacy recipients.
The token68 notation was introduced for compatibility with existing authentication schemes (such as Basic) that use a single base64-encoded value. New schemes ought to use auth-param syntax instead, because token68 can only be used once per challenge or credential, making future extensions impossible if used.
Many clients fail to parse a challenge that contains an unknown authentication scheme. A workaround is to list well-supported schemes (such as "basic") first in WWW-Authenticate responses.
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 use of Cache-Control directives (e.g., "no-store" or "private"), since Authorization credentials automatically have the effect of the "private" Cache-Control directive.
A proxy forwarding a request MUST NOT modify any Authorization fields in that request.
A proxy forwarding a response MUST NOT modify any WWW-Authenticate fields in that response.
For the realm parameter, 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.
HTTP authentication is presumed to be stateless: all information necessary to authenticate a request MUST be provided in the request itself, rather than depending on the server remembering prior requests. Authentication bound to the underlying connection is outside this specification's scope.
New authentication schemes MUST NOT use the reserved "realm" parameter in a way incompatible with its definition as a protection space indicator in Section 2.2.
The proxy MUST send a Proxy-Authenticate header field containing a challenge applicable to that proxy in each 407 (Proxy Authentication Required) response. The client MAY repeat the request with a new or replaced Proxy-Authorization header field.
The server generating a 401 response MUST send a WWW-Authenticate header field containing at least one challenge applicable to the target resource.
Upon receipt of a request for a protected resource that omits credentials, contains invalid credentials, or partial credentials, an origin server SHOULD send a 401 (Unauthorized) response containing a WWW-Authenticate header field with at least one applicable challenge.
Upon receipt of a request that omits or contains invalid proxy credentials, a proxy that requires authentication SHOULD generate a 407 (Proxy Authentication Required) response containing a Proxy-Authenticate header field with at least one applicable challenge.
A protection space is defined by the canonical root URI (scheme and authority components of the effective request URI) combined with the realm value if present. Realms allow partitioning protected resources into sets with their own authentication scheme and/or authorization database.
HTTP authentication uses a challenge-response framework with a case-insensitive auth-scheme token followed by either a comma-separated list of auth-param name=value pairs or a single token68 value. Authentication parameters are name=value pairs where parameter names are matched case-insensitively and each name MUST only occur once per challenge.
The 401 (Unauthorized) status code indicates the request lacks valid authentication credentials for the target resource. If the request included credentials, 401 indicates those credentials were refused. The user agent MAY repeat the request with a new or replaced Authorization header field.
The Authorization header field allows a user agent to authenticate itself with an origin server. ABNF: Authorization = credentials. If a request is authenticated and a realm specified, the same credentials are presumed valid for all other requests within that realm.
The Proxy-Authenticate header field consists of at least one challenge indicating authentication scheme(s) and parameters applicable to the proxy. Unlike WWW-Authenticate, it applies only to the next outbound client on the response chain. ABNF: Proxy-Authenticate = 1#challenge.
The Proxy-Authorization header field allows the client to identify itself to a proxy. Unlike Authorization, it applies only to the next inbound proxy that demanded authentication using Proxy-Authenticate, and is consumed by the first inbound proxy expecting credentials. A proxy MAY relay credentials to the next proxy.
The WWW-Authenticate header field indicates the authentication scheme(s) and parameters applicable to the target resource. ABNF: WWW-Authenticate = 1#challenge. It can contain multiple challenges, each with a comma-separated list of authentication parameters, and the header field itself can occur multiple times.
The HTTP Status Code Registry has been updated to register 401 (Unauthorized) and 407 (Proxy Authentication Required) as defined in this document.
The Permanent Message Header Field Names registry has been updated to register Authorization, Proxy-Authenticate, Proxy-Authorization, and WWW-Authenticate as standard HTTP header fields.
This document establishes the "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry" defining the namespace for authentication schemes in challenges and credentials. New values require IETF Review. Registrations must include Authentication Scheme Name, pointer to specification text, and optional notes.
Authentication schemes relying solely on the realm mechanism expose credentials to all resources on an origin server, allowing one resource to harvest credentials meant for another. Mitigations include restricting direct access to Authorization header content and separating protection spaces by using different host names or port numbers per party.
Existing HTTP clients typically retain authentication information indefinitely, and HTTP provides no mechanism for servers to direct clients to discard cached credentials. User agents that cache credentials are encouraged to provide a readily accessible mechanism for discarding them under user control.
The HTTP authentication framework does not define a mechanism for maintaining confidentiality of credentials; each scheme defines its own encoding. HTTP depends on the security properties of the underlying transport-level connection (e.g., TLS) for confidential transmission of credentials. Services requiring individual user authentication often require a TLS-secured connection prior to exchanging credentials.
A challenge is defined as: challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ]. Credentials follow the same structure: credentials = auth-scheme [ 1*SP ( token68 / #auth-param ) ].
The token68 syntax allows the 66 unreserved URI characters plus a few others, enabling base64, base64url, base32, or base16 encodings with or without padding but excluding whitespace. ABNF: token68 = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) *"=".