401 Unauthorized

Uso

Cuando llega un error 401 Unauthorized, el cliente entiende que se necesitan credenciales de inicio de sesión válidas antes de obtener acceso al recurso solicitado. El cliente debe iniciar sesión primero o aportar las credenciales como parte de la solicitud HTTP. Las credenciales ya enviadas con la solicitud tampoco son válidas. Este estado se distingue de 403 Forbidden, que informa al cliente de que la acción no está permitida con independencia de las credenciales.

Nota

El nombre “Unauthorized” resulta engañoso por motivos históricos. 401 significa que el cliente no está autenticado: faltan credenciales o no son válidas. Los usuarios autenticados que carecen de permiso para realizar la acción solicitada reciben en su lugar 403 Forbidden. Esta denominación persiste desde la especificación original de HTTP/1.0.

Cuando el servidor envía una respuesta 401 Unauthorized, se incluye la cabecera de respuesta WWW-Authenticate. Esta informa al cliente de los métodos de autorización permitidos. IANA mantiene una lista de esquemas de autenticación estándar, que varían en seguridad y popularidad. Esquemas de autenticación habituales:

Basic

Transmite las credenciales como pares ID/contraseña.

Bearer

También conocida como autenticación por token, se basa en tokens de seguridad generados por el servidor y devueltos al cliente tras un inicio de sesión correcto. El cliente envía estos tokens en las solicitudes posteriores para acceder a recursos protegidos. El servidor incluye detalles del error cuando es necesario: WWW-Authenticate: Bearer error=“invalid_token”, error_description=“Token expired”.

Digest

Un protocolo de desafío-respuesta utilizado para autenticar solicitudes de recursos.

HOBA

Abreviatura de HTTP Origin-Bound Authentication, un esquema que no requiere que el servidor almacene contraseñas, lo que lo hace resistente a los ataques de phishing.

Mutual

También conocida como autenticación bidireccional, es similar a los esquemas Basic y Digest, con la diferencia de que se garantiza que el servidor conoce la contraseña cifrada del cliente. Cliente y servidor se autentican mutuamente antes de que continúe la interacción.

AWS4-HMAC-SHA256

Un algoritmo de autenticación que proporciona información de autenticación a Amazon Web Services AWS S3 API Reference.

El servidor puede especificar más de un método de autenticación en varias líneas o en una sola línea separada por comas. Cuando el cliente dispone de las credenciales requeridas, las envía mediante la cabecera de solicitud Authorization.

Impacto en SEO

Los motores de búsqueda como Google no indexan una URL que devuelve el estado 401 Unauthorized. Las URL indexadas previamente que devuelven este código de estado se eliminan de los resultados de búsqueda. Las páginas que devuelven este código no consumen presupuesto de rastreo. No utilice 401 para frenar a Googlebot. Solo 429 reduce la frecuencia de rastreo.

Ejemplo

El cliente solicita un recurso y el servidor responde con 401 Unauthorized para indicar que el recurso está protegido. El servidor indica que admite tanto la autorización Basic como Mutual. El cliente responde con un par username:password usando el protocolo de autenticación Basic, especificado en la cabecera Authorization. A continuación, el servidor transmite el recurso solicitado.

Solicitud inicial

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

Respuesta inicial

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

Siguiente solicitud, incluyendo Authorization

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

Respuesta final

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

<PDF document included in message body>

Cómo solucionarlo

Un 401 Unauthorized significa que el servidor exige credenciales válidas antes de conceder el acceso.

Revise la cabecera WWW-Authenticate en la respuesta. Esta cabecera especifica el esquema de autenticación esperado (Basic, Bearer, Digest, etc.). Haga que la solicitud del cliente coincida con el esquema requerido. Abra las DevTools del navegador, seleccione la pestaña Network y busque la entrada WWW-Authenticate bajo Response Headers.

Verifique las credenciales. Confirme que el nombre de usuario y la contraseña, la clave de API o el token bearer son correctos. Un solo error tipográfico o carácter de espacio en el valor de la cabecera Authorization provoca el rechazo. Pruebe las credenciales de forma aislada con curl -H “Authorization: Bearer ” para descartar problemas en el nivel de la aplicación.

Confirme que el token no ha caducado. Los tokens bearer y los tokens de sesión tienen una vida útil limitada. Decodifique un JWT en un depurador local para comprobar la reclamación exp. Regenere o actualice el token de acceso a través del proveedor de autenticación.

Haga que el formato de la cabecera Authorization coincida con el esquema. Basic espera un par username:password codificado en Base64. Bearer espera una cadena de token sin procesar. Un formato incorrecto desencadena un 401 incluso con credenciales válidas. Un error habitual es omitir el prefijo del esquema (enviar el token solo, sin Bearer ).

Regenere las credenciales si es necesario. Rote la clave de API o solicite un token nuevo al servidor de autorización. Las credenciales revocadas o invalidadas siempre producen este estado.

Borre la caché del navegador y las Cookies. Las cookies de sesión obsoletas o las cabeceras Authorization almacenadas en caché entran en conflicto con las credenciales actualizadas. Borre los datos almacenados y vuelva a autenticarse.

Revise la configuración de autenticación del lado del servidor. Los archivos .htpasswd de Apache, las directivas auth_basic de nginx y las reglas AuthType de .htaccess controlan el acceso. Verifique que existen la ruta del archivo de credenciales, el nombre del realm y la entrada de usuario. En nginx:

auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;

En Apache:

AuthType Basic
AuthName "Restricted"
AuthUserFile /etc/apache2/.htpasswd
Require valid-user

Verifique los ámbitos de OAuth y las reclamaciones de audiencia. Un token de acceso con credenciales correctas pero ámbitos erróneos, o con una reclamación aud que no coincide con el servidor de recursos, sigue desencadenando un 401. Confirme que el token se emitió para la API de destino.

Referencias de código

.NET

HttpStatusCode.Unauthorized

Rust

http::StatusCode::UNAUTHORIZED

Rails

:unauthorized

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