Content Manager OnDemand V9.0 LDAP authentication process

Technote (FAQ)


Question

How does the Content Manager OnDemand V9.0 LDAP authentication process work?

Answer

Content Manager OnDemand (OnDemand) has a simple logon scenario without the LDAP authentication involved follows:

Scenario #1 -- 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 OnDemand server to be authenticated.
  3. If the user ID exists in the 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 -- OnDemand logon with the LDAP authentication and anonymous bind


When the 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 doors 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 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 OnDemand.

When the 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 OnDemand server to be authenticated.
  3. The 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 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 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 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 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 OnDemand server fails.
  8. If the attribute name is correct, a value is returned. For example, if the ID that is entered on the 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 OnDemand server database, the user logs on. Otherwise, the logon fails. The 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 OnDemand user ID and password sensitivity is enabled, and the IDs that are stored in the 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 -- 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 ID and password are stored in the LDAP configuration under the parameters ARS_LDAP_BIND_DN and ARS_LDAP_BIND_DN_PWD, 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.

Starting in OnDemand V9.0, both parameters, ARS_LDAP_BIND_DN and ARS_LDAP_BIND_DN_PWD have been moved to the instance stash file and are no longer specified in ars,cfg on Unix or under the Windows registry on Windows. If ARS_LDAP_ALLOW_ANONYMOUS is set to FALSE, both parameters 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 Unix, one must use the arsstash command to enter the values for ARS_LDAP_BIND_DN and ARS_LDAP_BIND_DN_PWD. The arsstash command can also be used on Windows to enter values for those parameters.

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 under the parameters ARS_LDAP_BIND_DN and ARS_LDAP_BIND_DN_PW.
  • 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 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 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 OnDemand server to be authenticated.
  3. The 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 OnDemand LDAP authentication component connects to the LDAP server with the LDAP user ID and password that are specified in the ARS_LDAP_BIND_DN and ARS_LDAP_BIND_DN_PWD parameters. 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 OnDemand server fails.
  5. After the connection is made, the 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 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 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 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 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 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 OnDemand server database, the user logs on. Otherwise, the logon fails. The 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 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 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 OnDemand user ID.
  • The returned value from the LDAP server matches an existing ID but it is in the wrong case and the OnDemand user ID case sensitivity has been turned on.
  • When the OnDemand user ID sensitivity option is off, the returned value is converted to the uppercase characters. If the stored 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.


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.



OnDemand IDs exempt from the LDAP authentication

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

In 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 ARS_LDAP_BIND_DN and ARS_LDAP_BIND_DN_PWD in a Stash File

In OnDemand V9.0, these two parameters have been moved into a stash file used for a given instance. The use of the stash file is required for the OnDemand V9.0 LDAP authentication.

On the Windows platform, the Configurator can be used to store and update ARS_LDAP_BIND_DN and ARS_LDAP_BIND_DN_PWD so using the arsstash command to manage ARS_LDAP_BIND_DN and ARS_LDAP_BIND_DN_PWD on Windows is optional.

On Unix platforms, one must use the arsstash command to accomplish this. Below is an example of using arsstash to store or update ARS_LDAP_BIND_DN and ARS_LDAP_BIND_DN_PWD.

/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 OnDemand, case insensitive means upper case. OnDemand server stores user IDs and passwords in uppercase when the case sensitivity is turned off.



Configuration parameters

ARS_LDAP_SERVER (required)
This is the LDAP server host name or the IP address that you are connecting to.

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.

ARS_LDAP_USE_SSL (optional)
The default is FALSE. If you want LDAP SSL support set to TRUE.

ARS_LDAP_OD_AUTHORITY_FALLBACK (optional)
Set this parameter to TRUE if you want the authentication to revert back to the OnDemand logon when the LDAP server cannot be reached or the userid does not exist on the LDAP server. The default is FALSE. Prior to OnDemand V8.5, the OnDemand server was fixed with TRUE.

ARS_LDAP_KEYRING_FILE (required if using SSL)
The absolute file name containing the SSL keystore database. 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.

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.

ARS_LDAP_BIND_DN (no longer used - moved to 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 BIND DN has to be specified in the true LDAP format. In OnDemand V9.0, this parameter has been moved into the stash file for that instance.

For example, if you were to use odadmin3 as the BIND DN, the full name could be:
CN=odadmin3,OU=users,OU=unit1,OU=mytown,DC=dc1,DC=dc2,DC=local

ARS_LDAP_BIND_DN_PWD (no longer used - moved to stash)
This is the initial bind (logon) password and is used for the non-anonymous bind. Note that this password is stored in clear text. In OnDemand V9.0, this parameter has been moved into the stash file for that instance.

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.

ARS_LDAP_MAPPED_ATTRIBUTE (required)
This is the attribute name that you want the LDAP server to return if the authentication is successful.

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 ARS_LDAP_BIND_DN and ARS_LDAP_BIND_DN_PWD parameters should be set to blank. In OnDemand V9.0, those two parameters do not need to be specified in the instance stash file if ARS_LDAP_ALLOW_ANONYMOUS parameter is set to TRUE.

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.

Hide details for Sample bind message INI file (arsldap.ini)Sample bind message INI file (arsldap.ini)

[BIND_MESSAGES]
PASSWORD_EXPIRED="C:\Program Files\IBM\OnDemand for Windows \V9.0\config\password_expired.txt"
ACCOUNT_LOCKED="C:\Program Files\IBM\OnDemand for Windows \V9.0\config\account_locked.txt"

[PASSWORD_EXPIRED]
TDS6="Password has expired"
AD="data 701"
UDEF1="OnDemand is expired"
UDEF2=
UDEF3=

[ACCOUNT_LOCKED]
TDS6="Account is locked"
AD="data 533"
UDEF1="NDS error: log account expired (-220)"
UDEF2=
UDEF3=

Hide details for Samples message file (password_expired.txt)Samples message file (password_expired.txt)
Your LDAP password has expired and needs to be changed.

Hide details for Samples message file (account_locked.txt)Samples message file (account_locked.txt)
Your LDAP account is locked or disabled.



Sample LDAP Configurations

Note: in OnDemand V9.0, both ARS_LDAP_BIND_DN and ARS_LDAP_BIND_DN_PWD parameters have been moved to the instance stash file and are no longer specified in ars,cfg. 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_DN=
ARS_LDAP_BIND_DN_PWD=
ARS_LDAP_BIND_ATTRIBUTE= mail
ARS_LDAP_MAPPED_ATTRIBUTE= userid
ARS_LDAP_ALLOW_ANONYMOUS= TRUE
ARS_LDAP_BIND_MESSAGES_FILE=

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_DN= CN=userid,OU=users,OU=yourunit,OU=yourcity,DC=dc1,DC=dc2,DC=local
ARS_LDAP_BIND_DN_PWD= password
ARS_LDAP_BIND_ATTRIBUTE= sAMAccountName
ARS_LDAP_MAPPED_ATTRIBUTE= sAMAccountName
ARS_LDAP_ALLOW_ANONYMOUS= FALSE
ARS_LDAP_BIND_MESSAGES_FILE=

3. Microsoft Active Directory Application Mode (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_DN= cn=admin,o=yourcompany
ARS_LDAP_BIND_DN_PWD= password
ARS_LDAP_BIND_ATTRIBUTE= mail
ARS_LDAP_MAPPED_ATTRIBUTE= cn
ARS_LDAP_ALLOW_ANONYMOUS= FALSE
ARS_LDAP_BIND_MESSAGES_FILE=

4. IBM Tivoli Directory server (TDS) 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_DN= cn=root
ARS_LDAP_BIND_DN_PWD= password
ARS_LDAP_BIND_ATTRIBUTE= email
ARS_LDAP_MAPPED_ATTRIBUTE= sn
ARS_LDAP_ALLOW_ANONYMOUS= FALSE
ARS_LDAP_BIND_MESSAGES_FILE=

5. Novel 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_DN= cn=admin,ou=users,o=yourcompany
ARS_LDAP_BIND_DN_PWD= password
ARS_LDAP_BIND_ATTRIBUTE= mail
ARS_LDAP_MAPPED_ATTRIBUTE= cn
ARS_LDAP_ALLOW_ANONYMOUS= FALSE
ARS_LDAP_BIND_MESSAGES_FILE=

6. Sun Java Directory server (JDS)
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_DN= cn=Directory Manager
ARS_LDAP_BIND_DN_PWD= password
ARS_LDAP_BIND_ATTRIBUTE= mail
ARS_LDAP_MAPPED_ATTRIBUTE= cn
ARS_LDAP_ALLOW_ANONYMOUS= FALSE
ARS_LDAP_BIND_MESSAGES_FILE=

Rate this page:

(0 users)Average rating

Document information


More support for:

Content Manager OnDemand for Multiplatforms
Server

Software version:

9.0, 9.5

Operating system(s):

AIX, HP Itanium, Linux, Linux zSeries, Solaris, Windows

Software edition:

All Editions

Reference #:

1597246

Modified date:

2014-11-10

Translate my page

Machine Translation

Content navigation