Ошибка 401 Unauthorized: причины и диагностика

HTTP 401 Unauthorized означает, что запрос не был применён, потому что для целевого ресурса нет действительных данных аутентификации. Несмотря на слово Unauthorized, по смыслу это прежде всего проблема authentication: сервер не получил подходящие credentials или не принял их.

RFC 9110 требует, чтобы сервер при 401 отправил заголовок WWW-Authenticate как минимум с одним challenge для целевого ресурса. Поэтому диагностика 401 должна начинаться не с догадок о правах пользователя, а с фактического ответа и способа аутентификации.

Что происходит при HTTP 401

Упрощённая схема:

клиент → защищённый ресурс
          ↓
   credentials отсутствуют
   или не приняты
          ↓
401 + WWW-Authenticate

После этого клиент может повторить запрос с новыми или исправленными credentials.

401 и 403 — принципиальная разница

RFC 9110 отдельно указывает: если credentials действительны, но недостаточны для доступа, серверу уместен 403 Forbidden.

Практический пример:

нет токена                → 401
токен просрочен/невалиден → 401
токен валиден, но роль не позволяет доступ → 403

Реальные приложения иногда используют эти коды иначе, поэтому всегда учитывайте контракт конкретной системы.

Шаг 1. Посмотрите полный HTTP-ответ

curl -i https://api.example.com/private

При стандартной HTTP-аутентификации ищите:

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

или другой authentication scheme.

Если WWW-Authenticate отсутствует, это важный сигнал: либо приложение реализует нестандартный login flow, либо ответ не соответствует требованиям 401 из RFC 9110.

Основные причины 401

Authorization вообще не отправлен

Проверьте Network в браузере или запрос curl.

Bearer Token:

curl -i \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.example.com/v1/profile

Если без заголовка 401, а с корректным токеном 200 — механизм работает ожидаемо.

Токен истёк

Access token может иметь ограниченный срок. Клиент продолжает использовать старое значение, сервер перестаёт его принимать и возвращает 401.

Не «лечите» это увеличением срока токена без анализа. Проверьте refresh flow, синхронизацию времени и то, какой token фактически отправляет клиент.

Отправляется не тот token

Типичные причины:

• перепутаны staging и production credentials;
• старый secret остался в environment;
• frontend держит устаревший token;
• proxy удаляет Authorization;
• клиент отправляет access token для другого audience/resource server.

Неверная Basic Auth пара

curl -i \
  -u "$API_USER:$API_PASSWORD" \
  https://example.com/private

-u формирует HTTP Basic credentials. Используйте его только поверх HTTPS для реальных секретов: Basic не является шифрованием credentials сам по себе.

Неправильная схема Authorization

Например, endpoint ожидает:

Authorization: Bearer <token>

а клиент отправляет:

Authorization: Token <token>

или добавляет лишние кавычки.

Session cookie не дошла до сервера

В browser-based приложении authentication может зависеть от cookie. Возможные причины:

• cookie отсутствует;
• истёк срок;
• домен/path не совпадают;
• cookie не отправляется из-за Secure/SameSite условий;
• запрос ушёл на другой hostname.

Reverse proxy не передаёт Authorization

Если прямой запрос к приложению работает, а через proxy получает 401, сравните headers на обоих участках.

клиент → proxy → приложение
          ↓
  Authorization потерян?

Шаг 2. Сравните запрос без credentials и с ними

Без токена:

curl -i https://api.example.com/v1/profile

С токеном:

curl -i \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.example.com/v1/profile

Сравнивайте не только статус, но и WWW-Authenticate, response body и request ID.

Шаг 3. Не выводите секреты в диагностику

Verbose-режим полезен:

curl -v \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.example.com/v1/profile

Но в выводе окажется Authorization. Перед публикацией или отправкой лога удалите token целиком.

Безопаснее в автоматизации хранить credentials в secret storage или environment, а не записывать в команду, shell history и документацию.

Шаг 4. Проверьте token lifecycle

Для bearer-token схемы задайте вопросы:

1. откуда получен token;
2. для какого environment;
3. не истёк ли он;
4. корректен ли issuer/audience по правилам вашей системы;
5. был ли token отозван;
6. работает ли refresh;
7. не рассинхронизировано ли системное время.

Не пытайтесь вручную «исправлять» подписанный token: если он неверен, получите новый корректным способом.

Шаг 5. Проверьте слой, который вернул 401

401 может сформировать:

• CDN/access layer;
• API gateway;
• reverse proxy с auth middleware;
• само приложение;
• внешний identity-aware proxy.

Определяйте слой по request ID, response headers и логам. Если application log не видит запрос, ищите причину до приложения.

401 в API после релиза

Проверьте изменения:

• issuer/audience;
• public keys/JWKS;
• secret/config;
• proxy headers;
• cookie domain;
• callback/redirect URL;
• middleware order.

Если 401 начались сразу у всех клиентов после deployment, вероятность общей конфигурационной причины выше, чем одновременное истечение всех пользовательских сессий.

Почему 401 может быть только у части пользователей

Возможны:

• разные сроки token;
• разные роли и login flows;
• старые cookies;
• разные версии мобильного приложения;
• отдельный tenant/config;
• rollout нового auth-механизма.

Сравнивайте один успешный и один неуспешный запрос с одинакового endpoint, не раскрывая credentials.

401 и браузерные cookies

Если проблема воспроизводится только в браузере:

1. проверьте Network → Request Headers;
2. есть ли Cookie;
3. совпадает ли hostname;
4. был ли redirect на другой домен;
5. не изменились ли cookie attributes;
6. что возвращает login endpoint.

Очистка cookies может временно помочь, но для владельца сервиса важнее понять, почему клиент оказался с некорректной сессией.

401 и мониторинг API

Для защищённого endpoint монитор должен использовать отдельные технические credentials с минимально необходимыми правами. Если token истёк, сам монитор начнёт получать 401 — это отдельный эксплуатационный сценарий, который нужно отличать от падения API.

Связанный материал: как мониторить API endpoint.

Как проверить восстановление

После исправления выполните серию авторизованных запросов:

for i in {1..10}; do
  curl -sS -o /dev/null \
    -H "Authorization: Bearer $API_TOKEN" \
    -w '%{http_code} %{time_total}\n' \
    https://api.example.com/v1/profile
  sleep 1
done

Если часть запросов 200, а часть 401, проверьте распределённые auth caches, разные backend-инстансы и консистентность конфигурации.

Типичные ошибки

Путать authentication и authorization

401 обычно про отсутствие действительных credentials; недостаточные права при уже признанных credentials — типичный случай 403.

Логировать полный token

Это создаёт риск компрометации. Для корреляции используйте безопасный идентификатор, а не секрет целиком.

Проверять только frontend

401 мог сформироваться в gateway до приложения.

Просто увеличить срок token

Это не исправляет потерянный header, неправильный issuer или сломанный refresh flow.

Практический чек-лист

1. Подтвердить 401 через curl.
2. Проверить WWW-Authenticate.
3. Определить используемую auth-схему.
4. Проверить, отправляются ли credentials.
5. Проверить срок и назначение token.
6. Сравнить прямой и proxy-запрос.
7. Проверить auth/application logs по request ID.
8. Не раскрывать credentials в логах.
9. Исправить lifecycle/configuration.
10. Подтвердить восстановление серией авторизованных запросов.

Источники и спецификации

• RFC 9110: 401 Unauthorized
• RFC 9110: HTTP Authentication
• curl: официальная документация