> 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/maiagent-user-guide/en/org/identity-sync.md).

# Identity Synchronization (LDAP)

Configure LDAP identity synchronization to automatically import users and groups from your enterprise directory service into MaiAgent, with support for signing in directly to the platform using LDAP p

Identity synchronization automatically imports user and group data from enterprise directory services such as AD, JumpCloud, and OpenLDAP into MaiAgent, eliminating the need to create accounts individually. With **LDAP credential login**, employees can also sign in to MaiAgent using their existing enterprise passwords without having to remember another one.

{% hint style="info" %}
Identity Synchronization (LDAP) is available exclusively with the **Enterprise plan**. To enable it, contact the MaiAgent sales team to upgrade to the Enterprise plan.
{% endhint %}

## Use Cases <a href="#use-cases" id="use-cases"></a>

1. **Your organization already has an AD / LDAP directory**: Automatically import employee data into MaiAgent instead of maintaining two separate user lists
2. **Automatically deactivate departing employees' accounts**: When an employee's account is deactivated in the enterprise directory, their access to MaiAgent is also revoked during synchronization
3. **Centralized password management**: Let employees remember only one enterprise password instead of a different password for every system
4. **Map department permissions**: Automatically assign corresponding MaiAgent role permissions based on groups in the enterprise directory
5. **Bulk user import**: Import more than 100 employees into the platform at once during the initial MaiAgent rollout

## How Is This Different from SSO? <a href="#difference-from-sso" id="difference-from-sso"></a>

Identity Synchronization (LDAP) and [Third-Party Login (SSO)](/maiagent-user-guide/en/org/sso.md) are both enterprise identity integration features, but they solve different problems:

| Comparison                       | Identity Synchronization (LDAP)                                  | Third-Party Login (SSO)                                  |
| -------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------- |
| **Primary purpose**              | Synchronize “people” from the enterprise directory into MaiAgent | Let users “sign in” to MaiAgent with enterprise accounts |
| **User creation**                | ✅ Automatic                                                      | ❌ Requires JIT or prior creation                         |
| **Sign-in method**               | Use an enterprise password after Bind login is enabled           | Redirect to the enterprise IdP to complete sign-in       |
| **Group / role synchronization** | ✅ Automatic based on group mappings                              | ⚠️ Depends on the IdP and integration method             |
| **Common integrations**          | Microsoft AD, JumpCloud, OpenLDAP                                | Azure AD, Okta, Keycloak                                 |

You can enable both at the same time: use SSO for redirected sign-in and LDAP synchronization to maintain the account list.

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before enabling LDAP identity synchronization, prepare the following information:

### Information Required from Your IT Contact <a href="#it-info-required" id="it-info-required"></a>

* **LDAP server address**: For example, `ldaps://ad.company.com:636`
* **Base DN**: The starting point for user searches, such as `DC=company,DC=com` or `ou=Users,o=<org>,dc=jumpcloud,dc=com`
* **Bind DN**: The full DN of a service account with read permission
* **Bind password**: The service account password
* **Firewall access**: Allow MaiAgent servers to connect to your LDAP server (default port 636 for LDAPS and 389 for LDAP)

### Permissions Required in MaiAgent <a href="#maiagent-permissions-required" id="maiagent-permissions-required"></a>

* An **Organization Owner** or a role with **organization management permissions**

{% hint style="warning" %}
**We strongly recommend using LDAPS (port 636)** instead of unencrypted LDAP (port 389). LDAPS encrypts data in transit to prevent passwords from being intercepted over the network.
{% endhint %}

## Open the Identity Synchronization Settings <a href="#enter-identity-sync-settings" id="enter-identity-sync-settings"></a>

1. From the left menu, click <mark style="color:blue;">Organization Settings</mark> > <mark style="color:blue;">Organization Overview</mark>
2. Click <mark style="color:blue;">Identity Synchronization</mark> to open the settings page
3. Click <mark style="color:blue;">Select Synchronization Method</mark>, then select <mark style="color:blue;">LDAP</mark> in the modal

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-79d17884ae20ce612b1521285258dc75b0c28e6f%2Fidentity-sync-08-change-sync-type.png?alt=media" alt="Select synchronization method"><figcaption><p>The synchronization method modal lets you select LDAP or SCIM (for information about SCIM endpoints and tokens, see “Member Provisioning: SCIM / Invitations / SSO” in the technical manual)</p></figcaption></figure>

The settings contain five tabs: **Connection Settings**, **Synchronization Scope**, **Group Mapping**, **Login and Synchronization**, and **Synchronization History**. Each is explained below.

## 1. Connection Settings <a href="#connection-settings" id="connection-settings"></a>

First, establish a connection between MaiAgent and your LDAP server. After completing the four fields, **always click “Test Connection” first** and save only after the connection has been verified.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ec7886fd2ba0e5bc7776d41ed932d076c5a69d41%2Fidentity-sync-01-connection-tab.png?alt=media" alt="Connection settings form"><figcaption><p>On the Connection Settings tab, enter the server address, Base DN, Bind DN, and password</p></figcaption></figure>

### Field Requirements <a href="#field-fill-rules" id="field-fill-rules"></a>

| Field              | Description                                                             | Example (JumpCloud)                                      | Example (AD)                                           |
| ------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------ |
| **Server address** | LDAP server connection address, including the protocol and port         | `ldaps://ldap.jumpcloud.com:636`                         | `ldaps://ad.company.com:636`                           |
| **Base DN**        | Starting point for user searches; must include `DC=` (case-insensitive) | `ou=Users,o=<ORG_ID>,dc=jumpcloud,dc=com`                | `DC=company,DC=com`                                    |
| **Bind DN**        | Full path of the service account used for authentication                | `uid=svcaccount,ou=Users,o=<ORG_ID>,dc=jumpcloud,dc=com` | `CN=svc-maiagent,OU=ServiceAccounts,DC=company,DC=com` |
| **Password**       | Password for the Bind DN account                                        | —                                                        | —                                                      |

Ask your IT contact for the exact values for each field. For a practical integration example, see [Example Procedure (JumpCloud)](#操作範例以-jumpcloud-為例) later in this guide.

### Test the Connection <a href="#test-connection" id="test-connection"></a>

After completing the fields, click <mark style="color:blue;">Test Connection</mark>. A successful test displays a green “Connection successful” message and the response time.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-08b93a2fe3e3ee13d49d8f813454379641365a3b%2Fidentity-sync-02-connection-success.png?alt=media" alt="Connection test successful"><figcaption><p>The connection test succeeded and displays the response time (approximately 200–300 ms is normal)</p></figcaption></figure>

{% hint style="warning" %}
**Always test the connection before clicking Save**. Features such as synchronization scope and the preview list cannot be used until the connection has been successfully verified.
{% endhint %}

### Common Errors <a href="#common-errors" id="common-errors"></a>

| Error message         | Possible cause                                             | Resolution                                                                                         |
| --------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `Invalid credentials` | Incorrect Bind DN or password                              | Verify the Bind DN format and confirm that the password is current                                 |
| `Server unreachable`  | Incorrect server address or firewall access is not enabled | Verify the URL and port, and ask IT to allow outbound connections from MaiAgent to the LDAP server |
| `Invalid DN syntax`   | Invalid Base DN format                                     | The Base DN must include `DC=`; check that commas and hierarchy levels are correct                 |
| `Timeout`             | No response after more than 10 seconds                     | Verify that the LDAP server is running normally and that the network route is reachable            |

## 2. Synchronization Scope <a href="#sync-scope" id="sync-scope"></a>

Select which LDAP users to synchronize into MaiAgent. Two modes are available:

### Simple Mode (Recommended) <a href="#simple-mode" id="simple-mode"></a>

Select the **organizational units (OUs)** or **groups** to synchronize. After making your selections, click <mark style="color:blue;">Preview List</mark> below to verify which users will be synchronized.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-2a894cb2d34aad020dc5385b1c7699c305dd9703%2Fidentity-sync-03-scope-simple.png?alt=media" alt="Simple synchronization scope mode"><figcaption><p>In Simple Mode, select the OUs or groups to synchronize. The number on the right indicates how many users are in that scope</p></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-e7d6248df58dd4e856f7b4deffe7a84e8d346a70%2Fidentity-sync-04-user-preview.png?alt=media" alt="User preview"><figcaption><p>After you click “Preview List,” all users who will be synchronized are listed. You can search by email / name</p></figcaption></figure>

{% hint style="info" %}
You can select both OUs and groups **at the same time**. If a user meets multiple conditions, they are synchronized only once, and all group associations are retained.
{% endhint %}

### Advanced Mode <a href="#advanced-mode" id="advanced-mode"></a>

If you need more granular filtering (for example, “only synchronize Engineering employees at Manager level or above”), switch to Advanced Mode and define a custom LDAP Filter.

Common Filter examples:

| Requirement                            | LDAP Filter                                                              |
| -------------------------------------- | ------------------------------------------------------------------------ |
| Synchronize active users only          | `(&(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))` |
| Synchronize a specific department only | `(&(objectClass=user)(department=Engineering))`                          |
| Exclude service accounts               | `(&(objectClass=user)(!(sAMAccountName=svc-*)))`                         |

{% hint style="warning" %}
Invalid LDAP Filter syntax in Advanced Mode causes synchronization to fail. If you are unfamiliar with LDAP Filters, use Simple Mode and ask IT to adjust the OU / group structure.
{% endhint %}

## 3. Group Mapping <a href="#group-mapping" id="group-mapping"></a>

Map LDAP groups to MaiAgent roles. **Unmapped groups automatically create MaiAgent roles with the same names** (you can disable this setting here).

{% hint style="info" %}
**Separation of responsibilities between identity synchronization and permission management**

Identity synchronization only imports “users” and “role assignments” from LDAP into MaiAgent. **An administrator must first configure each role's specific permission scope (which features it can use and which resources it can access) once** on the [Role Permission Management](/maiagent-user-guide/en/org/roles/role-permission.md) page.

Afterward, when a new employee is added to the corresponding group in LDAP, they are automatically synchronized into MaiAgent and receive that role's permissions—administrators do not need to configure every new employee individually.
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-2e27e9c4e521f84a761492f1719843e1a2818fbd%2Fidentity-sync-05-mapping.png?alt=media" alt="Group mapping"><figcaption><p>On the Group Mapping tab, configure mappings individually or import them in bulk with a CSV file</p></figcaption></figure>

### Mapping Options <a href="#mapping-options" id="mapping-options"></a>

* <mark style="color:blue;">Add Mapping</mark>: Manually map an LDAP group to a MaiAgent role
* <mark style="color:blue;">Download Template</mark>: Download a CSV template to create mappings in bulk
* <mark style="color:blue;">Import File</mark>: Upload the completed CSV file
* <mark style="color:blue;">Automatically create roles for unmapped groups</mark>: Enabled by default. If synchronization encounters an LDAP group that has not been mapped, MaiAgent automatically creates a role with the same name

### Mapping Examples <a href="#mapping-examples" id="mapping-examples"></a>

| LDAP group    | MaiAgent role       | Purpose                                                                            |
| ------------- | ------------------- | ---------------------------------------------------------------------------------- |
| `Engineering` | `Engineer`          | Shared role for the Engineering department                                         |
| `Finance`     | `Finance`           | Shared role for the Finance department                                             |
| `AI-Project`  | `AI Project Member` | Cross-departmental project role whose members may also belong to other departments |

{% hint style="info" %}
If an employee belongs to multiple LDAP groups (for example, both `Engineering` and `AI-Project`), they are **assigned both corresponding MaiAgent roles** after synchronization.
{% endhint %}

{% hint style="warning" %}
**The “Default Role” cannot be mapped**: MaiAgent's “Default Role” is a system role that is automatically assigned to every organization member and cannot be mapped to an LDAP group. To give everyone in the company a shared permission, adjust the permissions of the “Default Role” itself instead of using it as a mapping target.
{% endhint %}

## 4. Login and Synchronization <a href="#login-and-sync" id="login-and-sync"></a>

This page controls two things: the **LDAP credential login setting** and **manual synchronization**.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-06d3a4d73c43d27440449fae74dd5638c206b4bf%2Fidentity-sync-06-login-sync.png?alt=media" alt="Login and synchronization"><figcaption><p>The Login and Synchronization tab contains the Bind login setting, manual synchronization button, and latest synchronization result</p></figcaption></figure>

### LDAP Credential Login <a href="#ldap-login" id="ldap-login"></a>

When enabled, synchronized users can sign in to MaiAgent directly with their **LDAP passwords** without configuring separate passwords.

{% hint style="info" %}
After LDAP credential login is enabled, password changes in the LDAP directory service take effect **immediately**, without waiting for the next synchronization.
{% endhint %}

{% hint style="warning" %}
**Prerequisites for enabling**: The LDAP connection has been verified and synchronization has run at least once.

**Behavior after enabling**: The authentication source for synchronized users changes to LDAP in bulk, and their **MaiAgent local passwords become invalid**. If you later disable this setting, users must ask an administrator to reset their passwords before they can sign in again.
{% endhint %}

### Trigger Synchronization Manually <a href="#manual-sync-trigger" id="manual-sync-trigger"></a>

Click <mark style="color:blue;">Synchronize Now</mark> to retrieve the latest data from LDAP and update MaiAgent.

* **Automatic synchronization**: By default, the system synchronizes automatically every 30 minutes; no manual action is required
* **Cooldown**: Manual synchronization has a 60-second cooldown to prevent repeated triggers within a short period
* **Synchronization actions**: Includes “add (Active users),” “update (changed data),” and “deactivate (removed from the LDAP scope or Suspended)”

### Latest Synchronization Result <a href="#last-sync-result" id="last-sync-result"></a>

Displays a statistical summary of the latest synchronization, including the number of added, updated, deactivated, and failed records. Open the **Synchronization History** tab for details.

## 5. Synchronization History <a href="#sync-history" id="sync-history"></a>

View full details for every synchronization: time, action, affected users, and trigger method.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-1bc48706c021a96484ccbf72dcdbb299caab6845%2Fidentity-sync-07-logs.png?alt=media" alt="Synchronization history"><figcaption><p>On the Synchronization History tab, search by email / name / role or filter by action type</p></figcaption></figure>

### Action Types <a href="#action-types" id="action-types"></a>

| Action         | Meaning                                                                    |
| -------------- | -------------------------------------------------------------------------- |
| **Add**        | The user is synchronized from LDAP into MaiAgent for the first time        |
| **Update**     | User data changes (name, email, or group assignments)                      |
| **Deactivate** | The user is removed from the LDAP scope, Suspended, or deleted             |
| **Failed**     | Synchronization failed for the user (see the error message in the details) |

### Trigger Methods <a href="#trigger-methods" id="trigger-methods"></a>

* **Manual**: An administrator clicks “Synchronize Now” on the **Login and Synchronization** tab
* **Automatic**: Triggered automatically by the system schedule every 30 minutes

## Verify That Synchronization Succeeded <a href="#verify-sync-success" id="verify-sync-success"></a>

After synchronization, use the following three locations to verify that users were imported correctly and LDAP groups were mapped to MaiAgent roles.

### Verification 1: View Users on the Member Management Page <a href="#verify-1-member-management" id="verify-1-member-management"></a>

Go to <mark style="color:blue;">Organization Settings</mark> > <mark style="color:blue;">Member Management</mark>. Users synchronized from LDAP appear in the list. Search by email to quickly find a specific user.

Each user's “Role” field displays their MaiAgent roles. For example, One Chen is assigned both `Group 1` and `Group 2`, reflecting that they belong to both groups in LDAP.

{% hint style="warning" %}
**The member list does not display a “Source” field**. Users synchronized from LDAP and manually invited members look the same in the list. To definitively determine whether a user came from LDAP, go to <mark style="color:blue;">Identity Synchronization</mark> > <mark style="color:blue;">Synchronization History</mark> and search for their email.
{% endhint %}

### Verification 2: View Roles on the Role Permission Management Page <a href="#verify-2-role-permission-management" id="verify-2-role-permission-management"></a>

Go to <mark style="color:blue;">Organization Settings</mark> > <mark style="color:blue;">Role Permissions</mark>. Roles corresponding to LDAP group mappings appear in the list, and the “Members” field displays users who are currently assigned to each role through synchronization.

Using the sample LDAP groups as an example, the role list shows that:

* `Group 1` has two members (Two Chen and One Chen), corresponding to the members of Group 1 in LDAP
* `Group 2` has two members (Three Chen and One Chen), corresponding to the members of Group 2 in LDAP
* One Chen appears in both roles, indicating that they belong to two groups in LDAP
* These roles look the same as manually created roles, and you can click them to adjust their permission scope

### Verification 3: Review Execution History in Synchronization History <a href="#verify-3-sync-history" id="verify-3-sync-history"></a>

Go to <mark style="color:blue;">Identity Synchronization</mark> > <mark style="color:blue;">Synchronization History</mark> to view the time, action (add / update / deactivate), corresponding user, and trigger method for every synchronization. This is the only place to determine whether synchronization failed and which user was affected.

### Verification Reference Table <a href="#verification-comparison-table" id="verification-comparison-table"></a>

| What you want to know                                                        | Where to look                                                                                                        |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Whether a user was imported successfully                                     | Search by email in the <mark style="color:blue;">Member Management</mark> list                                       |
| Which roles a user was assigned                                              | The user's “Role” field in the <mark style="color:blue;">Member Management</mark> list                               |
| Whether an LDAP group became a role                                          | The <mark style="color:blue;">Role Permissions</mark> list                                                           |
| Which members are actually assigned to a role                                | The role's “Members” field in the <mark style="color:blue;">Role Permissions</mark> list                             |
| Whether a user was synchronized from LDAP or added manually                  | Search by email in <mark style="color:blue;">Synchronization History</mark>; a record indicates LDAP synchronization |
| Whether synchronization failed and why                                       | Filter the action type by “Failed” in <mark style="color:blue;">Synchronization History</mark>                       |
| How many users were imported / deactivated during the latest synchronization | The “Latest Synchronization Result” statistics in <mark style="color:blue;">Login and Synchronization</mark>         |

### Operational Recommendations <a href="#operation-recommendations" id="operation-recommendations"></a>

After enabling identity synchronization, some manual actions on the member / role management pages conflict with LDAP. Note the following.

**Member Management page**:

| Action                                                     | Consequence                                                              |
| ---------------------------------------------------------- | ------------------------------------------------------------------------ |
| Manually delete a user synchronized from LDAP              | The user is created again during the next synchronization                |
| Directly change the email of a user synchronized from LDAP | The LDAP value overwrites the change during synchronization              |
| Manually reset a password after enabling Bind login        | The local password cannot be used; passwords can only be changed in LDAP |

**Role Permission Management page**:

| Action                                         | Consequence                                                                                                          |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Delete a role corresponding to an LDAP mapping | The role is recreated during the next synchronization if “Automatically create roles for unmapped groups” is enabled |
| Manually add or remove members from that role  | The member list is overwritten based on the LDAP group during the next synchronization                               |
| Rename a role                                  | Its association with the LDAP group is broken; remap it on the <mark style="color:blue;">Group Mapping</mark> page   |

{% hint style="info" %}
**Simple rule**: **MaiAgent roles control permissions, while LDAP groups control membership**. To change permissions, go to the role settings. To change who belongs to a group, make the change in LDAP.
{% endhint %}

### Initial Role Permission Setup <a href="#initial-role-permission-setup" id="initial-role-permission-setup"></a>

After synchronization, newly created roles (such as `Group 1` and `Group 2`) **have no permissions by default**. Go to the [Role Permission Management](/maiagent-user-guide/en/org/roles/role-permission.md) page and configure the following for each role:

* **Feature permissions**: Which features the role can use (AI assistants, knowledge bases, customer service conversations, etc.)
* **Resource access**: Which specific assistants, knowledge bases, and databases the role can access

**Each role only needs to be configured once**. New members of the role who are synchronized from LDAP automatically inherit these permissions, so administrators do not need to assign permissions to every new employee individually.

## Example Procedure (JumpCloud) <a href="#jumpcloud-example" id="jumpcloud-example"></a>

The following is a complete integration procedure using JumpCloud as the LDAP server. **The steps are the same for other systems such as Microsoft AD and OpenLDAP; only the field formats differ**. Refer to the comparison table in the appendix at the end of this guide.

### Step 1: Find the Connection Information in JumpCloud <a href="#step-1-find-connection-info" id="step-1-find-connection-info"></a>

Sign in to [JumpCloud Admin](https://console.jumpcloud.com), then go to <mark style="color:blue;">Access</mark> > <mark style="color:blue;">LDAP</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0cd0ae758364454b886ca48d96daa245a9ad6b99%2Fidentity-sync-jumpcloud-02-ldap-page.png?alt=media" alt="JumpCloud LDAP page"><figcaption><p>Access > LDAP in the left menu of JumpCloud Admin</p></figcaption></figure>

Open the **JumpCloud LDAP** directory and copy its **ORG DN**.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b7cb9e559e365b6959d50025ec4c20655a58e53c%2Fidentity-sync-jumpcloud-03-ldap-details.png?alt=media" alt="JumpCloud LDAP Directory details page"><figcaption><p>On the JumpCloud LDAP Directory details page, the value in the <strong>ORG DN</strong> field is the organization identifier you need</p></figcaption></figure>

### Step 2: Verify That LDAP Bind DN Is Enabled for the User <a href="#step-2-enable-ldap-bind-dn" id="step-2-enable-ldap-bind-dn"></a>

Open any user (for example, `bob.chen`) > switch to the <mark style="color:blue;">Directories</mark> tab > verify that the user is bound to JumpCloud LDAP and marked as an **LDAP Bind DN**.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-219c0c0f84e45701269ca7d12ab12f64040c625d%2Fidentity-sync-jumpcloud-06-user-ldap-bind-dn.png?alt=media" alt="User LDAP Bind DN"><figcaption><p>On the user details page > Directories, verify that LDAP Bind DN is enabled</p></figcaption></figure>

{% hint style="warning" %}
**The Bind DN account must be an LDAP Bind DN**. The connection fails if you use a regular user as the Bind DN without selecting this option.
{% endhint %}

### Step 3: Compose the Connection Parameters <a href="#step-3-compose-connection-params" id="step-3-compose-connection-params"></a>

For example, if the ORG DN is `o=69de10c5be030ec43849f7a1,dc=jumpcloud,dc=com`:

| Field          | Value                                                                  |
| -------------- | ---------------------------------------------------------------------- |
| Server address | `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` |
| Password       | Bob Chen's JumpCloud password                                          |

### Step 4: Enter the Values in MaiAgent and Test <a href="#step-4-fill-and-test" id="step-4-fill-and-test"></a>

Paste the values into MaiAgent's Connection Settings, click <mark style="color:blue;">Test Connection</mark>, and save when you see the green “Connection successful” message.

### Step 5: Set the Synchronization Scope and Run <a href="#step-5-set-sync-scope" id="step-5-set-sync-scope"></a>

Switch to **Synchronization Scope** and select `ou=Users`, then save → go to **Login and Synchronization** and click <mark style="color:blue;">Synchronize Now</mark> → go to **Synchronization History** and verify that the users were added.

## Frequently Asked Questions <a href="#faq" id="faq"></a>

### Q1. The connection test says “Invalid credentials,” but I am sure the password is correct <a href="#faq-invalid-credentials" id="faq-invalid-credentials"></a>

Check these three items:

1. **Bind DN format**: Verify the full path, including every `ou=` and `dc=` level
2. **LDAP Bind DN setting** (JumpCloud): Open the user > Directories > verify that “Enable as LDAP Bind DN” is selected
3. **Special characters in the password**: If the password contains characters such as `$` or `!`, they may need to be escaped in some systems

### Q2. Why weren't some users synchronized? <a href="#faq-some-users-not-synced" id="faq-some-users-not-synced"></a>

Check the following:

* Whether the user's status in LDAP is **Active** (JumpCloud users with Staged / Suspended status are not synchronized)
* Whether the user is within the selected OU / group scope (in Advanced Mode, they must meet the Filter conditions)
* Whether the user's email field is empty (MaiAgent uses email as the unique identifier and skips users without an email)

Open <mark style="color:blue;">Synchronization History</mark> to view detailed failure reasons.

### Q3. Can I synchronize only a specific department? <a href="#faq-sync-specific-department" id="faq-sync-specific-department"></a>

Yes. There are two approaches:

* **Simple Mode**: Create a separate OU or group for the department in LDAP and select only that item in MaiAgent
* **Advanced Mode**: Use a custom LDAP Filter, such as `(&(objectClass=user)(department=Engineering))`

### Q4. After an employee changes their LDAP password, does MaiAgent need to wait for synchronization? <a href="#faq-ldap-password-change" id="faq-ldap-password-change"></a>

**No**. As long as **LDAP credential login** is enabled, MaiAgent verifies the new password with LDAP in real time when the user signs in, so the change takes effect immediately.

### Q5. Can the original MaiAgent local password still be used after LDAP credential login is enabled? <a href="#faq-local-password-after-ldap" id="faq-local-password-after-ldap"></a>

**No**. After it is enabled, the authentication source for all synchronized users changes to LDAP, and their original MaiAgent passwords are made unavailable. Users can only sign in with their LDAP passwords.

If this setting is later disabled, users must ask an administrator to reset their passwords before they can sign in again.

### Q6. Will employees be automatically deactivated in MaiAgent after leaving the company? <a href="#faq-offboarding-auto-disable" id="faq-offboarding-auto-disable"></a>

Yes. After a user is suspended or disabled in LDAP, MaiAgent will deactivate the user during the next synchronization (manual or automatic every 30 minutes). If Bind login is enabled, the employee will immediately be unable to log in.

### Q7. What happens in MaiAgent if an LDAP group is renamed or deleted? <a href="#faq-ldap-group-rename-delete" id="faq-ldap-group-rename-delete"></a>

* **Group renamed**: The original role name in MaiAgent is not automatically renamed; we recommend manually updating the corresponding group mapping
* **Group deleted**: If a mapping has been created, it remains in place, but the LDAP group will have no users; we recommend manually removing the mapping

### Q8. How often does automatic synchronization run? Can the interval be changed? <a href="#faq-auto-sync-interval" id="faq-auto-sync-interval"></a>

Automatic synchronization currently runs at a fixed interval of every 30 minutes, and custom intervals are not yet supported. For urgent needs, use "Synchronize Now" to trigger it manually.

## Appendix: Connection Examples for Different LDAP Systems <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>

| Field          | Value                                                  |
| -------------- | ------------------------------------------------------ |
| Server address | `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>

| Field          | Value                                                    |
| -------------- | -------------------------------------------------------- |
| Server address | `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>

| Field          | Value                                        |
| -------------- | -------------------------------------------- |
| Server address | `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 does not provide an LDAP port itself, but the paid Azure add-on **Azure AD Domain Services (AADDS)** can provide an LDAP interface. If your organization uses Azure AD, choose one of the following approaches:

| Purpose                          | Recommended approach                                                                                                    |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Synchronize users                | Enable AADDS and enter AADDS as the LDAP server (using the same field format as Microsoft AD)                           |
| Login authentication             | Use [Third-party Login (SSO)](/maiagent-user-guide/en/org/sso.md) directly with SAML / OAuth; LDAP Bind is not required |
| On-premises AD is also available | Connect it directly as Microsoft AD; AADDS is not required                                                              |

{% hint style="info" %}
If you only want employees to **log in** to MaiAgent with their Azure AD accounts and do not need to synchronize user data, see the [Third-party Login (SSO)](/maiagent-user-guide/en/org/sso.md) documentation instead. You do not need this identity synchronization guide.
{% endhint %}

## Next Steps <a href="#next-steps" id="next-steps"></a>

* [Third-party Login (SSO)](/maiagent-user-guide/en/org/sso.md) — Use it together with identity synchronization to let employees sign in directly with their corporate accounts
* [Role and Permission Management](/maiagent-user-guide/en/org/roles/role-permission.md) — Define the permission scope of the roles mapped to groups on this page
* [Member Management](/maiagent-user-guide/en/org/member.md) — View all organization members, including members synchronized from LDAP and manually invited members


---

# 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/maiagent-user-guide/en/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.