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:
| Thing | Value used in this guide | Where it must match |
|---|---|---|
| Directory domain | example.com | Base DN, service-account DN |
| Base DN | ou=users,dc=example,dc=com | Bichon Base DN |
| Service account | cn=admin,dc=example,dc=com | Bichon Service-account DN |
| Test user | alice / alicepass | Directory entry |
| LDAP address | ldap://<LDAP_HOST>:389 | Must be reachable from the Bichon server |
| Bichon address | http://<BICHON_HOST>:15630 | Browser |
What you are building
- The user opens Bichon's sign-in page and enters their directory username and password.
- Bichon binds to the directory as the service account and searches for the user.
- Bichon binds again as the user's DN with the password the user typed, to verify it.
- 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:rootoruser:manage). - The Bichon server can reach the LDAP address. Do not use
localhostunless Bichon and LDAP run on the same machine. - You know:
- the LDAP host and port (
389for LDAP,636for LDAPS); - the Base DN that contains your users;
- a service account DN and password, if your directory does not allow anonymous searches.
- the LDAP host and port (
- 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.0What the parts mean:
LDAP_DOMAINcreates the base DNdc=example,dc=com.LDAP_ADMIN_PASSWORDcreates the admin entrycn=admin,dc=example,dc=com.-v ldap-dataand-v ldap-configkeep users and configuration when the container is recreated.LDAP_TLS=falsekeeps this test simple. Section Production notes covers TLS.
Check that it started:
docker logs bichon-ldapThe 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.ldifTwo things matter beyond the password:
uid: aliceis the attribute Bichon will read as the username.mailis 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=comIf 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 field | Test value | What it means |
|---|---|---|
| LDAP sign-in enabled | ON | Offers LDAP/AD on the sign-in page |
| Server URL | ldap://<LDAP_HOST>:389 | Where the Bichon server connects |
| Base DN | ou=users,dc=example,dc=com | Where Bichon searches for users |
| Service-account DN (optional) | cn=admin,dc=example,dc=com | The account Bichon binds as to perform the search |
| Service-account password | adminpass | Password for that service account |
| User search filter | (&(objectClass=person)(uid={username})) | How to find one user by the typed name |
| Search scope | Whole subtree | Search the base DN and everything below it |
| Username attribute | uid | Attribute read as the local username |
| SSO id attribute | entryDN | Attribute stored as the stable identity |
| Timeout (seconds) | 10 | How long to wait for the directory |
| Use StartTLS | OFF | Plain ldap:// for this test |
| Skip certificate verification | OFF | Keep 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.
| Value | When to use |
|---|---|
ldap://ldap.example.com:389 | Plain LDAP, or LDAP upgraded with StartTLS |
ldaps://ldap.example.com:636 | LDAP 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=comThis 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=comWhy 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:
| Part | Meaning |
|---|---|
& | 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.
| Option | Technical value | Behaviour |
|---|---|---|
| Whole subtree | subtree | Searches the Base DN and every level below it (recursive). This is the normal choice |
| One level | onelevel | Searches only the direct children of the Base DN; deeper users are invisible |
Examples:
- Base DN
dc=example,dc=com, users inou=usersandou=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.
| Directory | Typical value |
|---|---|
| OpenLDAP | uid |
| Active Directory | sAMAccountName |
| Email-style logins | userPrincipalName (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.
| Directory | Recommended value |
|---|---|
| OpenLDAP | entryDN |
| Active Directory | distinguishedName |
Why it matters:
- It links the directory user to the same local Bichon user on every login.
distinguishedName(andentryDN) 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.
entryDNis a good default for OpenLDAP;distinguishedNameis 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
- Open Bichon in a new incognito window.
- The sign-in page should now show the LDAP option alongside the local login.
- Sign in as
alicewithalicepass.
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.loginentry. A failed attempt writesldap.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
- Binds as the service account (if DN and password are set) and searches the Base DN with the configured filter and scope.
- Requires the filter to return exactly one entry.
- Binds as that entry's DN with the password the user typed. A rejected bind and an unknown user produce the same message.
- Looks up the local user by SSO id, then by email (only linking users that are unbound or already LDAP).
- 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 field | Example value |
|---|---|
| Server URL | ldaps://dc1.corp.example.com:636 |
| Base DN | OU=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 password | the service account password |
| User search filter | (&(objectClass=person)(sAMAccountName={username})) |
| Search scope | Whole subtree |
| Username attribute | sAMAccountName |
| SSO id attribute | distinguishedName |
| Timeout (seconds) | 10 |
| Use StartTLS | OFF (the URL already uses ldaps://) |
| Skip certificate verification | OFF |
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.
| Message | What it means | What to do |
|---|---|---|
| Connected and the base DN is searchable. | Server, service-account bind and base DN are fine | Save, then test a real login |
| The address is not a valid LDAP URL | The URL does not start with ldap:// or ldaps:// | Use ldap://host:389 or ldaps://host:636 |
| The server refused the connection | Nothing is listening on that host/port | Check the container or service, the port mapping and the firewall |
| The connection timed out | No answer — wrong host or blocked network | Check that the Bichon server can reach the address |
| The TLS handshake failed | Certificate or TLS-mode problem | Use a trusted certificate, or ldaps:// without StartTLS |
| The service account DN or password was rejected | Bind failed (LDAP result 49) | Check the DN spelling and the password; use the full DN, not a login name |
| The base DN does not exist | LDAP result 32 | Check the DN order (ou=…,dc=…), spaces and capitalisation |
| The bind account may not search this base DN | Insufficient access | Grant read/search to the service account, or use one that has it |
| The directory returned an error | Server-side error | Check the directory's own logs |
Problems that appear after clicking the LDAP login button:
| Message on the sign-in page | Likely cause |
|---|---|
LDAP sign-in is not enabled | The switch is off, required fields are incomplete, or the licence is not Pro or Enterprise |
LDAP sign-in is not enabled or configured | The stored configuration is incomplete (URL or Base DN missing) |
Incorrect LDAP credentials or user not found | Wrong 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 unavailable | The server is unreachable, or the service-account bind failed |
| No LDAP fields on the sign-in page | Not 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
uidagainst Active Directory (AD usessAMAccountName), orsAMAccountNameagainst OpenLDAP. - Choosing One level while users are deeper than one level below the Base DN.
- Using
localhostwhile 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 port636, orldap://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.
uidandsAMAccountNameare normally unique in their directories; attributes likecnare 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, collectionldap), 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.