WWW-Authenticate

Применение

Когда клиент запрашивает защищённый ресурс без действительных учётных данных, сервер отвечает кодом состояния 401 и включает заголовок WWW-Authenticate. Этот заголовок несёт один или несколько запросов аутентификации, каждый из которых указывает схему и все параметры, необходимые клиенту для формирования корректных учётных данных.

Получив такой запрос, клиент повторно отправляет запрос с заголовком Authorization, содержащим учётные данные, оформленные согласно выбранной схеме. Сервер проверяет учётные данные и в случае успеха возвращает запрошенный ресурс.

Несколько запросов аутентификации в одном ответе позволяют серверу одновременно предложить несколько схем. Клиент выбирает самую надёжную схему, поддерживаемую обеими сторонами. Запросы указываются либо отдельными строками заголовка, либо одной строкой через запятую.

Эквивалентный заголовок для аутентификации на уровне прокси — Proxy-Authenticate, он вызывает ответ 407 вместо 401.

Схема

Схема определяет метод аутентификации. Реестр зарегистрированных схем ведёт IANA. Самые распространённые на практике схемы описаны ниже.

Basic отправляет пару username:password, закодированную в Base64. Схема принимает параметр realm и необязательный параметр charset (обычно UTF-8).

Bearer выполняет аутентификацию с помощью непрозрачного токена доступа, который чаще всего выдаётся через процесс OAuth. Схема поддерживает параметры realm, scope и error. Параметр scope перечисляет разрешения, которыми должен обладать токен. Параметр error сообщает конкретные причины отказа, такие как invalid_token или insufficient_scope.

Digest улучшает Basic, хэшируя учётные данные с предоставленным сервером значением nonce, что избавляет от передачи пароля в открытом виде. Обязательные параметры включают realm, nonce и qop (quality of protection). Необязательные параметры включают algorithm, opaque и stale.

Negotiate запускает аутентификацию на базе SPNEGO, которая в корпоративных средах обычно опирается на Kerberos или NTLM. Во время выполнения согласования схема несёт закодированный в Base64 токен SPNEGO.

realm

Параметр realm — необязательная строка, определяющая пространство защиты. Значение помогает пользователям понять, какие учётные данные требуются. Сервер, защищающий разные области, назначает каждой из них отдельное значение realm.

token68

Синтаксис token68 — альтернативное кодирование учётных данных, допускаемое механизмом HTTP-аутентификации. Значение использует ограниченный набор символов (буквы и цифры, -, ., _, ~, +, /) с необязательным дополнением символами = в конце.

Пример

Сервер, защищающий ресурс с помощью Basic-аутентификации, возвращает запрос с именем realm, которое отображается пользователю.

WWW-Authenticate: Basic realm="Staging Environment"

Запрос Bearer-токена сообщает требуемую область действия и с помощью параметра error сигнализирует об истёкшем токене.

WWW-Authenticate: Bearer realm="api.example.re", scope="read write", error="invalid_token"

Запрос Digest включает сгенерированное сервером значение nonce и настройку качества защиты.

WWW-Authenticate: Digest realm="admin@example.re", nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v", qop="auth", algorithm=SHA-256

Сервер, предлагающий несколько схем, перечисляет их, чтобы клиент выбрал самый надёжный вариант.

WWW-Authenticate: Negotiate
WWW-Authenticate: Bearer realm="api.example.re"
WWW-Authenticate: Basic realm="api.example.re"

Полное рукопожатие Basic-аутентификации. Сначала клиент запрашивает защищённый ресурс без учётных данных:

GET /admin HTTP/1.1
Host: example.re

Сервер отвечает кодом 401 и запросом по схеме Basic:

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

Клиент повторяет запрос с заголовком Authorization, содержащим пару username:password в кодировке Base64:

GET /admin HTTP/1.1
Host: example.re
Authorization: Basic dXNlcjpwYXNz

Сервер проверяет учётные данные и возвращает ресурс:

HTTP/1.1 200 OK
Content-Type: text/html