Porsche Chen
360533393f
Major Features: - ✅ Multi-tenant architecture (tenant isolation) - ✅ Employee CRUD with lifecycle management (onboarding/offboarding) - ✅ Department tree structure with email domain management - ✅ Company info management (single-record editing) - ✅ System functions CRUD (permission management) - ✅ Email account management (multi-account per employee) - ✅ Keycloak SSO integration (auth.lab.taipei) - ✅ Redis session storage (10.1.0.254:6379) - Solves Cookie 4KB limitation - Cross-system session sharing - Sliding expiration (8 hours) - Automatic token refresh Technical Stack: Backend: - FastAPI + SQLAlchemy - PostgreSQL 16 (10.1.0.20:5433) - Keycloak Admin API integration - Docker Mailserver integration (SSH) - Alembic migrations Frontend: - Next.js 14 (App Router) - NextAuth 4 with Keycloak Provider - Redis session storage (ioredis) - Tailwind CSS Infrastructure: - Redis 7 (10.1.0.254:6379) - Session + Cache - Keycloak 26.1.0 (auth.lab.taipei) - Docker Mailserver (10.1.0.254) Architecture Highlights: - Session管理由 Keycloak + Redis 統一控制 - 支援多系統 (HR/WebMail/Calendar/Drive/Office) 共享 session - Token 自動刷新,異質服務整合 - 未來可無縫遷移到雲端 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
193 lines
4.5 KiB
Markdown
193 lines
4.5 KiB
Markdown
# 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 單一登入了! 🎉
|