401 Unauthorized

HTTP response status code 401 Unauthorized is a client error that is returned by the server to indicate that the HTTP request has to be authenticated, and that appropriate login credentials have not yet been received.

Usage

When the 401 Unauthorized error message is received, the client understands that valid login credentials need to be supplied in advance of being granted access to the requested resource. It may be that the client needs to first log in to the system, or alternatively, supply credentials as part of the HTTP request. It may also be that the login credentials are not valid. It is relevant to distinguish this from 403 Forbidden, which informs the client that the action is not allowed.

When the server sends a 401 Unauthorized response, it must include the WWW-Authenticate response header. This informs the client as to what authorization methods it allows. IANA has a list of the standard authentication schemes, varying in both security and popularity. The specifications for common Authentication schemes can be found at the following links:

• Basic

  This type of authentication is the transmission of credentials and ID/Password pairs RFC 7617.

• Bearer

  This authentication, also known as token authentication, relies on security tokens that are generated by the server and returned to the client following a successful login. The client is responsible for sending these tokens in any subsequent attempt to access secure resources RFC 6750.

• Digest

  HTTP Digest access authentication is a challenge-response protocol that can be used to authenticate resource requests RFC 7616.

• HOBA

  Short for HTTP Origin-Bound Authentication, is a scheme that does not require the server to maintain a list of stored passwords, and thus is not vulnerable to phishing attacks RFC 7486.

• Mutual

  Mutual authentication, also known as two-way authentication, is similar to the basic and digest authentication schemes, with the difference that the server is guaranteed to know the client’s encrypted password. Essentially, the client and server authenticate each other before the interaction continues RFC 8120.

• AWS4-HMAC-SHA256

  This is an authentication algorithm designed to provide authentication information to Amazon Web Services AWS S3 API Reference.

More than one Authentication method can be specified by the server, either on multiple lines or a single, comma-delimited line. When the client has the credentials required, they are sent to the server using the Authorization request header.

Example

In the example, the client requests a resource and the server responds with the 401 Unauthorized status code to indicate that the resource is protected. As part of the response, the server indicates that it supports both basic authorization and mutual authorization. The client responds by stating that it is providing a username:password pair using the basic authentication protocol, which is specified in the Authorization header. Finally, the server responds by transmitting the requested resource.

Initial request

GET /documents/tech-news HTTP/1.1
Host: www.example.re

Initial response

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic; realm=”Documents”
WWW-Authenticate: Mutual

Next request, including Authorization

GET /documents/tech-news HTTP/1.1
Host: www.example.re
Authorization: Basic RXhhbXBsZTphaQ==

Final response

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 25000

<PDF document included in message body>

Code references

.NET

HttpStatusCode.Unauthorized

Rust

http::StatusCode::UNAUTHORIZED

Rails

:unauthorized

Go

http.StatusUnauthorized

Symfony

Response::HTTP_UNAUTHORIZED

Python3.5+

http.HTTPStatus.UNAUTHORIZED

Java

java.net.HttpURLConnection.HTTP_UNAUTHORIZED

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_UNAUTHORIZED

Angular

@angular/common/http/HttpStatusCode.Unauthorized

Takeaway

The 401 Unauthorized status code indicates that authorization is required to access the requested resource. The server will inform which Authentication method(s) it supports and the client is required to authenticate itself before access is granted. Several common authentication schemes exist.

See also

• RFC 7235