Content Manager OnDemand LDAP authentication process

Answer

This document was originally written with Content Manager OnDemand for Multiplatforms in mind but its content also applies to all platforms on which Content Manager OnDemand runs.


Content Manager OnDemand has a simple logon scenario without the LDAP authentication involved as shown in the following example:


Scenario #1 -- Content Manager OnDemand logon without the LDAP authentication
In a very simplistic view, the logon process without the LDAP authentication can be described in the following steps.

1. The user types the user ID and password in the Logon to a Server panel of the OnDemand Client.
2. The user ID and password are sent to the Content Manager OnDemand server to be authenticated.
3. If the user ID exists in the Content Manager OnDemand server database and the password is correct, the user logs on.

Note: If the user ID and password case sensitivity is disabled (the default), the user ID and password are converted to uppercase before they are validated. The user ID is converted to uppercase and then compared with the user IDs that are stored in the database. The password is converted to uppercase, encrypted, and compared with the stored version.

Scenario #2 -- Content Manager OnDemand logon with the LDAP authentication and anonymous bind


When the Content Manager OnDemand server is set to authenticate through an external LDAP server, the logon process can get a bit more complicated. Some LDAP servers are set up to allow "anonymous bind" and others are set up to allow only the "non-anonymous" bind. The term "non-anonymous" bind is explained in the next scenario.

The terminology "anonymous bind" can be a bit confusing. The bind here means the initial connection to the LDAP server. An LDAP server that is set up to allow "anonymous bind" is "open" to the world. Anyone can connect to the LDAP server and search. It is like a building with its front door unlocked. Anyone can walk in and look for a name from the directory in the lobby. In this example, even though the building is open, the individual offices might not be open. The individual offices are analogous to the entries in the LDAP server.

After a record is found, you might need to supply a password to access the information in that record (analogous to a key for a locked office). An example of an LDAP server that allows the "anonymous bind" is a company's intranet server. With this type of "open" LDAP server, the only logon information that an employee of that company would need is a user ID and password.

The anonymous bind LDAP authentication process can be described as follows:

• Connect to the LDAP server (called initial bind) without a user ID or password.
• If the initial bind is successful, search for an entry under the bind attribute name that is specified in ARS_LDAP_BIND_ATTRIBUTE at the location specified by ARS_LDAP_BASE_DN.
• If an entry is found, perform a second bind (logon) to it by using the user ID and password that was entered into the Content Manager OnDemand logon panel.
• If the second bind is successful, locate the value under the mapped attribute name that is specified in ARS_LDAP_MAPPED_ATTRIBUTE.
• If the value is found, return it to Content Manager OnDemand.

When the Content Manager OnDemand LDAP authentication is configured with the anonymous bind set to true, the logon process can be described as follows:

1. The user types the user ID and password in the Logon to a Server panel of the OnDemand Client.
2. The user ID and password are sent to the Content Manager OnDemand server to be authenticated.
3. The Content Manager OnDemand LDAP authentication component connects to the LDAP server. If the LDAP server is down or cannot be reached, the logon will fail.
4. The Content Manager OnDemand LDAP authentication component searches the LDAP server for the user ID that is under the attribute name specified in the ARS_LDAP_BIND_ATTRIBUTE configuration parameter. Note that this user ID can be an e-mail address. If the attribute name does not exist on the LDAP server, the logon to the Content Manager OnDemand server fails.
5. If the attribute name is correct but the user ID does not exist on the LDAP server, then the flow will be based on the setting of ARS_LDAP_OD_AUTHORITY_FALLBACK.
6. If the user ID exists on the LDAP server and the password is wrong, the logon to the Content Manager OnDemand server fails.
7. If the user ID exists on the LDAP server and the password is correct, the LDAP server returns a value to the Content Manager OnDemand server. You tell the LDAP server what to return by setting the value on the configuration parameter ARS_LDAP_MAPPED_ATTRIBUTE to an attribute or field name that is known to the LDAP server. If this attribute name does not exist on the LDAP server, the logon to the Content Manager OnDemand server fails.
8. If the attribute name is correct, a value is returned. For example, if the ID that is entered on the Content Manager OnDemand logon screen is J12345, ARS_LDAP_MAPPED_ATTRIBUTE is set to odid, and the J12345 attribute odid is jasson1, then jasson1 is returned. If the returned value matches a user ID that is stored in the Content Manager OnDemand server database, the user logs on. Otherwise, the logon fails. The Content Manager OnDemand password is not checked if the LDAP authentication is successful.

Note: If the user ID and password case sensitivity is disabled (the default), the user ID and password are converted to uppercase before they are sent to the LDAP server. The returned user ID string from the LDAP server is then converted to uppercase and compared with the user IDs that are stored in the database.

If the Content Manager OnDemand user ID and password sensitivity is enabled, and the IDs that are stored in the Content Manager OnDemand database are in uppercase (for example, as a result of case insensitivity in the past), the ID that is returned by LDAP must be in uppercase too. Otherwise, the logon will fail.

Scenario #3 -- Content Manager OnDemand logon with the LDAP authentication and non-anonymous bind

In the previous scenario, the term "anonymous bind" was used. An LDAP server can also be set up to disallow the "anonymous bind", or to allow only the "non-anonymous bind." The Microsoft® Windows® Active Directory® (AD) server can only be set up using "non-anonymous bind.". When an LDAP server is set up this way, it is not "open" to the world. It is like a locked building that requires a key or badge to enter. In this example, the individual offices might or might not be locked. The individual offices are analogous to the entries in the LDAP server.

There are essentially two logons to an LDAP server that disallows the "anonymous bind" during the LDAP authentication process. The first logon (the initial bind) is required to gain connection to the LDAP server, and the second logon (the bind) is required to gain access to the entry or the record.

To connect to this type of LDAP server, you must supply a valid user ID and password at the initial bind time. It is like entering a locked building that requires a key or badge to enter. The initial bind LDAP user ID and password are stored in the stash file used for the instance and are not entered by the user at logon time. When you are connected, you can perform the search. When you find a record, you might need to supply a password to access the record's information.

If ARS_LDAP_ALLOW_ANONYMOUS is set to FALSE, both initial bind ID and password must exist in the instance stash file or the LDAP authentication will fail. On Windows, use the OnDemand Configurator to enter or change those parameter values. On non-Windows platforms, one must use the ARSSTASH command to enter the values for the initial bind ID and password. The ARSSTASH command can also be used on Windows to enter values for those parameters if you prefer.

The non-anonymous bind LDAP authentication process can be described as follows:

• Connect to the LDAP server (called initial bind) with a user ID and password that are specified in the stash file of the instance.
• If the initial bind is successful, search for an entry under the bind attribute name that is specified in ARS_LDAP_BIND_ATTRIBUTE at the location specified by ARS_LDAP_BASE_DN.
• If an entry is found, perform a second bind (logon) to it using the user ID and password entered into the Content Manager OnDemand logon panel.
• If the second bind is successful, locate the value under the mapped attribute name that is specified in ARS_LDAP_MAPPED_ATTRIBUTE.
• If a value is found, return it to Content Manager OnDemand.

When the LDAP authentication is configured with the non-anonymous bind set to false, the logon process has one extra logon (or bind) involved (see Step 4).

1. The user types the user ID and password on in the logon panel of the OnDemand Client.
2. The user ID and password are sent to the Content Manager OnDemand server to be authenticated.
3. The Content Manager OnDemand LDAP authentication component connects to the LDAP server. If the LDAP server is down or cannot be reached, the logon will fail.
4. If the LDAP server can be reached, the Content Manager OnDemand LDAP authentication component connects to the LDAP server with the initial bind LDAP user ID and password stored in the stash file. If the user ID and password are valid, the connection is established. Depending on the LDAP server setup, this user ID might need to have some administrative authority. For the Windows Active Directory server, the default is that any valid user ID that is a member of the domain can be used in this initial logon to the LDAP server. This is the first logon. If this logon fails, the logon to the Content Manager OnDemand server fails.
5. After the connection is made, the Content Manager OnDemand LDAP authentication component searches the LDAP server for the user ID that is under the attribute name specified in the ARS_LDAP_BIND_ATTRIBUTE configuration parameter. Note that the user ID can be an e-mail address. If the attribute name does not exist on the LDAP server, the logon to the Content Manager OnDemand server fails.
6. If the attribute name that is specified in the ARS_LDAP_BIND_ATTRIBUTE parameter is correct but the user ID does not exist on the LDAP server, then the flow will be based on the setting of ARS_LDAP_OD_AUTHORITY_FALLBACK. For example, if ARS_LDAP_BIND_ATTRIBUTE=mail and the user entered jscott@us.ibm.com in the Content Manager OnDemand logon panel, but this e-mail address does not exist on the LDAP server.
7. If the user ID exists on the LDAP server and the password is wrong, the logon to the Content Manager OnDemand server fails.
8. If the user ID exists on the LDAP server and the password is correct, the LDAP server returns a value to the Content Manager OnDemand server. You tell the LDAP server what to return by setting the value on the configuration parameter ARS_LDAP_MAPPED_ATTRIBUTE to an attribute or field name that is known to the LDAP server. If this attribute name does not exist on the LDAP server, the logon to the Content Manager OnDemand server fails.
9. If the attribute name is correct, a value is returned. If the returned value matches a user ID that is stored in the Content Manager OnDemand server database, the user logs on. Otherwise, the logon fails. The Content Manager OnDemand password is not checked if the LDAP authentication is successful.

Note: If the user ID and password case sensitivity is disabled (the default), the user ID and password are converted to uppercase before they are sent to the LDAP server. The returned user ID string from the LDAP server is then converted to uppercase and compared with the user IDs that are stored in the database.

If the Content Manager OnDemand user ID that is stored is in uppercase, if the user ID case-sensitivity is enabled, and if the returned user ID is in lowercase, then the logon fails.

Other considerations

The LDAP server authentication is bypassed if following condition is true. The logon process is reverted back to the normal Content Manager OnDemand logon:

• The user ID does not exist on the LDAP server for the bind attribute and ARS_LDAP_OD_AUTHORITY_FALLBACK=TRUE

The LDAP authentication may fail if one of the following conditions is true:

• The LDAP server is down or cannot be reached.
• The initial bind fails because of the incorrect user ID, password, or both.
• The second bind fails because of the incorrect user ID, password, or both.
• The attribute name that is specified in the ARS_LDAP_BIND_ATTRIBUTE configuration parameter does not exist on the LDAP server.
• The returned value from the LDAP server does not match any existing Content Manager OnDemand user ID.
• The returned value from the LDAP server matches an existing ID but it is in the wrong case and the Content Manager OnDemand user ID case sensitivity has been turned on.
• When the Content Manager OnDemand user ID sensitivity option is off, the returned value is converted to the uppercase characters. If the stored Content Manager OnDemand ID is in lower or mixed case, the logon can fail.

Depending on the LDAP server type and setup, the response you get from the LDAP authentication might not always be the same. The best way to diagnose the LDAP authentication problems is to get a detail trace and examine it. The trace can tell you which step went wrong in the LDAP authentication process.

Additionally, the following tools can be quite useful to examine the LDAP setup and to help with the problem determination.

• AD Explorer (freeware)
• Softerra LDAP Browser (note that only the browser is freeware)

Important: The information in this document concerning non-IBM products was obtained from the suppliers of those products. IBM has not tested such products and cannot confirm the accuracy of the performance, compatibility or any other claims related to non-IBM products. Questions about the capabilities of non-IBM products should be addressed to the suppliers of those products.

Content Manager OnDemand IDs exempt from the LDAP authentication

The Content Manager OnDemand user ID of admin will never be subjected to the LDAP authentication. Content Manager OnDemand administrators depend on this user ID to log on to Content Manager OnDemand. It is, however, affected by the case-sensitivity settings just as any other user ID is.

Starting in Content Manager OnDemand V9.0, an optional ARS_LDAP_IGN_USERIDS parameter is added and can be used to specify additional IDs that will be exempt from the LDAP authentication. On Windows, the OnDemand Configurator can be used to specify values.

If the parameter does not exist or no value is specified, only the ID admin is exempt. Otherwise, up to 10 user IDs can be specified with commas used as delimiter. Here is an example of three user IDs that are exempt from the LDAP authentication.

ARS_LDAP_IGN_USERIDS=user1,user2,user3

The exempted user IDs should not contain any comma characters as comma is used as the delimiter on the exempted list.

Store and Update LDAP Initial BIND LDAP User ID and Password in a Stash File

Starting in Content Manager OnDemand V9.0, the initial bind LDAP user ID and password are stored in a stash file of the instance. The use of the stash file is required for the Content Manager OnDemand LDAP authentication starting from Content Manager OnDemand V9.0.

On non-Windows platforms, the stash file name is specified in the ARS.INI configuration file. The following example shows the stash file used for the instance named ARCHIVE.

[@SRV@_ARCHIVE]
HOST=od95.sample.com
...
SRVR_OD_STASH=/opt/IBM/ondemand/V9.5/config/ars.stash

On the Windows platform, the OnDemand Configurator can manager the task of storing and updating the initial bind LDAP user ID and password so using the ARSSTASH command on Windows is not necessary.

On non-Windows platforms, one must use the ARSSTASH command to accomplish this. Below is an example of using ARSSTASH to store or update the initial bind LDAP user ID and password.

/home/user1> arsstash -a 7 -s ars.stash -u "CN=odadmin3,OU=users,DC=dc123,DC=local"
OnDemand Password:
Verify OnDemand Password:
/home/user1>

In the example, the ARSSTASH command prompts the user to enter the password and to verify it. If the stash file does not already exist, the -c option needs to be used to create a new stash file.

Note: In Content Manager OnDemand, case insensitive means upper case. Content Manager OnDemand server stores user IDs and passwords in uppercase when the case sensitivity is turned off.

Enable Content Manager OnDemand LDAP Authentication and Server Restart

The Content Manager OnDemand LDAP authentication is enabled through the OnDemand Administrator client. To enable the LDAP authentication, logon to the Content Manager OnDemand server, right click on the logged on server and select System Parameters. From the System Parameters panel, select the Login Information page, Check Enable LDAP box under the LDAP Authentication section. The Password Case Sensitive box under the Login Processing also needs to be checked as the password is case sensitive on LDAP servers supported by Content Manager OnDemand. The User ID Case Sensitive box may need to be check for LDAP servers requiring the user ID to be case sensitive.

Note once a user ID or password case sensitive box is checked, the Content Manager OnDemand server no longer upper cases the user ID or password entered. To login to the Content Manager OnDemand server using an exempted user ID, the user ID or the password or both will need to be entered in upper case. For example, if one wishes to login using the ID admin to bypass the LDAP authentication, the password for admin must be entered in upper case when the Password Case Sensitive box is unchecked unless the user ID was created with the Password Case Sensitive box unchecked.

Finally after the LDAP authentication is checked or unchecked, the Content Manager OnDemand server must be restarted for the authentication change to take effect.

Configuration parameters

ARS_LDAP_SERVER (required)
This is the LDAP server host name or the IP address that you are connecting to. This is equivalent to the parameter, "LDAP server to connect to" used in the OnDemand Configurator on Windows.

ARS_LDAP_PORT (optional)
The LDAP server port number that you are connecting to. The default is 389 for non-SSL and 636 for SSL. Normally, you can leave it blank and let it default. This is equivalent to the parameter, "Port on LDAP server to use" used in the OnDemand Configurator on Windows.

ARS_LDAP_USE_SSL (optional)
The default is FALSE. If you want LDAP SSL support set to TRUE. This is equivalent to the parameter, "Use Secure Socket Layer (SSL) connection" used in the OnDemand Configurator on Windows.

ARS_LDAP_OD_AUTHORITY_FALLBACK (optional)
Set this parameter to TRUE if you want the authentication to revert back to the Content Manager OnDemand logon when the userid does not exist on the LDAP server. The default is FALSE. Prior to Content Manager OnDemand V8.5, the Content Manager OnDemand server was fixed with TRUE. This is equivalent to the parameter, "Allow authentication fallback to OnDemand" used in the OnDemand Configurator on Windows.

ARS_LDAP_IGN_USERIDS (optional)
The user ID(s) that should be authenticated directly by the Content Manager OnDemand server when you enable LDAP for authentication. If this parameter is not specified, ADMIN is assumed. This is equivalent to the parameter, "Exempt following user IDs from LDAP authentication" used in the OnDemand Configurator on Windows.

ARS_LDAP_KEYRING_FILE (required if using SSL)
The absolute file name containing the SSL keystore database. This is equivalent to the parameter, "Secure Socket Layer (SSL) Key Ring File Name" used in the OnDemand Configurator on Windows.

Content Manager OnDemand will also use the keystore database stash file with the same name and the .sth extension. For example, if the SSL key ring file name specified is C:\Program Files\IBM\OnDemand for Windows\config\ondemand.kdb, OnDemand will also use the keystore database stash file named C:\Program Files\IBM\OnDemand for Windows\config\ondemand.sth.

ARS_LDAP_KEYRING_LABEL (required if using SSL)
The label name of the SSL certificate to use to access the LDAP server. This is equivalent to the parameter, "Secure Socket Layer (SSL) Key Ring Label" used in the OnDemand Configurator on Windows.

ARS_LDAP_BASE_DN (required)
This is the base distinguished name (DN), or the top level directory name. Think of it as a directory name on a file system or a drive. It is usually set to the top level directory name from which the user IDs can be found from that point down. This is equivalent to the parameter, "Distinguished name tree base" used in the OnDemand Configurator on Windows.

ARS_LDAP_BIND_ATTRIBUTE (required)
This is the attribute name that you want to look up, for example, a user ID or an e-mail address. This is equivalent to the parameter, "Which attribute is bound" used in the OnDemand Configurator on Windows.

ARS_LDAP_MAPPED_ATTRIBUTE (required)
This is the attribute name that you want the LDAP server to return if the authentication is successful. This is equivalent to the parameter, "Which attribute to return" used in the OnDemand Configurator on Windows.

ARS_LDAP_ALLOW_ANONYMOUS (optional)
The default is FALSE. This parameter has to be set to FALSE for the Microsoft AD and ADAM servers. For all other LDAP servers, the ARS_LDAP_ALLOW_ANONYMOUS parameter can be set to TRUE or FALSE. When this parameter is set to TRUE, the values for the initial bind LDAP user ID and password do not need to be specified in the instance stash file. This is equivalent to the parameter, "Allow Anonymous" used in the OnDemand Configurator on Windows.

ARS_LDAP_BIND_MESSAGES_FILE (optional)
This is an optional parameter. When it is set, it can be used to map the response text that is returned from the LDAP server to messages that can be sent back to the client. This is equivalent to the parameter, "Path to bind messages INI file" used in the OnDemand Configurator on Windows.

LDAP Initial BIND User ID (required - stored in stash)
This is the initial bind (logon) user ID and is used for the non-anonymous bind. It should be set to a valid user ID on the LDAP server. Depending on the LDAP server setup, this user ID might need to have some administrative authority. Similar to the BASE DN parameter, the initial bind LDAP user ID (BIND DN) should be specified in the true LDAP format. This parameter is stored in the stash file of the instance for security.

For example, if you were to use odadmin3 as the initial bind LDAP user ID, the full name could be:
CN=odadmin3,OU=users,OU=unit1,OU=mytown,DC=dc1,DC=dc2,DC=local

This is equivalent to the parameter, "Which distinguished name to bind (for non-anonymous binding)" used in the OnDemand Configurator on Windows. On Windows, one can enter this parameter directly into the OnDemand Configurator field. On non-Windows platforms, one must use the ARSSTASH command for this task.

Note:

Initial BIND LDAP User ID examples:

1. Microsoft Active Directory (AD) Server
CN=userid,OU=users,OU=yourunit,OU=yourcity,DC=dc1,DC=dc2,DC=local

2. Microsoft Active Directory Lightweight Directory Services (ADAM) Server
cn=admin,o=yourcompany

3. IBM Security Directory Server (formerly known as IBM Tivoli Directory Server)
cn=root

4. Novel eDirectory Server
cn=admin,ou=users,o=yourcompany

5. Oracle Sun Java Directory Server (ODSEE)
cn=Directory Manager


LDAP Initial BIND Password (required - stored in stash)
This is the initial bind (logon) password and is used for the non-anonymous bind. This parameter is stored in the stash file of the instance for security.

This is equivalent to the parameter, "Password for initial bind (for non-anonymous binding)" used in the OnDemand Configurator on Windows. On Windows, one can enter this parameter directly into the OnDemand Configurator field. On non-Windows platforms, one must use the ARSSTASH command for this task.

Sample LDAP Configurations

Note: Starting in Content Manager OnDemand V9.0, both initial bind LDAP user ID and password are stored in the instance stash file and are no longer specified in the ARS.CFG configuration file. However, if ARS_LDAP_ALLOW_ANONYMOUS is set to FALSE, both parameters must exist in the stash file or the LDAP authentication will fail.


1. Anonymous Bind LDAP Server
ARS_LDAP_SERVER=ldap1.yourcompany.com
ARS_LDAP_PORT=
ARS_LDAP_USE_SSL=FALSE
ARS_LDAP_BASE_DN=ou=yourgroup,o=yourcompany.com
ARS_LDAP_BIND_ATTRIBUTE=mail
ARS_LDAP_MAPPED_ATTRIBUTE=userid
ARS_LDAP_ALLOW_ANONYMOUS=TRUE
ARS_LDAP_BIND_MESSAGES_FILE=
ARS_LDAP_IGN_USERIDS=ADMIN,user1,user2

2. Microsoft Active Directory (AD) Server
ARS_LDAP_SERVER=adserver.yourcompany.com
ARS_LDAP_PORT=
ARS_LDAP_USE_SSL=FALSE
ARS_LDAP_BASE_DN=dc=ondemand,dc=yourdomain,dc=local
ARS_LDAP_BIND_ATTRIBUTE=sAMAccountName
ARS_LDAP_MAPPED_ATTRIBUTE=sAMAccountName
ARS_LDAP_ALLOW_ANONYMOUS=FALSE
ARS_LDAP_BIND_MESSAGES_FILE=
ARS_LDAP_IGN_USERIDS=ADMIN,user1,user2

3. Microsoft Active Directory Lightweight Directory Services (ADAM) Server
ARS_LDAP_SERVER=adamserver.yourcompany.com
ARS_LDAP_PORT=
ARS_LDAP_USE_SSL=FALSE
ARS_LDAP_BASE_DN=ou=yourlocation,o=yourcompany
ARS_LDAP_BIND_ATTRIBUTE=mail
ARS_LDAP_MAPPED_ATTRIBUTE=cn
ARS_LDAP_ALLOW_ANONYMOUS=FALSE
ARS_LDAP_BIND_MESSAGES_FILE=
ARS_LDAP_IGN_USERIDS=ADMIN,user1,user2


4. IBM Security Directory Server (formerly known as IBM Tivoli Directory Server) with SSL
ARS_LDAP_SERVER=yourtds.yourcompany.com
ARS_LDAP_PORT=
ARS_LDAP_USE_SSL=TRUE
ARS_LDAP_KEYRING_FILE=<CMOD_directory>/config/ondemand.kdb
ARS_LDAP_KEYRING_LABEL=LDAP Label
ARS_LDAP_BASE_DN=ou=yourlocation,o=yourcompany
ARS_LDAP_BIND_ATTRIBUTE=email
ARS_LDAP_MAPPED_ATTRIBUTE=sn
ARS_LDAP_ALLOW_ANONYMOUS=FALSE
ARS_LDAP_BIND_MESSAGES_FILE=
ARS_LDAP_IGN_USERIDS=ADMIN,user1,user2


5. Novell eDirectory Server
ARS_LDAP_SERVER=yournds.yourcompany.com
ARS_LDAP_PORT=
ARS_LDAP_USE_SSL=FALSE
ARS_LDAP_BASE_DN=ou=yourlocation,o=yourcompany
ARS_LDAP_BIND_ATTRIBUTE=mail
ARS_LDAP_MAPPED_ATTRIBUTE=cn
ARS_LDAP_ALLOW_ANONYMOUS=FALSE
ARS_LDAP_BIND_MESSAGES_FILE=
ARS_LDAP_IGN_USERIDS=ADMIN,user1,user2


6. Oracle Sun Java Directory Server (ODSEE)
ARS_LDAP_SERVER=yourjds.yourcompany.com
ARS_LDAP_PORT=
ARS_LDAP_USE_SSL=FALSE
ARS_LDAP_BASE_DN=ou=boulder,o=yourcompany
ARS_LDAP_BIND_ATTRIBUTE=mail
ARS_LDAP_MAPPED_ATTRIBUTE=cn
ARS_LDAP_ALLOW_ANONYMOUS=FALSE
ARS_LDAP_BIND_MESSAGES_FILE=
ARS_LDAP_IGN_USERIDS=ADMIN,user1,user2