# Keycloak Client 配置 - HR Portal Frontend

## 需要在 Keycloak 建立的 Client

### Client 基本資訊
- **Client ID**: `hr-portal-web`
- **Client Type**: OpenID Connect
- **Access Type**: Public (因為是 SPA 應用)

### Client 配置

#### 1. Settings
```
Client ID: hr-portal-web
Name: HR Portal Web Application
Description: HR Portal Frontend SPA
Client Protocol: openid-connect
Access Type: public
Standard Flow Enabled: ON
Direct Access Grants Enabled: OFF
Implicit Flow Enabled: OFF
```

#### 2. Valid Redirect URIs
開發環境:
```
http://localhost:3000/*
http://10.1.0.245:3000/*
```

生產環境 (待部署):
```
https://hr.ease.taipei/*
```

**建議**: 如果想要更嚴格的安全控制,可以只允許根路徑:
```
http://localhost:3000/
http://10.1.0.245:3000/
https://hr.ease.taipei/
```

**說明**:
- `/*` - 允許任何路徑作為回調 URI (方便但較不安全)
- `/` - 只允許根路徑作為回調 URI (更安全但需確保 Keycloak 回調到根路徑)
- 對於開發環境,使用 `/*` 比較方便
- 對於生產環境,建議使用更具體的路徑

#### 3. Valid Post Logout Redirect URIs
```
http://localhost:3000/
http://10.1.0.245:3000/
https://hr.ease.taipei/
```

**注意**: Post Logout URIs 不需要 `*`,因為登出後只會導向根路徑

#### 4. Web Origins
```
http://localhost:3000
http://10.1.0.245:3000
https://hr.ease.taipei
```

#### 5. Advanced Settings
```
PKCE Code Challenge Method: S256
```

### Realm Roles (如果需要)

為 HR Portal 建立以下角色:
- `hr-admin` - HR 管理員 (完整權限)
- `hr-manager` - HR 經理 (查看與編輯)
- `hr-viewer` - HR 檢視者 (僅查看)

### Client Scopes

確保以下 scopes 已啟用:
- `openid` - 必須
- `profile` - 使用者基本資料
- `email` - 使用者電子郵件
- `roles` - 角色資訊

## 建立步驟

### 1. 登入 Keycloak Admin Console
```
URL: https://auth.ease.taipei
Realm: porscheworld
```

### 2. 建立 Client
1. 進入 **Clients** 頁面
2. 點擊 **Create** 或 **Add Client**
3. 填寫 Client ID: `hr-portal-web`
4. 選擇 Client Protocol: `openid-connect`
5. 點擊 **Save**

### 3. 配置 Client Settings
1. **Access Type**: 改為 `public`
2. **Standard Flow Enabled**: 勾選 ON
3. **Direct Access Grants Enabled**: 取消勾選
4. **Implicit Flow Enabled**: 取消勾選
5. **Valid Redirect URIs**: 加入上述 URIs
6. **Web Origins**: 加入上述 Origins
7. 點擊 **Save**

### 4. 配置 Advanced Settings
1. 進入 **Advanced Settings** 標籤
2. **PKCE Code Challenge Method**: 選擇 `S256`
3. 點擊 **Save**

### 5. 驗證 Client Scopes
1. 進入 **Client Scopes** 標籤
2. 確認 `openid`, `profile`, `email` 都在 **Assigned Default Client Scopes**
3. 如果沒有,從 **Available Client Scopes** 加入

## 測試配置

### 1. 測試 OIDC Discovery
```bash
curl https://auth.ease.taipei/realms/porscheworld/.well-known/openid-configuration | jq
```

### 2. 測試前端登入流程
1. 啟動開發伺服器: `npm run dev`
2. 瀏覽器開啟: http://localhost:3000
3. 應該會被導向登入頁面
4. 點擊「使用 SSO 登入」
5. 應該會跳轉到 Keycloak 登入頁面
6. 登入成功後應該回到 HR Portal 首頁

## 環境變數配置

前端 `.env` 檔案:
```env
VITE_API_BASE_URL=https://hr-api.ease.taipei
VITE_KEYCLOAK_URL=https://auth.ease.taipei
VITE_KEYCLOAK_REALM=porscheworld
VITE_KEYCLOAK_CLIENT_ID=hr-portal-web
```

## 常見問題

### CORS 錯誤
- 確認 **Web Origins** 已正確設定
- 檢查 Keycloak Realm Settings 的 CORS 設定

### 重新導向錯誤
- 確認 **Valid Redirect URIs** 包含當前使用的 URL
- 確認 URL 結尾有 `/*` 萬用字元

### Token 過期
- 檢查 Keycloak 的 Token Lifespan 設定
- 確認前端有正確實作 Token 刷新機制

## 相關文件

- Keycloak Documentation: https://www.keycloak.org/docs/latest/
- Keycloak JS Adapter: https://www.keycloak.org/docs/latest/securing_apps/#_javascript_adapter
- PKCE Flow: https://oauth.net/2/pkce/