# Keycloak 整合

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

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

**主要優勢**：

* 支援 Keycloak Realm 隔離
* 自動合成虛擬 Email 身份，適用於無 Email 的帳號
* 支援伺服器端 Token 撤銷（Logout）
* 整合 Keycloak 生態系的各項功能

## 設定步驟 <a href="#setup-steps" id="setup-steps"></a>

### 1. 在 Keycloak 中建立 Client <a href="#step-1-create-client" id="step-1-create-client"></a>

1. 登入 Keycloak Admin Console
2. 選擇目標 Realm
3. 在 <mark style="color:blue;">Clients</mark> 中新增一個 Client
4. 設定 Client Protocol 為 `openid-connect`
5. 設定 Access Type 為 `public`（或根據安全需求選擇 `confidential`）
6. 設定 Valid Redirect URIs 為 MaiAgent 的前端域名
7. 記下 Client ID

### 2. 在 MaiAgent 後台填寫 Keycloak 設定 <a href="#step-2-fill-keycloak-settings" id="step-2-fill-keycloak-settings"></a>

<figure><img src="/files/iFPoaFWktENIy6r5fRYP" alt="Keycloak 設定"><figcaption><p>Keycloak 認證設定：填寫認證來源名稱、Email Domain 與伺服器 URL</p></figcaption></figure>

選擇 <mark style="color:blue;">Keycloak</mark> 認證類型後，需要填寫以下欄位：

| 欄位           | 必填 | 說明                                                  |
| ------------ | -- | --------------------------------------------------- |
| 認證來源名稱       | 是  | 用作 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. 儲存並測試 <a href="#step-3-save-and-test" id="step-3-save-and-test"></a>

在 MaiAgent 後台點擊 <mark style="color:blue;">儲存</mark>，然後使用產生的 Login URL 測試登入流程。

## Keycloak 虛擬 Email 機制 <a href="#keycloak-virtual-email-mechanism" id="keycloak-virtual-email-mechanism"></a>

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

```
虛擬 Email = {preferred_username}@{email_domain}
```

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

{% hint style="info" %}
此虛擬 Email 僅作為系統內部識別用途，不會用於實際的 Email 發送。
{% endhint %}

## Keycloak 登出 <a href="#keycloak-logout" id="keycloak-logout"></a>

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

## 設定欄位速查表 <a href="#settings-quick-reference" id="settings-quick-reference"></a>

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/org/sso/sso-keycloak.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.