> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LDAP

Lightweight Directory Access Protocol (LDAP) is a vendor-neutral software protocol used to lookup information or devices within a network. Bytebase supports using LDAP for configuring Single Sign-On (SSO).

## Configuration

Basic information:

* **Name**: the display name shown to your users (e.g. `JumpCloud`)
* **Identity Provider ID**: a human-readable unique string, only lower-case alphabets and hyphens are allowed (e.g. `jumpcloud`)
* **Domain**: the domain name to scope associated users (e.g. `jumpcloud.com`, optional)

Identity provider information:

* **Host**: the host of LDAP server (e.g. `ldap.jumpcloud.com`)
* **Port**: the port number of the LDAP server, usually 389 for StartTLS and 636 for LDAPS
* **Bind DN**: the Distinguished Name (DN) of the user to bind as a service account to perform search requests (e.g. `uid=system,ou=Users,dc=jumpcloud,dc=com`)
* **Bind Password**: the password of the user to bind as a service account
* **Base DN**: the base Distinguished Name (DN) to search for users (e.g. `ou=users,dc=jumpcloud,dc=com`)
* **User Filter**: the LDAP search filter to match users during authentication. The `%s` placeholder will be replaced with the username entered during login (e.g. `(uid=%s)` searches for a user with matching `uid` attribute)
* **Security protocol**: the security protocol to be used for establishing connections with the LDAP server

User information field mapping:

* **Email**: the attribute to be used as the Bytebase user email address (e.g. `mail`)
* **Display name**: the attribute to be used as the Bytebase user display name (e.g. `displayName`, optional)
* **Phone**: the attribute to be used as the Bytebase user phone number (e.g. `phone`, optional)

## User Filter Configuration

The **User Filter** field is critical for LDAP authentication. It defines how Bytebase searches for users in your LDAP directory.

### Understanding the User Filter

* The `%s` placeholder is **required** and will be replaced with the username entered during login
* Filters must use valid LDAP filter syntax with proper parentheses
* The filter should uniquely identify users to prevent authentication issues

### Common User Filter Patterns

Different LDAP providers use different object classes and attributes:

| Provider         | Recommended User Filter                    | Description                                                     |
| ---------------- | ------------------------------------------ | --------------------------------------------------------------- |
| Okta             | `(&(objectClass=inetOrgPerson)(uid=%s))`   | Matches users with `inetOrgPerson` class and matching `uid`     |
| JumpCloud        | `(&(objectClass=posixAccount)(uid=%s))`    | Matches users with `posixAccount` class and matching `uid`      |
| Active Directory | `(&(objectClass=user)(sAMAccountName=%s))` | Matches users with matching `sAMAccountName` (Windows username) |
| OpenLDAP         | `(&(objectClass=inetOrgPerson)(uid=%s))`   | Standard OpenLDAP user filter                                   |

### Best Practices

1. **Use AND conditions**: Combine object class with the user identifier for more precise matching:

   * Good: `(&(objectClass=inetOrgPerson)(uid=%s))`
   * Avoid: `(uid=%s)` (too broad, may match non-user entries)

2. **Match your directory schema**: Verify the object class used in your LDAP directory:

   * Common classes: `inetOrgPerson`, `posixAccount`, `user`, `person`
   * Use LDAP browser tools to inspect your directory structure

3. **Test the filter**: Use the **Test Connection** button to verify your filter works before saving

### Common Issues

| Issue Type                 | Description                                                                                    | Bad Example                          | Correction                               |
| -------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------- |
| **Invalid filter syntax**  | Parentheses must be balanced and properly nested following LDAP filter syntax                  | `&(objectClass=user)(uid=%s)`        | `(&(objectClass=user)(uid=%s))`          |
| **Missing %s placeholder** | The `%s` placeholder must be present for username substitution                                 | `(uid=username)`                     | `(uid=%s)`                               |
| **Wrong attribute name**   | Username attribute must match your LDAP schema (common: `uid`, `sAMAccountName`, `cn`, `mail`) | `(&(objectClass=user)(username=%s))` | `(&(objectClass=user)(uid=%s))`          |
| **Wrong object class**     | Object class must match the user entries in your LDAP directory                                | `(&(objectClass=person)(uid=%s))`    | `(&(objectClass=inetOrgPerson)(uid=%s))` |

<Tip>
  If you're unsure about your LDAP schema, use an LDAP browser tool (like Apache Directory Studio or ldapsearch) to inspect a user entry and identify the correct object class and username attribute.
</Tip>

## Examples

### JumpCloud

<Note>
  The attribute `uid` is the username (e.g. `system`) not the email (e.g. `system@example.com`) in JumpCloud.
</Note>

1. Follow the JumpCloud [Use Cloud LDAP](https://jumpcloud.com/support/use-cloud-ldap) to create an LDAP binding user and add Users to the LDAP directory.
2. In Bytebase, go to **Settings > SSO** to create a new LDAP provider (all values are examples):
   * **Name**: `JumpCloud`
   * **Identity Provider ID**: `jumpcloud`
   * **Domain**: `jumpcloud.com`
   * **Host**: `ldap.jumpcloud.com`
   * **Port**: `389`
   * **Bind DN**: `uid=YOUR_USERNAME,ou=Users,o=YOUR_ORG_DN,dc=jumpcloud,dc=com`
   * **Bind Password**: `YOUR_PASSWORD`
   * **Base DN**: `ou=Users,o=YOUR_ORG_NAME,dc=jumpcloud,dc=com`
   * **User Filter**: `(&(objectClass=posixAccount)(uid=%s))`
   * **Security protocol** `StartTLS`
   * **Email**: `mail`
   * **Display name**: `displayName`

### Okta

<Note>
  The attribute `uid` is the username (e.g. `system`) not the email (e.g. `system@example.com`) in Okta.
</Note>

1. Follow the Okta [Enable the LDAP interface](https://help.okta.com/en-us/Content/Topics/Directory/LDAP-interface-enable.htm) to enable LDAP interface for your directory.
2. In Bytebase, go to **Settings > SSO** to create a new LDAP provider (all values are examples):
   * **Name**: `Okta`
   * **Identity Provider ID**: `okta`
   * **Domain**: `okta.com`
   * **Host**: `YOUR_SUBDOMAIN.ldap.okta.com`
   * **Port**: `389`
   * **Bind DN**: `uid=YOUR_USERNAME,ou=users,dc=YOUR_SUBDOMAIN,dc=okta,dc=com`
   * **Bind Password**: `YOUR_PASSWORD`
   * **Base DN**: `ou=users,dc=YOUR_SUBDOMAIN,dc=okta,dc=com`
   * **User Filter**: `(&(objectClass=inetOrgPerson)(uid=%s))`
   * **Security protocol** `StartTLS`
   * **Email**: `mail`
   * **Display name**: `cn`