SSO r8.1 provides greater integration and interoperability with Active Directory as a user datastore. The ADS Listener enables mutual support for typical business scenarios in organizations when an employee is moved from one department (organizational unit) to another or where an employee leaves a company. In previous versions of SSO, the user logon information would need to be manually redirected to the new location the user account exists in Active Directory by means of a customized script or using an LDAP browser such as 'Jxplorer', provided with the default SSO server installation. This component automates the process for decreased overhead and scalability.
This article walks through the installation steps and basic troubleshooting methods to ensure that the ADS Listener is installed correctly and supporting future changes in Active Directory. The documentation provided is not specific to any one company or architectural design. It does however use specific operating systems and straight-forward server topology.
IMPORTANT: This article contains information about modifying the registry.
Before you modify the registry, make sure to create back up of the registry and ensure that you understand how to restore the registry if a problem may occur.
For more information about how to back up, restore, and edit the registry, please review the relevant Microsoft Knowledge Base articles on support.microsoft.com.
When using Active Directory as the SSO user datastore, the ADS Listener "listens" for changes to user and user group information on Active Directory, and sends notification of these changes to the SSO Server. This prevents the information in Active Directory and CA SSO from becoming out of sync. During the installation steps there will be a few key concerns to ponder when implementing this component for use in the SSO environment. These are not to be considered best practices, but only indicate the relative amount of influence you would have the Listener place in Active Directory. The basic installation will be followed by a brief on configuration.
- Example detail
SSO Server= ssosvr81a
The ADS Listener:
- Can optionally be installed on the Domain Controller
- Must be installed on a domain member
- Must not be installed on the SSO Server host
Although the ADS Listener can be installed on any machine, the following shows the pros and cons of some of the options.
Active Directory Domain Controller (DC) machine
In a single domain controller environment, we recommend that you install the ADS Listener on the DC because this saves network traffic.
A domain member machine
In a multiple domain controller environment, we recommend installing the ADS Listener on a domain member that is not the domain controller because this improves failover.
SSO Server host
We do not recommend installing the ADS Listener on the same machine as the SSO Server, because this reduces SSO Server performance: the ADS
Listener and the SSO Server will share the same network interface, overloading it with the additional network traffic coming from the Active Directory DC.
The screenshots below are taken from each step of the wizard based install of the ADS Listener. They are prefaced by definitions and/or considerations.
Figure 1 - Click next to begin the wizard installation of the ADS Listener.
Figure 2 - Scroll to the bottom of the E.U.L.A in order to agree to the terms and click next.
Figure 3 - Define the path to the install location for the ADS Listener. Click Next
Figure 4 - Define the Active Directory Host Name(Domain controller machine name), the LDAP port which is filled in by default, and the AD Naming context(example provided). You may choose to monitor the entire Domain tree if you wish, but please note: When the Listener starts up, it will review all objects in Active Directory to be monitored. Depending on the size of your AD, this can take quite some time. If you wish to restrict the amount of objects that are monitored by the ADS Listener, you may add multiple Naming Contexts during the install. This is described in Figure 8 below. You may also choose to use LDAP over SSL at this point if you wish. This will require the use of a pre-generated SSL certificate. This document does not cover creating this option. After you have filled out the appropriate fields, click Next.
Figure 5 - Define the Administrative user that will obtain authentication to Active Directory in order to conduct Policy Server notifications. You must use the full DN or distinguished name for this user in the field below. In this example we use the default Administrator account in the Users container. You may choose to use a different user if you wish. Some SSO Admins will use the same service account that binds SSO to read Active Directory, as this account most often is set with a password that does not expire. It is important that the user be at least a domain user, and have pre-windows 2000 compatible access. Then enter the password for the user and confirm it again. Click Next.
Figure 6 - Define the Single-Sign On server or servers you wish to receive Active Directory change notifications from the Listener. You may choose to list the entire list of SSO member names here (separated by comma) for redundancy, or list only one server for scalability if you choose to install the Listener on multiple domain controllers. This is more of an architectural conversation to be had with a CA Services Architect. Then define the Active Directory datastore name that was previously created in the SSO Policy Manager. Click Next.
Figure 7 - On this screen the ps-admin SSO server user should be pre-defined. All that is needed is to enter and confirm the password set during the SSO server installation for this user. Click Next.
Figure 8 - Define the AD Naming Context in the top field. This can be the entire domain if you wish. This could also be just one container or organizational unit (OU) of your choosing. Then populate the Monitoring Context box with the necessary paths in Active Directory. As it states in the below dialog It should either be the same container as the User Data Store base path or a container under it. It is recommended to define specific containers to be read and monitored instead of the entire Active Directory user repository. More Monitoring Contexts can be defined later in the Windows Registry for this component. Example is shown below:
Figure 9 - Click the Install button to continue and install the ADS Listener.
The installation will create a service called "eTrust SSO Active Directory Listener". This service can be found in the Windows Services console. You will see in Task Manager the executable 'ADListener.exe' running. This concludes the installation portion of this Document. Please continue below.
Configuration and Tuning
This section provides the configuration settings for the ADS Listener with advice following the settings which normally require extra attention and configuration. The intent is to help avoid possible problems during normal production usage and load.
The ADS Listener service may be installed on any computer in the network. It can remotely monitor Domain Controllers. It can only listen to one Domain Controller at a time. When multiple Domain Controllers are involved, the ADS Listener will listen to one Domain Controller at a certain time, with the ability to failover to one of the others.
Active Directory Server data is configured as follows:
Changing any of these parameters will require you to restart the ADS Listener service.
Defines the Active Directory LDAP port number
Value: port number
Defines the Active Directory Domain Controller host name or a list of
names (comma or space separated)
Value: computer name
Defines the Active Directory domain DN (for example: dc=domain,
Value: domain name
Defines whether to use LDAP over SSL while communicating with
1 = SSL enabled
0 = SSL diabled
Defines the time (in seconds) to wait between each connection attempt in case of a problem connecting to Active Directory.
Value: time in seconds
Specifies the DN of the container to be monitored. This DN should relative to the Base Path (defined in the SSO Server's Active Directory User Data store) or a location below that. The ADS Listener can monitor multiple contexts. X is a sequential number (starting from 0) of the defined monitored context.
For every one of those keys a MonitoringContextScopeSubTree_X can be specified to determine if that Monitoring Context should be treated as a sub tree scope (scope that includes also its sub containers) or one level only.
(The above defines the parent container as a one level container and one of its child-containers as a sub-tree scope. Note that those contexts don't overlap.)
Note: The ADS Listener Caches ALL records in AD at the specified Monitoring Context. It will cache the records below that level as well if the scope is set to SubTree (default).
This means if you used your AD base as your Monitoring Context upon installation you are caching your DomainControllers, Computers, BuiltIn, ForeignSecurityPrincipals, etc in AD which do not need monitoring for changes.
Important: Minimally you would need 1 ADS Listener running to monitor AD changes, but when implementing the ADS Listener in large environments it is suggested to have separate ADS Listeners pointing to separate Monitoring Contexts and each ADS Listener to point to separate SSO Servers. This can improve server performance during ADS Listener initialization in terms of CPU load. If all ADS Listeners were to be installed in the same method, you would see in the Listener logs, duplicate information from install to install. This would indicate that the Listeners are doing double or even triple-duty. While this does promote the idea of redundancy, the potential impact of this clearly outweighs the means. Moreover, Embedded CA Directory replication would already take care of the Users' Login Information across the SSO farm.
SSO Server data is configured as follows:
Defines the SSO Server host name (or a list of names). Host names can also be in a host:port format.
Value: computer name or computer name:port number
Defines the Active Directory user data store name as defined in the SSO Server.
Value: data store name
Defines the Active Directory base path as defined in the user data store in the SSO Server.
Defines the full name, including path of the file, that will be used to store SSO Server's public key information. This file is created automatically.
Value: path and file name
Defines the directory path to where SSO Server's message file is located.
Defines the SSO Server's message file name ("enu.msg").
Value: file name
ADS Listener generic information is configured as follows:
Defines the full name, including path, to the ADListenerLog.ini file.
Value: path and file name
Defines the path to the data directory, containing the two encrypted credentials files (ads_ps.dat containing SSO Server credentials and ads_ldap.dat containing Active Directory credentials).
Defines the maximum number of Active Directory notifications that will be stored in Active Directory queue while waiting to be processed by the notification handler. In the event that this queue reaches its limit, a message will be written to the log file, saying: "Fail to submit XXX Notification to queue. AD Queue is full."
Value: number of notifications
Defines the maximum number of SSO Server notifications that will be stored in SSO Server queue while waiting to be sent to SSO Server. In the event that this queue reaches its limit, a message will be written to the log file, saying: "Fail to submit XXX Notification to queue. PS Queue is full."
Value: number of notifications
Important Note: It is important that both the MaxADQueueSize and MaxPSQueueSize settings be adjusted after the AD Listener is installed. Using the defaults provided may yield unwanted results. If either of these queues are maxed the Listener will display an error message to the logs and stop "Listening" for requests until the queue size decreases. The default value is only a suggestion that the pending changes to AD are going to be somewhere in the neighborhood of this number. Please consult with your Active Directory Administration team to review the possible activity that would occur in the Domain as far as moving/deleting users are concerned. Medium to Large enterprises will require higher than default values so that the notification handler will accept all pending changes. This should be set higher then the maximum number of moves or deletes which might occur within your domain. There is no limit value that can be set for these two parameters and it is suggested that both of these values remain the same.
Defines the path to the OfflineData directory, where all offline information is stored.
This folder contains all the cache entries since the AD Listener last read through Active Directory during its last initialization process. If the contents of this folder are deleted, the Listener will need to re-read through Active Directory again for the most current information. This would be done when the Listener is restarted. The initialization process, depending on the scope that the monitoring context is responsible for, can be time consuming. If the data is left alone and at some instance the Listener was stopped due unforeseen circumstances, upon restart the Listener will attempt to complete any pending changes based on the data is has in this folder. But if the above PS and AD queue size settings are too low based on the change activity in AD that you are conducting, the Listener may have dropped some or all of the notifications once the queue size has been exceeded.
The Installation will create two encrypted files that contain the credentials required in order to connect Active Directory and the credential required in order to connect to SSO Server. This information can be changed by running:
ADListener -s <user_name> <password>
This is used to set the user name and password for SSO Server.
ADListener -l <ldap_user_dn> <password>
This is used to set the user name and password for Active Directory.