Table of Contents

“fail” API を用いたエラーレスポンスの生成

fail-api_1 — /auth/authorization/fail API

概要

Authlete では、認可サーバーからクライアントへのエラーレスポンス生成をサポートするために、/auth/authorization/fail と /auth/token/fail の 2 つの API （以下 “fail” API）を提供しています。

認可サーバーはこれらの API を用いることにより、OAuth 2.0 に準拠したエラーレスポンスの返却が容易になります。

“fail” API の基本動作

認可サーバーは、認証・認可処理の結果、クライアントに対してトークン発行を行わないと判断した場合、その理由を “reason” パラメーターに指定して Authlete の “fail” API に送信します。

Authlete はその内容に基づき、返却すべきエラーメッセージについて、その伝達方法の決定とコンテンツの生成を行い、認可サーバーに、それぞれ “action” “responseContent” として回答します。

/auth/authorization/fail API

この API は、クライアントから認可リクエストを受け取った認可サーバーが、Authlete の /api/auth/authorization API を呼び出して認可リクエストに問題がないことを確認し、ユーザーとの認証・認可に関するインタラクションを行った後、クライアントに対してトークン発行ではなくエラーレスポンスを返却する場合に用います。

“action” と “responseContent” の概要を以下に示します。通常は redirect_uri が定まっており、Authlete は LOCATION を返却する場合が一般的です。

action	responseContent
INTERNAL_SERVER_ERROR	Authlete 側のエラーの場合、認可サーバーにはエラー内容を記述した JSON が返却される。ただし、認可サーバーは必ずしもその内容をそのまま回答する必要はない
BAD_REQUEST	redirect_uri が定まっていないのでエラーをクライアントに返却できない。認可サーバーがどのようなエラー出力をするかは要件に依存するが、たとえばステータスコード 400 と合わせて HTML ページを回答することが想定される
LOCATION	Authlete がリダイレクト先の URI を生成し返却する。認可サーバーはそれを Location ヘッダーの値とし、ステータスコード 302 のレスポンスを返却することが期待される
FORM	Authlete が、ある内容を自動的にリダイレクト先に POST するための JavaScript を埋め込んだ HTML を生成する。認可サーバーはその HTML を、ステータスコード 200 と合わせて返却することが期待される

/auth/token/fail API

この API は ROPC (Resource Owner Password Credentials) グラント種別の場合に用います。認可サーバーとして ROPC をサポートしないのであれば、呼ぶ必要はありません。

構造は /api/auth/authorization/fail APIと同様です。

“fail” API を用いないエラー処理

返却すべきエラーメッセージについて、その伝達方法の決定とコンテンツの生成を完全に認可サーバー側だけで実装する場合には、“fail” API を呼び出す必要はありません。（Authlete の動作には問題ありません）

しかしその場合には、認可サーバーはたとえば以下のような実装を独自に行う必要があります。

redirect_uri の値の記録
返却方法（クエリパラメーター、フラグメントなど）の記録。さらに、response_mode=fragment の場合には、response_type=code でもフラグメントによって返却することが必要となるなどの場合わけ
response_type=form_post の場合の HTML フォームの生成
state の値の記録

このような観点から、“fail” API は非常に有用であり、利用を推奨します。

参考情報

Laravel による OAuth 2.0 と OpenID Connect の実装（Authlete）
- 3.9.3. Authlete に認可リクエスト解析処理を任せる
  - 例えば、認可リクエストに client_id パラメーターが含まれていない場合、Authlete の /api/auth/authorization API は、「クライアントに 400 Bad Request を返してください。エラーメッセージの内容としては◯◯を使ってください。」という応答を返します。認可リクエストが正常であれば、「認可リクエストに問題はありませんでした。ユーザーとインタラクティブにやりとりして、認可リクエストに対する同意をとってください。その後、同意結果に応じて、/api/auth/authorization/issue API もしくは /api/auth/authorization/fail API を呼んでください。」といった応答を返します。
- 3.11.3. Authlete にトークンリクエスト処理を任せる
  - リソースオーナーパスワードクレデンシャルズフローの場合のみ、/api/auth/token API だけでは処理が完結せず、トークンエンドポイントは、続けて /api/auth/token/issue API もしくは /api/auth/token/fail API を呼ぶことになります。