HTTP Headers
WWW Authenticate
HTTP Header
The HTTP WWW-Authenticate response header is used to advertise the authentication methods, or challenges, that a server supports for accessing a particular resource.
This header is a component of the broader General HTTP authentication framework, which accommodates various authentication schemes. Each challenge specifies a supported scheme and includes additional parameters relevant to that scheme.
A server employing HTTP authentication responds with a 401 Unauthorized status code when a request targets a protected resource. This response must contain at least one WWW-Authenticate header along with at least one challenge, detailing the authentication schemes available and any extra data those schemes require.
It is permissible to include multiple challenges within a single WWW-Authenticate header, or to send multiple such headers in one response. Additionally, servers may include the WWW-Authenticate header in other response messages to indicate that providing credentials could influence the response outcome.
Upon receiving the WWW-Authenticate header, a client typically prompts the user to enter credentials and then reissues the request. The new request includes an Authorization header, which supplies the credentials encoded appropriately according to the selected authentication method. The client should choose the most secure authentication challenge it supports, noting that in some cases, determining the most secure method can be subjective.
Syntax
The WWW-Authenticate header indicates the authentication challenge sent by the server. It includes an authentication scheme, optionally followed by a token or a list of authentication parameters.
The structure of a challenge is as follows:
challenge = <auth-scheme> <auth-param>, …, <auth-paramN>
challenge = <auth-scheme> <token68>Examples of challenges include:
WWW-Authenticate: <auth-scheme>
WWW-Authenticate: <auth-scheme> token68
WWW-Authenticate: <auth-scheme> auth-param1=param-token1
WWW-Authenticate: <auth-scheme> auth-param1=param-token1, …, auth-paramN=param-tokenN
Whether a token68 or authentication parameters are used depends on the specific authentication scheme. For instance, Basic authentication requires a realm and may optionally specify a charset, but does not support a token68:
<WWW-Authenticate: Basic realm="Dev", charset="UTF-8">Multiple challenges can be sent within a comma-separated list:
<WWW-Authenticate: challenge1, …, challengeN>Alternatively, multiple headers can be included in a single response:
<WWW-Authenticate: challenge1>
<WWW-Authenticate: challengeN>Directives
<auth-scheme>- A case-insensitive value indicating the authentication method used. Common types include Basic, Digest, Negotiate, and AWS4-HMAC-SHA256. IANA maintains a list of authentication schemes, but other services may offer their own.
<auth-param>Optional- A parameter for the authentication scheme. Its format depends on the specific
<auth-scheme>. The<realm>parameter is common to many schemes and is described below.<realm>Optional- The string realm followed by = and a quoted string that identifies a protected area, like realm=”staging environment”. A realm allows a server to divide its protected areas. Some clients might display this to the user to indicate which credentials are needed, though most browsers no longer do this to prevent phishing. Only the us-ascii character set is reliably supported for this value. If no realm is given, clients often show a formatted hostname instead.
<token68>Optional- A token used by some authentication schemes. This token can contain Base64, Base64url, Base32, or Base16 (hex) encoded data, with or without padding, but without whitespace. The token68 format is included for compatibility with older authentication schemes.
Typically, you’ll need to refer to the specific documentation for each <auth-scheme> to determine the required authentication parameters. The following sections outline parameters and tokens for some widely used authentication schemes.
Basic authentication directives:
<realm>A
<realm>as explained earlier. Note that the realm is required for Basic authentication.charset="UTF-8"OptionalIndicates to the client the server’s preferred encoding for sending a username and password. The only acceptable value is the case-insensitive string UTF-8. This does not affect the encoding of the realm string.
Digest authentication parameters:
<realm>Optional- A
<realm>as mentioned above, indicating which username and password pair to use. At a minimum, it should include the hostname, but it might also specify the users or groups that have access. domainOptional- A quoted, space-separated list of URI prefixes where the authentication information can be applied. If this is not provided, the authentication information can be used anywhere within the web root.
nonce- A quoted string provided by the server that controls how long specific credentials are considered valid. This string must be unique for each 401 response and might be generated more frequently (e.g., allowing a digest to be used only once). The specification offers guidance on algorithms for creating this value. The nonce value is not interpretable by the client.
opaque- A quoted string provided by the server that the client should return without modification in the Authorization header. This value is not interpretable by the client. The server is advised to include Base64 or hexadecimal data.
staleOptional- A case-insensitive flag indicating that the client’s previous request was rejected because the nonce used was too old (stale). If this is true, the request can be attempted again using the same username and password, encrypted with the new nonce. If it’s any other value, the username or password is not valid and must be requested from the user again.
algorithmOptional- A string specifying the algorithm used to generate a digest. Valid non-session values are: MD5 (the default if algorithm is not specified), SHA-256, SHA-512. Valid session values are: MD5-sess, SHA-256-sess, SHA-512-sess.
qop- A quoted string indicating the level of protection the server supports. This must be provided, and any options that are not recognized should be ignored.
- “auth”: Authentication only
- “auth-int”: Authentication with integrity protection
charset="UTF-8"Optional- Informs the client of the server’s preferred encoding for usernames and passwords. The only accepted value is the case-insensitive string “UTF-8”.
userhashOptional- A server can specify “true” to indicate that it supports hashing of usernames (the default is “false”).
HTTP Origin-Bound Authentication (HOBA) parameters:
<challenge>- A series of pairs in the format of <len>:<value> concatenated together, provided to the client. This challenge consists of a nonce, algorithm, origin, realm, key identifier, and the challenge itself.
<max-age>- The duration in seconds, starting from when the HTTP response is sent, during which responses to this challenge will be accepted.
<realm>Optional- As described in the directives section above.
Example
Issuing multiple authentication challenges
Multiple challenges can be included in a single response header:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: challenge1, …, challengeN
Or, challenges can be sent in separate headers within the same response:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: challenge1
WWW-Authenticate: challengeN
Basic authentication
A server supporting only basic authentication may send a header like this:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Staging server", charset="UTF-8"
Clients receiving this prompt the user for credentials and then re-request the resource with the encoded credentials in the Authorization header:
Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
Credentials are formed by combining username and password with a colon (username:password) and encoding the string in base64 (e.g., YWxhZGRpbjpvcGVuc2VzYW1l).
Digest authentication with SHA-256 and MD5
Note: This example is derived from RFC 7616 “HTTP Digest Access Authentication”. Other examples in the RFC include SHA-512, charset, and userhash.
The client tries to access a protected document at http://www.example.org/dir/index.html. The username is “Mufasa” and the password is “Circle of Life”. On the initial request, no Authorization header is present. The server responds with a 401 status and challenges the client with supported digest algorithms, like SHA-256 and MD5:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Digest
realm="[email protected]",
qop="auth, auth-int",
algorithm=SHA-256,
nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",
opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"
WWW-Authenticate: Digest
realm="[email protected]",
qop="auth, auth-int",
algorithm=MD5,
nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",
opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"
The client prompts the user for credentials and responds with a new request containing the encoded authorization info. For MD
How to Modify Header using Requestly
Requestly is a powerful Chrome extension that allows you to modify HTTP headers, including the WWW-Authenticate header. This is especially useful for testing authentication flows and troubleshooting issues related to server challenges. Steps to Modify the WWW-Authenticate Header:
- Install and open the Requestly Chrome extension. You can find it on the Chrome Web Store.
- Create a new rule: Click on “Create Rule” and choose “Modify Headers” from the list of available rule types.
- Add a new header modification:
- Under “Action”, select “Add” or “Override”.
- In the “Header Name” field, enter WWW-Authenticate.
- In the “Header Value” field, enter the desired authentication challenge value (e.g., Basic realm=”User Visible Realm”).
- Set the URL condition: Specify the URL or pattern where this header change should apply (e.g., https://your-api.com/*).
- Save the rule.
Using Requestly to modify the WWW-Authenticate header lets you test different authentication scenarios without changing server configurations. This helps you troubleshoot login issues and verify how your app handles authentication challenges.
Table of Contents
- No headings found.
