# Kk0ga Employee Time Attendance Entra Msal Auth Spa

> Entra ID + MSAL Auth (SPA) Skill

- Skill: `tomevault-io/kk0ga-employee-time-attendance-entra-msal-auth-spa` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/kk0ga-employee-time-attendance-entra-msal-auth-spa`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/kk0ga-employee-time-attendance-entra-msal-auth-spa/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/kk0ga-employee-time-attendance-entra-msal-auth-spa

---


# Entra ID + MSAL Auth (SPA) Skill

## 目的
勤怠システムの認証を **Entra ID（OIDC Authorization Code + PKCE）** で実装し、
「動く」だけでなく **運用・失敗時UX・セキュリティ** まで含めて整える。

## 最重要ルール（このリポジトリ方針）
- SPAなので XSS 対策を最優先（`dangerouslySetInnerHTML` は原則禁止）
- アクセストークンを localStorage に永続保存しない（memory / sessionStorage）
- トークン・個人情報（mail, oid 等）を console に出さない

## 進め方（推奨手順）
1. **環境変数の整理（秘密情報は置かない）**
   - `VITE_ENTRA_CLIENT_ID`
   - `VITE_ENTRA_TENANT_ID`
   - `VITE_ENTRA_REDIRECT_URI`（GitHub Pages の basePath を含める）

2. **MSAL の初期化（起動時に必ず実行）**
   - `PublicClientApplication.initialize()`
   - `handleRedirectPromise()`
   - これを「アプリ描画より前」に行い、ログイン状態を一貫させる

3. **ログイン/ログアウト導線**
   - ログイン: `loginRedirect()`（必要なら `prompt` 指定）
   - ログアウト: `logoutRedirect()`
   - ログイン済みで `/login` に来たら、通常はダッシュボードへ誘導

4. **ルートガード（未ログインは /login）**
   - ルーティング層で「保護ルート」を定義し、未ログインは `redirect()`
   - “一部だけ公開” の画面（/about など）を明確に分ける

5. **トークン取得方針**
   - 第一選択: `acquireTokenSilent()`
   - 失敗時のみ: `acquireTokenRedirect()`（ユーザー操作が必要なケースのフォールバック）
   - scope は最小化（必要なGraph権限のみ）

## 失敗時のUX（必須）
- **401/403**
  - 再ログイン導線 or 権限不足の案内（管理者へ連絡導線）
- **interaction_required / login_required**
  - 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)

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kk0ga) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->