LDAP authentication

This topic provides an overview of the tasks that you must perform to set up LDAP authentication.

The TrueSight Server Automation Authentication Server can authenticate users defined in an LDAP registry by validating users against LDAP servers. When you log in and provide an LDAP distinguished name and password, the Authentication Service uses that information to bind to an external LDAP server. Binding means the Authentication Service connects to an LDAP server and authenticates you. If the binding is successful, the Authentication Service issues session credentials with a distinguished name.

To set up LDAP-based authentication, perform the following steps:

1. Provision the Authentication Server with trusted certificates for all LDAP servers. 
2. Specify the LDAP servers, including any servers used for high-availability purposes. 
3. Define the distinguished name template and enable LDAP authentication.
4. Configure the Authentication Server to refresh session credentials.
5. Validate that users can log on by using LDAP.

To provision the Authentication Server with trusted certificates for all LDAP servers

The Authentication Service uses the Transport Layer Security (TLS) protocol to encrypt its connection to the LDAP server.

The Authentication Service sends the user credentials to the LDAP server only if it can validate the LDAP server certificate. LDAP servers are authenticated through X.509 certificates that LDAP servers provide during the TLS handshake. When configuring LDAP, you must identify a file that contains trusted X.509 certificates. This file is the trust store. When provisioning X.509 certificates for the trust store of Authentication Server, you can use one of the following approaches:

• Install certificates for all LDAP servers. You must repeat this procedure each time an LDAP server certificate is updated.
• Install the certificate of the trusted Certificate Authority (CA) that issued certificates to the LDAP servers. Because all CA-issued certificates are trusted, all current and future LDAP certificates are automatically trusted. If the common names (CN) specified in the issued certificates are set to the fully-qualified domain names of the directory server, ensure that IsHostValidationEnabled is also set to True.

To add X.509 certificates to the trust store of Authentication Server, do the following:

1. Log in to the server where TrueSight Server Automation - Data Warehouse is installed.
2. Navigate to the <TSSA-DWInstallationDirectory>\bin (Windows) or <TSSA-DWInstallationDirectory>/br (UNIX) directory.

3. Either add certificates from individual LDAP servers or import a certificate from a PEM file by using the blcred utility. For more information about the blcred utility, see the blcred man page.

   For example, to add the certificate for an LDAP server called ldap1.mycompany.com with a port number of 389, use the following blcred command:

   blcred -x ldapTrustStore.p12 cert -add -host ldap1.mycompany.com:389 -protocol ldap

   For example, to import a certificate from a PEM file, use the following blcred command:

   blcred -x ldapStore.pem cert -add -host <host>:<port> -protocol ldap

4. Start the Application Server Administration console (the blasadmin  utility) as follows.
   • (Windows) Navigate to the <TSSA-DWInstallationDirectory>\bin directory and enter the following command: blasadmin.
   • (UNIX) Navigate to the <TSSA-DWInstallationDirectory>/br directory and enter the following command: blasadmin.

5. Identify the trust store containing trusted certificates by using the following blasadmin command:

   set Ldap TrustStore <storeLocation>

   where <storeLocation> is the local path to a trust store.

6. Check that common name (CN) of the certificate matches the fully qualified domain name (FQDN) of the LDAP server by using the following blasadmin command:

   set Ldap IsHostValidationEnabled True

   Setting this value to true causes the Authentication Server to reject X.509 certificates, if the LDAP server's fully qualified domain name (FQDN) is not contained in one of the alternative names or the common name (CN).

   Note

   The Authentication Server only reads its certificate store when it starts. If you change the certificate trust store, be sure to restart the Authentication Service.

To specify the LDAP servers, including any servers used for high-availability purposes

When the Authentication Service needs to authenticate users by connecting to an LDAP server, provide a list of LDAP servers that it can potentially contact. Listing multiple servers ensures high availability and failover capability. When a list of multiple LDAP servers is available, LDAP connects to the first functional LDAP server in the list.

To identify LDAP servers, including any servers used for high availability configurations, do the following:

1. Start the Application Server Administration console (the blasadmin  utility) as follows.
   • (Windows) Navigate to the <TSSA-DWInstallationDirectory>\bin directory and enter the following command: blasadmin.
   • (UNIX) Navigate to the <TSSA-DWInstallationDirectory>/br directory and enter the following command: blasadmin.

2.  Specify the URLs of all available LDAP servers by using the following blasadmin command:

   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. URLs must point to LDAPv3 servers that support the StartTLS extension. Separate URLs with commas or other delimiters.
   For example,
   

   set Ldap LdapServerURLs ldap://server1:998,ldap://server2:1021,ldap://121.121.121.121:389,ldap://[2001::::::1]:389

3. Specify the amount of time to wait for an LDAP server to respond before terminating the connection by using the following blasadmin command:

   set Ldap ConnectionTimeoutMs <#>

   where <#> is the number of milliseconds to wait. In a high availability configuration, this time is the amount of time that the service waits for a response from one URL before trying the next URL in the list you provided.

To define the distinguished name template and enable LDAP authentication

LDAP users are uniquely identified by distinguished names (DN), such as CN=admin, ou=dev, o=bladelogic. To authenticate an LDAP user, the Authentication Service requires a full DN and a corresponding password. Rather than entering a full DN, however, LDAP users only have to enter the part of a DN that is unique to their accounts. The name the LDAP user provides is transformed to a full DN by the use of a distinguished name template.

A DN template is a static string containing a {0} substring that is replaced with the name the LDAP user provides when logging on. For example, with a DN template of CN={0}, ou=dev, o=bladelogic, the LDAP user only enters a string such as "qatest3", which replaces the {0} substring. Consequently, the LDAP user DN becomes CN=qatest3, ou=dev, o=bladelogic.

DN templates can be defined in two places: the Authentication Service and the logon window for TrueSight Server Automation - Data Warehouse. These templates can be used together or by themselves.

For example,

• The DN template provided in the logon window might be CN={0}, CN=Users, DC=sub1.
  
• The Authentication Service DN template might be {0}, DC=bladelogic, DC=com. 
  

If the LDAP user enters admin as a user name when logging on, the logon template transforms the name to CN=admin, CN=Users, CN=sub1 before sending it to the Authentication Service. Then, it is transformed into CN=admin, CN=Users, DC=sub1, DC=bladelogic, DC=com, where it is used to contact the LDAP server.

You can also define a distinguished name template when logging on to the client for TrueSight Smart Reporting for Server Automation. This template can be used in conjunction with the distinguished name template of the Authentication Server, or each template can be used individually. When you define a distinguished name template using the logon window for the TrueSight Smart Reporting for Server Automation client, that template remains in effect until you define a new distinguished name template using the logon window of client. 

Do the following:

1. Define an LDAP distinguished name template by using the following blasadmin command:

   set AuthServer LdapUserDnTemplate "<text> {0}<text>"

   where <text> represents any distinguished name objects that should be included in the template. 

2. Enable LDAP authentication by using the following blasadmin command:

   set AuthServer IsLdapAuthEnabled true

   
   By default LDAP authentication is not turned on.

3. Restart the Authentication Service.

   Note

   On UNIX, if umask is not set to 022, the Authentication Service will not start. Run the following commands from <TSSA-DWInstallationDirectory>and start the authentication service:

   #chmod –R 775 br/
#umask 022
#cd br
#./blauthservice start

To configure the Authentication Server to refresh session credentials

TrueSight Smart Reporting for Server Automation relies on the ability to refresh session credentials when executing scheduled jobs. This feature allows you to run scheduled reports without requiring you to authenticate again.

When refreshing session credentials, the Authentication Service validates the user account on the directory server. The account must exist and be enabled for logging on.

User account attributes that indicate whether an account has been disabled or locked differ across directory servers. The Authentication Service relies on the user validation filters to specify how to validate account attributes. If a custom user validation filter is not defined, the Authentication Service can only verify that the user account has not been deleted.

To refresh session credentials, the Authentication Service might need to authenticate itself to the directory server. If authentication is required, you must define a default LDAP user name and password.

Do the following:

1. Provide a default LDAP user name and password that can be used to log on when refreshing session credentials by using the following blasadmin commands:

   set Ldap DefaultUser <name>

   set Ldap DefaultPassword <password>

2. Restart the Authentication Service.
   

To validate that users can log on by using LDAP

TrueSight Server Automation - Data Warehouse uses user validation filters when refreshing LDAP session credentials. These filters help determine whether a user account is in good standing.

A user validation filter is applied to a search query of the distinguished name of a user. If an account is disabled, locked, or not authorized to log on, the query must return empty results. The filter checks schema-specific attributes for values that indicate an account is not in good standing. If a custom validation filter is not defined, the Authentication Service can only verify whether a user account still exists. The Authentication Service cannot determine, for example, whether the account has been locked. User validation filters must be properly formatted LDAP search filters. See below for descriptions of some common validation filters.

Directory servers enforce different access controls on user account attributes. A directory server might allow anonymous connections to browse user account data, but a directory server typically restricts access to attributes that indicate whether an account is disabled. To take advantage of a custom user validation filter, the Authentication Service must log on to the directory server with a privileged account. The name and password of the privileged account are defined by the LDAP DefaultUser and LDAP DefaultPassword settings. If you are not employing user validation filters and your directory server allows anonymous connections, you do not need to define a default LDAP user and password.

1. Enter the following command:

   set AuthServer LDAPUserValidationFilter <filter>

   <filter> is a validation filter used to validate users for a particular LDAP schema. Depending upon the type of LDAP directory server, use the following user validation filters:

   • Configuring LDAP with Active Directory

      Click here for steps to configure LDAP with Microsoft Active Directory.

     This topic describes the steps that you must perform to use Microsoft Active Directory. Active Directory does not allow anonymous connections. Consequently, you must define a default LDAP user name and password so that LDAP session credentials can be refreshed. 

     The status of a user account is controlled by the userAccountControl attribute, which indicates whether the account is locked or disabled. The following user validation filter can be used with Active Directory deployments. It ensures that the user account is not disabled or locked.
     
     

     (&(userAccountControl:1.2.840.113556.1.4.803:=512)
       (!(userAccountControl:1.2.840.113556.1.4.803:=2))
       (!(userAccountControl:1.2.840.113556.1.4.803:=16)))

     By default, Authentication Service of the Active Directory does not support TLS connections. To enable them, you must install an X.509 certificate that can be used for authenticating the LDAP server. Because Active Directory requires the server certificate to contain the fully-qualified domain name (FQDN) of the server in its common name or in one of its alternative names, BMC recommends you always enable FQDN checking on the Authentication Service. To enable FQDN checking, use the following blasadmin command:
     
     

     set Ldap IsHostValidationEnabled true

   • Configuring LDAP with Novell eDirectory

      Click here for steps to configure LDAP with Novell eDirectory.

     By default, Novell eDirectory allows anonymous users to browse user accounts. However, only users with special permissions are able to see whether another user account is disabled. To use custom user validation filters, the Authentication Service must be configured with privileged LDAP credentials.

     An eDirectory account is considered disabled when the loginDisabled attribute is set to TRUE. Use the following user validation filter to prevent users with disabled accounts from refreshing their session credentials:
     
     

     (!(loginDisabled=TRUE))

   • Configuring LDAP with Sun Java System Directory Server 

      Click here for steps to configure LDAP with Sun Java System Directory Server .

     By default, the Sun Java System Directory Server allows anonymous users to browse the directory. However, only authenticated users are able to see whether a user account is disabled. To use custom validation filters, the Authentication Service must be configured with LDAP credentials.

     The TrueSight Server Automation Authentication Server uses the LDAPv3 StartTLS protocol extension to provide the endpoint authentication, data confidentiality, and integrity. Sun Directory Server does not, by default, enable StartTLS when installed on Microsoft Windows. You must enable StartTLS by setting ds-start-tls-enabled to on.

     An account is considered disabled when the nsAccountLock attribute is set to true. Use the following user validation filter to prevent users with disabled accounts from refreshing their session credentials:

     (!(nsAccountLock=true))

2. Restart the Authentication Service.