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:
ProviderRecommended User FilterDescription
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 TypeDescriptionBad ExampleCorrection
Invalid filter syntaxParentheses must be balanced and properly nested following LDAP filter syntax&(objectClass=user)(uid=%s)(&(objectClass=user)(uid=%s))
Missing %s placeholderThe %s placeholder must be present for username substitution(uid=username)(uid=%s)
Wrong attribute nameUsername attribute must match your LDAP schema (common: uid, sAMAccountName, cn, mail)(&(objectClass=user)(username=%s))(&(objectClass=user)(uid=%s))
Wrong object classObject class must match the user entries in your LDAP directory(&(objectClass=person)(uid=%s))(&(objectClass=inetOrgPerson)(uid=%s))
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

​
JumpCloud

The attribute uid is the username (e.g. system) not the email (e.g. [email protected]) 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. [email protected]) 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