Skip to main content
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:

​
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

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.

​
Examples

​
Active Directory

Users sign in with their sAMAccountName (the Windows logon name, e.g. jdoe), not their email address. The user information mapping fields take LDAP attribute names (e.g. mail), not actual values — entering a literal email address there leaves the user profile empty after login.
This example covers on-premises Active Directory Domain Services. Microsoft Entra ID (formerly Azure AD) is not an LDAP server — configure it via OIDC instead.
  1. Create (or reuse) a domain service account for Bytebase to bind as, e.g. svc-bytebase. It only needs read access to the users it should authenticate.
  2. In Bytebase, go to Settings > SSO to create a new LDAP provider (all values are examples):
    • Name: Active Directory
    • Identity Provider ID: active-directory
    • Domain: corp.example.com
    • Host: dc01.corp.example.com (a domain controller; the AD domain name itself also works since it resolves to domain controllers)
    • Port: 389
    • Bind DN: CN=svc-bytebase,OU=Service Accounts,DC=corp,DC=example,DC=com (AD also accepts the UPN form svc-bytebase@corp.example.com)
    • Bind Password: YOUR_PASSWORD
    • Base DN: DC=corp,DC=example,DC=com (scope it down to an OU like OU=Employees,DC=corp,DC=example,DC=com to limit who can sign in)
    • User Filter: (&(objectClass=user)(sAMAccountName=%s))
    • Security protocol: StartTLS
    • Email: mail (if mail is not populated in your directory, use userPrincipalName)
    • Display name: displayName

​
JumpCloud

The attribute uid is the username (e.g. system) not the email (e.g. system@example.com) in JumpCloud.
  1. Follow the JumpCloud 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

The attribute uid is the username (e.g. system) not the email (e.g. system@example.com) in Okta.
  1. Follow the Okta Enable the LDAP interface 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