Licensed to be used in conjunction with basebox, only.
// integration
LDAP / OIDC
Applies to
Product: Cloud · Server · Audience: Platform Operator · IT · Administrator
Identity integration: users and groups from LDAP/Active Directory, single sign-on via OpenID Connect. What is configured in basebox, what at your identity provider, and which network paths are needed. The admin view without the technology is under LDAP integration and OIDC / single sign-on.
How basebox handles identity
basebox ships Keycloak as its identity provider. The frontend authenticates users via OpenID Connect against Keycloak; the application server AISRV verifies the issued JWTs. Both integrations attach to Keycloak:
| Integration | Keycloak feature | What happens |
|---|---|---|
| LDAP / Active Directory | User Federation | Keycloak reads users (and optionally groups) from the directory and verifies passwords there |
| OIDC provider (Entra ID, Okta, …) | Identity Providers (brokering) | Keycloak redirects the sign-in to your provider and adopts the confirmed identity |
Both can be combined; local accounts – such as the first administrator – remain alongside.
LDAP / Active Directory
Required: address and port of the LDAP server (389, for LDAPS 636), a service account with read access (bind DN + password), the base DN of the users, the vendor (Active Directory or Other).
Setup in the Keycloak Admin Console (https://<basebox-domain>/auth, realm usually primary): User Federation → Add provider → ldap, enter connection details, Test connection and Test authentication, Save, Synchronize all users. Step by step: Connecting Keycloak to LDAP / Active Directory.
Recommended settings:
- Edit mode
READ_ONLY– Keycloak writes nothing back. - Periodic Changed Users Sync
3600s, Periodic Full Sync86400s. - User LDAP Filter to limit the population, e.g.
(memberOf=CN=AppUsers,OU=Groups,DC=corp,DC=example,DC=com). group-ldap-mapperif directory groups are to be mirrored; further attributes viauser-attribute-ldap-mapper.- LDAPS in production; import certificates from a private CA into the Keycloak truststore.
Network path: Keycloak → LDAP server, TCP 389/636. In basebox Cloud, your directory has to be reachable from the Noris data center (private connectivity or exposure) – which is why OIDC is usually the more practical path for the Cloud.
OpenID Connect (single sign-on)
Required: client ID and client secret of an application registered with your provider, the discovery URL (…/.well-known/openid-configuration), and the redirect URI from Keycloak to enter at the provider: https://<basebox-domain>/auth/realms/<realm>/broker/<alias>/endpoint.
Setup: Keycloak Admin Console → Identity Providers → OpenID Connect v1.0 → import discovery URL, enter client ID and secret, assign an alias, save; test sign-in with a test account. Optionally: adjust the First login flow (e.g. link accounts by e-mail address) and attribute mappers for first name, last name, e-mail.
Network path: users' browsers → your provider (public); Keycloak → provider (token endpoint, TCP 443). Works in Cloud and Server without private connectivity as long as the provider is reachable from both directions.
What stays in basebox
- Roles (administrator/user) are assigned in basebox, not taken from the directory.
- Groups for sharing are managed under Administration → Groups.
- Licence seats: every synchronised or SSO-signed-in user occupies one.
- User synchronisation between Keycloak and AISRV became more robust in 1.8, including for users already present in Keycloak.
Relevant configuration on basebox Server
| Component | Variable | Meaning |
|---|---|---|
| Frontend | VITE_BB_OIDC_DOMAIN |
Base URL of the OIDC provider with realms path, ends with /, e.g. https://basebox.company.com/auth/realms/ |
| Frontend | VITE_BB_OIDC_FORCE_REALM |
Realm, usually primary |
| Frontend | VITE_BB_OIDC_CLIENT_ID |
OIDC client ID (default aiclient) |
| AISRV | AISRV_OIDC_IDP_URL |
Base URL of the IdP (without realm) |
| AISRV | AISRV_OIDC_ISSUER_URL |
Optional expected issuer – change only if you know why |
| AISRV | AISRV_OIDC_AUD |
Expected audience |
Failure patterns – "Organisation not found", redirect loop, "iss does not match", 404 on /auth/… – are in the FAQ with solutions. The full Keycloak configuration: IDP (Keycloak).
The issuer is a security boundary
AISRV uses the issuer to check that a token comes from your Keycloak. A foreign issuer would admit foreign tokens. Changes only by the Platform Operator and only with a reason.
Decision aid
| Situation | Recommendation |
|---|---|
| Active Directory present, basebox Server in your own network | LDAP federation; LDAPS; filter on an AD group |
| Entra ID / Okta in use | OIDC brokering – in Cloud and Server |
| basebox Cloud, directory reachable internally only | OIDC instead of LDAP, or private connectivity (Network connectivity) |
| Small organisation without central identity | Local accounts via invitation; migrate later |
Next: Keycloak LDAP integration · Keycloak LDAP (advanced) · VPN / networking