Configuring Altus Director Server for LDAP and Active Directory

By default, the Altus Director server uses its own internal database to store user accounts and authorizations. You can instead configure the server to perform authentication and authorization using an external LDAP server, including Active Directory.

User and Group Model

When configured for LDAP, Altus Director expects that each user has an entry in an LDAP server under some base DN. When a user attempts to log in to the Altus Director server, the server will locate the user in LDAP and try to authenticate the user against the LDAP server using the provided password.

Altus Director expects that LDAP groups, collected under some base DN, are used to determine the roles that a user is authorized for. If a user is a member of a group in LDAP, then the user is granted the role that maps to that group. Multiple groups can map to the same role in Altus Director, and users can have multiple roles. Altus Director does not support the use of nested groups in LDAP to determine roles.

Basic LDAP Configuration

Determine the following pieces of information in order to configure Altus Director for LDAP. The same information is also needed for Active Directory.
  • The LDAP server host and port.
  • The bind DN and password that Altus Director should use when searching for users and groups. This account does not need administrative access to the LDAP server, but only read access for the necessary searches.
  • The base DN for user searches.
  • The filter to use for user searches or the DN pattern that all user DNs adhere to. More information on these is provided below.
  • The base DN for group searches.
  • The filter to use for group searches. More information on this is provided below.
  • The attribute of each group that forms the basis for an Altus Director role. More information on this is provided below.
The user search filter is employed to locate a user attempting to log in to Altus Director. The user's login username is substituted into the filter before it is submitted to the LDAP server. The string {0} indicates where the username is substituted.
  • To look for a username in the uid attribute of a user entry, use the filter (uid={0}).
  • To look for a username in the cn attribute of a user entry, use the filter (cn={0}).
  • For Active Directory, use the filter (sAMAccountName={0}).
Instead of specifying a user search filter, you can instead supply a user DN pattern. This avoids a search, because Altus Director can determine a user DN by substituting the user's login username into the pattern. The string {0} indicates where the username is substituted.
  • The user DN pattern cannot be used for Active Directory. Instead, a user search filter must be supplied.
The group search is employed to locate groups that an authenticated user belongs to. The user's DN is substituted into the filter before it is submitted to the LDAP server. The string {0} indicates where the username is substituted.
  • When using the objectclass groupOfUniqueNames for user groups, use the filter (uniqueMember={0}).
  • For Active Directory, use the filter (member={0}).
The group role attribute selects which attribute of a group entry is used as the basis for determining the corresponding Altus Director role. Usually this is the CN of the group, but any attribute can be selected instead.
  • The group role attribute is not used for Active Directory. The group name is always used as the basis for determining a role.
The following configuration properties control basic LDAP connectivity. Additional configuration properties described in a later section are needed for Active Directory.
Configuration Property Default Meaning
lp.security.userSource internal Where to look for user data; for LDAP or Active Directory connectivity, set this to LDAP.
lp.security.ldapConfig.url N/A The LDAP URL, with host and optional port, e.g.: ldap://ldaphost:389/.
lp.security.ldapConfig.bindDn N/A The bind DN for Altus Director to use for searches.
lp.security.ldapConfig.bindPw N/A The bind password for Altus Director to use for searches.
lp.security.ldapConfig.userSearchBase N/A The base DN for user searches.
lp.security.ldapConfig.userSearchFilter N/A The user search filter, e.g., (uid={0}).
lp.security.ldapConfig.ldapDnPattern N/A The DN pattern for users.
lp.security.ldapConfig.groupSearchBase N/A The base DN for group searches.
lp.security.ldapConfig.groupSearchFilter N/A The group search filter, e.g., (uniqueMember={0}).
lp.security.ldapConfig.groupRoleAttribute N/A The group attribute to use as a basis for selecting a role, e.g., cn.

After setting or changing these configuration properties, restart the Altus Director server for them to take effect.

The following is an example of an LDAP configuration that points to an OpenLDAP server. Each user's uid attribute is used as their login username, and group membership is determined by the uniqueMember attribute. 
lp.security.userSource: LDAP
lp.security.ldapConfig.url: ldap://openldaphost/
lp.security.ldapConfig.bindDn: cn=ldapadm,dc=domain,dc=example
lp.security.ldapConfig.bindPw: password
lp.security.ldapConfig.userSearchBase: ou=People,dc=domain,dc=example
lp.security.ldapConfig.userSearchFilter: (uid={0})
lp.security.ldapConfig.ldapDnPattern: uid={0},ou=People,dc=domain,dc=example
lp.security.ldapConfig.groupSearchBase: ou=Groups,dc=domain,dc=example
lp.security.ldapConfig.groupSearchFilter: (uniqueMember={0})
lp.security.ldapConfig.groupRoleAttribute: cn

Local User Management under LDAP

Altus Director does not provide user management services when configured for LDAP. To make changes to user accounts and roles, make the necessary changes in the source LDAP server. Users might need to log out of Altus Director and log back in for changes to take effect.

Most user API endpoints for the Altus Director server are disabled when the server is configured for LDAP, and will return the HTTP response code 400 (Bad Request) for any request. Also, the Altus Director server UI does not present user management capabilities, such as password changes, when the server is configured for LDAP.

Role Mapping

Altus Director maps LDAP groups to its own roles in a simple fashion.
  1. The value of the group role attribute, such as cn, is found.
  2. The value is converted to uppercase.
  3. The prefix ROLE_ is prepended.

Therefore, a group with a role attribute of admin is converted to the role ROLE_ADMIN. When using a role attribute of cn, then the DN for the group is similar to cn=admin,ou=Groups,dc=domain,dc=example.

Currently, the only roles supported by Altus Director are:
  • ROLE_READONLY - read-only / guest access
  • ROLE_ADMIN - full access

An administrative account should have all roles, and therefore be a member of all mapped groups.

Role mapping is more complex for Active Directory and is described below.

Active Directory Configuration

Determine the following additional pieces of information in order to configure Altus Director for Active Directory.
  • The domain for users and groups.
  • The desired role mapping from group names to Altus Director roles.
The following configuration properties control Active Directory connectivity, in addition to those for basic LDAP configuration.
Configuration Property Default Meaning
lp.security.ldapConfig.activeDirectory.domain N/A The domain.
lp.security.ldapConfig.activeDirectory.roleMapping.* N/A The role mapping (multiple properties).

After setting or changing these configuration properties, restart the Altus Director server for them to take effect.

The following is an example of an LDAP configuration that points to an Active Directory server. Each user's sAMAccountName attribute is used as their login username, and group membership is determined by the member attribute. 
lp.security.userSource: LDAP
lp.security.ldapConfig.url: ldap://adhost/
lp.security.ldapConfig.bindDn: cn=Administrator,ou=Users,dc=domain,dc=example
lp.security.ldapConfig.bindPw: password
lp.security.ldapConfig.userSearchBase: ou=Users,dc=domain,dc=example
lp.security.ldapConfig.userSearchFilter: (sAMAccountName={0})
lp.security.ldapConfig.groupSearchBase: ou=Groups,dc=domain,dc=example
lp.security.ldapConfig.groupSearchFilter: (member={0})
lp.security.ldapConfig.activeDirectory.domain: DOMAIN.EXAMPLE
lp.security.ldapConfig.activeDirectory.roleMapping.adminGroup: admin
lp.security.ldapConfig.activeDirectory.roleMapping.readonlyGroup: readonly

Role Mapping

Altus Director provides flexibility in mapping the names of Active Directory groups to Altus Director roles. The mapping process is:
  1. The group name is searched for among the roleMapping configuration properties.
    1. If one is found, the property value is used as the base name for the role.
    2. If one is not found, the group is ignored.
  2. The base name is converted to uppercase.
  3. The prefix ROLE_ is prepended.
In the example below, two groups named group1Name and group2Name are mapped to the ROLE_READONLY Altus Director role, while another group3Name is mapped to the ROLE_ADMIN role. 
lp.security.ldapConfig.activeDirectory.roleMapping.group1Name: readonly
lp.security.ldapConfig.activeDirectory.roleMapping.group2Name: readonly
lp.security.ldapConfig.activeDirectory.roleMapping.group3Name: admin