401 Unauthorized: що означає і як виправити

Що означає 401 Unauthorized

RFC 9110 визначає 401 як запит, що потребує автентифікації, або тому що жодної не надали, або тому що надана не пройшла. Відповідь 401 має включати заголовок WWW-Authenticate, що називає схему, яку очікує сервер, наприклад Basic, Bearer чи Digest. Цей заголовок - підказка, яку більшість пропускає повз: він точно каже, який тип облікових даних хоче сервер, що зазвичай швидше за здогадки.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"

Як з'являється помилка

У браузері 401, захищений HTTP Basic автентифікацією, спричиняє власне вікно введення імені користувача й пароля, а не сторінку, відрендерену сайтом. 401 від JSON API, натомість, зазвичай видно лише у вкладці мережі чи спливному повідомленні про помилку, яке побудував застосунок, оскільки для збою Bearer-токена немає стандартного інтерфейсу браузера. З командного рядка облікові дані і заголовок обидва видно в одному запиті:

curl -i -H "Authorization: Bearer eyJhbGciOi..." https://api.example.com/v1/account
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="token is expired"

Логи сервера й застосунку зазвичай теж записують причину, наприклад "token expired," "signature invalid," чи "no Authorization header," що звужує причину швидше, ніж сам загальний код статусу.

Що спричиняє 401 Unauthorized

Приблизно в порядку того, наскільки часто кожна виявляється причиною:

• Облікові дані взагалі не надіслані. Сесія без входу, відсутній API-ключ чи клієнт, що взагалі ніколи не долучав заголовок Authorization.
• Прострочений токен. Кукі сесії, токени доступу OAuth і JWT усі мають термін дії, і клієнт, що використовує застарілий, отримує 401, хоча той працював хвилини тому.
• Розбіжність годинника між клієнтом і сервером. Претензії exp і nbf JWT оцінюють проти годинника сервера. Сервер чи клієнт із неправильним часом можуть відхилити токен, який за власною математикою токена все ще чинний, чи прийняти той, що вже прострочений.
• Неправильна схема автентифікації. Надсилання Authorization: Basic ... на ендпоінт, що очікує Bearer, чи навпаки, провалюється, навіть коли заголовок присутній.
• API-ключ розміщений не в тому місці. Деякі API очікують ключ у власному заголовку на кшталт X-API-Key, інші в Authorization, а треті - як параметр запиту. Розміщення валідного ключа не в тому місці виглядає ідентично до взагалі відсутнього ключа.
• Зворотний проксі чи шлюз прибирає заголовок Authorization. Деякі конфігурації проксі й CDN відкидають заголовки, які явно не пересилають, і цілком валідні облікові дані ніколи не доходять до origin-сервера.
• Відкликані облікові дані. Користувач змінив пароль, адміністратор змінив API-ключ, чи токен явно визнали недійсним при виході.

401 проти 403

Ці два часто плутають, бо обидва відхиляють запит, але специфікація проводить чітку межу. 401 означає, що сервер потребує, щоб ви автентифікувалися, і валідні облікові дані могли б змінити результат; він має нести WWW-Authenticate. 403 означає, що сервер точно зрозумів, хто ви, і все одно відмовляє, з причини, яку автентифікація не може виправити, наприклад обмеження ролі чи плану. Якщо повторний вхід правдоподібно допоміг би, це має бути 401. Якщо користувач уже увійшов і йому просто не дозволено, це має бути 403, хоча на практиці чимало API вільно використовують 401 для обох випадків.

Як зрозуміти, хто винен

Якщо ви той, хто викликає API, відтворіть запит зі свіжими обліковими даними з чистого середовища; якщо новостворений токен успішний, старий просто прострочився чи його відкликали. Якщо зовсім новий токен теж провалюється, перевірте схему й назву заголовка проти документації API, перш ніж припускати, що сервер зламаний. Якщо ви керуєте службою, а користувачі повідомляють про 401, які ви не можете відтворити зі своїм власним акаунтом, найшвидший спосіб відділити "сервер у порядку, окремі токени застаріли" від "сама автентифікація зламана для всіх" - запустити HTTP-перевірку із завідомо робочими обліковими даними з кількох локацій одночасно й порівняти результати.

Як виправити 401 Unauthorized

Якщо ви відвідувач

1. Увійдіть знову. Більшість 401 від веб-застосунку - просто прострочена сесія, і повторний вхід її оновлює.
2. Перевірте системний годинник на своєму пристрої, якщо той самий вхід постійно провалюється одразу після автентифікації. Годинник, зсунутий на кілька хвилин, може зробити недійсними токени на основі часу на деяких клієнтах.
3. Перегенеруйте API-ключ чи токен у налаштуваннях акаунта, якщо підозрюєте, що його змінили чи відкликали, а не припускайте, що баг у вашому коді інтеграції.
4. Підтвердьте, що заголовок Authorization справді надсилається, використовуючи вкладку мережі браузера чи звичайний виклик curl, оскільки деякі бібліотеки HTTP-клієнтів мовчки відкидають власні заголовки при перенаправленні.

Якщо ви керуєте сайтом

1. Прочитайте заголовок WWW-Authenticate і власні логи на предмет конкретної причини відмови, перш ніж щось міняти; "expired," "invalid signature" і "missing header" вказують на різні виправлення.
2. Перевірте синхронізацію годинника на серверах, що видають і перевіряють токени. Дрейф NTP на будь-якому боці - класична, періодична причина відхилень JWT, що інакше виглядають випадковими.
3. Переконайтеся, що проксі чи балансувальник навантаження пересилає заголовок Authorization. Правило, додане з непов'язаної причини, може мовчки прибирати його для кожного запиту за цим переходом.
4. Чітко задокументуйте очікувану схему й назву заголовка у своїй документації API і поверніть конкретний error_description у заголовку WWW-Authenticate, щоб інтеграторам не доводилося гадати.
5. Відрізняйте 401 від 403 у власних відповідях там, де це важливо для викликачів, щоб клієнтський код міг відрізнити "онови свій токен" від "тобі ніколи не дозволять цього робити."

Як запобігти мовчазному збою 401

401, спричинений простроченим сертифікатом підпису, годинником, що розсинхронізувався, чи зміною проксі, що почала прибирати заголовок Authorization, не виглядатиме як збій. Служба відповідає миттєво й правильно за власними правилами, тож може лишатися зламаною для кожного викликача, доки хтось не помітить. HTTP-перевірка з умовою на очікуваний код статусу, запущена з живими обліковими даними проти автентифікованого ендпоінта, ловить це тієї миті, коли воно починається. Для API зокрема поєднання цього з API-моніторингом, що перевіряє тіла відповідей так само, як коди статусу, ловить і токен, що автентифікується, але повертає неправильно сформовані дані.

Пов'язані помилки

Дивіться 403 Forbidden для запитів, які сервер зрозумів і відхилив незалежно від облікових даних, огляд 4xx для ширшої родини помилок клієнта, і інші посібники цієї партії: 405 Method Not Allowed, 422 Unprocessable Content.

Часті запитання

Чому я отримую 401 одразу після успішного входу?

Зазвичай через розбіжність годинника між вашим пристроєм і сервером, чи клієнт, що закешував старий, уже недійсний токен замість використання щойно виданого. Підтвердьте, що системний час правильний і що справді надсилається новий токен.

Чи означає 401, що мій акаунт зламали?

Не сам по собі. Це майже завжди означає прострочену сесію, відкликаний ключ чи неправильно надісланий заголовок. Ставтеся до цього як до проблеми безпеки, лише якщо ви не очікували, що облікові дані перестануть працювати, і не можете пояснити, чому це сталося.

Яка різниця між 401 і збоєм автентифікації на рівні TLS?

Збій клієнтського сертифіката TLS взагалі не дає з'єднанню встановитися, тож жоден код статусу HTTP ніколи не повертається. 401 означає, що з'єднання встановилося успішно, і сервер отримав повний HTTP-запит, а тоді відхилив його на рівні застосунку через відсутність валідних облікових даних.

Чи має форма входу сама коли-небудь повертати 401?

Ні. Ендпоінт входу, що оцінює ім'я користувача й пароль, не автентифікує наявний запит; неправильний пароль там за конвенцією дає 400 чи 200 з тілом помилки, оскільки все призначення ендпоінта - приймати неавтентифіковані спроби й оцінювати їх.

Чи може валідний API-ключ усе одно дати 401?

Так, якщо його надіслали не в тому заголовку чи не тією схемою, якщо його змінили після того, як ваша інтеграція закешувала старий, чи якщо запит дійшов до сервера через проксі, що прибрав заголовок перед пересиланням.