Implementing LDAP authentication

The TrueSight Server Automation Authentication Service can authenticate users defined in an LDAP registry. LDAP authentication can be configured to accept users from a single LDAP container (basic) or multiple (enhanced).

Note: Using Active Directory as the LDAP Server

If you are using Active Directory as the LDAP Server, BMC recommends to configure and use Domain Authentication. For more information, see Implementing Domain Authentication.

This topic provides information about the concepts and the steps involved in setting up LDAP-based authentication. These steps are performed on the application servers used for authentication, which will be any instances of type CONFIG or ALL in the environment. The steps below would not be performed on instances of type JOB or NSH_PROXY.

The high level steps for configuring LDAP authentication are noted below:

Specify the LDAP servers

Identify the LDAP server(s) you will authenticate against. Multiple LDAP servers can be provided.

The LDAP server(s) identified must support LDAPv3 over STARTTLS. LDAPS is not supported.
On the Application Server, start the blasadmin command line utility.
Specify the LDAP servers by performing the following steps:
1. Specify the URLs of all available LDAP servers:
```
set Ldap LdapServerURLs <serverList>
```
  where <serverList> is a list of one or more URLs of the LDAP servers in the environment. Each URL contains a server name or IP address (IPv4 or IPv6) and port. For example:
```
set Ldap LdapServerURLs ldap://server1:998,ldap://server2:1021,ldap://121.121.121.121:389,ldap://[2001::::::1]:389
```
2. If using multiple LDAP servers, optionally configure the timeout value the authentication request will wait for a response before moving on to the next LDAP server in the list.:
```
set Ldap ConnectionTimeoutMs <#>
```
  where <#> is the number of milliseconds to wait. The default value is set to 7000 milliseconds and should be sufficient for most environments.
If there are multiple application servers in the environment, repeat the above steps on all application instances used for LDAP authentication.

Provision the Authentication Service with trusted certificates

Communication between the Authentication Service and the LDAP server uses STARTTLS. In order to validate establish the TLS connection, the Authentication Service must be able to validate the LDAP server(s) certificate. This can be accomplished one of two ways:

Import certificates for all LDAP servers. You must repeat this procedure each time an LDAP server's certificate is updated.
Import the certificate chain of the trusted Certificate Authority that issued certificates to the LDAP servers.

Importing LDAP Server Certificates

To import each LDAP server's certificate, use the blcred command to create the trust store file and add the server certificate as described in Obtaining a certificate used to trust the LDAP server. For example, use the following command:
```
blcred -x ldapStore.pem cert -add -host <host>:<port> -protocol ldap
```
Repeat this command for each LDAP server, using the same trust store file.

Importing CA chain certificates:

If you have the CA chain certificates that signed the LDAP server's cert in PEM format, you can import each certificate into the store using the below command
```
blcred -x ldapStore.pem cert -import <cacert.pem>
```

If there are multiple application servers in the environment, copy the trust store file (ldapStore.pem) to the other application servers used for LDAP authentication.

Configuring the Authentication Service to use the trusted certificates

To identify the trust store containing trusted certificates, use the following command in the blasadmin utility:
```
set Ldap TrustStore <certificateStore>
```
where <certificateStore> is the local path to a trust store
To require the LDAP server(s)' hostname configured in the LDAPUrls setting above match the common name or alternate name on the certificate, set the following setting to true. If the name does not match, the connection from the Authentication Service to the LDAP server will not be allowed.
```
set Ldap IsHostValidationEnabled true
```
The Application Server only reads its certificate store when it starts up. If you change the certificate trust store, ensure that you restart the Application Server.

If there are multiple application servers in the environment, repeat the above steps on all application instances used for LDAP authentication.

Enabling LDAP Authentication

Enable LDAP authentication with the following command:
```
set AuthServer IsLdapAuthEnabled true
```
If there are multiple application servers in the environment, repeat the above steps on all application instances used for LDAP authentication.
Restart the application server after making the above changes

Logging in with a Distinguished Name

Users can now login with their Distinguished Name:

The users can be exist in different Organizational Units or groups.

Using a Distinguished Name Template

A Distinguished Name Template replaces the string {0} in the template with user supplied text. This allows the user to supply their Common Name instead of the full DN. For example, with a DN template of CN={0},CN=Users, DC=ad,DC=example,DC=net the user only enters a string such as "user1", which replaces the {0} substring. Consequently, the user's DN becomes CN=user1,CN=Users,DC=ad,DC=example,DC=net.

The DN template can be defined in the Authentication profile on each RCP client:

If this is your selected authentication method, restart the appserver services and skip ahead to Creating RBAC Users below.

If all users are in the same group or Organizational Unit, the DN template can be defined in the application server with the AuthServer LdapUserDnTemplate setting, and left blank in the RCP client

To define an LDAP distinguished name template, enter the following:
```
set AuthServer LdapUserDnTemplate "<text> {0} <text>"
```
where <text> represents any distinguished name objects that should be included in the template.
For example,
```
set AuthServer LdapUserDnTemplate "CN={0},OU=OU1,CN=Users,DC=ad,DC=example,DC=net"
```
If there are multiple application servers in the environment, repeat the above steps on all application instances used for LDAP authentication.

Restart the application server after making the above changes

If users are in multiple groups or Organizational Units in the directory and you want users to login with only their Common Name, then use Enhanced LDAP Authentication and leave the LDAPUserDnTemplate blank.

Enhanced LDAP authentication

To use Enhanced LDAP authentication set the below settings using blasadmin

- set Ldap UseEnhancedLdapAuth true
  Enables the use of the Enhanced LDAP Authentication feature for accepting a shorter version of the LDAP user name.
- set Ldap UserSearchBaseDn <baseDistinguishedName>
  Defines the base distinguished name(s) to use for searching for users. For example, if the full distinguished name of the user is "CN=user1,OU=ou1,DC=ad,DC=example,DC=net", then UserSearchBaseDn should be set to "OU=ou1,DC=ad,DC=example,DC=net". Separate multiple DNs with a semicolon ( ; ).
- set Ldap UserLookupAttribute <shortNameAttribute>
  Defines the attribute of an LDAP user object whose value should match the short name given by each user at logon. For example, if the full distinguished name of the user is "CN=user1,OU=ou1,DC=ad,DC=example,DC=net", then the UserLookupAttribute will be CN. The value of this attribute should be the same as the name for the corresponding TrueSight Server Automation RBAC User object.
- set Ldap LoginAttribute <distinguishedNameAttribute>
  Defines the attribute of an LDAP user object whose value should be the full distinguished name of the user. For example ActiveDirectory uses distinguishedName
- set Ldap defaultUser <serviceAccountUser>
  Defines the full distinguished name of a service account with read access to the list of users stored in the LDAP directory in the database.
- set Ldap defaultPassword <password>
  Defines the password of the service account. This will be stored as an encoded string.
- set Ldap UserLdapFilter <filter>(Optional) Defines a filter to use to optimize the query to the LDAP server when obtaining user information. For example, using a filter of (objectClass=user) would be faster than using a filter of (objectclass=*). If no filter is set, the objectClass of the service account is used as the default filter.

For example, to authenticate users in two OUs using their CNs, the below settings would be set:

[Ldap]
ConnectionTimeoutMs:7000
DefaultPassword:EENVBWLLPVUBAOUQOWZOVQLNPWWVBKPZWTPLEXBZNMUTPZAUUVKPMVLLZWOWNBEU
DefaultUser:CN=Bind User,CN=Users,DC=ad,DC=example,DC=net
IsHostValidationEnabled:true
LdapServerURLs:ldap://dc1.ad.example.net:389
LoginAttribute:distinguishedName
TrustStore:/opt/bmc/bladelogic/NSH/br/ldapStore.pem
UseEnhancedLDAPAuth:true
UserLDAPFilter:(objectClass=user)
UserLookupAttribute:cn
UserSearchBaseDn:OU=ou1,DC=ad,DC=example,DC=net;OU=ou2,DC=ad,DC=example,DC=net

Restart the Application Server (see Restarting a specific Application Server).

Create RBAC User Objects for LDAP Users

For LDAP users to authenticate, RBAC user objects must be created for each user. The RBAC user name will depend on the above options in use. If the DN template is defined in blasadmin or enhanced LDAP authentication is used, then the RBAC User should be named as the CN. For example if the DN for the user is CN=user1,OU=ou1,DC=ad,DC=example,DC=net, then the RBAC user will be user1.

Otherwise, the full DN should be used for the RBAC user name, eg CN=user1,OU=ou1,DC=ad,DC=example,DC=net.

When creating the RBAC user the Allow LDAP Authentication should be checked and other authentication mechanisms unchecked.

For more information about adding users to RBAC, see Creating users.