Licensed to be used in conjunction with basebox, only.
// admin
LDAP integration
Overview
Using users from an existing directory (LDAP / Active Directory) in basebox. This page describes the admin perspective: what is connected, what arrives in basebox, what stays in the directory and how this affects your daily work. The technical setup is done by the Platform Operator in Keycloak – see Connecting Keycloak to LDAP / Active Directory.
What it is for
Without a directory integration you invite every person individually by e-mail and maintain accounts by hand. With LDAP integration:
- employees sign in with their existing company account – no new passwords,
- new employees arrive automatically as soon as they are in the directory,
- departed employees lose access when their directory account is deactivated,
- directory groups can be mirrored to structure sharing.
Where to find the setting
Not in the basebox administration. basebox authenticates via Keycloak, the integrated identity provider. The LDAP integration is configured in the Keycloak Admin Console under User Federation – on basebox Server reachable at https://<your-basebox-domain>/auth, realm usually primary. The Platform Operator has this access.
In basebox Cloud, basebox sets up the integration for you; contact support@basebox.ai.
Step by step
What you prepare as an administrator:
- Clarify responsibilities – Who operates Keycloak (your IT or basebox)? Who manages the directory?
- Define the user population – Should all directory users be allowed to use basebox or only one group? The latter is implemented via a User LDAP Filter, e.g. members of a specific AD group.
- Have a service account provided – Keycloak needs a directory account with read access to the user entries (bind DN + password) plus address and port of the LDAP server (389, or 636 for LDAPS).
- Decide on groups – Should directory groups be mirrored into Keycloak (
group-ldap-mapper)? This makes assigning sharing easier later. - Hand over to the Platform Operator – with the guide Connecting Keycloak to LDAP / Active Directory.
What happens in basebox after the integration:
- Directory users appear under Administration → Users after synchronisation.
- The role in basebox (administrator or user) is still assigned in basebox – it does not come from the directory. New users are users.
- Groups for sharing are created under Administration → Groups.
What arrives in basebox – and what does not
| Stays in the directory | Comes to basebox (Keycloak) |
|---|---|
| Passwords – sign-in is verified against the directory | Username, first name, last name, e-mail |
| Account status (active/deactivated) | Further attributes only if a mapper maps them (e.g. department) |
| Group memberships (source) | Groups as a mirror, if configured |
The default mode is READ_ONLY: Keycloak writes nothing back to the directory. Password changes happen in the directory, not in basebox.
Synchronisation
Keycloak picks up changes on a schedule – recommended: changed users hourly, full sync daily. Deletions and deactivations in the directory take effect at the latest with the full sync; a manual sync is possible at any time. An account deactivated in the directory can no longer sign in.
Notes
Note
- LDAPS (TLS) for production. Certificates from a private CA must be imported into Keycloak's truststore – a Platform Operator task.
- Licence limit. Every synchronised user occupies a user seat of your licence. Narrow the population with a filter instead of importing the whole directory.
- Mixed operation is possible. Locally invited accounts and directory accounts can coexist.
- User synchronisation with the identity provider became more robust in 1.8, including for users that already exist in Keycloak.
- Single sign-on via an existing OpenID Connect provider is the alternative path – see OIDC / single sign-on.
Frequently asked questions
Do I still have to invite directory users? No. They appear after synchronisation and sign in with their directory account.
Can I delete a directory user in basebox? The account would come back with the next synchronisation. Deactivate it in the directory or exclude it via the filter.
What happens if the directory is unreachable? Sign-ins of directory users fail until the connection is restored. Local accounts are not affected.
Who sees clear-text passwords? Nobody in basebox. Verification happens in the directory; basebox stores no directory passwords.
Need help? Contact support