SKILL.md
Entra ID + MSAL Auth (SPA) Skill
目的
勤怠システムの認証を Entra ID（OIDC Authorization Code + PKCE） で実装し、 「動く」だけでなく 運用・失敗時UX・セキュリティ まで含めて整える。
最重要ルール（このリポジトリ方針）
- SPAなので XSS 対策を最優先（
dangerouslySetInnerHTMLは原則禁止） - アクセストークンを localStorage に永続保存しない（memory / sessionStorage）
- トークン・個人情報（mail, oid 等）を console に出さない
進め方（推奨手順）
- 環境変数の整理（秘密情報は置かない）
- VITEENTRACLIENTID - VITEENTRATENANTID - VITEENTRAREDIRECT_URI（GitHub Pages の basePath を含める）
- MSAL の初期化（起動時に必ず実行）
- PublicClientApplication.initialize() - handleRedirectPromise() - これを「アプリ描画より前」に行い、ログイン状態を一貫させる
- ログイン/ログアウト導線
- ログイン: loginRedirect()（必要なら prompt 指定） - ログアウト: logoutRedirect() - ログイン済みで /login に来たら、通常はダッシュボードへ誘導
- ルートガード（未ログインは /login）
- ルーティング層で「保護ルート」を定義し、未ログインは redirect() - “一部だけ公開” の画面（/about など）を明確に分ける
- トークン取得方針
- 第一選択: acquireTokenSilent() - 失敗時のみ: acquireTokenRedirect()（ユーザー操作が必要なケースのフォールバック） - scope は最小化（必要なGraph権限のみ）
失敗時のUX（必須）
- 401/403
- 再ログイン導線 or 権限不足の案内（管理者へ連絡導線）
- interactionrequired / loginrequired
- UIで「再ログインが必要」と明示し、インタラクティブに誘導
- 429/503
- すぐにログインし直させず、Graph呼び出し側でリトライを検討
GitHub Pages（Hashルーティング）注意
- SPAルーティングはHashを使うと Pages 側の404問題を避けやすい
- ただし redirectUri は
#を含めない（IdPの戻り先は通常パス部分） - Pagesの basePath（
/repo-name/）を使う構成なら redirectUri にも反映する
成果物（このスキルで必ず出す）
.env.exampleに必要なキー（値はダミー）- ルートガード仕様（公開/保護ルート一覧）
- 主要エラーのユーザー表示文言（日本語）
依頼例
- 「Entra ID + MSAL のログインを導入して、未ログイン時は /login に飛ばしたい」
- 「acquireTokenSilent を優先して、失敗時だけredirectフォールバックしたい」
- 「GitHub Pages（Hashルーティング）でMSALのredirectUriをどうするべき？」
References
- [docs/README.md](../../../docs/README.md)