LDAP and Active Directory Sign-In

With an LDAP / Active Directory identity provider, users sign in to UTMStack v12 with their directory email and password on the normal UTMStack sign-in page, and UTMStack checks them against your directory over LDAP (Lightweight Directory Access Protocol). This page explains how the check works, every field, and a complete Microsoft Active Directory example.

Read Single Sign-On first for how accounts and roles work. Creating identity providers needs an Enterprise licence.

How an LDAP sign-in works

1. The user opens the UTMStack sign-in page. They either click Continue with the directory's name (the page then shows "Signing in to" and the name, with Use another to go back), or simply type their email and password.

2. UTMStack connects to the directory server on the configured port and, if Use StartTLS is on, switches the connection to encryption.

3. UTMStack signs in to the directory with the service account (Bind DN and Bind password).

4. It searches below Base DN with User filter, where %s is replaced by what the user typed. The search must find exactly one entry.

5. It signs in to the directory again as that entry, with the password the user typed. If the directory accepts it, the password is right.

6. It reads the user's email, name and groups from the entry, finds or creates the UTMStack account with that email, and decides the roles as described in Single Sign-On.

7. If the user turned on UTMStack two-step sign-in, UTMStack asks for the code.

When the user does not choose a directory, UTMStack tries every active LDAP provider of the tenant, but only for addresses that have no local UTMStack account or whose account was created through an identity provider. A user who has a local UTMStack password signs in with that password unless they click Continue with the directory first.

Requirements

• The UTMStack server can reach the directory server on the LDAP port (389 by default) over TCP.

• A service account that can search the directory. In Active Directory, an ordinary domain user can read users and their groups; it needs no administrator rights.

• Use StartTLS works only if the directory server's certificate is valid for the Host name you enter and is issued by a certificate authority that the UTMStack server trusts, such as a public certificate authority. Certificates issued by a private certificate authority, as is common for domain controllers, are not trusted, and the sign-in fails.

Fields

Fill in all three attribute fields, or clear all three. If only some are filled in, UTMStack asks the directory only for those attributes, and the others come back empty.

Under Accounts and roles, the Groups attribute field is not used for LDAP; the Group attribute above is. Map group common names in Group to role.

Example: Microsoft Active Directory

The domain in this example is corp.example.com, and UTMStack access is given through three groups: UTMStack-Admins, UTMStack-Analysts and UTMStack-Viewers.

In Active Directory

1. Create a service account, for example svc-utmstack, in an organizational unit such as OU=Service Accounts. Give it a long password and decide how you will update UTMStack when the password changes.

2. Create the three security groups and add the users.

3. Make sure every UTMStack user has an email address in the E-mail field (mail attribute). That address is their UTMStack sign-in.

In UTMStack

Go to Configure > Settings > Identity Providers, click Add provider, name it corp-ad, choose LDAP / Active Directory, and enter:

The longer filter lets only members of a UTMStack-Users group sign in. Leave it out if the group mapping with Default role set to None is enough for you.

Keep Active (show on the login page) on (the default), click Create provider, and test by signing in with a directory user in a private browser window. An inactive LDAP provider is never tried.

Useful filters

Ask users to type the same address that the Email attribute holds. That address is the UTMStack account.

Things to know about Active Directory groups

• memberOf lists only direct memberships. If a user is in a group that is itself a member of UTMStack-Admins, UTMStack does not see UTMStack-Admins. Add users directly to the mapped groups.

• The primary group (usually Domain Users) is not listed in memberOf.

• Group names are compared without regard to case.

Check the connection from the server

Before you blame UTMStack, check the directory from the UTMStack server with ldapsearch (package ldap-utils on Ubuntu and Debian, openldap-clients on Red Hat). It uses the same steps as UTMStack:

ldapsearch -x -ZZ -H ldap://dc01.corp.example.com:389 
  -D "CN=svc-utmstack,OU=Service Accounts,DC=corp,DC=example,DC=com" -W 
  -b "DC=corp,DC=example,DC=com" 
  "(&(objectClass=user)([email protected]))" mail displayName memberOf

-ZZ requires StartTLS, like Use StartTLS; remove it to test without. The search must return exactly one entry.

Troubleshooting

The reason behind a failed LDAP sign-in is not shown in App Audit Logs. Use the ldapsearch check to find it.