Subject: WWW-Authenticate, Authorization and 401's

From: Hugo Haas <[email-masked]>
Date: Wed, 25 Jul 2007 17:30:30 -0700

Hi,

I'm trying to figure out how the WWW-Authenticate header relates to  
the Authorization header.

Authentication in an HTTP request is not always done with the  
Authorization header. It's sometimes done with cookies for example.  
When a user is not authenticated and authentication is required,  
returning a 401 seems natural:

[[

10.4.2 401 Unauthorized

    The request requires user authentication.

]] -- RFC2616

401 requires a WWW-Authenticate header, which itself requires a  
scheme and a realm:

[[

    The response MUST include a
    WWW-Authenticate header field (section 14.47) containing a challenge
    applicable to the requested resource.

]] -- RFC2616

and:

[[

    The 401 (Unauthorized) response message is used by an origin server
    to challenge the authorization of a user agent. This response MUST
    include a WWW-Authenticate header field containing at least one
    challenge applicable to the requested resource.

[…]

    The realm directive (case-insensitive) is required for all
    authentication schemes that issue a challenge.

]] -- RFC2617

The scheme and realm are concepts that are core to the HTTP  
authentication framework defined in RFC 2617. However, it's not clear  
whether the Authorization header is the required response to this WWW- 
Authenticate challenge:

[[

    The client MAY repeat the
    request with a suitable Authorization header field (section  
14.8). If
    the request already included Authorization credentials, then the 401
    response indicates that authorization has been refused for those
    credentials.

]] -- RFC 2616

[[

    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.

]] -- RFC 2617

Does this mean that the client may repeat the request with  
credentials, and if so this must be done with the Authorization  
header, or that the client may repeat the request with the right  
credentials, and may do so with the Authorization header or using  
some other way?

If the former, that would mean that the 401 error code is reserved to  
the use of the Authorization request header. That would be  
unfortunate as having an error code for standard unauthorized  
responses is handy for obvious reasons.

Additionally, RFC 2616 talks about 401 pertaining to user  
authentication:

[[

10.4.2 401 Unauthorized

    The request requires user authentication.

]] -- RFC2616

while RFC 2617 talks about authenticating the user agent:

[[

    The 401 (Unauthorized) response message is used by an origin server
    to challenge the authorization of a user agent.

]] -- RFC 2617

A request may carry credentials for a number of things (the user, the  
calling application, etc.), and 401 seems like a good response code  
for those, with the meaning that some credentials that the server was  
expecting were not found.

Regards,

Hugo