Setting up an LDAP server for authenticating Teracloud® Streams users

The preferred authentication service for user authentication in a Teracloud® Streams enterprise domain is the Lightweight Directory Access Protocol (LDAP) authentication service. If you are using LDAP for user authentication, it must be installed and configured before you create an enterprise domain.

Procedure

  1. The system administrator installs and configures LDAP by using the instructions in the LDAP documentation.
  2. Obtain the LDAP property values for Teracloud® Streams.
    Important:
    • You must specify the serverUrl and userDNPattern property values when you create an enterprise domain.

    • The group, user, and secondary lookup properties are optional.
      • The group and user properties control how user groups are searched on the LDAP server and how Teracloud® Streams determines which groups have a user as a member.
      • Teracloud® Streams uses the secondary lookup property to perform an LDAP query to find the LDAP username for the provided username, and then authenticates at the LDAP server with this LDAP username and the provided password.

    • The group, user, and secondary lookup functions that are used by Teracloud® Streams no longer require that the LDAP server allow anonymous binds.

    • If you use an LDAP server that does not enable anonymous binds, Teracloud® Streams uses the credentials that are specified on the security.ldapAdministratorUser and security.ldapAdministratorPassword domain properties when it runs LDAP queries during the authentication process. You can specify these property values when you create the domain or after the domain is created by using the streamtool setldapadminconfig command. For more information about these properties, enter streamtool man domainproperties. For more information about the command, enter streamtool man setldapadminconfig.
    The following streamtool mkdomain command example shows the LDAP options that are specified on the command:
    streamtool mkdomain -d sampledomain --zkconnect myzookeeper:2181 
--ldap --server-url "ldap://ldap1.ibm.com:389"
--user-dn "cn=*,ou=people,dc=ibm,dc=com"
--group-obj groupOfNames --group-attr member --user-attr uid
--group-srch "ou=group,dc=ibm,dc=com"
--user-secondary-lookup "(&(objectclass=person)(uidNumber=*)) uid"
--property security.ldapAdministratorUser=admin1
--property security.ldapAdministratorPassword=password
    serverUrl
    LDAP server URL. This URL includes the host name and port number of the LDAP server, for example, ldap://ldap1.ibm.com:389.
    userDnPattern
    User DN Pattern. This pattern is used to create a distinguished name (DN) for a user during login, for example:
    • cn=*,ou=people,dc=ibm,dc=com, which is valid for any LDAP server type.
    • ADDOMAINNAME\\\*, which is valid for Windows™ Active Directory only.
    When the user logs in, the user ID is substituted for the asterisk (*) in the pattern.
    groupObjectClass
    LDAP group object class that is used to search for group names.
    groupSearchBaseDn
    LDAP base DN that is used to search for groups.
    groupAttributeWithUserNames
    LDAP name of the element in the group record that contains the list of members in the group.
    userAttributeStoredInGroupAttribute
    LDAP name of the element in a user record that is stored in the group record.
    userSecondaryLookup
    LDAP user secondary lookup query that Teracloud® Streams uses to find the LDAP user name from the specified user ID, for example: "(&(objectclass=ibmperson)(notesshortname=*)) uid".

Example

The following examples show how to use LDAP search commands to validate the following options for the streamtool mkdomain command:
  • --server-url: Specifies the URL for the LDAP server that the domain uses to authenticate users.
  • --user-dn: Specifies the LDAP pattern that is used to create a DN when the user logs in. For example: "cn=*,ou=People,ou=streams,o=ibm.com®". When the user logs in, their user ID is substituted for the asterisk (*) in the pattern.
  • --user-secondary-lookup: Specifies an LDAP user secondary lookup query, which Teracloud® Streams uses to find the LDAP user name from the provided user name.
Note: Your values will be different in the following examples. Your LDAP server administrator who controls and manages the LDAP schema can provide the appropriate strings to use in the LDAP searches.
The LDAP server in this example authenticates John Doe by using his uid, which is the serial number plus the country code.
  • John Doe
  • serial number: 123456
  • country code: 897
  • uid: 123456897
  • Notes® short name: jdoe

In the following LDAP search, John Doe's record is looked up by using objectclass=ibmperson and uid=123456897, which is a combination of the serial number and country code.

ldapsearch -xLLL -h bluepages.ibm.com:389  -b "c=us,ou=bluepages,o=ibm.com"  "(&(objectclass=ibmperson)(uid=123456897))"
Result:
dn: uid=123456897,c=us,ou=bluepages,o=ibm.com
objectclass: person
objectclass: organizationalPerson
objectclass: ibmPerson
objectclass: ePerson
objectclass: top
ou: bluepages
o: ibm.com
ibmserialnumber: 123456
employeecountrycode: 897
notesemail: CN=John Doe/OU=Rochester/O=IBM@IBMUS
notesmaildomain: IBMUS
notesmailfile: mail1\jdoe
notesshortname: jdoe
co: USA
uid: 123456897

In the following LDAP search, the data is filtered by objectclass=ibmperson and notesshortname=jdoe, and the uid is returned. 

ldapsearch -xLLL -h bluepages.ibm.com:389  -b "c=us,ou=bluepages,o=ibm.com"  "(&(objectclass=ibmperson)(notesshortname=jdoe))" uid
Result:
dn: uid=123456897,c=us,ou=bluepages,o=ibm.com
uid: 123456897

Domain users know their notesshortname but might not know their uid, which is a combination of their serial number and country code. For users to log in with their notesshortname, the following streamtool mkdomain command can be used to create the enterprise domain. The previous ldapsearch example verified the value to use for the --user-secondary-lookup parameter.

streamtool mkdomain -d jhbMiniCluster --ldap --server-url "ldap://bluepages.ibm.com:389" --user-dn "uid=*,c=us,ou=bluepages,o=ibm.com" --user-secondary-lookup "(&(objectclass=ibmperson)(notesshortname=*)) uid" --owner jdoe
Result
User jdoe LDAP password:*********
CDISA0017I Creating the following domain: jhbMiniCluster.
CDISA0018I The following domain was created successfully: jhbMiniCluster.