> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/org/identity-sync.md).

# 身分同步（LDAP／SCIM）

設定 LDAP 或 SCIM 身分同步，自動將企業目錄服務的使用者與群組匯入 MaiAgent；LDAP 另支援以 LDAP 密碼直接登入平台

身分同步讓您將企業目錄服務（AD、JumpCloud、OpenLDAP 等）中的使用者與群組資料自動匯入 MaiAgent，免除逐一建立帳號的工作。搭配 **LDAP 帳密登入** 功能，員工更可直接使用企業既有密碼登入 MaiAgent，無需另外記憶。

若您的 IdP（Okta、Microsoft Entra ID、JumpCloud 等）支援 SCIM，也可以改選 SCIM，由 IdP 主動把人員與群組推送進來，見[選擇 SCIM 時的後台操作](#scim-setup)。

{% hint style="info" %}
身分同步（LDAP）為 **企業版** 專屬功能。如需啟用，請聯繫 MaiAgent 業務團隊升級至企業方案。
{% endhint %}

本頁內容：[使用場景](#use-cases)｜[跟 SSO 有什麼差別？](#difference-from-sso)｜[前置條件](#prerequisites)｜[進入身分同步設定](#enter-identity-sync-settings)｜[1. 連線設定](#connection-settings)｜[2. 同步範圍](#sync-scope)｜[3. 群組映射](#group-mapping)｜[4. 登入與同步](#login-and-sync)｜[5. 同步紀錄](#sync-history)｜[選擇 SCIM 時的後台操作](#scim-setup)｜[驗證同步是否成功](#verify-sync-success)｜[操作範例（以 JumpCloud 為例）](#jumpcloud-example)｜[常見問題](#faq)｜[附錄：不同 LDAP 系統連線範例](#appendix-ldap-connection-examples)｜[下一步](#next-steps)

## 使用場景 <a href="#use-cases" id="use-cases"></a>

1. **企業已有 AD / LDAP 目錄**：希望員工資料自動流入 MaiAgent，不想手動維護兩套名單
2. **離職帳號同步停用**：員工離職時在企業端停用帳號，MaiAgent 端也會同步失去存取權
3. **統一密碼管理**：希望員工只需記一組企業密碼，不要每個系統各一組
4. **部門權限映射**：依據企業目錄中的群組，自動賦予 MaiAgent 對應的角色權限
5. **大量使用者匯入**：初次導入 MaiAgent 時，一次性將 100+ 員工帶入平台

## 跟 SSO 有什麼差別？ <a href="#difference-from-sso" id="difference-from-sso"></a>

身分同步（LDAP）與 [第三方登入（SSO）](/org/sso.md) 都是企業級身分整合功能，但解決的問題不同：

| 比較面向          | 身分同步（LDAP）                      | 第三方登入（SSO）                                                 |
| ------------- | ------------------------------- | ---------------------------------------------------------- |
| **主要目的**      | 把「人」從企業目錄同步進 MaiAgent           | 讓使用者用企業帳號「登入」 MaiAgent                                     |
| **使用者建立**     | ✅ 同步時自動建立                       | ✅ 第一次登入時自動建立                                               |
| **登入方式**      | 啟用 Bind 登入後用企業密碼登入              | 跳轉企業 IdP 完成登入                                              |
| **群組 / 角色同步** | ✅ 自動依據群組映射                      | ⚠️ 只有 EIP 會在登入時同步角色；SAML、Keycloak、Cloudflare Access 不同步    |
| **離職停用**      | ✅ 下一次同步自動停用成員                   | ❌ 只擋下 SSO 登入，成員資格要另外停用，見[離職與停用成員](/org/sso.md#offboarding) |
| **常見整合對象**    | Microsoft AD、JumpCloud、OpenLDAP | Azure AD、Okta、Keycloak                                     |

兩者可同時啟用：用 SSO 負責跳轉登入、用 LDAP 同步維護帳號清單。

## 前置條件 <a href="#prerequisites" id="prerequisites"></a>

啟用 LDAP 身分同步前，請先備齊以下資訊：

### 您的 IT 窗口需要提供 <a href="#it-info-required" id="it-info-required"></a>

* **LDAP 伺服器位址**：例如 `ldaps://ad.company.com:636`
* **Base DN**：搜尋使用者的起點，例如 `DC=company,DC=com` 或 `ou=Users,o=<org>,dc=jumpcloud,dc=com`
* **Bind DN**：具備讀取權限的服務帳號完整 DN
* **Bind 密碼**：服務帳號的密碼
* **防火牆開通**：允許 MaiAgent 伺服器連線至您的 LDAP 伺服器（預設 port 636 for LDAPS、389 for LDAP）

### MaiAgent 端需要的權限 <a href="#maiagent-permissions-required" id="maiagent-permissions-required"></a>

* 只有 **組織擁有者（Owner）** 可以選擇同步方式、修改設定與觸發同步
* 角色具備 **身分同步權限** 的成員可以進入頁面檢視，但無法修改

{% hint style="warning" %}
**強烈建議使用 LDAPS（port 636）** 而非明文 LDAP（port 389）。LDAPS 會加密傳輸，避免密碼在網路上被竊取。
{% endhint %}

## 進入身分同步設定 <a href="#enter-identity-sync-settings" id="enter-identity-sync-settings"></a>

1. 從左側選單點選 <mark style="color:blue;">組織設定</mark> > <mark style="color:blue;">組織概覽</mark>
2. 點擊 <mark style="color:blue;">身份同步</mark> 進入設定頁面
3. 點擊 <mark style="color:blue;">選擇同步方式</mark>，在 Modal 中選擇 <mark style="color:blue;">LDAP</mark>（選擇 SCIM 時見[選擇 SCIM 時的後台操作](#scim-setup)）

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-79d17884ae20ce612b1521285258dc75b0c28e6f%2Fidentity-sync-08-change-sync-type.png?alt=media" alt="選擇同步方式"><figcaption><p>選擇同步方式 Modal，可選 LDAP 或 SCIM（SCIM 的端點與 Token 說明見技術人員手冊「成員開通：SCIM／邀請／SSO」）</p></figcaption></figure>

選擇 LDAP 後，會看到 5 個分頁：**連線設定**、**同步範圍**、**群組映射**、**登入與同步**、**同步紀錄**。接下來分別說明。

## 1. 連線設定 <a href="#connection-settings" id="connection-settings"></a>

第一步先建立 MaiAgent 與您 LDAP 伺服器的連線。填完四個欄位後，**務必先按「測試連線」驗證**，確認無誤再儲存。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-ec7886fd2ba0e5bc7776d41ed932d076c5a69d41%2Fidentity-sync-01-connection-tab.png?alt=media" alt="連線設定表單"><figcaption><p>連線設定分頁，填入伺服器位址、Base DN、Bind DN 與密碼</p></figcaption></figure>

### 各欄位填入規則 <a href="#field-fill-rules" id="field-fill-rules"></a>

| 欄位          | 說明                         | 範例（JumpCloud）                                            | 範例（AD）                                                 |
| ----------- | -------------------------- | -------------------------------------------------------- | ------------------------------------------------------ |
| **伺服器位址**   | LDAP 伺服器的連線位址，需帶協定與 port   | `ldaps://ldap.jumpcloud.com:636`                         | `ldaps://ad.company.com:636`                           |
| **Base DN** | 搜尋使用者的起點，必須包含 `DC=`（不分大小寫） | `ou=Users,o=<ORG_ID>,dc=jumpcloud,dc=com`                | `DC=company,DC=com`                                    |
| **Bind DN** | 用於驗證的服務帳號完整路徑              | `uid=svcaccount,ou=Users,o=<ORG_ID>,dc=jumpcloud,dc=com` | `CN=svc-maiagent,OU=ServiceAccounts,DC=company,DC=com` |
| **密碼**      | Bind DN 帳號的密碼              | —                                                        | —                                                      |

各欄位的具體值需要由您的 IT 窗口提供，實際串接案例可參考後方 [操作範例（以 JumpCloud 為例）](#jumpcloud-example) 章節。

### 測試連線 <a href="#test-connection" id="test-connection"></a>

填好欄位後按 <mark style="color:blue;">測試連線</mark>。成功時會顯示綠色「Connection successful」訊息與回應時間。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-08b93a2fe3e3ee13d49d8f813454379641365a3b%2Fidentity-sync-02-connection-success.png?alt=media" alt="連線測試成功"><figcaption><p>測試連線成功，顯示回應時間（約 200–300ms 為正常）</p></figcaption></figure>

{% hint style="warning" %}
**務必先測試連線再按儲存**。連線未驗證通過前，同步範圍與預覽清單等功能都無法使用。
{% endhint %}

### 常見錯誤 <a href="#common-errors" id="common-errors"></a>

| 錯誤訊息                  | 可能原因           | 處理方式                                      |
| --------------------- | -------------- | ----------------------------------------- |
| `Invalid credentials` | Bind DN 或密碼錯誤  | 確認 Bind DN 格式，密碼是否為最新                     |
| `Server unreachable`  | 伺服器位址錯誤或防火牆未開通 | 確認 URL、port，請 IT 開通 MaiAgent 連出該 LDAP 伺服器 |
| `Invalid DN syntax`   | Base DN 格式不符   | Base DN 必須包含 `DC=`，檢查逗號、層級是否正確            |
| `Timeout`             | 連線超過 10 秒仍無回應  | 確認 LDAP 伺服器正常運作、網路路由可達                    |

## 2. 同步範圍 <a href="#sync-scope" id="sync-scope"></a>

選擇要將 LDAP 中哪些使用者同步進 MaiAgent。支援兩種模式：

### 簡單模式（推薦） <a href="#simple-mode" id="simple-mode"></a>

勾選要同步的 **組織單位（OU）** 或 **群組（Group）**。勾選後下方可按 <mark style="color:blue;">預覽清單</mark> 確認會被同步的使用者。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-2a894cb2d34aad020dc5385b1c7699c305dd9703%2Fidentity-sync-03-scope-simple.png?alt=media" alt="同步範圍簡單模式"><figcaption><p>簡單模式，勾選要同步的 OU 或群組。右側數字表示該範圍內的使用者人數</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e7d6248df58dd4e856f7b4deffe7a84e8d346a70%2Fidentity-sync-04-user-preview.png?alt=media" alt="使用者預覽"><figcaption><p>按下「預覽清單」後，列出所有會被同步的使用者。支援 Email / 姓名搜尋</p></figcaption></figure>

{% hint style="info" %}
OU 與 Group **可同時勾選**。若一位使用者同時符合多個條件，只會被同步一次，群組對應關係會保留全部。
{% endhint %}

### 進階模式 <a href="#advanced-mode" id="advanced-mode"></a>

若需要更精細的篩選（例如「只同步職等 Manager 以上的工程部員工」），可切換到進階模式自訂 LDAP Filter。

常用 Filter 範例：

| 需求                        | LDAP Filter                                                                                                |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- |
| 只同步啟用中的使用者                | `(&(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))`                                   |
| 只同步特定部門                   | `(&(objectClass=user)(department=Engineering))`                                                            |
| 排除服務帳號                    | `(&(objectClass=user)(!(sAMAccountName=svc-*)))`                                                           |
| 同步 AD 群組的所有成員，包含巢狀子群組裡的成員 | `(&(objectClass=user)(mail=*)(memberOf:1.2.840.113556.1.4.1941:=CN=AI-Users,OU=Groups,DC=company,DC=com))` |

{% hint style="warning" %}
進階模式的 LDAP Filter 語法錯誤會讓同步失敗。若不熟悉 LDAP Filter，建議使用簡單模式並請 IT 協助調整 OU / Group 結構。
{% endhint %}

#### 同步 AD 巢狀群組的成員 <a href="#nested-ad-groups" id="nested-ad-groups"></a>

簡單模式勾選群組時，只會帶入**直接隸屬**該群組的使用者。若您的 AD 是「群組裡再放群組」的巢狀結構（例如 `AI-Users` 底下還有 `Sales-Team`、`RD-Team` 兩個子群組），子群組的成員不會被同步；先前已同步進來的帳號，若只剩子群組的隸屬關係，下一次同步也會被停用。

這時請改用進階模式，在群組條件加上 AD 的遞迴比對規則 `1.2.840.113556.1.4.1941`：

```
(&(objectClass=user)(mail=*)(memberOf:1.2.840.113556.1.4.1941:=CN=AI-Users,OU=Groups,DC=company,DC=com))
```

* `memberOf:1.2.840.113556.1.4.1941:=` 後面填上層群組的完整 DN，AD 會一路展開所有子群組的成員。
* `(mail=*)` 只取有 Email 的帳號。MaiAgent 以 Email 識別帳號，沒有 Email 的帳號會同步失敗。
* 這條規則是 Microsoft AD 的擴充比對規則，其他 LDAP 目錄服務不一定支援。儲存後請先按 <mark style="color:blue;">預覽清單</mark>，確認帶出的使用者與人數。
* 遞迴寫法只影響「同步哪些人」。[群組映射](#group-mapping) 仍依使用者帳號上 `memberOf` 屬性列出的群組對應角色，如需依子群組分配角色，請為子群組分別建立映射。

## 3. 群組映射 <a href="#group-mapping" id="group-mapping"></a>

設定 LDAP 群組與 MaiAgent 角色的對應關係。**未映射的群組會自動建立同名的 MaiAgent 角色**（可在此開關關閉）。

{% hint style="info" %}
**身分同步 vs 權限管理的分工**

身分同步只負責把「使用者」與「角色歸屬」從 LDAP 同步進 MaiAgent；**每個角色的具體權限範圍（可以用哪些功能、存取哪些資源）需要管理員先到** [角色權限管理](/org/roles/role-permission.md) **頁設定一次**。

設定完成後，之後新進員工只要在 LDAP 端加入對應的群組，就會自動同步進 MaiAgent 並取得該角色的權限 — 不需要管理員個別為每位新人設定。
{% endhint %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-2e27e9c4e521f84a761492f1719843e1a2818fbd%2Fidentity-sync-05-mapping.png?alt=media" alt="群組映射"><figcaption><p>群組映射分頁，可逐筆設定、或用檔案批次匯入</p></figcaption></figure>

### 操作選項 <a href="#mapping-options" id="mapping-options"></a>

* <mark style="color:blue;">新增映射</mark>：手動對應一個 LDAP 群組到 MaiAgent 角色
* <mark style="color:blue;">下載範本</mark>：取得範本檔，批次建立映射
* <mark style="color:blue;">匯入檔案</mark>：上傳填寫完成的檔案，接受 `.csv`、`.xlsx`、`.xls`
* <mark style="color:blue;">自動建立未映射的角色</mark>：預設開啟。同步時遇到尚未映射的 LDAP 群組，會自動在 MaiAgent 建立同名角色

### 映射範例 <a href="#mapping-examples" id="mapping-examples"></a>

| LDAP 群組       | MaiAgent 角色 | 用途                  |
| ------------- | ----------- | ------------------- |
| `Engineering` | `工程師`       | 工程部門共用角色            |
| `Finance`     | `財務`        | 財務部門共用角色            |
| `AI-Project`  | `AI 專案成員`   | 跨部門專案角色，成員可同時來自其他部門 |

{% hint style="info" %}
若員工屬於多個 LDAP 群組（例如同時在 `Engineering` 和 `AI-Project`），同步後會**同時被賦予兩個對應的 MaiAgent 角色**。
{% endhint %}

{% hint style="warning" %}
**「預設角色」不能被映射**：MaiAgent 的「預設角色」是系統角色，所有組織成員自動被指派，無法透過 LDAP 群組映射對應到。若您想讓全公司都有某個共通權限，請調整「預設角色」本身的權限設定，不要把它當成映射目標。
{% endhint %}

## 4. 登入與同步 <a href="#login-and-sync" id="login-and-sync"></a>

這一頁管兩件事：**LDAP 帳密登入開關** 和 **手動觸發同步**。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-06d3a4d73c43d27440449fae74dd5638c206b4bf%2Fidentity-sync-06-login-sync.png?alt=media" alt="登入與同步"><figcaption><p>登入與同步分頁，包含 Bind 登入開關、手動同步按鈕、上次同步結果</p></figcaption></figure>

### LDAP 帳密登入 <a href="#ldap-login" id="ldap-login"></a>

啟用後，同步進來的使用者可以直接用 **LDAP 密碼** 登入 MaiAgent，無需另外設定。

{% hint style="info" %}
啟用 LDAP 帳密登入後，使用者在 LDAP 目錄服務變更密碼會**立即生效**，不需要等下一次同步。
{% endhint %}

{% hint style="warning" %}
**啟用前置條件**：LDAP 連線已驗證、至少執行過一次同步。

**啟用後行為**：已同步的使用者其認證來源會批次變更為 LDAP，**MaiAgent 本地密碼失效**。若日後關閉此開關，使用者需請管理員重設密碼才能再次登入。
{% endhint %}

### 手動觸發同步 <a href="#manual-sync-trigger" id="manual-sync-trigger"></a>

按下 <mark style="color:blue;">立即執行同步</mark> 會從 LDAP 拉取最新資料並更新 MaiAgent。

* **自動同步**：系統預設每 30 分鐘自動同步一次，不需手動介入
* **冷卻時間**：手動同步有 60 秒冷卻限制，避免短時間重複觸發
* **同步動作**：包含「新增（Active 使用者）」、「更新（資料變更）」、「停用（LDAP 移出範圍或被 Suspended）」

### 上次同步結果 <a href="#last-sync-result" id="last-sync-result"></a>

顯示最近一次同步的統計摘要，包含新增、更新、停用、失敗的筆數。詳細明細請到 **同步紀錄** 分頁查看。

## 5. 同步紀錄 <a href="#sync-history" id="sync-history"></a>

查看每一次同步的完整明細：時間、動作、影響的使用者、觸發方式。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-1bc48706c021a96484ccbf72dcdbb299caab6845%2Fidentity-sync-07-logs.png?alt=media" alt="同步紀錄"><figcaption><p>同步紀錄分頁，可搜尋 Email / 姓名 / 角色，或以動作類型篩選</p></figcaption></figure>

### 動作類型 <a href="#action-types" id="action-types"></a>

| 動作     | 意義                               |
| ------ | -------------------------------- |
| **新增** | 使用者從 LDAP 第一次被同步進 MaiAgent       |
| **更新** | 使用者資料變更（姓名、Email、群組歸屬）           |
| **停用** | 使用者在 LDAP 被移出範圍、被 Suspended，或被刪除 |
| **失敗** | 該使用者同步失敗（詳見明細中的錯誤訊息）             |

### 紀錄詳情與重試 <a href="#log-detail-and-retry" id="log-detail-and-retry"></a>

點列表中任何一筆紀錄會開啟 <mark style="color:blue;">同步紀錄詳情</mark> 視窗，依這筆紀錄的內容顯示：

| 區塊       | 內容                                                                                    |
| -------- | ------------------------------------------------------------------------------------- |
| **使用者**  | 名稱與 Email                                                                             |
| **群組映射** | 這次套用的「LDAP 群組 → MaiAgent 角色」對應；角色是同步時自動建立的會帶 <mark style="color:blue;">自動建立</mark> 標籤 |
| **變更內容** | 更新類紀錄列出變更的欄位、舊值與新值                                                                    |
| **錯誤訊息** | 失敗類紀錄顯示失敗原因                                                                           |
| 底部       | 發生時間與觸發方式                                                                             |

失敗的紀錄在視窗右下角有 <mark style="color:blue;">重試</mark> 按鈕，只對這一位使用者重新執行同步，不必整批重跑；按下後顯示「重試已送出」，結果會成為一筆新紀錄。<mark style="color:blue;">重試</mark> 只有組織擁有者看得到，其他成員只能查看。SCIM 的同步紀錄也用同一個詳情視窗。

### 觸發方式 <a href="#trigger-methods" id="trigger-methods"></a>

* **手動**：由管理員在 **登入與同步** 分頁點擊「立即執行同步」
* **自動**：系統每 30 分鐘自動排程觸發

## 選擇 SCIM 時的後台操作 <a href="#scim-setup" id="scim-setup"></a>

SCIM 由您的 IdP 主動把使用者與群組推送到 MaiAgent。和 LDAP 不同，MaiAgent 不會連到您的目錄讀取資料，所以沒有連線測試、同步範圍與排程，人員異動在 IdP 推送的當下就生效。

1. 在 <mark style="color:blue;">選擇同步方式</mark>（已啟用其他方式時為 <mark style="color:blue;">變更方式</mark>）視窗選擇 <mark style="color:blue;">SCIM</mark>，按 <mark style="color:blue;">確認變更</mark>。在 LDAP 與 SCIM 之間切換時，原本的設定（含 Token、群組映射）會保留，可以再切回來。
2. 設定頁會出現三個分頁：<mark style="color:blue;">連線資訊</mark>、<mark style="color:blue;">群組映射</mark>、<mark style="color:blue;">同步紀錄</mark>。

### 連線資訊 <a href="#scim-connection" id="scim-connection"></a>

| 項目                                            | 操作                                                                                                                                                                         |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Endpoint URL</mark> | 按 <mark style="color:blue;">複製</mark>，填進 IdP 的 SCIM 設定                                                                                                                     |
| Token                                         | 按 <mark style="color:blue;">重新產生 Token</mark> 取得。新的 Token **只顯示一次**，複製保存後再按 <mark style="color:blue;">我已複製</mark>。重新產生後舊 Token 立即失效，IdP 端要一併更新；Token 建立超過 180 天時，頁面會提醒重新產生 |

{% hint style="warning" %}
**SCIM 同步需搭配 SSO**：SCIM 新建立的帳號沒有密碼，成員要登入 MaiAgent 時必須透過 SSO。分頁上方的提醒可按 <mark style="color:blue;">前往認證設定</mark>，設定 Keycloak 或 SAML，見[第三方登入（SSO）](/org/sso.md)。
{% endhint %}

### 群組映射 <a href="#scim-mapping" id="scim-mapping"></a>

設定 IdP 群組對應哪個 MaiAgent 角色，IdP 推送的使用者會依映射加入對應角色。<mark style="color:blue;">IdP 群組</mark> 請填 IdP 端群組的 displayName。<mark style="color:blue;">新增映射</mark>、<mark style="color:blue;">下載範本</mark>、<mark style="color:blue;">匯入檔案</mark> 的操作與 LDAP 的[群組映射](#group-mapping)相同。

<mark style="color:blue;">自動建立未映射的角色</mark> 開啟時，IdP 推送映射表裡沒有的群組，會自動建立同名角色。自動建立的角色沒有任何權限，請到 [角色權限管理](/org/roles/role-permission.md) 設定；建議先建好角色並設定權限，再建立映射。

### 同步紀錄 <a href="#scim-logs" id="scim-logs"></a>

IdP 每次推送造成的新增、更新、停用都會記錄在這裡，觸發方式顯示為「SCIM 推送」。點任一筆可看詳情，失敗的紀錄可由擁有者重試，見 [紀錄詳情與重試](#log-detail-and-retry)。

### 啟用 SCIM 後成員會怎樣 <a href="#scim-member-behavior" id="scim-member-behavior"></a>

* **既有成員**：啟用 SCIM 不會讓既有帳號的密碼或 SSO 登入失效，也不會停用 IdP 沒有推送的成員。IdP 推送的 Email 和既有成員相同時，該成員改由 SCIM 管理：之後姓名以 IdP 為準，在 IdP 停用或移除就會跟著停用。
* **停用**：IdP 停用或移除使用者時，MaiAgent 停用該成員並刪除其 API Key；對話與額度紀錄保留，重新啟用後角色恢復。組織的最後一位擁有者不會被停用。
* **由 SCIM 管理的成員**，請在 IdP 端停用或移除，不要只在 MaiAgent 後台處理。

SCIM 的端點、欄位與停用語意，以及 Okta、Microsoft Entra ID 的設定方式，見技術人員手冊 [成員開通：SCIM／邀請／SSO](https://docs.maiagent.ai/tech/identity-and-access/member-provisioning#scim)。

## 驗證同步是否成功 <a href="#verify-sync-success" id="verify-sync-success"></a>

執行同步後，透過以下三個地方可以確認使用者是否正確匯入、LDAP 群組是否對應到 MaiAgent 角色。

### 驗證 1：到成員管理頁查看使用者 <a href="#verify-1-member-management" id="verify-1-member-management"></a>

進入 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">組織概覽</mark> → <mark style="color:blue;">管理操作</mark> → <mark style="color:blue;">編輯成員</mark>，LDAP 同步進來的使用者會出現在列表中。以 Email 搜尋可快速定位特定使用者。

每位使用者的「角色」欄位會顯示其所屬的 MaiAgent 角色，例如 One Chen 對應到 `Group 1` 與 `Group 2` 兩個角色，反映了他在 LDAP 端同時屬於這兩個群組。

{% hint style="warning" %}
**成員列表不顯示「來源」欄位**，LDAP 同步的使用者與手動邀請的成員在列表上看起來相同。要明確追溯某位使用者是否來自 LDAP，請到 <mark style="color:blue;">身份同步</mark> > <mark style="color:blue;">同步紀錄</mark> 搜尋該 Email。
{% endhint %}

### 驗證 2：到角色權限管理頁查看角色 <a href="#verify-2-role-permission-management" id="verify-2-role-permission-management"></a>

進入 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">組織概覽</mark> → <mark style="color:blue;">管理操作</mark> → <mark style="color:blue;">編輯角色權限</mark>，LDAP 群組映射對應的角色會出現在列表中，「成員」欄位顯示目前透過同步加入此角色的使用者。

以範例中的 LDAP 群組為例，角色列表會呈現：

* `Group 1` 有兩位成員（Two Chen、One Chen），對應 LDAP 端 Group 1 的成員
* `Group 2` 有兩位成員（Three Chen、One Chen），對應 LDAP 端 Group 2 的成員
* One Chen 同時出現在兩個角色中，代表他在 LDAP 端屬於兩個群組
* 這些角色外觀與手動建立的角色相同，可以點進去調整權限範圍

### 驗證 3：到同步紀錄查執行歷程 <a href="#verify-3-sync-history" id="verify-3-sync-history"></a>

進入 <mark style="color:blue;">身份同步</mark> > <mark style="color:blue;">同步紀錄</mark>，可以看到每一次同步的時間、動作（新增 / 更新 / 停用）、對應使用者、觸發方式。這是判斷「同步有沒有失敗、失敗在哪位」的唯一地方。

### 不同驗證需求的對照表 <a href="#verification-comparison-table" id="verification-comparison-table"></a>

| 想知道什麼               | 去哪裡看                                                           |
| ------------------- | -------------------------------------------------------------- |
| 使用者有沒有匯入成功          | <mark style="color:blue;">成員管理</mark> 列表，以 Email 搜尋            |
| 使用者被分到哪些角色          | <mark style="color:blue;">成員管理</mark> 列表，該使用者的「角色」欄位           |
| LDAP 群組有沒有變成角色      | <mark style="color:blue;">角色權限</mark> 列表                       |
| 某角色實際有哪些成員          | <mark style="color:blue;">角色權限</mark> 列表，該角色的「成員」欄位            |
| 某使用者是 LDAP 同步還是手動新增 | <mark style="color:blue;">同步紀錄</mark>，以 Email 搜尋，有紀錄代表 LDAP 同步 |
| 同步有沒有失敗、失敗原因        | <mark style="color:blue;">同步紀錄</mark>，以「失敗」篩選動作類型              |
| 上次同步帶進 / 停用幾位       | <mark style="color:blue;">登入與同步</mark>，「上次同步結果」統計              |

### 操作建議 <a href="#operation-recommendations" id="operation-recommendations"></a>

啟用身分同步後，在成員 / 角色管理頁做部分手動操作會和 LDAP 衝突，請注意以下事項。

**成員管理頁**：

| 操作                    | 後果                    |
| --------------------- | --------------------- |
| 手動刪除 LDAP 同步的使用者      | 下次同步會再次建立             |
| 直接改 LDAP 同步使用者的 Email | 同步時會以 LDAP 為準覆蓋       |
| 啟用 Bind 登入後手動重設密碼     | 本地密碼不可用，密碼只能在 LDAP 端改 |

**角色權限管理頁**：

| 操作              | 後果                                                               |
| --------------- | ---------------------------------------------------------------- |
| 刪除 LDAP 映射對應的角色 | 下次同步若開啟「自動建立未映射的角色」會重建                                           |
| 手動在該角色中增減成員     | 下次同步時成員名單會以 LDAP 群組為準覆蓋                                          |
| 重命名角色           | 與 LDAP 群組的關聯會斷裂，建議改在 <mark style="color:blue;">群組映射</mark> 頁重新對應 |

{% hint style="info" %}
**簡單原則**：**權限由 MaiAgent 角色控制、成員歸屬由 LDAP 群組控制**。想改權限去角色設定、想改誰在哪個群組去 LDAP 端。
{% endhint %}

### 角色權限的首次設定 <a href="#initial-role-permission-setup" id="initial-role-permission-setup"></a>

同步完成後，新建立的角色（例如 `Group 1`、`Group 2`）**預設沒有任何權限**。請到 [角色權限管理](/org/roles/role-permission.md) 頁為每個角色設定：

* **功能權限**：這個角色能使用哪些功能（Agent、知識庫、客服對話…）
* **資源存取**：能存取哪些特定的 Agent、知識庫、資料庫

**每個角色只需要設定一次**。之後該角色的新成員（從 LDAP 同步進來的）會自動繼承這些權限，不需要管理員為每位新人個別分配。

## 操作範例（以 JumpCloud 為例） <a href="#jumpcloud-example" id="jumpcloud-example"></a>

以下是以 JumpCloud 為 LDAP 伺服器的完整串接流程。**其他系統（Microsoft AD、OpenLDAP 等）步驟相同，差別只在各欄位的格式**，可參考文末附錄的對照表。

### Step 1：在 JumpCloud 找到連線資訊 <a href="#step-1-find-connection-info" id="step-1-find-connection-info"></a>

登入 [JumpCloud Admin](https://console.jumpcloud.com)，進 <mark style="color:blue;">Access</mark> > <mark style="color:blue;">LDAP</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-0cd0ae758364454b886ca48d96daa245a9ad6b99%2Fidentity-sync-jumpcloud-02-ldap-page.png?alt=media" alt="JumpCloud LDAP 頁"><figcaption><p>JumpCloud Admin 左側選單 Access > LDAP</p></figcaption></figure>

點進 **JumpCloud LDAP** Directory，複製頁面中的 **ORG DN**。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b7cb9e559e365b6959d50025ec4c20655a58e53c%2Fidentity-sync-jumpcloud-03-ldap-details.png?alt=media" alt="JumpCloud LDAP Directory 詳細頁"><figcaption><p>JumpCloud LDAP Directory 詳細頁，<strong>ORG DN</strong> 欄位的值就是您需要的組織識別碼</p></figcaption></figure>

### Step 2：確認使用者已啟用 LDAP Bind DN <a href="#step-2-enable-ldap-bind-dn" id="step-2-enable-ldap-bind-dn"></a>

點進任一使用者（例如 `bob.chen`）> 切換到 <mark style="color:blue;">Directories</mark> 分頁 > 確認該使用者已綁定 JumpCloud LDAP 並標示為 **LDAP Bind DN**。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-219c0c0f84e45701269ca7d12ab12f64040c625d%2Fidentity-sync-jumpcloud-06-user-ldap-bind-dn.png?alt=media" alt="使用者 LDAP Bind DN"><figcaption><p>使用者詳細頁 > Directories，確認已綁定 LDAP Bind DN</p></figcaption></figure>

{% hint style="warning" %}
**Bind DN 帳號必須是 LDAP Bind DN**。若用一般使用者當 Bind DN 且未勾選此選項，連線會失敗。
{% endhint %}

### Step 3：組合連線參數 <a href="#step-3-compose-connection-params" id="step-3-compose-connection-params"></a>

以 ORG DN 為 `o=69de10c5be030ec43849f7a1,dc=jumpcloud,dc=com` 為例：

| 欄位      | 值                                                                      |
| ------- | ---------------------------------------------------------------------- |
| 伺服器位址   | `ldaps://ldap.jumpcloud.com:636`                                       |
| Base DN | `ou=Users,o=69de10c5be030ec43849f7a1,dc=jumpcloud,dc=com`              |
| Bind DN | `uid=bob.chen,ou=Users,o=69de10c5be030ec43849f7a1,dc=jumpcloud,dc=com` |
| 密碼      | Bob Chen 的 JumpCloud 密碼                                                |

### Step 4：在 MaiAgent 填入並測試 <a href="#step-4-fill-and-test" id="step-4-fill-and-test"></a>

貼到 MaiAgent 連線設定，按 <mark style="color:blue;">測試連線</mark>，看到綠色「Connection successful」即可儲存。

### Step 5：設定同步範圍並執行 <a href="#step-5-set-sync-scope" id="step-5-set-sync-scope"></a>

切到 **同步範圍** 勾 `ou=Users`，儲存 → 到 **登入與同步** 按 <mark style="color:blue;">立即執行同步</mark> → 到 **同步紀錄** 確認使用者已新增。

## 常見問題 <a href="#faq" id="faq"></a>

### Q1. 測試連線顯示「Invalid credentials」，但我確定密碼是對的 <a href="#faq-invalid-credentials" id="faq-invalid-credentials"></a>

檢查三個地方：

1. **Bind DN 格式**：確認完整路徑，包含所有 `ou=`、`dc=` 層級
2. **LDAP Bind DN 勾選**（JumpCloud）：進該使用者 > Directories > 確認有勾「Enable as LDAP Bind DN」
3. **密碼特殊字元**：若密碼含有 `$`、`!` 等字元，在某些系統中需要 escape

### Q2. 為什麼有些使用者沒被同步進來？ <a href="#faq-some-users-not-synced" id="faq-some-users-not-synced"></a>

查以下項目：

* 使用者狀態在 LDAP 是否為 **Active**（JumpCloud 的 Staged / Suspended 不會同步）
* 是否在勾選的 OU / Group 範圍內（進階模式則需符合 Filter 條件）
* 使用者的 Email 欄位是否為空（MaiAgent 以 Email 為唯一識別，缺 Email 會跳過）

到 <mark style="color:blue;">同步紀錄</mark> 可以看到詳細的失敗原因。

### Q3. 可以只同步特定部門嗎？ <a href="#faq-sync-specific-department" id="faq-sync-specific-department"></a>

可以。兩種做法：

* **簡單模式**：在 LDAP 裡把該部門獨立成一個 OU 或 Group，在 MaiAgent 只勾該項目
* **進階模式**：用自訂 LDAP Filter，例如 `(&(objectClass=user)(department=Engineering))`

### Q4. 員工改了 LDAP 密碼，MaiAgent 這邊要等同步嗎？ <a href="#faq-ldap-password-change" id="faq-ldap-password-change"></a>

**不用**。只要啟用了 **LDAP 帳密登入**，使用者用新密碼登入時 MaiAgent 會即時向 LDAP 驗證，完全即時生效。

### Q5. 啟用 LDAP 帳密登入後，原本 MaiAgent 的本地密碼還能用嗎？ <a href="#faq-local-password-after-ldap" id="faq-local-password-after-ldap"></a>

**不能**。啟用後所有已同步的使用者認證來源會變為 LDAP，原本的 MaiAgent 密碼被設為不可用。使用者只能用 LDAP 密碼登入。

若之後關閉此開關，使用者需請管理員重設密碼後才能再次登入。

### Q6. 員工離職了，MaiAgent 這邊會自動停用嗎？ <a href="#faq-offboarding-auto-disable" id="faq-offboarding-auto-disable"></a>

會。在 LDAP 端把使用者 Suspend 或 Disable 後，下一次同步（手動或 30 分鐘自動）MaiAgent 就會將其停用。若啟用了 Bind 登入，該員工當下就無法再登入。

### Q7. LDAP 群組改名或刪除，MaiAgent 會怎樣？ <a href="#faq-ldap-group-rename-delete" id="faq-ldap-group-rename-delete"></a>

* **群組改名**：MaiAgent 端的原角色名稱不會自動改名；建議手動更新對應的群組映射
* **群組刪除**：若已建立映射，映射會保留但該 LDAP 群組下無使用者；建議手動清理

### Q8. 自動同步是每幾分鐘一次？可以調整嗎？ <a href="#faq-auto-sync-interval" id="faq-auto-sync-interval"></a>

目前是固定每 30 分鐘一次，尚不支援客製化週期。若有急迫需求，可用「立即執行同步」手動觸發。

### Q9. 為什麼帳號一直被停用？ <a href="#faq-account-keeps-disabled" id="faq-account-keeps-disabled"></a>

每次同步（每 30 分鐘自動，或手動按 <mark style="color:blue;">立即執行同步</mark>）時，透過 LDAP 同步管理的帳號只要符合下列任一情況就會被停用，同時刪除該成員的 API Key：

1. **帳號不在圈選的範圍內**：使用者不在勾選的 OU 底下，也不直接隸屬勾選的群組。最常見的是 AD 巢狀群組：使用者只在子群組裡，簡單模式不會帶入，請改用 [巢狀群組的遞迴寫法](#nested-ad-groups)。
2. **帳號在目錄中被停用或鎖定**：AD 帳號被停用（`userAccountControl` 帶有停用旗標），或 JumpCloud、OpenLDAP 的帳號被鎖定（設有 `pwdAccountLockedTime`）。
3. **帳號沒有 Email，或 Email 改過**：MaiAgent 以 Email 識別帳號，目錄端 Email 改了以後，同步會以新 Email 建立新帳號，舊 Email 的帳號則被視為已離開範圍而停用。

原因沒有排除前，帳號會一直維持停用；在目錄端或同步範圍排除原因後，下一次同步就會自動重新啟用該帳號。到 <mark style="color:blue;">同步紀錄</mark> 以 <mark style="color:blue;">停用</mark> 篩選，可以看到每次被停用的帳號與時間。

{% hint style="info" %}
**兩道防護**：組織的最後一位擁有者不會被停用，同步紀錄會記為失敗並顯示「無法停用最後一位擁有者」；LDAP 回傳 0 位使用者時（例如同步範圍內沒有任何帳號），系統會整次跳過停用，避免誤停全部帳號。
{% endhint %}

## 附錄：不同 LDAP 系統連線範例 <a href="#appendix-ldap-connection-examples" id="appendix-ldap-connection-examples"></a>

### Microsoft Active Directory <a href="#microsoft-active-directory" id="microsoft-active-directory"></a>

| 欄位      | 值                                                      |
| ------- | ------------------------------------------------------ |
| 伺服器位址   | `ldaps://ad.company.com:636`                           |
| Base DN | `DC=company,DC=com`                                    |
| Bind DN | `CN=svc-maiagent,OU=ServiceAccounts,DC=company,DC=com` |

### JumpCloud <a href="#jumpcloud" id="jumpcloud"></a>

| 欄位      | 值                                                        |
| ------- | -------------------------------------------------------- |
| 伺服器位址   | `ldaps://ldap.jumpcloud.com:636`                         |
| Base DN | `ou=Users,o=<ORG_ID>,dc=jumpcloud,dc=com`                |
| Bind DN | `uid=<username>,ou=Users,o=<ORG_ID>,dc=jumpcloud,dc=com` |

### OpenLDAP / FreeIPA <a href="#openldap-freeipa" id="openldap-freeipa"></a>

| 欄位      | 值                                            |
| ------- | -------------------------------------------- |
| 伺服器位址   | `ldaps://ldap.company.local:636`             |
| Base DN | `dc=company,dc=local`                        |
| Bind DN | `uid=maiagent,ou=system,dc=company,dc=local` |

### Azure AD（Entra ID） <a href="#azure-ad-entra-id" id="azure-ad-entra-id"></a>

Azure AD 本身不開 LDAP port，但可以透過 **Azure AD Domain Services（AADDS）** 這個 Azure 付費 add-on 提供 LDAP 介面。若您的企業使用 Azure AD，可以走以下任一路徑：

| 目的             | 建議做法                                                         |
| -------------- | ------------------------------------------------------------ |
| 同步使用者          | 啟用 AADDS，把 AADDS 當成 LDAP 伺服器填入（欄位格式與 Microsoft AD 相同）        |
| 登入認證           | 直接使用 [第三方登入（SSO）](/org/sso.md) 搭配 SAML / OAuth，不需走 LDAP Bind |
| 同時有 on-prem AD | 直接當 Microsoft AD 串接，不需 AADDS                                 |

{% hint style="info" %}
若您只想讓員工用 Azure AD 帳號 **登入** MaiAgent、不需要同步使用者資料，請直接看 [第三方登入（SSO）](/org/sso.md) 文件，不需這份身分同步手冊。
{% endhint %}

## 下一步 <a href="#next-steps" id="next-steps"></a>

* [第三方登入（SSO）](/org/sso.md) — 搭配使用可讓員工直接用企業帳號跳轉登入
* [角色權限管理](/org/roles/role-permission.md) — 群組映射對應到的角色在此頁設計權限範圍
* [成員管理](/org/overview/member.md) — 查看所有組織成員，含 LDAP 同步與手動邀請


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/org/identity-sync.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.