# Keycloak SSO 設定指南

## 目標
為 HR Portal 前端建立 Keycloak Client,啟用 SSO 單一登入功能。

---

## 步驟 1: 登入 Keycloak Admin Console

1. 開啟瀏覽器訪問: https://auth.ease.taipei
2. 點擊 "Administration Console"
3. 使用管理員帳號登入
4. 選擇 Realm: **porscheworld**

---

## 步驟 2: 創建新的 Client

1. 左側選單點擊 **Clients**
2. 點擊右上角 **Create client** 按鈕
3. 填寫以下資訊:

### General Settings (第一頁)
- **Client type**: `OpenID Connect`
- **Client ID**: `hr-portal-web`
- **Name**: `HR Portal Web Application`
- **Description**: `HR Portal 人力資源管理系統前端`

點擊 **Next**

### Capability config (第二頁)
- ✅ **Client authentication**: ON (重要!)
- ✅ **Authorization**: OFF
- ✅ **Authentication flow**:
  - ✅ Standard flow (勾選)
  - ❌ Direct access grants (不勾選)
  - ❌ Implicit flow (不勾選)
  - ❌ Service accounts roles (不勾選)
  - ❌ OAuth 2.0 Device Authorization Grant (不勾選)
  - ❌ OIDC CIBA Grant (不勾選)

點擊 **Next**

### Login settings (第三頁)
- **Root URL**: `http://localhost:3000`
- **Home URL**: `http://localhost:3000`
- **Valid redirect URIs**:
  ```
  http://localhost:3000/*
  http://10.1.0.245:3000/*
  https://hr.ease.taipei/*
  ```
- **Valid post logout redirect URIs**:
  ```
  http://localhost:3000/*
  http://10.1.0.245:3000/*
  https://hr.ease.taipei/*
  ```
- **Web origins**:
  ```
  http://localhost:3000
  http://10.1.0.245:3000
  https://hr.ease.taipei
  ```

點擊 **Save**

---

## 步驟 3: 獲取 Client Secret

1. 在剛才建立的 `hr-portal-web` Client 頁面
2. 切換到 **Credentials** 標籤
3. 找到 **Client secret** 欄位
4. 點擊 👁️ (眼睛圖示) 查看密碼
5. 點擊 📋 (複製圖示) 複製密碼

**重要**: 請將複製的 Client Secret 保存好,稍後需要填入前端環境變數。

---

## 步驟 4: 設定前端環境變數

1. 開啟檔案: `W:\DevOps-Workspace\3.Develop\4.HR_Portal\frontend\.env.local`
2. 將剛才複製的 Client Secret 填入:

```bash
# 將下面的 <YOUR_CLIENT_SECRET> 替換成剛才複製的密碼
KEYCLOAK_CLIENT_SECRET=<YOUR_CLIENT_SECRET>

# 同時生成一個 NEXTAUTH_SECRET (可用以下指令生成)
# openssl rand -base64 32
NEXTAUTH_SECRET=<RANDOM_STRING>
```

### 生成 NEXTAUTH_SECRET 方法

在命令列執行以下其中一個:

**方法 1 (推薦)**: 使用 OpenSSL
```bash
openssl rand -base64 32
```

**方法 2**: 使用 Node.js
```bash
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
```

將生成的結果貼到 `NEXTAUTH_SECRET=` 後面。

---

## 步驟 5: 重新啟動前端

配置完成後,重新啟動前端開發服務器:

```bash
# 停止當前服務器 (Ctrl+C)
# 然後重新啟動
cd W:\DevOps-Workspace\3.Develop\4.HR_Portal\frontend
npm run dev
```

---

## 步驟 6: 測試 SSO 登入

1. 開啟瀏覽器訪問: http://localhost:3000
2. 應該會自動導向登入頁面
3. 點擊 "使用 Keycloak SSO 登入" 按鈕
4. 系統會導向 Keycloak 登入頁面
5. 使用您的 Keycloak 帳號登入
6. 登入成功後會導回 HR Portal 主控台

---

## 完整 .env.local 範例

```bash
# API 配置
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api/v1

# Keycloak 配置
NEXT_PUBLIC_KEYCLOAK_URL=https://auth.ease.taipei
NEXT_PUBLIC_KEYCLOAK_REALM=porscheworld
NEXT_PUBLIC_KEYCLOAK_CLIENT_ID=hr-portal-web

# NextAuth 配置
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=<請生成一個隨機字串>

# Keycloak Client Secret (從 Keycloak 取得)
KEYCLOAK_CLIENT_SECRET=<請從 Keycloak Client Credentials 複製>

# 環境
NEXT_PUBLIC_ENVIRONMENT=development
```

---

## 故障排除

### 問題 1: 登入後出現 "Redirect URI mismatch"
- 檢查 Keycloak Client 的 "Valid redirect URIs" 是否包含當前 URL
- 確認沒有拼寫錯誤

### 問題 2: 無法獲取使用者資訊
- 檢查 Client Secret 是否正確填入 .env.local
- 確認 .env.local 檔案有被正確載入

### 問題 3: CORS 錯誤
- 檢查 "Web origins" 設定是否正確
- 確認沒有多餘的斜線 (/)

---

## 檢查清單

- [ ] Keycloak Client `hr-portal-web` 已建立
- [ ] Client authentication 已開啟
- [ ] Redirect URIs 已正確設定
- [ ] Client Secret 已複製並填入 .env.local
- [ ] NEXTAUTH_SECRET 已生成並填入 .env.local
- [ ] 前端服務器已重新啟動
- [ ] 可以成功導向 Keycloak 登入頁面
- [ ] 可以成功登入並返回 HR Portal

---

完成以上步驟後,HR Portal 就可以使用 Keycloak SSO 單一登入了! 🎉