メインコンテンツまでスキップ

3. WWW-Authenticate レスポンスヘッダーフィールド

保護されたリソースリクエストに認証情報が含まれていない場合、または保護されたリソースへのアクセスを可能にするアクセストークンが含まれていない場合、リソースサーバーはHTTP「WWW-Authenticate」レスポンスヘッダーフィールドを含めなければなりません (しなければならない)。他の条件に対応して含めてもよい (してもよい)。「WWW-Authenticate」ヘッダーフィールドは、HTTP/1.1 [RFC2617]で定義されているフレームワークを使用します。

本仕様で定義されているすべてのチャレンジは、auth-scheme値「Bearer」を使用しなければなりません (しなければならない)。このスキームには、1つ以上のauth-param値が続かなければなりません (しなければならない)。本仕様で使用または定義されているauth-param属性は次のとおりです。他のauth-param属性も使用してもよい (してもよい)。

「realm」属性は、HTTP/1.1 [RFC2617]で説明されているように、保護の範囲を示すために含めてもよい (してもよい)。「realm」属性は、複数回出現してはなりません (してはならない)。

「scope」属性は、[RFC6749]のセクション3.3で定義されています。「scope」属性は、要求されたリソースにアクセスするために必要なアクセストークンのスコープを示す、スペースで区切られた大文字小文字を区別するスコープ値のリストです。「scope」値は実装定義であり、それらの集中レジストリはありません。許可される値は、認可サーバーによって定義されます。「scope」値の順序は重要ではありません。場合によっては、保護されたリソースを利用するのに十分なアクセススコープを持つ新しいアクセストークンを要求するときに「scope」値が使用されます。「scope」属性の使用は任意です (任意である)。「scope」属性は、複数回出現してはなりません (してはならない)。「scope」値は、プログラムによる使用を目的としており、エンドユーザーに表示することを意図していません。

以下は2つのスコープ値の例です。これらは、それぞれOpenID Connect [OpenID.Messages]およびOpen Authentication Technology Committee (OATC) Online Multimedia Authorization Protocol [OMAP] OAuth 2.0ユースケースから取られています:

scope="openid profile email"
scope="urn:example:channel=HBO&urn:example:rating=G,PG-13"

保護されたリソースリクエストにアクセストークンが含まれていて認証に失敗した場合、リソースサーバーは、アクセスリクエストが拒否された理由をクライアントに提供するために「error」属性を含めるべきです (すべきである)。パラメータ値は、セクション3.1で説明されています。さらに、リソースサーバーは、エンドユーザーに表示することを意図していない、開発者向けの人間が読める説明を提供するために「error_description」属性を含めてもよい (してもよい)。また、エラーを説明する人間が読めるWebページを識別する絶対URIを持つ「error_uri」属性を含めてもよい (してもよい)。「error」、「error_description」、および「error_uri」属性は、複数回出現してはなりません (してはならない)。

「scope」属性の値([RFC6749]の付録A.4で指定)は、スコープ値を表すための%x21 / %x23-5B / %x5D-7Eのセットおよびスコープ値間の区切り文字のための%x20の外側の文字を含んではなりません (してはならない)。「error」および「error_description」属性の値([RFC6749]の付録A.7およびA.8で指定)は、%x20-21 / %x23-5B / %x5D-7Eのセットの外側の文字を含んではなりません (してはならない)。「error_uri」属性の値([RFC6749]の付録A.9で指定)は、URI-reference構文に準拠しなければならず (しなければならない)、したがって%x21 / %x23-5B / %x5D-7Eのセットの外側の文字を含んではなりません (してはならない)。

例えば、認証なしで保護されたリソースリクエストに対する応答:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example"

そして、期限切れのアクセストークンを使用した認証試行による保護されたリソースリクエストに対する応答:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example",
                  error="invalid_token",
                  error_description="The access token expired"

3.1. エラーコード (Error Codes)​

リクエストが失敗した場合、リソースサーバーは、適切なHTTPステータスコード(通常、400、401、403、または405)を使用して応答し、レスポンスに以下のエラーコードの1つを含めます:

invalid_request : リクエストに必須パラメータが欠けている、サポートされていないパラメータまたはパラメータ値が含まれている、同じパラメータが繰り返されている、アクセストークンを含めるために複数のメソッドを使用している、またはその他の方法で不正な形式である。リソースサーバーは、HTTP 400 (Bad Request)ステータスコードで応答すべきです (すべきである)。

invalid_token : 提供されたアクセストークンが期限切れ、取り消され、不正な形式、または他の理由で無効である。リソースは、HTTP 401 (Unauthorized)ステータスコードで応答すべきです (すべきである)。クライアントは、新しいアクセストークンを要求し、保護されたリソースリクエストを再試行してもよい (してもよい)。

insufficient_scope : リクエストが、アクセストークンによって提供されるよりも高い特権を必要とする。リソースサーバーは、HTTP 403 (Forbidden)ステータスコードで応答すべきであり (すべきである)、保護されたリソースにアクセスするために必要なスコープを持つ「scope」属性を含めてもよい (してもよい)。

リクエストに認証情報が欠けている場合(例えば、クライアントが認証が必要であることを知らなかった、またはサポートされていない認証方法を使用しようとした場合)、リソースサーバーは、エラーコードまたは他のエラー情報を含めるべきではありません (すべきでない)。

例:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example"
に最終更新