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

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

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

## 構成の考え方

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

## ログインの流れ

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

## 守ること

- 公開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仕様説明](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie)を参照してください。Secureを外す開発設定が必要なら、許可されたloopback環境に限定し、公開HTTPS環境ではSecureを必須にします。

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

## 提供サンプルの位置づけ

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

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

## 利用者への表示

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

競合や結果不明のときの復帰は、[競合・再送・復帰](reliability.md)にあります。