Bichon Docs
Pro EditionSingle Sign-On

This guide walks through a complete LDAP setup for Bichon, from starting a test OpenLDAP server to signing in with a test user. It explains what every field on Settings → LDAP means, what to put in it, and why.

LDAP sign-in is a Pro feature (Enterprise includes it), so a Pro or Enterprise license — or either binary's trial — unlocks it; the settings page stays locked on Community.

The names used in this guide are examples. Use your own values, but keep the same value everywhere it appears:

ThingValue used in this guideWhere it must match
Directory domainexample.comBase DN, service-account DN
Base DNou=users,dc=example,dc=comBichon Base DN
Service accountcn=admin,dc=example,dc=comBichon Service-account DN
Test useralice / alicepassDirectory entry
LDAP addressldap://<LDAP_HOST>:389Must be reachable from the Bichon server
Bichon addresshttp://<BICHON_HOST>:15630Browser

What you are building

  1. The user opens Bichon's sign-in page and enters their directory username and password.
  2. Bichon binds to the directory as the service account and searches for the user.
  3. Bichon binds again as the user's DN with the password the user typed, to verify it.
  4. On success, the local user is found or created, and a normal Bichon session is issued.

There is no browser redirect. Bichon never stores the user's password — it is only used for the second bind.

Before you start

  • Bichon Pro or Enterprise is running, and you can sign in as an administrator (system:root or user:manage).
  • The Bichon server can reach the LDAP address. Do not use localhost unless Bichon and LDAP run on the same machine.
  • You know:
    • the LDAP host and port (389 for LDAP, 636 for LDAPS);
    • the Base DN that contains your users;
    • a service account DN and password, if your directory does not allow anonymous searches.
  • For a first test, a local OpenLDAP container is enough. Plain LDAP is fine on a trusted test network; use TLS in production.

Step 1 — Start a test OpenLDAP server

On any machine the Bichon server can reach:

docker run -d --name bichon-ldap \
  --restart unless-stopped \
  -p 389:389 \
  -e LDAP_ORGANISATION="Bichon Test" \
  -e LDAP_DOMAIN="example.com" \
  -e LDAP_ADMIN_PASSWORD="adminpass" \
  -e LDAP_TLS=false \
  -v ldap-data:/var/lib/ldap \
  -v ldap-config:/etc/ldap/slapd.d \
  osixia/openldap:1.5.0

What the parts mean:

  • LDAP_DOMAIN creates the base DN dc=example,dc=com.
  • LDAP_ADMIN_PASSWORD creates the admin entry cn=admin,dc=example,dc=com.
  • -v ldap-data and -v ldap-config keep users and configuration when the container is recreated.
  • LDAP_TLS=false keeps this test simple. Section Production notes covers TLS.

Check that it started:

docker logs bichon-ldap

The last line should mention slapd starting. If the container exits immediately, look at the full log; the most common cause is a port already in use.

Step 2 — Create a user

The directory needs at least one user entry. Create an ou=users container and a test user alice:

cat > /tmp/users.ldif <<'EOF'
dn: ou=users,dc=example,dc=com
objectClass: organizationalUnit
ou: users

dn: uid=alice,ou=users,dc=example,dc=com
objectClass: inetOrgPerson
uid: alice
cn: Alice Anderson
sn: Anderson
displayName: Alice Anderson
mail: alice@example.com
userPassword: alicepass
EOF

docker cp /tmp/users.ldif bichon-ldap:/tmp/users.ldif
docker exec bichon-ldap ldapadd -x \
  -H ldap://localhost:389 \
  -D "cn=admin,dc=example,dc=com" \
  -w adminpass \
  -f /tmp/users.ldif

Two things matter beyond the password:

  • uid: alice is the attribute Bichon will read as the username.
  • mail is optional, but it lets Bichon link an existing local account by email. Entries without it still work.

Step 3 — Verify the directory (optional)

These three commands perform exactly the steps Bichon will perform. Run them on the host or inside the container:

# 1. Bind as the service account and search the base DN.
docker exec bichon-ldap ldapsearch -x \
  -H ldap://localhost:389 \
  -D "cn=admin,dc=example,dc=com" -w adminpass \
  -b "ou=users,dc=example,dc=com" \
  "(&(objectClass=person)(uid=alice))"

# 2. The result must contain exactly one entry:
#    dn: uid=alice,ou=users,dc=example,dc=com

# 3. Bind as that user's DN with the password the user will type.
docker exec bichon-ldap ldapwhoami -x \
  -H ldap://localhost:389 \
  -D "uid=alice,ou=users,dc=example,dc=com" \
  -w alicepass
# dn:uid=alice,ou=users,dc=example,dc=com

If step 1 returns zero or several entries, Bichon will reject the login even with the correct password. Adjust the filter until it matches exactly one entry.

Step 4 — Fill in Bichon

In Bichon: Settings → LDAP. This page requires system:root or user:manage and a Pro or Enterprise licence.

Fill in the form exactly for the test directory above:

Bichon fieldTest valueWhat it means
LDAP sign-in enabledONOffers LDAP/AD on the sign-in page
Server URLldap://<LDAP_HOST>:389Where the Bichon server connects
Base DNou=users,dc=example,dc=comWhere Bichon searches for users
Service-account DN (optional)cn=admin,dc=example,dc=comThe account Bichon binds as to perform the search
Service-account passwordadminpassPassword for that service account
User search filter(&(objectClass=person)(uid={username}))How to find one user by the typed name
Search scopeWhole subtreeSearch the base DN and everything below it
Username attributeuidAttribute read as the local username
SSO id attributeentryDNAttribute stored as the stable identity
Timeout (seconds)10How long to wait for the directory
Use StartTLSOFFPlain ldap:// for this test
Skip certificate verificationOFFKeep TLS checks on

In this test we use the OpenLDAP admin account as the service account for brevity. For production, create a dedicated read-only service account — see Production notes.

Click Test connection. You should see Connected and the base DN is searchable. If not, see Troubleshooting. Then click Save.

Test connection checks the server, the service-account bind, and that the base DN exists and is readable. It does not test the user filter or a user's password — use Step 5 for that.

Every field explained

The labels below are the exact labels shown in the WebUI.

LDAP sign-in enabled

Turns the LDAP option on for everyone. It only becomes active when the required fields are complete and the licence is Pro or Enterprise. Until then the sign-in page does not offer LDAP, even if the button is on.

Server URL

The address of the directory, as seen from the Bichon server.

ValueWhen to use
ldap://ldap.example.com:389Plain LDAP, or LDAP upgraded with StartTLS
ldaps://ldap.example.com:636LDAP over TLS from the first byte

Use the host name or IP address the Bichon server can resolve. 127.0.0.1 only means "the machine Bichon runs on" — inside a container that is the container itself, not the host.

Base DN

The starting point of the user search, written as a distinguished name:

ou=users,dc=example,dc=com

This is where your users live — it does not have to be the domain root (dc=example,dc=com). A narrower base DN is faster and gives the service account less to read.

The DN must be written in order from the smallest scope to the largest: uid=alice,ou=users,dc=example,dc=com.

Service-account DN (optional)

Technical name: bind DN. This is the account Bichon uses only to search, before it knows who the user is. It is not the user's login name and it is not the password being verified.

cn=bichon-svc,ou=services,dc=example,dc=com

Why it is needed:

  • Most directories refuse anonymous searches, so Bichon must bind as someone to look up the user.
  • This account needs read/search permission on the base DN. It does not need write access, and it should not be a domain administrator.

When you may leave it empty:

  • If the directory allows anonymous search, leave both the DN and the password empty.
  • If you set the DN but leave the password empty, Bichon will not bind before searching (it falls back to an anonymous search, which many directories reject). Set both, or neither.

After the search, Bichon always binds as the found user's DN with the password the user typed. The service account is never used to impersonate the user.

Service-account password

The password for the DN above. It is encrypted at rest with BICHON_ENCRYPT_PASSWORD and is never returned to the browser.

While a password is stored, the field shows ******** (unchanged). Leave it untouched to keep it; type a new value to replace it; click Clear to remove it.

User search filter

An LDAP filter that finds exactly one entry for the username the user typed. Bichon replaces the literal placeholder {username} with that value.

For OpenLDAP:

(&(objectClass=person)(uid={username}))

For Active Directory:

(&(objectClass=person)(sAMAccountName={username}))

Reading the filter piece by piece:

PartMeaning
&Logical AND — every condition inside must match
(objectClass=person)Keep only user entries; groups, computers and OUs are excluded. inetOrgPerson inherits person, so normal users match
(uid={username})Match the typed name against the uid attribute
{username}The placeholder Bichon replaces with what the user typed; the filter must contain it

If the user types alice, the filter above becomes:

(&(objectClass=person)(uid=alice))

Rules that matter:

  • Exactly one entry must match. Zero entries and several entries are both rejected — with the same generic "incorrect credentials or user not found" message, so the directory cannot be enumerated.

  • The placeholder is required. Saving an enabled configuration without {username} fails with a validation error.

  • The value is inserted verbatim. Usernames containing LDAP filter characters (*, (, ), \) are not supported; most directories do not allow them anyway.

  • To allow users to sign in with either a username or an email address, use an OR:

    (&(objectClass=person)(|(uid={username})(mail={username})))

Search scope

How far from the Base DN the search may go.

OptionTechnical valueBehaviour
Whole subtreesubtreeSearches the Base DN and every level below it (recursive). This is the normal choice
One levelonelevelSearches only the direct children of the Base DN; deeper users are invisible

Examples:

  • Base DN dc=example,dc=com, users in ou=users and ou=contractors: choose Whole subtree.
  • Base DN ou=users,dc=example,dc=com, all users directly under that OU: One level works and avoids scanning nested OUs.

If a valid user cannot be found, check the scope before changing anything else: a user who is one level deeper than the scope allows will never match.

Username attribute

The directory attribute Bichon stores as the local username.

DirectoryTypical value
OpenLDAPuid
Active DirectorysAMAccountName
Email-style loginsuserPrincipalName (with a matching filter)

If the attribute is missing from the entry, Bichon falls back to the local part of the email address, then to the name the user typed. If that username already exists locally, Bichon appends -2, -3, … rather than overwriting an account.

SSO id attribute

The value Bichon stores as the user's permanent directory identity. On every later login, Bichon checks this first, before email.

DirectoryRecommended value
OpenLDAPentryDN
Active DirectorydistinguishedName

Why it matters:

  • It links the directory user to the same local Bichon user on every login.
  • distinguishedName (and entryDN) is unique, but it changes if the entry is renamed or moved. If that happens, Bichon falls back to the email address and re-links the account when the email matches. Entries without an email may be treated as a new user after a rename.
  • If your directory offers an immutable identifier that is returned as a readable attribute, it is the most stable choice. entryDN is a good default for OpenLDAP; distinguishedName is the AD default.
  • If the configured attribute is not returned by the search, Bichon uses the entry's DN as the id.

Timeout (seconds)

How long Bichon waits for connect, search and bind operations. The default is 10. Keep it short enough that a broken directory does not stall the sign-in page.

Use StartTLS

Upgrades an ldap:// connection to TLS after connecting, on the same port (389). Do not enable it with an ldaps:// URL — ldaps is already TLS, and Bichon rejects that combination.

Skip certificate verification

Disables TLS certificate checks. Use it only for a private CA or a self-signed test certificate. It turns off a real security check, so leave it off whenever the certificate can be trusted normally.

Step 5 — Test the login

  1. Open Bichon in a new incognito window.
  2. The sign-in page should now show the LDAP option alongside the local login.
  3. Sign in as alice with alicepass.

What to expect:

  • Users page: a new user alice (description LDAP-provisioned user) with the default Member role and no account access.
  • Audit log: an ldap.login entry. A failed attempt writes ldap.login_failed.
  • An admin still has to grant account access and roles, exactly as for any other user.
  • If the user has TOTP enabled, Bichon asks for the code after the directory bind succeeds.

What Bichon does on every login

  1. Binds as the service account (if DN and password are set) and searches the Base DN with the configured filter and scope.
  2. Requires the filter to return exactly one entry.
  3. Binds as that entry's DN with the password the user typed. A rejected bind and an unknown user produce the same message.
  4. Looks up the local user by SSO id, then by email (only linking users that are unbound or already LDAP).
  5. Creates a user on first login with the username from the configured attribute, the default Member role, and no account access.

The directory password exists only in memory for the duration of the bind. It is never written to the database or logs.

Active Directory example

The same form, filled in for a typical AD deployment:

Bichon fieldExample value
Server URLldaps://dc1.corp.example.com:636
Base DNOU=Users,DC=corp,DC=example,DC=com
Service-account DN (optional)CN=bichon-svc,OU=Service Accounts,DC=corp,DC=example,DC=com
Service-account passwordthe service account password
User search filter(&(objectClass=person)(sAMAccountName={username}))
Search scopeWhole subtree
Username attributesAMAccountName
SSO id attributedistinguishedName
Timeout (seconds)10
Use StartTLSOFF (the URL already uses ldaps://)
Skip certificate verificationOFF

If users sign in with their full email address instead, use a filter like:

(&(objectClass=person)(userPrincipalName={username}))

and keep sAMAccountName as the username attribute if you want short local usernames.

Troubleshooting

Start with Test connection. It reports one of these categories in plain language.

MessageWhat it meansWhat to do
Connected and the base DN is searchable.Server, service-account bind and base DN are fineSave, then test a real login
The address is not a valid LDAP URLThe URL does not start with ldap:// or ldaps://Use ldap://host:389 or ldaps://host:636
The server refused the connectionNothing is listening on that host/portCheck the container or service, the port mapping and the firewall
The connection timed outNo answer — wrong host or blocked networkCheck that the Bichon server can reach the address
The TLS handshake failedCertificate or TLS-mode problemUse a trusted certificate, or ldaps:// without StartTLS
The service account DN or password was rejectedBind failed (LDAP result 49)Check the DN spelling and the password; use the full DN, not a login name
The base DN does not existLDAP result 32Check the DN order (ou=…,dc=…), spaces and capitalisation
The bind account may not search this base DNInsufficient accessGrant read/search to the service account, or use one that has it
The directory returned an errorServer-side errorCheck the directory's own logs

Problems that appear after clicking the LDAP login button:

Message on the sign-in pageLikely cause
LDAP sign-in is not enabledThe switch is off, required fields are incomplete, or the licence is not Pro or Enterprise
LDAP sign-in is not enabled or configuredThe stored configuration is incomplete (URL or Base DN missing)
Incorrect LDAP credentials or user not foundWrong password, missing user, or the filter matched zero/multiple entries. This message is intentionally the same in all three cases
LDAP sign-in is temporarily unavailableThe server is unreachable, or the service-account bind failed
No LDAP fields on the sign-in pageNot enabled, not fully configured, not Pro or Enterprise, or the page was not reloaded

Common mistakes

  • Putting the user's login name in Service-account DN instead of a full DN (cn=svc,ou=services,dc=…).
  • Using a domain administrator as the service account instead of a read-only account.
  • Leaving the Base DN as the domain root when users live under a narrower OU — slower, and more data exposed to the search account.
  • Writing the DN in the wrong order (dc=example,dc=com,ou=users).
  • A filter that matches several entries — for example (objectClass=person) without the username condition. Bichon then rejects the login even with the right password.
  • Using uid against Active Directory (AD uses sAMAccountName), or sAMAccountName against OpenLDAP.
  • Choosing One level while users are deeper than one level below the Base DN.
  • Using localhost while Bichon runs in a container or on another machine.
  • Enabling Use StartTLS together with an ldaps:// URL.
  • Forgetting to click Save after a successful Test connection.
  • Expecting the new user to see mail immediately — JIT users start with no account access.

Production notes

  • Use TLS. Prefer ldaps:// on port 636, or ldap:// with Use StartTLS enabled. Plain LDAP sends the user's password and the service-account password in clear text.

  • Dedicated read-only service account. Create an account that can only read the Base DN. For OpenLDAP, a minimal bind entry looks like this:

    dn: cn=bichon-svc,ou=services,dc=example,dc=com
    objectClass: organizationalRole
    objectClass: simpleSecurityObject
    cn: bichon-svc
    userPassword: <service-account-password>
  • Least-privilege search. Point the Base DN at the OU that contains users, not the whole domain. Use One level where it matches your layout.

  • Unique filter. The filter must identify one person. uid and sAMAccountName are normally unique in their directories; attributes like cn are not.

  • Password handling. The service-account password is encrypted at rest with BICHON_ENCRYPT_PASSWORD. It is included in native backups; restoring under a different encryption password requires re-entering it.

  • Rotate the service password in the directory, then paste the new value into Service-account password and click Save. No restart is needed; existing sessions stay valid.

  • Keep local login available. If the directory is down, LDAP sign-in is unavailable; local administrators can still sign in.

  • Trust TLS certificates rather than disabling verification. Skip certificate verification should be a temporary, private-CA exception.

  • LDAP settings are stored in MemDb (<data-root>/memdb, collection ldap), so they are included in native backups and restores. LDAP has no environment variables or CLI flags; older releases' BICHON_LDAP_* variables are no longer read — enter the values in Settings → LDAP instead.

On this page