WWW-Authenticate

使い方

クライアントが有効な認証情報なしに保護されたリソースを要求すると、サーバーは 401 ステータスコードで応答し、WWW-Authenticate ヘッダーを含めます。このヘッダーは 1 つ以上の認証チャレンジを運び、それぞれが方式と、クライアントが有効な認証情報を組み立てるために必要なパラメーターを指定します。

チャレンジを受け取ったクライアントは、選択した方式に従って整形した認証情報を含む Authorization ヘッダーを付けてリクエストを再送します。サーバーは認証情報を検証し、成功すれば要求されたリソースを返します。

1 つのレスポンスに複数のチャレンジを含めることで、サーバーは複数の方式を同時に提示できます。クライアントは双方がサポートする中で最も強力な方式を選びます。チャレンジは別々のヘッダー行として現れることも、1 行にカンマ区切りで現れることもあります。

プロキシレベルの認証で同等の役割を果たすヘッダーは Proxy-Authenticate で、こちらは 401 ではなく 407 レスポンスを引き起こします。

scheme

scheme は認証方式を識別します。登録済みの方式は IANA が管理しています。実際によく使われる方式を以下で説明します。

Basic は username:password の組を Base64 でエンコードして送ります。この方式は realm パラメーターと、任意の charset パラメーター（通常は UTF-8）を受け付けます。

Bearer は不透明なアクセストークンで認証します。トークンは多くの場合 OAuth のフローで発行されます。この方式は realm、scope、error のパラメーターをサポートします。scope パラメーターはトークンが持つべき権限を列挙します。error パラメーターは invalid_token や insufficient_scope といった具体的な失敗理由を伝えます。

Digest は、サーバーが提供する nonce で認証情報をハッシュ化することで Basic を改善し、パスワードが平文で流れるのを防ぎます。必須のパラメーターには 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 と quality of protection の設定が含まれます。

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"

クライアントは username:password の組を Base64 でエンコードした Authorization ヘッダーを付けて再試行します。

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

サーバーは認証情報を検証し、リソースを返します。

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