The HTTPWWW-Authenticateresponse header advertises theHTTP authentication methods (orchallenges) that might be used to gain access to a specific resource.

This header is part of theGeneral HTTP authentication framework, which can be used with a number ofauthentication schemes.Each challenge identifies a scheme supported by the server and additional parameters that are defined for that scheme type.

A server usingHTTP authentication will respond with a401 Unauthorized response to a request for a protected resource.This response must include at least oneWWW-Authenticate header and at least one challenge to indicate what authentication schemes can be used to access the resource and any additional data that each particular scheme needs.

Multiple challenges are allowed in oneWWW-Authenticate header, and multipleWWW-Authenticate headers are allowed in one response.A server may also include theWWW-Authenticate header in other response messages to indicate that supplying credentials might affect the response.

After receiving theWWW-Authenticate header, a client will typically prompt the user for credentials, and then re-request the resource.This new request uses theAuthorization header to supply the credentials to the server, encoded appropriately for the selected authentication method.The client is expected to select the most secure of the challenges it understands (note that in some cases the "most secure" method is debatable).

Syntax

WWW-Authenticate: <challenge>

Where a<challenge> is comprised of an<auth-scheme>, followed by an optional<token68> or a comma-separated list of<auth-params>:

challenge = <auth-scheme> <auth-param>, …, <auth-paramN>challenge = <auth-scheme> <token68>

For example:

WWW-Authenticate: <auth-scheme>WWW-Authenticate: <auth-scheme> token68WWW-Authenticate: <auth-scheme> auth-param1=param-token1WWW-Authenticate: <auth-scheme> auth-param1=param-token1, …, auth-paramN=param-tokenN

The presence of atoken68 or authentication parameters depends on the selected<auth-scheme>.For example,Basic authentication requires a<realm>, and allows for optional use ofcharset key, but does not support atoken68:

WWW-Authenticate: Basic realm="Dev", charset="UTF-8"

Multiple challenges can be sent in a comma-separated list

WWW-Authenticate: <challenge>, …, <challengeN>

Multiple headers can also be sent in a single response:

WWW-Authenticate: <challenge>WWW-Authenticate: <challengeN>

Directives

<auth-scheme>

A case-insensitive token indicating theAuthentication scheme used.Some of the more common types areBasic,Digest,Negotiate andAWS4-HMAC-SHA256.IANA maintains alist of authentication schemes, but there are other schemes offered by host services.

<auth-param>Optional

An authentication parameter whose format depends on the<auth-scheme>.<realm> is described below as it's a common authentication parameter among many auth schemes.

<realm>Optional

The stringrealm followed by= and a quoted string describing a protected area, for examplerealm="staging environment".A realm allows a server to partition the areas it protects (if supported by a scheme that allows such partitioning).Some clients show this value to the user to inform them about which particular credentials are required — though most browsers stopped doing so to counter phishing.The only reliably supported character set for this value isus-ascii.If no realm is specified, clients often display a formatted hostname instead.

<token68>Optional

A token that may be useful for some schemes.The token allows the 66 unreserved URI characters plus a few others.It can hold abase64, base64url, base32, or base16 (hex) encoding, with or without padding, but excluding whitespace.The token68 alternative to auth-param lists is supported for consistency with legacy authentication schemes.

Generally, you will need to check the relevant specifications for the authentication parameters needed for each<auth-scheme>.The following sections describe token and auth parameters for some common auth schemes.

Basic authentication directives

<realm>

A<realm> asdescribed above.Note that the realm is mandatory forBasic authentication.

charset="UTF-8"Optional

Tells the client the server's preferred encoding scheme when submitting a username and password.The only allowed value is the case-insensitive stringUTF-8.This does not relate to the encoding of the realm string.

Digest authentication directives

<realm>Optional

A<realm> asdescribed above indicating which username/password to use.Minimally should include the host name, but might indicate the users or group that have access.

domainOptional

A quoted, space-separated list of URI prefixes that define all the locations where the authentication information may be used.If this key is not specified then the authentication information may be used anywhere on the web root.

nonce

A server-specified quoted string that the server can use to control the lifetime in which particular credentials will be considered valid.This must be uniquely generated each time a 401 response is made, and may be regenerated more often (for example, allowing a digest to be used only once).The specification contains advice on possible algorithms for generating this value.Thenonce value is opaque to the client.

opaque

A server-specified quoted string that should be returned unchanged in theAuthorization.This is opaque to the client. The server is recommended to include Base64 or hexadecimal data.

staleOptional

A case-insensitive flag indicating that the previous request from the client was rejected because thenonce used is too old (stale).If this istrue the request can be retried using the same username/password encrypted using the newnonce.If it is any other value then the username/password are invalid and must be re-requested from the user.

algorithmOptional

A string indicating the algorithm used to produce a digest.Valid non-session values are:MD5 (default ifalgorithm not specified),SHA-256,SHA-512.Valid session values are:MD5-sess,SHA-256-sess,SHA-512-sess.

qop

Quoted string indicating the quality of protection supported by the server. This must be supplied, and unrecognized options must be ignored.

• "auth": Authentication
• "auth-int": Authentication with integrity protection

charset="UTF-8"Optional

Tells the client the server's preferred encoding scheme when submitting a username and password.The only allowed value is the case-insensitive string "UTF-8".

userhashOptional

A server may specify"true" to indicate that it supports username hashing (default is"false")

HTTP Origin-Bound Authentication (HOBA)

<challenge>

A set of pairs in the format of<len>:<value> concatenated together to be given to a client.The challenge is made of up a nonce, algorithm, origin, realm, key identifier, and the challenge.

<max-age>

The number of seconds from the time the HTTP response is emitted for which responses to this challenge can be accepted.

<realm>Optional

As above in thedirectives section.

Examples

Issuing multiple authentication challenges

Multiple challenges may be specified in a single response header:

HTTP/1.1 401 UnauthorizedWWW-Authenticate: challenge1, …, challengeN

Multiple challenges can be sent in separateWWW-Authenticate headers in the same response:

HTTP/1.1 401 UnauthorizedWWW-Authenticate: challenge1WWW-Authenticate: challengeN

Basic authentication

A server that only supports basic authentication might have aWWW-Authenticate response header which looks like this:

HTTP/1.1 401 UnauthorizedWWW-Authenticate: Basic realm="Staging server", charset="UTF-8"

A user-agent receiving this header would first prompt the user for their username and password, and then re-request the resource with the encoded credentials in theAuthorization header.TheAuthorization header might look like this:

Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l

ForBasic authentication, the credentials are constructed by first combining the username and the password with a colon (aladdin:opensesame), and then by encoding the resulting string inbase64 (YWxhZGRpbjpvcGVuc2VzYW1l).

Digest authentication with SHA-256 and MD5

The client attempts to access a document at URIhttp://www.example.org/dir/index.html that is protected via digest authentication.The username for this document is "Mufasa" and the password is "Circle of Life" (note the single space between each of the words).

The first time the client requests the document, noAuthorization header field is sent.Here the server responds with an HTTP 401 message that includes a challenge for each digest algorithm it supports, in its order of preference (SHA256 and thenMD5)

HTTP/1.1 401 UnauthorizedWWW-Authenticate: Digest    realm="http-auth@example.org",    qop="auth, auth-int",    algorithm=SHA-256,    nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",    opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"WWW-Authenticate: Digest    realm="http-auth@example.org",    qop="auth, auth-int",    algorithm=MD5,    nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",    opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"

The client prompts the user for their username and password, and then responds with a new request that encodes the credentials in theAuthorization header field.If the client chose the MD5 digest theAuthorization header field might look as shown below:

Authorization: Digest username="Mufasa",    realm="http-auth@example.org",    uri="/dir/index.html",    algorithm=MD5,    nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",    nc=00000001,    cnonce="f2/wE4q74E6zIJEtWaHKaf5wv/H5QzzpXusqGemxURZJ",    qop=auth,    response="8ca523f5e9506fed4657c9700eebdbec",    opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"

If the client chose the SHA-256 digest theAuthorization header field might look as shown below:

Authorization: Digest username="Mufasa",    realm="http-auth@example.org",    uri="/dir/index.html",    algorithm=SHA-256,    nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v",    nc=00000001,    cnonce="f2/wE4q74E6zIJEtWaHKaf5wv/H5QzzpXusqGemxURZJ",    qop=auth,    response="753927fa0e85d155564e2e272a28d1802ca10daf449        6794697cf8db5856cb6c1",    opaque="FQhe/qaU925kfnzjCev0ciny7QMkPqMAFRtzCUYo5tdS"

HOBA Authentication

A server that supports HOBA authentication might have aWWW-Authenticate response header which looks like this:

HTTP/1.1 401 UnauthorizedWWW-Authenticate: HOBA max-age="180", challenge="16:MTEyMzEyMzEyMw==1:028:https://www.example.com:8080:3:MTI48:NjgxNDdjOTctNDYxYi00MzEwLWJlOWItNGM3MDcyMzdhYjUz"

The to-be-signed blob challenge is made from these parts:www.example.com using port 8080, the nonce is1123123123, the algorithm for signing is RSA-SHA256, the key identifier is123, and finally the challenge is68147c97-461b-4310-be9b-4c707237ab53.

A client would receive this header, extract the challenge, sign it with their private key that corresponds to key identifier 123 in our example using RSA-SHA256, and then send the result in theAuthorization header as a dot-separated key id, challenge, nonce, and signature.

Authorization: 123.16:MTEyMzEyMzEyMw==1:028:https://www.example.com:8080:3:MTI48:NjgxNDdjOTctNDYxYi00MzEwLWJlOWItNGM3MDcyMzdhYjUz.1123123123.<signature-of-challenge>

Specifications

Browser compatibility

See also

• HTTP authentication
• Authorization
• Proxy-Authorization
• Proxy-Authenticate
• 401,403,407