Next.js – SSO in BIRC

本文件透過商業智慧研究中心 – 智慧校園:活動系統來說明商智中心的SSO架構。

商智中心的SSO為自架伺服器，非Google SSO，但原理大同小異。

該文章所述程式碼皆提供於文章最下方GitHub中。

版本：0.1.0
最後更新時間：06/10/2026
最後更新人員：陳泓毓

設計原則

系統角色

flowchart LR
    User[使用者]
    FE[Campus Activity 前端]
    SSO[SSO 登入中心]
    BE[Campus Activity 後端]

    User -->|點擊登入| FE
    FE -->|GET /sso/prelogin| SSO
    SSO -->|302 ?code=| FE
    FE -->|POST /auth-tokens/exchange| BE
    BE -->|X-Auth-Token JWT| FE
    FE -->|Bearer JWT| BE

整體流程

sequenceDiagram
    participant User as 使用者
    participant Navbar as Navbar / AuthContext
    participant SSO as SSO 登入中心
    participant BE as Campus Activity 後端

    User->>Navbar: 點擊右上角「登入」
    Navbar->>SSO: GET /sso/prelogin?redirect_url={目前頁面網址}
    SSO->>User: 顯示 Google 登入頁
    User->>SSO: 完成身分驗證
    SSO->>Navbar: 302 跳轉 redirect_url?code={授權碼}
    Navbar->>BE: POST /auth-tokens/exchange<br/>Header: X-Client-Token: {code}
    BE->>SSO: POST /sso/verify-code（僅後端）
    SSO-->>BE: { email, name, picture }
    BE-->>Navbar: 200 OK<br/>Header: X-Auth-Token: {JWT}
    Navbar->>Navbar: 解析 JWT、儲存 authToken、更新 UI
    User->>Navbar: 右上角顯示頭像（Google 照片或名稱首字）
    User->>Navbar: 點擊頭像進入 /profile

環境變數

.env.local 範例：

NEXT_PUBLIC_API_URL=http://localhost:8080/api
NEXT_PUBLIC_SSO_BASE_URL=https://sso.ntubimdbirc.twCode language: JavaScript (javascript)

前端實作

檔案職責

發起登入

使用者點擊 Navbar「登入」時，呼叫 startSsoLogin()：

const redirectUrl = window.location.origin + pathname;
window.location.href = buildSsoLoginUrl(redirectUrl);
// → https://sso.ntubimdbirc.tw/sso/prelogin?redirect_url={encodeURIComponent(redirectUrl)}Code language: JavaScript (javascript)

實作位置：lib/sso.ts → buildSsoLoginUrl()

處理 SSO 回調

AuthProvider 監聽 URL 查詢參數：

// lib/hooks/AuthContext.tsx（摘要）
const code = searchParams.get('code');
if (code) {
  const { token, user } = await exchangeCodeForToken(code);
  saveAuthToken(token);
  router.replace(pathname); // 清除 URL 中的 code
}Code language: JavaScript (javascript)

向後端交換 JWT

// lib/sso.ts
const response = await fetch(`${NEXT_PUBLIC_API_URL}/auth-tokens/exchange`, {
  method: 'POST',
  headers: {
    'X-Client-Token': code,
  },
});

const jwt = response.headers.get('X-Auth-Token');Code language: JavaScript (javascript)

CORS： 後端已將 X-Auth-Token 加入 exposedHeaders，前端才能從 Response Header 讀取 JWT。

JWT 儲存與解析

登入成功後，JWT 儲存於 localStorage：

localStorage.setItem('authToken', jwt);Code language: JavaScript (javascript)

使用者資訊從 JWT Payload 解析（不需另外儲存使用者物件）：

實作位置：lib/sso.ts → parseJwtPayload()、authUserFromJwt()、isTokenExpired()

呼叫受保護 API

使用 lib/api.ts 封裝：

import { apiJson, apiFetch } from '@/lib/api';

// GET 範例
const events = await apiJson<Event[]>('/events');

// 自訂請求
const response = await apiFetch('/events', { method: 'GET' });Code language: JavaScript (javascript)

apiFetch 會自動：

1. 從 localStorage 讀取 authToken
2. 附加 Authorization: Bearer {JWT}
3. 收到 401 時清除 Token 並拋出 ApiError

UI 行為

Navbar 右上角

手機版 Overlay 選單亦有對應的登入按鈕與頭像連結。

個人頁同步

登入成功後，AuthContext 會將 JWT 中的使用者資料同步至 EventsContext，供 /profile 等頁面使用：

// role 對應
ROLE_ADMIN / ROLE_ACTIVITY_ADMIN / ROLE_VENUE_ADMIN → 'admin'
其餘 → 'user'Code language: JavaScript (javascript)

錯誤處理

SSO 回調錯誤

SSO 登入失敗時，會以 ?error={代碼} 跳轉回前端。AuthContext 以 Toast 提示使用者。

後端交換錯誤

後端回應格式（參考後端文件）：

{
  "errorCode": "SSO_ERROR",
  "message": "unauthorized",
  "status": 401
}Code language: JSON / JSON with Comments (json)

JWT 過期

• 頁面載入時：getStoredAuth() 檢查 exp，過期則視為未登入
• API 請求時：apiFetch 收到 401 自動清除 Token

建議後續在 401 時自動觸發 startSsoLogin() 引導重新登入。

安全性考量

1. Client Secret 不得出現在前端程式碼或環境變數中。
2. 授權碼一次性：取得 code 後應立即交換，並以 router.replace 清除 URL 參數。
3. HTTPS：生產環境 SSO 與 API 通訊必須使用 HTTPS。
4. Token 儲存：目前使用 localStorage 儲存 JWT。若需更高安全性，可改為 httpOnly Cookie（需後端配合 Set-Cookie）。
5. 不要在日誌中輸出 JWT 或授權碼。

本地測試

啟動步驟

npm install
# 建立 .env.local 並設定 NEXT_PUBLIC_API_URL
npm run devCode language: CSS (css)

測試流程

1. 確認後端已啟動，且 POST /api/auth-tokens/exchange 可正常運作
2. 開啟前端（預設 http://localhost:3000）
3. 點擊右上角「登入」
4. 完成 Google SSO 登入
5. 確認跳轉回前端後右上角顯示頭像
6. 點擊頭像進入 /profile，確認名稱與信箱正確
7. 開啟 DevTools → Application → Local Storage，確認存在 authToken

常見問題與解法

原始碼索引

與後端文件對照