LDAP Authentication

LDAP (Lightweight Directory Access Protocol) is often used by organizations as a central repository for user information and as an authentication service. It can also be used to store role information for application users.

The LDAP integration is based on the spring-security-ldap module with useful extensions.

Before you start configuring the Governor LDAP integration, ensure that you have access to your organization’s LDAP server. Or you can try ldap-sdk-tools to run LDAP locally as an alternative.

  • CN: Common Name

  • OU: Organizational Unit

  • DC: Domain Component

Configuration

LDAP Connectivity

The URL of the LDAP server is specified using the url property. The URL should be in the format ldap://myserver.example.com:389. For SSL access, use the ldaps protocol and the appropriate port, e.g. ldaps://myserver.example.com:636.

It is possible to configure multiple alternate LDAP servers using the urls property. In this case, provide all server URLs in a String array for the urls property.

spring.ldap.urls=ldap://localhost:389

You can also specify the root context for all LDAP operations using the base property. When a value has been specified for this property, all Distinguished Names supplied to and received from LDAP operations will be relative to the LDAP path supplied. This can significantly simplify working with the LDAP tree; however, there are several occasions when you will need to have access to the base path.

spring.ldap.base=dc=synthesized,dc=io

The LDAP user selection

It is possible to customize a user selection strategy according to the organization’s structure. Let’s consider the following example of a user definition:

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: bobspassword

To fetch this user, you need to specify two predicates:

ldap.user-details.user-search-base=ou=people (1)
ldap.user-details.user-search-filter=uid={0} (2)
1 Define the predicate where users would be located. In this example, the user is located in the people unit.
2 Define the predicate that extracts a user login from the uid variable.
The property values are set by default and do not require overriding in the base scenario.

Authentication

The Governor’s LDAP supplies two authentication implementations:

  1. Using Password Authentication

  2. Using Bind Authentication

Where Password Authentication is used by default.

Using Password Authentication

Password comparison involves comparing the password supplied by the user with the one stored in the LDAP Server. The password value is retrieved from an attribute and checked locally. This method is less secure than Using Bind Authentication, and usually requires SSL access.

An LDAP compare cannot be done when the password is properly hashed with a random salt.

The integration supports many password encoder formats: SHA, SHA256, SHA384, SHA512, SSHA, SSHA256, SSHA384, SSHA512, MD5, SMD5, PKCS5S2, CRYPT, PLAIN TEXT which are detected automatically.

You can specify the attribute name where the password is stored:

ldap.password-comparison-authenticator.password-attribute-name=userPassword (1)
1 The attribute name where the password is stored.

Using Bind Authentication

Bind Authentication is the most common mechanism for authenticating users with LDAP. In bind authentication, the user’s credentials (username and password) are submitted to the LDAP server, which authenticates them. The advantage of using bind authentication is that the user’s secrets (the password) do not need to be exposed to clients, which helps protect them from leaking.

To enable this type of authentication, set this property:

ldap.bind-authenticator.enabled=true

Authorities

According to the Governor’s Roles and permissions model, the user must have one of the following roles:

  • USER

  • OPERATOR

  • COMPLIANCE

  • ADMINISTRATOR

  • OWNER

The Governor’s LDAP supports one of two methods of fetching the authorities:

  1. In-house Authority Policy

  2. LDAP Authority Policy

In-house Authority Policy

In this case, role management is controlled at the Governor side by the OWNER or ADMINISTRATION role. The first user that signs up for the system is granted the OWNER role, and subsequent users are granted the USER role.

LDAP Authority Policy

In this case, role management is controlled at the LDAP Server side. You need to create Governor’s Authorities in any case and specify the method of extraction. Let’s consider the following example:

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=io

To activate authority retrieval from LDAP, set the following property:

ldap.authorities.enabled=true

For a more customizable search, you can override the default properties:

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=false (4)
ldap.authorities.ignore-partial-result-exception=false (5)
ldap.authorities.default-role=USER (6)
1 The LDAP search predicate for extracting groups.
2 The ID of the attribute that contains the role name for a group.
3 If set to true, a subtree scope search will be performed. If set to false, a single-level search is used. Setting to true enables searching the entire tree below the group-search-base.
4 The pattern to be used for the user search. {0} represents the user’s DN.
5 Sets the corresponding property on the underlying template, avoiding specific issues with Active Directory. A true value specifies whether PartialResultException should be ignored in searches. Refer to LdapTemplate.setIgnoreNameNotFoundException
6 The role set when another role is not found.
A user must be a member of only one Governor’s role.

In cases where you can’t create Governor’s roles, you can use role aliases from your group names:

ldap.authorities.role-aliases.operators=operator
ldap.authorities.role-aliases.developers=user
ldap.authorities.role-aliases.<ldap_group_name>=user

Active directory

Governor supports a specialized LDAP authentication provider that uses Active Directory configuration conventions. It authenticates using the Active Directory User-Principal-Name attribute.

To configure this provider, you can use the following properties:

activedirectory.urls=ldap://localhost:389 (1)
activedirectory.domain=synthesized.io (2)
activedirectory.root-dn=dc=synthesized,dc=io (3)
activedirectory.authorities.enabled=false (4)
1 The LDAP URL (or multiple URLs).
2 The domain name (may be null or empty).
3 The root DN (may be null or empty).
4 If set to false, it will manage authorities on the Governor side.
The activedirectory.domain will be used when activedirectory.root-dn is empty. In cases where activedirectory.domain is empty too, the search starts from the root.