使う

アプリの推奨構成（参考）

トークンをブラウザーに置かないことは、守るべき要件です（基盤の考え方と責任分界）。このページのBFF構成は、その要件を満たす方法の一例で、契約ではなく参考です。

ブラウザーで使うアプリを作るときの、サーバー側の構成を説明します。ブラウザーは、利用者の手元で動くため、アクセストークンのような大事な資格を、安全に預かれません。そこで、資格を、顧客アプリのサーバー側（BFF）で預かります。

構成の考え方

ブラウザーには、利用者のセッションを示すcookieだけを渡します。アクセストークンとリフレッシュトークンは、サーバー側で預かります。
ブラウザーは、基盤APIを、直接呼びません。顧客アプリのサーバー側が、トークンを付けて、呼びます。

ログインの流れ

ブラウザーが、顧客アプリのサーバー側の、ログイン開始の入口を呼びます。
サーバー側が、ブラウザーを、認証サービスのログイン画面へ移動させます。
登録済みの戻り先（redirect_uri）で、stateとPKCEを確認し、codeをトークンに交換します。
サーバー側が、トークンを保護して預かり、ブラウザーには、セッションのcookieだけを渡します。
ログアウトは、同じセッションで行います。サーバー側が、トークンの失効を確認します。

守ること

公開HTTPS環境のcookieは、Secure、HttpOnly、適切なSameSiteにします。
書き込みのリクエストは、同じoriginであることと、CSRFトークンを検査します。CSRFトークンと、アクセストークンを、混同しません。
資格はサーバー側で保管します。URL、ログ、エラー画面には資格やcookieを含めない情報を出します。
リフレッシュは、セッションごとに1つずつ行い、更新されたトークンを安全に保存します。セッション継続が必要な運用では、再起動後も有効期限と失効状態に従って復旧できるようにします。
401の認証更新には上限を設けます。失効や期限切れなら、利用者の再ログインへ戻します。
403のときは、権限を広げようとせず、必要なMFAの実施、または管理者への確認へ案内します。
一定の間隔で動くバックグラウンドの呼び出しを、利用者の操作として扱いません。

開発時のCookieとセッション

開発用のHTTP loopbackを使う場合は、redirect_uriの登録可否と、ブラウザーがCookieを受理・送信する条件を確認します。localhostにはブラウザーの例外扱いがあるため、Secure属性やCookie名の接頭辞の扱いは、実際のscheme・ホスト・ブラウザーで確認します。__Host-を使う場合は、Secure、Path=/、Domain属性の省略が条件です。MDNのSet-Cookie仕様説明を参照してください。Secureを外す開発設定が必要なら、許可されたloopback環境に限定し、公開HTTPS環境ではSecureを必須にします。

セッションをプロセスのメモリだけに保管する構成は、再起動によるセッション終了を許容した開発・検証用の簡易構成です。再起動でstateやPKCEの値を失ったログインは、別セッションへ引き継がず、開始し直します。個別アプリの登録・BFF接続の提供状態は、対応状況とバージョンで確認してください。

提供サンプルの位置づけ

Claudia Partnerは、このページの構成を動かして確認できる、サンプル（BFFと業務画面の例）を、お客様に提供することがあります。入手の方法は、環境管理者に確認してください。

サンプルは、製品ではありません。画面や構成の例で、契約ではありません。仕様の正は、このドキュメントとOpenAPIです。食い違いを見つけたときは、このドキュメントに従い、サポートと窓口へ知らせてください。
複製・改変・再配布の条件は、サンプルに付く利用条件に従います。このドキュメントの利用条件とは別です。
サンプルが基盤を呼ぶ操作は、公開のOpenAPIに載っている操作に限ります。サンプルの中の操作名が、OpenAPIのoperationIdと異なるときは、パスとメソッドで対応を確認します。
サンプルは、登録済みのclient_idとredirect_uriで、利用者としてログインします。個別アプリのクライアント登録・BFF接続は準備中です（対応状況とバージョン）。サンプルで動いたことは、お客様のアプリ用のclient_idが使えることを意味しません。
サンプルの確認は、限られた利用環境と操作の範囲です。MFA、権限（表・列・行）、応答の速度、再認証の条件は、接続先の利用環境で、改めて確認してください。
サンプルには、基盤に接続せずに動かせる、テスト（シミュレーション）環境が付いています。1つのコマンドで起動し、実際の基盤にも認証サービスにも接続しません。契約どおりの形の応答を返す模擬で、画面の上に「テスト環境（模擬）」と表示されます。本人のログイン、MFA、権限（表・列・行）、応答の速度、期限切れ、レート制限は模擬しません。本番の接続と同じ結果を保証するものではないため、これらは接続先の利用環境で確認してください。

利用者への表示

「権限がない」「未接続」「一時的に取得できない」を、区別して表示します。基盤の応答のcodeとrequest_idを、問い合わせに使えるように、控えます。

競合や結果不明のときの復帰は、競合・再送・復帰にあります。