hr-portal/KEYCLOAK_SSO_設定指南.md

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 填入:

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

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

生成 NEXTAUTH_SECRET 方法

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

方法 1 (推薦): 使用 OpenSSL

openssl rand -base64 32

方法 2: 使用 Node.js

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

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

---

步驟 5: 重新啟動前端

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

# 停止當前服務器 (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 範例

# 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 單一登入了! 🎉