LDAP login configurations in API Connect

This blog is the second part of the series Securing your API Connect Cloud with LDAP. The series aims to provide a brief introduction to LDAP, how its used for user authentication and how you can secure your API Connect cloud with LDAP to meet your enterprise security needs. You can find the complete list of entries for this series from the main page here.

IBM API Connect supports a variety of login configurations when using LDAP for user authentication. This post aims to explain each type and when you might want to use one type of login configuration over another.

LDAP authentication:

To successfully authenticate(or bind) a user with an LDAP server, you are required to pass the Distinguished Name or DN of the user and the user’s password to the LDAP server. The Distinguished Name is globally unique in an LDAP tree and typically any enterprise directory would have a large number of user entries. A sample DN for a user Tom Riddle under a hogwarts division could look like the following:

DN: cn=triddle,ou=users,dc=hogwarts,dc=com

When logging into an application that is backed by an LDAP server in your enterprise, you might have used your email or uid for example and not the entire DN. This is possible becasue your application would have been configured in such a way that just by giving the email or uid, it is able been able to construct the full DN to send to the LDAP server.

In some cases, constructing the DN might be straightforward — think of a use case where the login name maps to an LDAP attribute that is part of their DN itself(explained in the compose_dn method later) — Eg: the LDAP cn attribute in the above case (where the username will be triddle).

In other cases, it might be a little more work — For example, think of a scenario where you want to allow user logins through employee email ids(the LDAP mail attribute) or ids (the LDAP uid attribute) and you have to figure the user’s DN from these values.

To accommodate such varied cases, API Connect supports three different types of login configurations when you create an LDAP resource. This is specified through the authentication_method property and takes one of the following values: search_dn, compose_dn or compose_upn each representing a login configuration type.

The search_dn method:

Assume you want users in your organization to login with their email address and assume the DN of the users is of the form shown earlier. In such cases, you the search_dn method could be leveraged.

With this method, when a user logs in with the attribute you configure (mail in this case), a user search is performed against the directory to find the LDAP user entry with the given email. If the search is successful and we find a user and his corresponding DN, we authenticate him with the given password against the LDAP server. So as the name suggests, a search for the user’s DN is first performed and then the bind.

With this method, you could also make sure that the users logging in meet certain other conditions (say, have an objectClass called organizationalPerson).

Required APIConnect configuration properties:

The search filter that will be used to search the user’s dn is formed off of the above properties as:

search_dn_filter_prefix + username + search_dn_filter_suffix

Using the first example in the table above, if a user Tom Riddle used his email Tom.Riddle@hogwarts.edu to login, our filter would resolve to:

(&(objectClass= organizationalPerson)(mail=Tom.Riddle@hogwarts.edu))

Notes:

• Values for the username attribute must always be unique: Always make sure that the attribute you choose for user login is globally unique across the directory. Any search with this login attribute and value is expected to return one and only one LDAP entry. A good example would be the mail (eg: mail=Tom.Riddle@hogwarts.edu) attribute since no two users would have the same email. On the other hand, using the givenName (eg: givenName=Tom) attribute would not be advisable since there might most probably be multiple users sharing the same givenName.
• Specify configuration properties as LDAP filters: Note that the values for the search_dn_filter_prefix, search_dn_filter_suffix properties are specified as LDAP filters. LDAP filters have the format: (attribute=value) and use an (& or |) operator to include more than one attribute.

The compose_dn method:

Think of a setup where you want the users in your organization to login with an attribute that is part of their DN itself. For example, for the same DN shown earlier, you wanted to use the cn atribute for login (Eg: Tom Riddle would use triddle to login) Since the cn attribute is already part of a user’s DN, we can easily compose the DN if the configuration had just enough information about the DN.

Required APIConnect configuration properties:

If we had the prefix and suffix portions of a user’s DN, then when a user signs in with his username, we could easily get the DN as:

bind_prefix + username + bind_suffix

Eg: Using the example in the table above, user Tom Riddle logging in with username triddle, will have a DN:

cn=triddle,ou=users,dc=hogwarts,dc=com

Notes:

• Use compose_dn over search_dn when possible: For the same example we saw above, you could also use the search_dn method with the following values for its required properties:

search_dn_filter_prefix: (cn=
search_dn_filter_suffix: )

Since the search_dn method will need to perform a user search first to find the user’s DN and then do the additional step to bind as the user, it is advisable to use compose_dn method over search_dn where possible.

• Specify configuration properties as strings: Note that the values for the bind_prefix, bind_suffix properties are specified as strings and not as filters as was the case for the search_dn method.

The compose_upn method:

This method is specific to Microsoft Active Directory(AD) and UPN here stands for the AD specific attribute userPrincipalName. In addition to allowing user authentication using DN, Active Directory allows login via the UPN attribute. The UPN generally consists of a UPN prefix (the user account name) and a UPN suffix (a DNS domain name). The prefix is joined with the suffix using the @ symbol to form the userPrincipalName and used for login.Eg: someone@ example.com.

Note that this by convention maps to a user’s email address. If you use an Active Directory server and want to allow user logins with userPrincipalName, you could leverage this configuration type.

Required LDAP configuration properties:

With the configuration property above, the username is formed as:

username + bindSuffix

Using the example in the table above, assuming the user Tom Riddle was in Active Directory with userPrincipalName triddle, he could login as triddle and would be authenticated against Active Directory as triddle@hogwarts.edu.

Notes:

• The compose_dn/search_dn methods are also valid for Active Directory: Note that you can still use the compose_dn and search_dn login configurations for Active Directory servers.

You can refer to this post for examples for all three types of login configurations explained here.

Summary:

• The search_dn method is the only method that can support login via any LDAP attribute. It also helps restrict the login through additional conditions specified as part of the filter.
• The compose_dn method can only be used if the username attribute is part of the dn itself .
• The compose_upn method is specific to Active Directory servers.
• When considering using the search_dn type, and the same username configuration can be achieved with the compose_dn or compose_upn types, use them over search_dn.