Implementing LDAP authentication

The BMC Server Automation Authentication Service can authenticate users defined in an LDAP registry. To accomplish this, the Authentication Service uses the LDAP Service. When a user logs in and provides an LDAP user name and password, the service uses that information to bind to an external LDAP server — that is, to connect to an LDAP server and authenticate a user. If the bind is successful, the Authentication Service issues a session credential with the user's distinguished name.

This topic provides information about the concepts and the steps involved in setting up LDAP-based authentication.

1. Specify the LDAP servers
2. Provision the authentication server with trusted certificates
3. Define the distinguished name template and enable LDAP authentication
4. Cross-register LDAP users with the RBAC user database

The following figure illustrates the process of setting up LDAP-based authentication:

Specify the LDAP servers

When the Authentication Service must authenticate a user by connecting to an LDAP server, you might want to provide a list of LDAP servers that it can potentially contact. Listing multiple servers helps to ensure 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.

Specifying the LDAP servers, including the high availability servers

1. On the Application Server, start the Application Server Administration console (the blasadmin utility).
2. Specify the LDAP servers, including any servers used for high availability purposes 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 and port.
      For example,

      set Ldap LdapServerURLs <ldap://server1:998,ldap://server2:1021,ldap://121.121.121.121:389>

      URLs must point to LDAP version 3 servers that support the StartTLS extension. Separate URLs with commas or other delimiters (see Specifying-multiple-values-for-a-parameter).

      Note

      LDAP communication over SSL uses StartTLS. BMC Server Automation does not use LDAPS, as LDAPS has been deprecated.

   2. Specify the amount of time to wait for an LDAP server to respond before terminating the connection:

      set Ldap ConnectionTimeoutMs <#>

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

Provision the authentication server with trusted certificates

The Authentication Service uses TLS to encrypt its connection to the LDAP server. The Authentication Service sends the user's credential to the LDAP server, only if it can validate the LDAP server's certificate. LDAP servers are authenticated using X.509 certificates that LDAP servers provide during the TLS handshake. While 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 Authentication Server's trust store, you can use one of the following approaches:

• Install certificates for all LDAP servers. You must repeat this procedure each time an LDAP server's certificate is updated.

• Install the certificate of the trusted Certificate Authority that issued certificates to the LDAP servers. Since 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 directory server's fully qualified domain names, you must set IsHostValidationEnabled to True.

  Note

  To add X.509 certificates to the Authentication Server's trust store, use the blcred utility. For more information, see the blcred man page.

Setting up a trust store for X.509 certificates

1. Provision a trust store with X.509 certificates, either by adding certificates from individual LDAP servers or by importing a certificate from a PEM file. To provision a trust store, use the blcred utility, 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

2. To identify the trust store containing trusted certificates, use the following command:

   set Ldap TrustStore <certificateStore>

   where <certificateStore> is the local path to a trust store

3. To check whether the certificate's common name matches the LDAP server's fully qualified name, enter the following:

   set Ldap IsHostValidationEnabled true

   Note

   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).

   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.

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 a user, the Authentication Service requires a full DN and a corresponding password. Rather than specifying a full DN, users can enter the part of a DN that is unique to their accounts. The name the user provides is transformed to a full DN with the use of a distinguished name template. A DN template is a static string containing a {0} substring, which is replaced with the name the user provides when logging in.

You can define DN templates in two ways: the Authentication Service and LDAP authentication profiles. The two templates can be used together or by themselves.

Setting up a distinguished name template and enabling LDAP authentication

1. 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 "uid={0},ou=dev,dc=sso,dc=bladelogic,dc=com"

   where "uid={0},ou=dev,dc=sso,dc=bladelogic,dc=com" is a distinguished name object.

   Note

   Enhanced LDAP authentication settings that define a short version of LDAP user names (see step 4) take precedence over an LDAP distinguished name template. Therefore, if you plan to define enhanced LDAP authentication settings, you do not need to define an LDAP distinguished name template.

2. On the BMC Server Automation client:
   1. Set up a distinguished name template, as necessary.
   2. Set up an authentication profile for LDAP authentication.
       For more information, see Authentication-profiles, Setting-up-an-authentication-profile, and Managing-authorizations.

3. Enable LDAP authentication with the following command:

   set AuthServer IsLdapAuthEnabled true

   Note

   By default, LDAP authentication is not turned on.

4. If you want LDAP authentication to accept an alias version of the LDAP user name that is shorter and simpler than the full distinguished LDAP user name (so that users do not need to know their full distinguished LDAP names), enter the following settings:

   Note

   To take advantage of this Enhanced LDAP Authentication feature, ensure that you have applied service pack 1 for BMC Server Automation 8.3 (product version 8.3.01).

   • 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 to use for searching for users. For example, if the full distinguished name of the user is "uid=jdoe,ou=my_ou,dc=my_company,dc=com", then UserSearchBaseDn should be set to "dc=my_company,dc=com".
   • 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 "uid=jdoe,ou=my_ou,dc=my_company,dc=com", then the UserLookupAttribute can be uid.  The value of this attribute should be the same as the name for the corresponding BMC Server Automation user.
   • set Ldap LoginAttribute <distinguishedNameAttribute>
     Defines the attribute of an LDAP user object whose value should be the full distinguished name of the user. With Sun LDAP servers, this is most likely "entryDN".
   • 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.
5. Restart the Application Server (see Restarting a specific Application Server).

Cross-register LDAP users with the RBAC user database

Cross-registration enables LDAP users to be authorized for RBAC roles. When cross-registering users, be sure to enter the users full distinguished name in both the RBAC and the LDAP registry. Use RBAC to add users to the BMC Server Automation database. While creating users in RBAC, ensure that you select the Allow LDAP Authentication check box. For more information about adding users to RBAC, see Creating-users.