action=INTERACTION を返した場合、認可サーバーはユーザーを認証して同意を取得しなければ認可リクエストに応答できません。そして、その応答は 2 回目の Authlete API 呼び出しによって生成されます。
認可エンドポイント API の 2 つのタイプ
認可エンドポイント API は 2 種類の API で構成されています。- 認可リクエストを解釈し、エンドユーザー認証など次のステップに必要な情報を提供する API
- トークンやコードを発行する、またはエラーを返す API
action=INTERACTION の典型的なフローは次のとおりです。
ユーザーがキャンセルした場合や認証に失敗した場合は、代わりに /auth/authorization/fail を呼び出します。Authlete がクライアント向けの適切なエラーレスポンスを構築します。
なお、2 回目の API 呼び出しのレスポンスにも action が含まれます。アクションハンドリングで説明したとおりに処理してください。
チケット
2 つの API 呼び出しはチケットで連携されます。/auth/authorization API がレスポンスでチケットを返し、/auth/authorization/issue または /auth/authorization/fail がそのチケットを受け取って処理を完了します。 チケットには次の性質があります。- チケットは 24 時間で有効期限切れになります。期限切れのチケットは Authlete のデータベースから削除されます。
- チケットは一度しか使えません。チケットを含むリクエストを /auth/authorization/issue または /auth/authorization/fail が正常に処理した直後に削除されます。
- 使用済みまたは期限切れのチケットを使うと、次のようなエラーになります。
2 段階の呼び出しが必要な API の例
他の 2 段階の呼び出しが必要な API の例としては userinfo エンドポイントがあげられます。 /auth/userinfo API はクライアントが提示したアクセストークンを検証し、action を返します。アクションが OK の場合、サーバーはエンドユーザーのクレーム値を収集して /auth/userinfo/issue を呼び出し、userinfo レスポンスを構築します。クライアントの設定に応じて、Authlete がプレーンな JSON または署名・暗号化された JWT として整形します。userinfo エンドポイントはチケットを使いません。ここでは、2 つの呼び出し間の文脈をアクセストークン自体が引き継ぎます。
トークンエンドポイントにも 2 段階のバリエーションがあります。サービスがリソースオーナーパスワードクレデンシャルズグラントをサポートする場合、/auth/token API は
action=PASSWORD を返し、サーバーがエンドユーザーのクレデンシャルを検証したうえで /auth/token/issue または /auth/token/fail を呼び出します。TOKEN_EXCHANGE（RFC 8693）や JWT_BEARER（RFC 7523）でも同じパターンで、サーバーが subject token や assertion を検証します。action ベースのモデルと 2 段階パターンを理解すれば、どの Core API も API リファレンスから自然に読み解けるようになります。