Ошибка 401 Unauthorized: нужна авторизация

Что значит ошибка 401

RFC 9110 (раздел 15.5.2): у запроса нет корректных учётных данных для целевого ресурса. Сервер обязан прислать заголовок WWW-Authenticate, где указывает, как пройти аутентификацию: Basic, Bearer и т. п. Если данные были отправлены, но сервер их не принял, снова вернётся 401. Несмотря на название «Unauthorized», по смыслу это именно проблема аутентификации («кто вы?»), а не прав («что вам можно?»).

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

401 и 403: в чём разница

Причины 401

• не введены или введены неверные логин и пароль;
• истекла сессия или срок токена, cookie с сессией удалена;
• API-ключ или токен не передан в заголовке Authorization, неверно сформирован или отозван;
• на сайт или раздел включена HTTP Basic-авторизация (закрытая тестовая копия, админка);
• системное время на устройстве или сервере сильно расходится с реальным (для подписанных токенов).

Что делать посетителю

1. Войдите в аккаунт или введите логин и пароль заново. Проверьте раскладку и Caps Lock.
2. Если сессия истекла, выйдите и войдите снова, очистите cookie сайта.
3. Проверьте, что у вас есть доступ к этому разделу: возможно, нужен другой аккаунт.
4. Если логин и пароль верные, а ошибка остаётся, обратитесь в поддержку сайта.

Что делать владельцу и разработчику

Закрыть тестовую копию или админку Basic-авторизацией

location / {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

htpasswd -c /etc/nginx/.htpasswd username

AuthType Basic
AuthName "Restricted"
AuthUserFile /var/www/.htpasswd
Require valid-user

Правильные ответы API

Если токена нет или он недействителен, возвращайте 401 с WWW-Authenticate: Bearer. Когда токен верный, но у пользователя нет прав на операцию, возвращайте 403. Не путайте их: клиентские библиотеки по 401 пытаются обновить токен и повторить запрос, а по 403 прекращают попытки.

function requireToken(req, res, next) {
  const auth = req.headers.authorization || "";
  if (!auth.startsWith("Bearer ") || !isValid(auth.slice(7))) {
    return res.status(401).set("WWW-Authenticate", "Bearer").json({ error: "unauthorized" });
  }
  next();
}

Типичные ошибки с Basic-авторизацией

• Пароль по HTTP. Basic передаёт логин и пароль в кодировке base64, это не шифрование. Используйте только по HTTPS.
• Логин и пароль в ссылке (https://user:pass@example.com/) попадают в историю и логи. Не публикуйте такие адреса.
• Прокси или PHP не получает заголовок `Authorization`. Приложение отвечает 401, хотя данные верные. В Apache с CGI/FastCGI добавьте в .htaccess строку ниже.
• Закрыли тестовый сайт только от посетителей, а мониторинг и вебхуки получили 401. Пропишите им исключение или передайте учётные данные.

RewriteEngine On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

Как 401 видят Яндекс и Google

Робот не умеет вводить пароль, поэтому страницы за авторизацией он не видит: ответ 401 для Google относится к группе 4xx, и такие URL не попадают в индекс. Яндекс ведёт себя так же. Это нормально для личных кабинетов и закрытых разделов, а для тестовой копии сайта Basic-авторизация надёжнее, чем robots.txt или noindex. Но если 401 получают роботы на открытых страницах (например, из-за правил защитного ПО или прокси), страницы со временем выпадут из поиска. Google отдельно предупреждает, что 401 и 403 нельзя использовать для ограничения частоты обхода: для этого служат 429, 500 и 503.

Как проверить

Откройте адрес в проверке кода ответа и посмотрите заголовки: для 401 там будет WWW-Authenticate. Из консоли: curl -sI https://example.com/admin/; с авторизацией: curl -sI -u user:password https://example.com/admin/.