action=INTERACTION を返した場合、認可サーバーはユーザーを認証して同意を取得しなければ認可リクエストに応答できません。そして、その応答は 2 回目の Authlete API 呼び出しによって生成されます。
認可エンドポイント API の 2 つのタイプ
認可エンドポイント API は 2 種類の API で構成されています。- 認可リクエストを解釈し、エンドユーザー認証など次のステップに必要な情報を提供する API
- トークンやコードを発行する、またはエラーを返す API
action=INTERACTION の典型的なフローは次のとおりです。
フローの各ステップ
認可リクエストと 1 回目の呼び出し
OAuth 2.0 / OpenID Connect のフローは、クライアントがエンドユーザーのブラウザーを認可サーバーの認可エンドポイントへリダイレクトすることで始まります。このとき送られるリクエスト（response_type、client_id、redirect_uri、scope などを含むクエリ文字列）が、上の図の「認可リクエスト」にあたります。
認可サーバーは、受け取ったリクエストを加工せずそのまま /auth/authorization に渡します（詳細はリクエストとレスポンスを参照）。認可リクエストがエンドユーザーとの対話を必要とする場合、Authlete は次のようなレスポンスを返します。
action=INTERACTIONは「認可リクエストに応答する前にエンドユーザーとの対話（認証・同意）が必要」という意味です。ticketは、2 回目の呼び出しへ処理を引き継ぐための値です（性質は後述の「チケット」を参照）。- レスポンスにはクライアント情報・サービス情報のほか、クライアントが要求したスコープやクレームも含まれます。認可サーバーはこれらを使って次の同意画面を組み立てます。
認証・同意画面の表示
認証・同意画面の表示、ユーザー認証、同意の取得はいずれも認可サーバー自身の責務であり、Authlete がこれらの画面を描画するわけではありません。認可サーバーは 1 回目のレスポンスに含まれる情報を使って同意画面を表示します。このあいだ、受け取ったticket は 2 回目の呼び出しまでサーバー側（セッションなど）で保持しておきます。
2 回目の呼び出しと認可レスポンスの生成
ユーザーが認証と同意を完了したら、認可サーバーは 2 回目の呼び出しとして /auth/authorization/issue にリクエストを送ります。このリクエストには、1 回目で受け取ったticket と、認証したエンドユーザーの識別子である subject を含めます。
us.authlete.com をご利用のクラスターホスト（eu.authlete.com、jp.authlete.com など）に置き換えてください。サービスアクセストークンの取得方法は認証を参照してください。
OpenID Connect の ID トークンを発行する場合は、authTime（ユーザーを認証した時刻）、acr（認証コンテキストクラス）、要求されたクレームの値などを併せて渡せます。渡せるパラメーターの一覧は /auth/authorization/issue の API リファレンスを参照してください。
このリクエストが成功すると、レスポンスの action は通常 LOCATION になり、responseContent に認可コードを含むリダイレクト先 URL が入ります。認可サーバーはこの値を使ってブラウザーに 302 Found を返し、認可レスポンスをクライアントに届けます。2 回目のレスポンスの action もアクションハンドリングで説明したとおりに処理してください。
ユーザーがキャンセルした場合や認証に失敗した場合は、/auth/authorization/issue の代わりに /auth/authorization/fail を同じ ticket とともに呼び出します。Authlete がクライアント向けの適切なエラーレスポンスを構築します。
チケット
前述のとおり、チケットは 1 回目の呼び出しの応答で発行され、2 回目の呼び出しで処理を完了させる一度限りの値です。次の性質があります。- チケットは 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 リファレンスから自然に読み解けるようになります。