Sign-in with Active Directory (LDAP)

Employees sign in to Vesana with their Windows domain account — same name, same password as on their PC. There is no second password anyone forgets. Whoever leaves the company and is disabled in AD is out of Vesana as well. Permissions come from AD groups.

Works with Active Directory (Windows Server 2016 to 2025) and with any other LDAP directory (OpenLDAP, FreeIPA, Samba AD, …).

Part of SSO — off by default

Directory sign-in is part of the preview feature SSO. Enable it under Admin → System → Preview features, then set it up under Admin → Login & Security → SSO → “Connect Active Directory / LDAP” (super admins only).

What users see

• The same sign-in form as always. The field is then called “User name or domain account”.
• Every common spelling works: max.muster, COMPANY\max.muster, max.muster@company.local.
• If sign-in fails, Vesana says why: password expired, account disabled, account locked, not enabled for Vesana, directory unreachable, … A typo in the password stays a plain “user name or password is wrong”.
• Two-factor protection stays in Vesana. AD only checks the password. Everyone sets up their authenticator app or passkey in Vesana as usual, and 2FA enforcement rules apply to domain accounts too.
• The password is changed in Windows. In the Vesana settings, a note replaces the password form.

Preparation in Active Directory (5 minutes)

On a domain controller, in PowerShell as a domain admin:

# 1. Read-only service account — no special rights
New-ADUser -Name "Vesana service account" -SamAccountName svc-vesana `
  -UserPrincipalName svc-vesana@company.local -Enabled $true -PasswordNeverExpires $true `
  -AccountPassword (Read-Host -AsSecureString "Password for svc-vesana")

# 2. Group whose members may sign in to Vesana (recommended)
New-ADGroup -Name "Vesana-Access" -GroupScope Global -GroupCategory Security

# 3. Optional: groups for roles, e.g. admins
New-ADGroup -Name "Vesana-Admins" -GroupScope Global -GroupCategory Security
Add-ADGroupMember "Vesana-Access" -Members "Vesana-Admins"

Then put users into Vesana-Access or a subgroup. Nested groups count: whoever is in a group that is a member of “Vesana-Access” may sign in too.

Encryption: Vesana only talks to the directory encrypted (LDAPS or StartTLS), so the DC needs a certificate. With an enterprise certificate authority (AD CS), the DCs have one automatically. Test-NetConnection dc1.company.local -Port 636 shows whether LDAPS is up. Without a certificate authority: install AD CS as an enterprise root CA, and the DCs fetch their certificate on their own.

Why no unencrypted LDAP?

From Windows Server 2025 on, a DC refuses simple binds without TLS anyway (“strongerAuthRequired”). Above all, every employee's password would cross the network in plain text. Vesana therefore does not offer that option at all.

Setup in Vesana

Admin → Login & Security → SSO → “Connect Active Directory / LDAP”. The dialog has two halves: the connection on the left, who may sign in on the right.

1. Connection

Field	What to enter
Name	Free text, e.g. “Company AD”
Directory	Active Directory, otherwise “Other LDAP”
Domain controllers / servers	DNS names of the DCs, e.g. dc1.company.local, dc2.company.local. Several = failover. Enter the name as it appears in the certificate (usually the full DNS name, not an IP address).
Encryption	LDAPS (port 636, default) or StartTLS (port 389)
Service account	svc-vesana@company.local, COMPANY\svc-vesana or the full DN, plus its password

Then “Test connection”:

• Certificate: if Vesana does not trust the DC's certificate yet, the dialog shows it: name, issuer, validity and SHA-256 fingerprint. “Trust this certificate” stores it. With Active Directory, Vesana also fetches the domain's certificate authority certificate from AD at the same time. That one is then trusted, which survives the yearly renewal of the DC certificates. Without an AD certificate authority, exactly the server certificate is stored. When the server renews it, simply fetch it again with “Fetch from server”.
• Base DN: detected and filled in (e.g. DC=company,DC=local).
• At the end it says “All good — the connection works”, or, for each step, what to do.

2. Who may sign in?

• Existing users only: only users who already exist in Vesana can sign in — with the same name as in AD (max.muster or max.muster@company.local). At the first sign-in with the domain password, the Vesana account is linked to the AD account; from then on, only the domain password counts.
• All domain users: whoever signs in for the first time automatically gets a Vesana account (user name max.muster@company.local). Along with this:
  • Only members of these groups (strongly recommended, e.g. Vesana-Access). Without a group, any domain user can sign in.
  • Default role for everyone whose groups have no role of their own.
  • Roles by directory group, e.g. Vesana-Admins → Admin. The first matching row wins. This applies when the account is created; afterwards you change the role in user management.
• Teams from directory groups: AD group → Vesana team. Synchronized at every sign-in and every 15 minutes: whoever leaves the group in AD loses the team (and its permissions). Manually assigned teams stay.

Write group names as in AD (Vesana-Admins); case does not matter, the full DN works as well.

3. Test a user

Bottom right in the dialog: enter a user name (password optional) → “Test user”. Vesana shows before saving:

• the account found and its display name
• all groups, including nested ones
• whether a Vesana account exists or will be created
• which role and which teams it gets
• with a password: whether sign-in would work, otherwise why not (disabled, expired, must change password, …)

Then Save. Done — the sign-in form accepts domain accounts right away.

What Vesana secures in the background

• Account disabled, deleted or removed from the group in AD ⇒ within 15 minutes at most, all Vesana sessions of that user end. Once the account is enabled again, the user can sign in normally.
• No AD account lockout caused by Vesana: after 5 wrong passwords for an account, Vesana sends no further attempts to AD for 15 minutes. The usual AD lockout threshold is higher. The user reads “Too many wrong passwords … please wait 15 minutes”.
• Local super admins are never linked to AD. They remain the emergency exit if the directory fails. Recommendation: keep at least one local super admin account.
• Directory unreachable: domain accounts cannot sign in (clear message). Only if an account had a local Vesana password before it was linked does that password serve as an emergency exit. An admin can set such an emergency password under user management → “Set password”.
• The service account password is stored encrypted in the database and never displayed. When you change the server, certificate or service account, Vesana asks for it again — so it can never be sent to another server.
• Disabling or deleting the directory ends all sessions of its users immediately. When deleted, the accounts become local again; whoever has a password signs in with it.

Troubleshooting

Message / symptom	Cause and fix
“The certificate is not trusted”	Trust the certificate shown by “Test connection”, or paste the CA certificate: on a domain PC run certutil -ca.cert ca.cer and certutil -encode ca.cer ca.pem, then paste the content of ca.pem under “Paste certificate”.
“The server you entered is not in the certificate”	Enter the name from the certificate (the dialog lists it) instead of an IP address or short name.
“Server reachable” fails	Can the Vesana server reach the DC? Is the DNS name resolvable (nslookup dc1.company.local on the Vesana server)? Firewall 636 or 389 open?
“Service account signed in” fails	Check the service account name/password; account enabled, password not expired?
User “not found”	Is the account below the base DN? For “Other LDAP”, adjust the user filter under “Advanced” if needed.
User: “not enabled for Vesana”	The user is in none of the groups under “Only members of these groups”.
User: “No Vesana account”	Mode “Existing users only” — create the account in Vesana (same name) or switch to “All domain users”.
User: “must change” / “expired”	Change the password in Windows first, then sign in again.

Every sign-in attempt is in the audit log (with the reason for failures), directory problems are in the diagnostic log (category “auth”).

Other LDAP directories

For OpenLDAP, FreeIPA & co., choose “Other LDAP”. Defaults: users by uid or mail, groups by memberOf or groupOfNames/posixGroup. Deviations under Advanced: user filter ({login} = name entered without domain, {upn} = as entered), attributes for user and display name, port, timeout.

See also: SSO (OIDC) for Entra ID, Keycloak & co. — both can run side by side.