LDAP / Active Directory Integration

Point Athena at your LDAP or Active Directory so staff sign in with their existing directory credentials — no second set of passwords to manage. Athena verifies each login against the directory, maps the user's directory groups to Athena roles, and creates the local account on first sign-in. Local accounts keep working alongside it, so you always retain a break-glass path.

How directory login works#

Athena uses the standard search-then-bind pattern. It never guesses a user's distinguished name from a template — it looks the user up first, then binds as the account it found:

1. Service bind. Athena connects to your directory and binds with the dedicated service account you configure (BindDn / BindPassword).
2. Search. Using your UserSearchFilter (the typed username is safely escaped), Athena finds the one matching entry under the BaseDn. A search that returns zero or more than one entry is treated as a failed login.
3. Group resolution. Athena reads the user's group membership — by default it resolves nested (transitive) membership on Active Directory, falling back to the direct memberOf list on directories that don't support that.
4. User bind. Athena opens a fresh connection and binds as the discovered account with the password the user typed. This bind is the real credential check.
5. Role & account. The user's groups are mapped to an Athena role, and the account is provisioned or refreshed just-in-time (see Group-to-role mapping and Just-in-time provisioning).

Before you start#

• A service / bind account in your directory with read access to user and group objects. Athena binds as this account to search; it fails closed (denies all directory logins) if the bind account is not configured, so it never silently falls back to an anonymous search.
• The directory host and port (default 636 for LDAPS) reachable from the Athena server.
• Your search base DN (for example DC=corp,DC=example).
• For TLS transports, the directory's CA certificate trusted by the Athena server (see Transport & TLS).
• An Admin Athena account to save the settings.

Configure the connection#

Fill in the directory connection on Settings → Security → Login, or send it to api/settings/ldap. The main fields:

Attribute & filter mapping#

The defaults target Active Directory. Adjust these for OpenLDAP or other directories. In the UserSearchFilter and NestedGroupSearchFilter, {0} is replaced by the (safely escaped) username or user DN respectively.

Transport & TLS#

The EncryptionMode controls how the connection is secured:

An unset or unrecognised mode is rejected and defaults to the fail-secure LDAPS. For the encrypted modes, the Athena server must trust the certificate the directory presents — install the directory's CA into the operating-system trust store, or point Athena at it with CaCertificatePath / CaCertificateThumbprint.

Test the connection#

Before you enable directory login, run the built-in probe. It performs the service bind, validates TLS, and checks that the base DN is reachable — and it can test settings you haven't saved yet, so you can validate a change before committing it.

# Probe the currently saved settings
Test-AthenaLdapConnection

# Probe an unsaved configuration (values you pass override the saved ones)
Test-AthenaLdapConnection -Host "dc01.corp.example" `
  -BindDn "CN=svc-athena,OU=Service,DC=corp,DC=example" `
  -BindPassword "<service-password>"

The probe never throws — a failure comes back as a result with Success = false plus a human-readable message and a non-sensitive diagnostic hint (the failing step), so you can tell a TLS problem from a bad bind or an unreachable base DN. The same probe backs the Test connection button in the Settings UI and the POST api/settings/ldap/test-connection endpoint.

Group-to-role mapping#

Athena has four fixed roles — User, Helpdesk, Operator, and Admin (see Roles & Permissions). You grant them to directory users by mapping directory groups to roles. Each mapping is one group → role rule.

• Highest role wins. If a user's groups match several mappings, they get the highest-privilege role among them.
• No match. A user whose groups match no mapping gets the DefaultRole — unless DenyOnNoMatch is on, in which case sign-in is denied.
• Per-provider. Mappings are scoped to a provider (Ldap or Keycloak): an LDAP login resolves only against Ldap mappings, so the same group name can be reused for Keycloak without collision.
• Edited mappings take effect on the next sign-in — no restart required.

Manage mappings in the console, or with the PowerShell module:

# Map a directory group to the Admin role
New-AthenaLdapMapping -GroupName "athena-admins" -Role Admin

# List the current LDAP mappings
Get-AthenaLdapMapping

# Change a mapping, then remove one by id
Set-AthenaLdapMapping -Id $id -GroupName "athena-operators" -Role Operator
Remove-AthenaLdapMapping -Id $id

Just-in-time provisioning#

You don't pre-create directory accounts in Athena. On a user's first successful directory sign-in, Athena creates their local account automatically and keys it to the immutable ExternalIdAttribute (objectGUID by default), so a later rename or OU move still recognises the same person. On every subsequent login, Athena refreshes the account's role, display name, and email from the current directory state. A few rules keep this safe:

• Directory accounts never store a local password — they can only sign in through the directory.
• A directory login can never take over an existing local account (or a different provider's account) that already owns the same username — that login is refused rather than converting the account.
• An account an admin has disabled in Athena stays disabled — a valid directory bind will not re-enable it.

REST API#

All endpoints below require an Admin session. See the API Reference for authentication details.

PowerShell#

The Athena module exposes the whole workflow. All of these require an Admin session — connect first with Connect-Athena.

A minimal end-to-end enablement, from a connected Admin session:

# 1) Configure the directory connection (LDAPS)
Set-AthenaLdapSettings -Enabled $true `
  -Host "dc01.corp.example" -Port 636 `
  -EncryptionMode "LDAPS" `
  -BaseDn "DC=corp,DC=example" `
  -BindDn "CN=svc-athena,OU=Service,DC=corp,DC=example" `
  -BindPassword "<service-password>"

# 2) Verify it works before anyone relies on it
Test-AthenaLdapConnection

# 3) Grant roles by group
New-AthenaLdapMapping -GroupName "athena-admins"    -Role Admin
New-AthenaLdapMapping -GroupName "athena-operators" -Role Operator
New-AthenaLdapMapping -GroupName "helpdesk"          -Role Helpdesk

Auditing#

Directory configuration changes are written to the audit log as an authentication settings change, recording a per-field old→new diff (the bind secret is never included). Directory sign-ins, role refreshes, and denials are logged like any other login. See Audit & SIEM for how to review and forward these events.

Troubleshooting#