LDAP and Active Directory
Users can sign in to Governor with their directory account. Governor checks the user name and password against your LDAP server or Active Directory, and can take each user’s role from their directory groups.
The integration is based on the spring-security-ldap module.
Before you start
-
You need access to your organization’s LDAP server, and a test account. To try the integration locally, you can run an LDAP server with ldap-sdk-tools.
-
Use
ldaps://, so passwords travel encrypted. Governor’s JVM must trust the certificate authority that signed the LDAP server’s certificate. -
The settings on this page are Spring properties of Governor’s API. On Docker Compose, set them as environment variables on the
backendservice, as described in Single Sign-On. -
Unless roles come from LDAP groups, the first user who signs in becomes the
OWNER. Sign in as the intended owner first.
In the examples, CN is a common name, OU an organizational unit and DC a domain component.
Connect to the server
Set the server’s URL with spring.ldap.urls, for example ldaps://ldap.example.com:636. To use several servers, list their URLs, separated by commas. Plain LDAP uses ldap:// and usually port 389.
spring.ldap.urls=ldaps://ldap.example.com:636
spring.ldap.base=dc=synthesized,dc=iospring.ldap.base is the root of all LDAP operations: the distinguished names in the other settings are relative to it.
Find users
Tell Governor where users are and how to match the name they sign in with. For a user defined like this:
dn: uid=bob,ou=people,dc=synthesized,dc=io
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Bob Hamilton
sn: Hamilton
uid: bob
userPassword: bobspasswordset:
ldap.user-details.user-search-base=ou=people (1)
ldap.user-details.user-search-filter=uid={0} (2)| 1 | Where users are: here, the people unit. |
| 2 | How to match the sign-in name: here, against uid. {0} is the name the user typed. |
These values are the defaults, so you only need them if your directory is organized differently.
Check passwords
Governor checks passwords in one of two ways:
| Method | How it works | When to use it |
|---|---|---|
Governor sends the user’s credentials to the LDAP server, which checks them. The password isn’t read from the directory. |
Recommended, and the most common way. |
|
Password comparison (default) |
Governor reads the stored password from the directory and compares it with the one the user typed. |
Only when bind isn’t possible. Use |
Bind
Bind authentication sends the user’s name and password to the LDAP server, which authenticates them. The password doesn’t need to be read from the directory, which helps keep it from leaking. Turn it on with:
ldap.bind-authenticator.enabled=truePassword comparison
Governor reads the password from an attribute of the user’s entry and compares it locally. It detects these password formats: SHA, SHA256, SHA384, SHA512, SSHA, SSHA256, SSHA384, SSHA512, MD5, SMD5, PKCS5S2, CRYPT and plain text. An LDAP compare can’t be done when the password is hashed with a random salt.
ldap.password-comparison-authenticator.password-attribute-name=userPassword (1)| 1 | The attribute that holds the password. |
Roles from LDAP groups
Every Governor user has one of the global roles MEMBER, ADMINISTRATOR or OWNER. See Roles and Permissions. Roles come from one of two places.
Roles managed in Governor (default)
Administrators and owners manage roles in Governor. The first user who signs in gets the OWNER role, and later users get MEMBER.
Roles from the directory
Governor reads the user’s groups from the directory at each sign-in. For groups like this one:
dn: cn=administrators,ou=groups,dc=synthesized,dc=io
objectclass: top
objectclass: groupOfUniqueNames
cn: administrators
ou: administrator
uniqueMember: uid=bob,ou=people,dc=synthesized,dc=ioturn it on with:
ldap.authorities.enabled=trueTo change how groups are found, set these. The values shown are the defaults:
ldap.authorities.group-search-base=ou=groups (1)
ldap.authorities.group-role-attribute=cn (2)
ldap.authorities.search-subtree=false (3)
ldap.authorities.group-user-search-filter=uniqueMember={0} (4)
ldap.authorities.ignore-partial-result-exception=false (5)
ldap.authorities.default-role=MEMBER (6)| 1 | Where groups are. |
| 2 | The attribute of a group that holds the role name. |
| 3 | true searches the whole tree below group-search-base; false searches one level only. |
| 4 | How to find the groups a user belongs to. {0} is the user’s distinguished name. |
| 5 | true ignores PartialResultException in searches, which avoids some issues with Active Directory. See LdapTemplate. |
| 6 | The role for a user whose groups match no role. |
A user must belong to only one group that maps to a Governor role.
If your group names aren’t Governor role names, map them with aliases:
ldap.authorities.role-aliases.operators=member
ldap.authorities.role-aliases.developers=member
ldap.authorities.role-aliases.<ldap_group_name>=memberActive Directory
Governor has a provider for Active Directory’s conventions. It signs users in with their User-Principal-Name.
activedirectory.urls=ldaps://ad.example.com:636 (1)
activedirectory.domain=synthesized.io (2)
activedirectory.root-dn=dc=synthesized,dc=io (3)
activedirectory.authorities.enabled=false (4)| 1 | The server URL, or several URLs. |
| 2 | The domain name. Can be empty. |
| 3 | The root distinguished name. Can be empty: then the domain is used, and if both are empty, searches start from the root. |
| 4 | false manages roles in Governor; true takes them from the directory. |
Check that it works
-
Sign in with a directory account in a private browser window.
-
Under Administration, check that the user has the role you expect.
-
With roles from the directory, sign in as a member of each mapped group.
LDAP uses Governor’s email and password form, so password sign-in stays on while LDAP is set up.