Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

04.06 Active Directory and LDAP

Configure SimpleRisk to authenticate against an LDAP directory or Active Directory via the Authentication Extra. Covers server connection, bind account, search filter, attribute mapping, group-to-team mapping, and the test-before-enforcing workflow for safe rollout.

Requires: Authentication Extra

LDAP and Active Directory authentication are added by the Authentication Extra at simplerisk/extras/authentication/. Without the Extra activated, SimpleRisk has only Core local authentication.

Why this matters

LDAP / Active Directory is the on-premises identity backbone for the substantial majority of mid-market and enterprise organizations. Even programs that use SaaS IdPs for cloud applications still run on-prem AD for the workstation, file-share, and legacy-app populations. For SimpleRisk deployments hosted on the corporate network (or in a hybrid posture), pointing the application at the AD that already governs every other internal service produces the cleanest operator and user experience: existing passwords work, deprovisioning a leaving employee in AD also blocks SimpleRisk access, and group memberships drive team assignment.

The honest scope to know up front: the LDAP path is bind-validation. SimpleRisk binds to the directory using the user's credentials; if the bind succeeds, the user is authenticated. There's no second-factor enforcement at the protocol level (LDAP doesn't carry MFA assertions). For MFA-on-LDAP, you need an external MFA solution that intercepts the LDAP bind (Microsoft Conditional Access for cloud-joined devices, third-party MFA gateways for on-prem, or PIV/smart-card via a separate auth flow). If MFA is non-negotiable and not deliverable at the LDAP layer, SAML 2.0 with an MFA-enforcing IdP (see Configuring SAML SSO) is the better path.

The other thing worth knowing: LDAP and SAML are mutually exclusive as the active auth method. The Authentication Extra exposes a dropdown selecting one. If you need both LDAP for the on-prem population and SAML for the cloud population, the supported pattern is to federate them at the IdP level (Azure AD Connect synchronizing on-prem AD to Azure AD; Azure becomes the SAML IdP for SimpleRisk) rather than running both protocols simultaneously against SimpleRisk.

Before you start

Have these in hand:

  • Admin access to Configure → Extras → Authentication Extra for the configuration UI.
  • The LDAP / AD server hostname and port. Common: ldap.corp.example.com on 389 (LDAP) or 636 (LDAPS); domain controllers typically expose both.
  • A service account for the bind. SimpleRisk binds with this account first to search for the user, then re-binds as the user to validate the password. The service account needs read access to the user OU and group OU (no write needed). Don't reuse a domain admin account; create a dedicated, least-privileged read account.
  • The bind DN format. Active Directory uses CN=Service Account Name,OU=Service Accounts,DC=corp,DC=example,DC=com; OpenLDAP varies by deployment.
  • The user search base DN (e.g., OU=Users,DC=corp,DC=example,DC=com) and group search base DN (e.g., OU=Groups,DC=corp,DC=example,DC=com).
  • The user search filter. AD: (&(objectCategory=Person)(sAMAccountName=%username%)) is the canonical filter. OpenLDAP: (&(objectClass=inetOrgPerson)(uid=%username%)). The %username% placeholder is replaced at runtime with the login attempt's username.
  • TLS configuration. LDAPS (port 636 with implicit TLS) or StartTLS on port 389 is mandatory for production; cleartext LDAP on port 389 is acceptable only on a fully-trusted network and even then is a security finding waiting to happen.
  • A test AD account (non-admin) for verifying the configuration without committing the rollout to all users.
  • The mapping plan from AD groups to SimpleRisk teams, if you want group-driven team assignment.

Step-by-step

1. Activate the Authentication Extra

Sidebar: Configure → Extras → Authentication Extra → Activate. See The Authentication Extra Overview for what activation does.

2. Configure the LDAP server connection

Open the Authentication Extra's configuration UI. The LDAP-specific settings (with their underlying settings table keys):

  • LDAP Host (LDAPHOST) — the directory hostname (e.g., dc01.corp.example.com). Avoid IP addresses for production; the certificate's CN/SAN won't match.
  • LDAP Port (LDAPPORT) — 389 for plain or StartTLS, 636 for LDAPS. Default: 389.
  • LDAP Version (LDAP_VERSION) — 3 for any modern AD or OpenLDAP. Default: 3.
  • Use TLS / StartTLS (TLS) — 1 to upgrade the connection to TLS via StartTLS (after connecting on port 389). Set to 1 for any production deployment.
  • Use SASL (SASL) — 1 for SASL DIGEST-MD5 auth instead of simple bind. Most AD deployments use simple bind over TLS; leave at 0 unless your environment specifically requires SASL.

Save and confirm the page accepts the values without error.

3. Configure the bind account

The service account SimpleRisk uses to search the directory before validating a user's password:

  • Bind First (BIND_FIRST) — 1 to bind with the service account before the user search. This is the typical flow; the service account does the search, then SimpleRisk re-binds as the user to validate the password.
  • Bind Account (BIND_ACCOUNT) — the service account's DN. Format varies:
  • Active Directory: CN=SimpleRisk LDAP Service,OU=Service Accounts,DC=corp,DC=example,DC=com (or the AD-style simplerisk-ldap@corp.example.com for UPN bind).
  • OpenLDAP: cn=simplerisk-ldap,ou=services,dc=corp,dc=example,dc=com.
  • Bind Account Password (BIND_ACCOUNT_PASS) — the service account password. Stored in the settings table; protect the database accordingly.

If BIND_FIRST is 0, SimpleRisk binds directly as the user (no service-account search step). This works only if the user's DN can be constructed from the username deterministically (e.g., template-based DN), which is rare for AD; default to 1.

4. Configure the user search

How SimpleRisk finds the user record in the directory once the service account is bound:

  • User Base DN (USERDN) — the search base for users (e.g., OU=Users,DC=corp,DC=example,DC=com). Narrow this to the OU containing your user accounts; a too-broad search base (the domain root) makes the search slower and may hit objects you don't expect.
  • User Filter (LDAP_USER_FILTER) — the filter template with %username% as the placeholder. Examples:
  • AD: (&(objectCategory=Person)(sAMAccountName=%username%))
  • OpenLDAP: (&(objectClass=inetOrgPerson)(uid=%username%))
  • AD with email-based login: (&(objectCategory=Person)(mail=%username%))
  • User Attribute (AUTHENTICATION_LDAP_USER_ATTRIBUTE) — which attribute on the LDAP user record corresponds to the SimpleRisk username. Options:
  • DN — full distinguished name.
  • email — the email attribute (mail in AD/OpenLDAP).
  • sAMAccountName — the AD pre-Windows-2000 username.
  • userPrincipalName — the AD UPN (e.g., alice@corp.example.com).

Pick the attribute that's stable for your environment. userPrincipalName is the most common AD choice; sAMAccountName is shorter but legacy. Whatever you pick, that's the value users will type into the SimpleRisk login form.

5. Configure attribute mapping for new-user provisioning

When a new user authenticates for the first time, SimpleRisk creates a local record from the LDAP attributes. The mapping fields:

  • Display Name attribute — typically displayName (AD) or cn (OpenLDAP).
  • Email attribute — typically mail.
  • Manager attribute (LDAP_MANAGER_ATTRIBUTE) — optional; the DN of the user's manager (manager in AD). Used to populate the manager field on the SimpleRisk user record, which feeds organizational-hierarchy and approval workflows.

The auto-provisioning behavior is gated on AUTHENTICATION_ADD_NEW_USERS (system-wide). When 1, any successful LDAP bind for an unknown username creates a new user; when 0, only pre-provisioned users can authenticate.

6. Configure group-to-team mapping

If you want LDAP group memberships to drive SimpleRisk team assignment:

  • Group Base DN (GROUPDN) — the search base for groups (e.g., OU=Groups,DC=corp,DC=example,DC=com).
  • Group Attribute (LDAP_GROUP_ATTRIBUTE) — the attribute on the group object identifying the group name. Typically cn.
  • Member Attribute (LDAP_MEMBER_ATTRIBUTE) — the attribute on the group object listing members. AD: member. OpenLDAP: uniqueMember.
  • Group Filter (LDAP_FILTER_FOR_GROUP) — optional filter to narrow which groups are considered (e.g., (cn=SimpleRisk-*) to only consider groups whose name starts with SimpleRisk-).

Once configured, the group-to-team mapping itself lives in the remote_team table (and ldap_group_and_teams). Map each LDAP group to a SimpleRisk team via the Authentication Extra's group-mapping UI. On every login, SimpleRisk re-reads the user's group membership from LDAP and updates the SimpleRisk team assignments accordingly.

7. Test the configuration before activating

The Authentication Extra exposes a test_ldap_configuration() function (typically surfaced as a Test Configuration button on the settings page). Run it before changing the active auth method:

  1. Click Test Configuration.
  2. The test attempts the service account bind, runs a sample user search, and reports the result.
  3. If the test fails, the error message indicates the layer (network, bind, search) — fix and retest.

After the configuration test passes, do an end-to-end test with a real user account:

  1. Without changing the active auth method yet, log out of SimpleRisk.
  2. Open a private/incognito browser window.
  3. Manually trigger the LDAP path (the test surface may expose a "log in as test user" flow, or you can temporarily switch the active method to LDAP).
  4. Authenticate as a test AD user.
  5. Confirm the user is created (if AUTHENTICATION_ADD_NEW_USERS = 1) or matched (if pre-provisioned).
  6. Confirm the attribute mapping populated the right fields.
  7. Confirm the group-to-team mapping (if configured) assigned the right teams.

Iterate until the test user authenticates cleanly. Then switch the active method.

8. Switch the active authentication method to LDAP

Once the test passes, switch the active auth method (the dropdown on the settings page) from Local to LDAP. Save.

What changes immediately:

  • New login attempts for users without type='simplerisk' go through the LDAP path.
  • Existing type='simplerisk' users (the operator account) continue to authenticate via local auth.
  • New users coming in via LDAP get type='ldap' and the auto-provisioning behavior takes over.

Don't deactivate local auth or change the operator account's type. The local-auth path stays as the recovery surface if LDAP breaks.

9. Plan for credential rotation and certificate lifecycle

The service account password should rotate on a cadence that matches your AD password policy. The rotation:

  1. Set a new password on the service account in AD.
  2. Update the Bind Account Password field in SimpleRisk (BIND_ACCOUNT_PASS).
  3. Click Test Configuration to confirm the new credentials work.
  4. The previous password expires out naturally.

If you're using LDAPS or StartTLS, the LDAP server's TLS certificate also has an expiration. Track it in your certificate inventory; renewals should be transparent to SimpleRisk if the new certificate is signed by the same CA SimpleRisk's PHP environment trusts.

10. Plan for AD changes that affect users

Some operational events to plan for:

  • User OU restructure (moving users between OUs): the user search may stop finding users if the search base no longer covers them. Update USERDN to cover the new structure.
  • Group renames or moves: the remote_team mappings reference groups by name (or DN, depending on configuration); a renamed group breaks the mapping. Update the remote_team rows to match.
  • AD migration (on-prem to Azure AD, or domain consolidation): plan the SimpleRisk re-configuration alongside the AD migration. The user records in SimpleRisk persist; the mapping just needs to point at the new directory.

Common pitfalls

A handful of patterns recur with LDAP/AD configuration.

  • Cleartext LDAP in production. LDAP on port 389 without StartTLS sends bind credentials (including the service account password) in the clear. Use LDAPS (636) or enable StartTLS (TLS=1). The performance overhead is negligible; the security delta is enormous.

  • Using a domain admin account for the bind. The bind account needs read access to the user OU and group OU; nothing more. A compromised bind account with domain admin privileges is a much bigger problem than one with read-only directory access. Create a dedicated, least-privileged service account.

  • Too-broad user search filter. A filter like (sAMAccountName=%username%) without the objectCategory=Person constraint may match computer objects, service accounts, and disabled users. Use the AD-canonical (&(objectCategory=Person)(sAMAccountName=%username%)) to constrain to actual users.

  • Forgetting to scope the search base. A USERDN set to the domain root (DC=corp,DC=example,DC=com) makes every search a full-domain scan. Narrow to the OU(s) containing actual users.

  • AUTHENTICATION_ADD_NEW_USERS = 1 without group-based gating. Auto-provisioning means every AD user who authenticates gets a SimpleRisk account on first login. For broad AD deployments, that's potentially thousands of unintended accounts. Either constrain LDAP_USER_FILTER to require membership in a SimpleRisk-specific group, or set the toggle to 0 and pre-provision.

  • Switching the active method without testing first. Changing Local → LDAP in production without a tested configuration locks every non-local user out until the configuration is fixed. Always test before switching.

  • Disabling local auth after switching to LDAP. If LDAP breaks (network outage, expired bind credentials, AD reconfiguration), the local-auth path is the recovery surface. Don't disable it.

  • Mismatched AUTHENTICATION_LDAP_USER_ATTRIBUTE and LDAP_USER_FILTER. If the filter searches by sAMAccountName but the user-attribute setting is email, SimpleRisk creates user records with email addresses as usernames but searches by sAMAccountName; lookup misses ensue. The two settings have to refer to attributes consistent with each other.

  • Group memberships not refreshing. SimpleRisk re-reads group membership on every login. If a user's group changes in AD and they don't log in, the SimpleRisk team assignment is stale. This is by design; pushing a "group changed, refresh now" event from AD to SimpleRisk isn't supported. The user's next login picks up the change.

  • Manager attribute pointing at a DN SimpleRisk doesn't have a user for. The LDAP_MANAGER_ATTRIBUTE populates the manager field on the SimpleRisk user record. If the manager isn't yet a SimpleRisk user (hasn't logged in), the manager link is empty until the manager logs in for the first time. Plan for this in onboarding workflows.

  • Storing the bind password in plain text in the settings table. It is stored in the settings table; anyone with database read access can retrieve it. Limit database read access accordingly. There's no encryption-at-rest for the bind password specifically.

Related

Reference

  • Permission required: check_admin for the Authentication Extra configuration UI.
  • API endpoint(s): None specific to LDAP configuration.
  • Implementing files: simplerisk/extras/authentication/index.php (is_valid_ad_user(), get_ldap_group_by_dn(), get_mapped_local_team_ids(), test_ldap_configuration(), authentication_add_new_user()).
  • Database tables: user (type='ldap' for LDAP-provisioned users); remote_team (LDAP/SAML group-to-team mapping); ldap_group_and_teams (LDAP-specific junction).
  • config_settings keys: LDAPHOST; LDAPPORT; LDAP_VERSION; TLS; SASL; BIND_FIRST; BIND_ACCOUNT; BIND_ACCOUNT_PASS; USERDN; LDAP_USER_FILTER; AUTHENTICATION_LDAP_USER_ATTRIBUTE; GROUPDN; LDAP_GROUP_ATTRIBUTE; LDAP_MEMBER_ATTRIBUTE; LDAP_FILTER_FOR_GROUP; LDAP_MANAGER_ATTRIBUTE; AUTHENTICATION_ADD_NEW_USERS; custom_auth; custom_auth_method.
  • External dependencies: PHP ldap extension; reachable LDAP/AD server with a service account that has read access to the user and group OUs.