WWW-Authenticate

Description

The WWW-Authenticate response header indicates the authentication scheme(s) and parameters applicable to the target resource. This header is included in 401 Unauthorized response messages, informing the client about the authentication mechanisms the server accepts for accessing the requested resource.

When a client makes a request for a protected resource without providing valid credentials, the server responds with a 401 Unauthorized status code and includes the WWW-Authenticate header to tell the client how to authenticate properly. The client can then use this information to formulate a new request with appropriate authentication credentials using the Authorization request header.

Common authentication schemes specified in this header include: - Basic: Simple username and password authentication - Digest: A more secure alternative to Basic authentication - Bearer: Token-based authentication, commonly used with OAuth 2.0 - NTLM: Windows-based challenge-response authentication - Negotiate: Allows the client to choose between multiple authentication mechanisms

Syntax

The syntax of the WWW-Authenticate header follows this structure:

WWW-Authenticate: <auth-scheme> [<auth-param>]

<auth-scheme>: The authentication scheme (e.g., Basic, Digest, Bearer).
<auth-param>: Parameters for the authentication scheme, typically in key=value format.
Multiple authentication schemes can be provided, each as a separate WWW-Authenticate header.

Example Syntax

WWW-Authenticate: Basic realm="Access to the staging site"

This example specifies Basic authentication with a realm named "Access to the staging site".

WWW-Authenticate: Bearer realm="example"

This example specifies Bearer token authentication with a realm named "example".

Examples

Basic Authentication Example

A response requesting Basic authentication:

HTTP/1.1 401 Unauthorized
Date: Tue, 03 Jun 2025 00:00:00 GMT
Content-Type: text/html; charset=UTF-8
WWW-Authenticate: Basic realm="User Visible Realm", charset="UTF-8"
Content-Length: 345

<!DOCTYPE html>
<html>
<head><title>Authentication Required</title></head>
<body>
  <h1>Authentication Required</h1>
  <p>This server could not verify that you are authorized to access the document requested. 
  Either you supplied the wrong credentials (e.g., bad password), or your browser doesn't
  understand how to supply the credentials required.</p>
</body>
</html>

In this example, the server requires Basic authentication and specifies "User Visible Realm" as the authentication realm, which is typically shown in the browser's authentication dialog.

Digest Authentication Example

A response requesting Digest authentication:

HTTP/1.1 401 Unauthorized
Date: Tue, 03 Jun 2025 00:10:30 GMT
Content-Type: text/html; charset=UTF-8
WWW-Authenticate: Digest realm="[email protected]", qop="auth,auth-int", algorithm=SHA-256, nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", opaque="5ccc069c403ebaf9f0171e9517f40e41"
Content-Length: 467

<!DOCTYPE html>
<html>
<head><title>Authentication Required</title></head>
<body>
  <h1>Digest Authentication Required</h1>
  <p>This server requires digest authentication to access the requested resource. 
  Please provide valid credentials.</p>
</body>
</html>

This example specifies Digest authentication with various parameters including realm, quality of protection (qop), algorithm, nonce, and opaque values.

Bearer Token Example

A response requesting Bearer token authentication:

HTTP/1.1 401 Unauthorized
Date: Tue, 03 Jun 2025 00:20:45 GMT
Content-Type: application/json
WWW-Authenticate: Bearer realm="api.example.com", error="invalid_token", error_description="The access token has expired"
Content-Length: 165

{
  "status": "error",
  "code": 401,
  "message": "Authentication required",
  "details": "The access token provided has expired or is invalid."
}

In this example, the server is requesting Bearer token authentication and provides information about why the previous token was rejected.

Multiple Authentication Schemes Example

A response offering multiple authentication options:

HTTP/1.1 401 Unauthorized
Date: Tue, 03 Jun 2025 00:30:15 GMT
Content-Type: application/json
WWW-Authenticate: Basic realm="api.example.com"
WWW-Authenticate: Bearer realm="api.example.com"
WWW-Authenticate: Digest realm="api.example.com", qop="auth", nonce="123456789"
Content-Length: 178

{
  "status": "error",
  "code": 401,
  "message": "Authentication required",
  "details": "Please authenticate using one of the supported methods."
}

In this example, the server offers three different authentication schemes (Basic, Bearer, and Digest), allowing the client to choose the most appropriate one.

Summary

The WWW-Authenticate response header is a crucial component of HTTP authentication, providing clients with the necessary information to authenticate properly when accessing protected resources. By specifying authentication schemes and their parameters, servers can implement various security mechanisms appropriate for their needs. When implementing authentication in web applications or APIs, it's important to select appropriate authentication schemes based on security requirements and to provide clear, informative WWW-Authenticate headers to guide clients through the authentication process. This header, working in conjunction with the Authorization request header, forms the foundation of HTTP's built-in authentication mechanisms.