# 身份同步（LDAP）

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

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

## 使用場景

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

## 跟 SSO 有什麼差別？

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

| 比較面向          | 身份同步（LDAP）                      | 第三方登入（SSO）             |
| ------------- | ------------------------------- | ---------------------- |
| **主要目的**      | 把「人」從企業目錄同步進 MaiAgent           | 讓使用者用企業帳號「登入」 MaiAgent |
| **使用者建立**     | ✅ 自動建立                          | ❌ 需搭配 JIT 或事先建立        |
| **登入方式**      | 啟用 Bind 登入後用企業密碼登入              | 跳轉企業 IdP 完成登入          |
| **群組 / 角色同步** | ✅ 自動依據群組映射                      | ⚠️ 視 IdP 與整合方式而定       |
| **常見整合對象**    | Microsoft AD、JumpCloud、OpenLDAP | Azure AD、Okta、Keycloak |

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

## 前置條件

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

### 您的 IT 窗口需要提供

* **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 端需要的權限

* 具備 **組織擁有者（Owner）** 或具備 **組織管理權限** 的角色

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

## 進入身份同步設定

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>

<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 即將推出</p></figcaption></figure>

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

## 1. 連線設定

第一步先建立 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>

### 各欄位填入規則

| 欄位          | 說明                         | 範例（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-為例) 章節。

### 測試連線

填好欄位後按 <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 %}

### 常見錯誤

| 錯誤訊息                  | 可能原因           | 處理方式                                      |
| --------------------- | -------------- | ----------------------------------------- |
| `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. 同步範圍

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

### 簡單模式（推薦）

勾選要同步的 **組織單位（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 %}

### 進階模式

若需要更精細的篩選（例如「只同步職等 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-*)))`                         |

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

## 3. 群組映射

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

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

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

設定完成後，之後新進員工只要在 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>群組映射分頁，可逐筆設定、或用 CSV 批次匯入</p></figcaption></figure>

### 操作選項

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

### 映射範例

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

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

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

## 4. 登入與同步

這一頁管兩件事：**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 帳密登入

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

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

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

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

### 手動觸發同步

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

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

### 上次同步結果

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

## 5. 同步紀錄

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

<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>

### 動作類型

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

### 觸發方式

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

## 驗證同步是否成功

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

### 驗證 1：到成員管理頁查看使用者

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-1b59d26cb3a1913d4b89acf91e663ac9591fc4e6%2Fidentity-sync-09-members-after-sync.png?alt=media" alt="成員列表，含 LDAP 同步使用者"><figcaption><p>成員管理列表，LDAP 同步進來的 Chen 家族與原本手動邀請的成員並列</p></figcaption></figure>

每位使用者的「角色」欄位會顯示其所屬的 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：到角色權限管理頁查看角色

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-91f0770e75426cb92145fa4e4c7c451c566745bf%2Fidentity-sync-10-roles-after-sync.png?alt=media" alt="角色權限管理列表"><figcaption><p>角色權限管理列表，Group 1 與 Group 2 是 LDAP 同步時自動建立的角色</p></figcaption></figure>

從上圖可以看到：

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

### 驗證 3：到同步紀錄查執行歷程

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

### 不同驗證需求的對照表

| 想知道什麼               | 去哪裡看                                                           |
| ------------------- | -------------------------------------------------------------- |
| 使用者有沒有匯入成功          | <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>，「上次同步結果」統計              |

### 操作建議

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

**成員管理頁**：

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

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

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

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

### 角色權限的首次設定

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

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

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

## 操作範例（以 JumpCloud 為例）

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

### Step 1：在 JumpCloud 找到連線資訊

登入 [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

點進任一使用者（例如 `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：組合連線參數

以 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 填入並測試

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

### Step 5：設定同步範圍並執行

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

## 常見問題

### Q1. 測試連線顯示「Invalid credentials」，但我確定密碼是對的

檢查三個地方：

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

### Q2. 為什麼有些使用者沒被同步進來？

查以下項目：

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

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

### Q3. 可以只同步特定部門嗎？

可以。兩種做法：

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

### Q4. 員工改了 LDAP 密碼，MaiAgent 這邊要等同步嗎？

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

### Q5. 啟用 LDAP 帳密登入後，原本 MaiAgent 的本地密碼還能用嗎？

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

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

### Q6. 員工離職了，MaiAgent 這邊會自動停用嗎？

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

### Q7. LDAP 群組改名或刪除，MaiAgent 會怎樣？

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

### Q8. 自動同步是每幾分鐘一次？可以調整嗎？

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

## 附錄：不同 LDAP 系統連線範例

### Microsoft Active Directory

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

### JumpCloud

| 欄位      | 值                                                        |
| ------- | -------------------------------------------------------- |
| 伺服器位址   | `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

| 欄位      | 值                                            |
| ------- | -------------------------------------------- |
| 伺服器位址   | `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）

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

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

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

## 下一步

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


---

# 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/identity-sync.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.