ほとんどの Core API のレスポンスには action フィールドが含まれます。Authlete を用いた認可サーバー実装の原則はシンプルです。Core API を呼び出し、レスポンスをパースし、action の値を確認して、その値に応じた処理を行います。
resultCode の値を処理の分岐条件に使ってはいけません。
/auth/authorization のアクション
/auth/authorization API のレスポンスの action フィールドには、次のいずれかの値が含まれます。
| アクション | 意味 | サーバーが行うこと（例） |
|---|
INTERACTION | 認可リクエストは有効で、ユーザーとの対話が必要です。 | 2 回目の API 呼び出しに進みます。2 段階の API 呼び出しを参照してください。 |
NO_INTERACTION | リクエストは有効で、ユーザーとの対話は不要です（prompt=none など）。 | 2 回目の API 呼び出しに進みます。2 段階の API 呼び出しを参照してください。 |
LOCATION | リダイレクトレスポンスを返すべき状態です。 | responseContent を Location ヘッダーとして 302 Found を返します。 |
FORM | フォーム POST レスポンスを返すべき状態です。 | responseContent（HTML フォーム）をボディとして 200 OK を返します。 |
BAD_REQUEST | 認可リクエストが不正です。 | responseContent をボディとして 400 Bad Request を返します。 |
INTERNAL_SERVER_ERROR | Authlete 側でエラーが発生したか、Authlete へのリクエストが不正です。 | responseContent をボディとして 500 Internal Server Error を返します。 |
action のほかに、クライアントの表示情報や要求されたスコープ・クレームなど、認可サーバーが認証・同意画面を組み立てるために必要な情報も含まれます。レスポンスの完全なスキーマは API リファレンスを参照してください。
アクションと HTTP レスポンスの対応
多くのアクションは、クライアントへ返す 1 つの HTTP レスポンスに直接対応します。認可サーバーは responseContent をそのレスポンスの本体やヘッダーに使います。
たとえば、Authlete Core API からの応答の action が BAD_REQUEST の場合、認可サーバーは次のようなレスポンスをクライアントに返します。
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
(responseContent)
action が LOCATION の場合は次のとおりです。
HTTP/1.1 302 Found
Location: (responseContent)
Cache-Control: no-store
Pragma: no-cache
追加のステップが必要なアクション
INTERACTION と NO_INTERACTION、そして PASSWORD・TOKEN_EXCHANGE・JWT_BEARER のようなグラント処理系のアクションは、1 つの HTTP レスポンスを返すだけでは処理を完了できません。ユーザーの認証や同意の取得などサーバー自身の処理を行ったうえで、2 つ目の Authlete API を呼び出して処理を完了する必要があります。このパターンは2 段階の API 呼び出しで説明します。
他の API の代表的なアクション
他の Core API も、それぞれ固有のアクションセットで同じ規約に従います。次に挙げるのは代表的なアクションであり、網羅的なリストではありません。
| アクション | API の例 | サーバーが行うこと（例） |
|---|
OK | /auth/introspection、/auth/userinfo ほか多数 | リクエストの処理に成功しました。通常は responseContent を 200 OK で返すか、次の処理に進みます（/auth/userinfo の場合はクレーム値を収集して /auth/userinfo/issue を呼び出します）。 |
CREATED | /client/registration | リソースが作成されました（ダイナミッククライアント登録など）。responseContent を 201 Created で返します。 |
UNAUTHORIZED | /auth/userinfo、/auth/introspection | 提示されたトークンが不正です。responseContent を WWW-Authenticate ヘッダーとして 401 Unauthorized を返します。 |
INVALID_CLIENT | /auth/token、/auth/revocation | クライアント認証に失敗しました。API リファレンスの記載に従い 400 または 401 を返します。 |
FORBIDDEN | /auth/introspection、/auth/userinfo | アクセストークンは有効ですが、要求されたリソースに必要なスコープ（やリソース）を持っていません。403 Forbidden を返します。 |
NOT_FOUND | /gm | 対象リソースが存在しません（例：Grant Management リクエストで指定された grant_id が存在しない場合）。404 Not Found を返します。 |
PASSWORD、TOKEN_EXCHANGE、JWT_BEARER | /auth/token | トークン発行の判断の前に、サーバー自身による検証（ユーザークレデンシャル、subject token、assertion）が必要です。2 段階の API 呼び出しを参照してください。 |
新しい世代の API（/vci/*、/gm など）では、エラーの発生箇所を区別します。CALLER_ERROR は実装側のリクエスト誤りを、AUTHLETE_ERROR は Authlete 内部のエラーを意味します。
