Keycloak 整合

透過 OpenID Connect 協定整合 Keycloak 開源身分驗證平台

Keycloak 是一套廣泛使用的開源身分驗證與存取管理平台，MaiAgent 支援透過 OpenID Connect 協定與 Keycloak 整合。

適用對象：使用 Keycloak 做統一身分管理的企業，或需要以 Realm 為單位管理使用者的組織

主要優勢：

• 支援 Keycloak Realm 隔離

• 自動合成虛擬 Email 身份，適用於無 Email 的帳號

• 支援伺服器端 Token 撤銷（Logout）

• 整合 Keycloak 生態系的各項功能

設定步驟

1. 在 Keycloak 中建立 Client

1. 登入 Keycloak Admin Console

2. 選擇目標 Realm

3. 在 Clients 中新增一個 Client

4. 設定 Client Protocol 為 openid-connect

5. 設定 Access Type 為 public（或根據安全需求選擇 confidential）

6. 設定 Valid Redirect URIs 為 MaiAgent 的前端域名

7. 記下 Client ID

2. 在 MaiAgent 後台填寫 Keycloak 設定

Keycloak 認證設定：填寫認證來源名稱、Email Domain 與伺服器 URL

選擇 Keycloak 認證類型後，需要填寫以下欄位：

欄位	必填	說明
認證來源名稱	是	用作 Realm 名稱對應，建議使用 Keycloak Realm 名稱
Email Domain	是	用於合成虛擬 Email 的網域，例如 company.com
Server URL	是	Keycloak 伺服器 URL，例如 https://keycloak.company.com/

填寫完成後，系統會自動產生 Login URL，格式為：

https://{前端域名}/auth/keycloak?url={Server URL}&clientId={Client ID}&realm={Realm}

3. 儲存並測試

在 MaiAgent 後台點擊 儲存，然後使用產生的 Login URL 測試登入流程。

Keycloak 虛擬 Email 機制

由於 Keycloak 的使用者不一定有 Email 地址，MaiAgent 會自動合成虛擬 Email 作為唯一識別：

虛擬 Email = {preferred_username}@{email_domain}

例如：使用者 john.doe 在 Email Domain 為 company.com 的設定下，會產生 [email protected] 作為 MaiAgent 的使用者 Email。

此虛擬 Email 僅作為系統內部識別用途，不會用於實際的 Email 發送。

Keycloak 登出

MaiAgent 的 Keycloak 整合支援伺服器端登出。當使用者在 MaiAgent 登出時，系統會同時向 Keycloak 伺服器發送 Token 撤銷請求，確保 Token 在 Keycloak 端也失效。

設定欄位速查表

欄位	必填	格式	範例
認證來源名稱	是	小寫英數 + 連字號，max 31 字元	company-kc
Email Domain	是	網域格式	company.com
Server URL	是	HTTPS URL	https://keycloak.company.com/