How to install, configure, test, and troubleshoot the SSO Password Synchronization Agent (PSA/PWSA).

Document ID : KB000055491
Last Modified Date : 14/02/2018
Show Technical Document Details

TABLE OF CONTENTS

1. Overview

2. Definitions

3. Installation

3.1. Prerequisites

3.2. Step by Step Installation

3.3. Testing

4. Troubleshooting

4.1. Registry Settings

4.2. Setting Definitions

4.3. Errors

4.4. Settings to Note

4.5. README Know Issues

1 Overview

This document describes how to install, configure, test, and troubleshoot the SSO Password Synchronization Agent (PSA / PWSA).

2 Definitions

PWSA = Password Synchronization Agent
PSA user = PS-psa_servername
SSO = Single Sign On
PS = Policy Server
DC = Active Directory Domain Controller
AD - Microsoft Active Directory

3 Installation

3.1 Prerequisites

This document requires that

  • SSO 8.0 is installed on at least one Policy Server which has a domain application defined.

  • The domain application should relate to the NETBIOS name of the domain to store the user domain passwords in the SSO server's database.

  • It also requires at least one Windows Domain Controller to install the PWSA on.

You will also need the following information:

  • Name of all the Policy Server computers

  • Name of the Policy Server administrator and its password (Default is ps-admin)

  • SSO AUTHHOST name (Default setting is SSO_Authhost)

  • Name of the User Data Store on the Policy Server (Default is ps-ldap)

  • NETBIOS name of the domain

You will also need to download the latest PWSA from Support Online.

To download an SSO patch please do the following.

  1. Go to https://support.ca.com

  2. Login (if you do not have a logon call 631-342-6364 to get one)

  3. Click "Product Home Pages" link in the left hand column under "Knowledge".

  4. Select "eTrust Single Sign-On" for the product drop down list.

  5. Under the "Solutions & Patches" heading click your product version.

  6. Select the latest Password Sync Agent.

  7. Click the underlined patch on the next page.

  8. Go to the bottom of the page and click download next to the .CAZ patch.

  9. You may also need to download the CAZIPXP utility if you do not already have it.

  10. Unzip the .CAZ file using the CAZIPXP command line utility as follows:

    cazipxp -u QOxxxxx.caz

3.2 Step by Step Installation

  1. Go to the Domain controller and run the setup.exe in the PWSA install folder.

  2. Click Next at the first install screen.

  3. Read the License agreement and scroll down to the bottom and click "I Agree" when it is becomes highlighted. Note: You must scroll all the way down for it to become available.

  4. If the noted installation directory is acceptable click next, if not click the change button and adjust as needed.

  5. In the Policy Server Name screen follow the below guidelines.

    1. In the first Policy Servers field type in all of the Policy Server names with a space between each one.
      NOTE: Only the first server in the list is sent the information to add the PS-psa_servername user. However the user creation command is expected to replicate to the other SSO servers in the farm.

    2. In the Administrator Username field you should leave the ps-admin username unless you have chosen a non default SSO Administrator name in which case enter it here.

    3. In the AUTHHOST field leave the SSO_Authhost defined.

    4. Click Next

      Figure 1

  6. On the Administrator password screen enter in the ps-admin password and confirm it. (Or the password of the administrator name used on the last screen)

  7. On the Synchronization Application Configuration screen enter in the NETBIOS Name for your domain you wish to keep SSO synchronized with. EXAMPLE: My domain was ca.local but my NETBIOS name for the domain was CA. You could also look at the Domain field of your Login Screen when logging into the domain controller.

  8. On the user Search configuration details screen enter in the SSO User Data store where your SSO end users are stored. Some examples are ps-ldap, ps-farm, or in most cases a custom data store created for your active directory like ad-ca

    In the Search Filter field enter in the search filter used by your SSO User datastore. You can determine this by looking at the Data Store properties from the Policy Manager. For most remote Microsoft Active Directory data stores this field will be (sAMAccountName=%s) and for ps-ldap it would be (cn=%s)

    Figure 2

  9. Click Next to begin the Installation.

    You must Reboot to Complete the installation.
    NOTE: See the SSO 8.0 Implementation Guide 11-4 pg.225 for information on using the silent install feature of the PWSA.

3.3 Testing

  1. Open the Jxplorer LDAP directory browser and navigate to the "LoginInfos" OU, next open the OU relating to the user store your users are in (ps-ldap or ad-???).

    Note: If you need information on how to open Jxplorer please refer to the SSO Administration guide.

    Figure 3

  2. Then expand the user OU, next click the domain application record which you will be changing the password for. Click the "Table Editor" tab to show all the values for the domain application. Write down the eTssoPwdChangedAt value.

    Figure 4

  3. Next open the "Active Directory Users and Computers" administration screen which can be found from the Administrative Tools Menu on your Microsoft Domain Controller.

  4. Then change the user password in the "Active Directory Users and Computers" administration screen.

  5. Now go back to your open Jxplorer screen and refresh the user's information by clicking "View" and then "Refresh" menu items (Or click the "Refresh" button). Now check if the eTssoPwdChangedAt value has changed for the user. If the user's CA application record has not updated proceed to the Troubleshoot Password Change in the Troubleshooting section below. If the eTssoPwdChangedAt value has changed for the user the PWSA is working properly.

4 Troubleshooting

4.1 Registry Settings

Below is a screenshot of the PWSA Registry keys.

Figure 5

4.2 Setting Definitions:

Information from the SSO Implementation Guide 11-1 to 11-6 with additional comments and suggestions by SSO Support. The below defined fields relate to the Silent install flags.

SERVERNAME Specifies the name of the Policy Server. Use the computer name or IP address.You can list all your servers in the farm with a space delimiter.

For example:
2003cadc.ca.local 2000svrca.ca.local

PSAADMINAUTHHOST The authentication host used by the PSA for SSO authentication.
Possible Settings:
SSO_Authhost does work in most cases unless another Authhost was configured for SSO Auth.
This setting is used for the PSA user to login to the Policy Server.

ADMINUSER Specify the Administrator defined on the Policy Server that is used to set up the trust relationship.

For example:
ps-admin.

Used ps-admin as this is the default Admin User unless you changed this at the time of install.
This setting is ONLY used for the PWSA install to login and create the PSA user.

ADMINPWD Specify the administrator password on the Policy Server.

For example:
the password for ps-admin.

PDC Specify the synchronization application. By default this is your Primary Domain Controller (PDC).
If you specify the name of the domain, use the NETBIOS domain name, not the FULL DNS name. For

Example:
NETBIOS = CA
FULL DNS name = ca.local

USERDATASTORE Specify the name of the user data store defined on the Policy Server.
This is where the users whose passwords will be synchronized are stored.
This should be the datastore you add your new users to. By default this is ps-ldap
It is common for people to use a custom created remote Microsoft Active Directory Data Store
The sample AD remote data store used is called ad-ca

SEARCHFILTER Search filter that is used to locate a specific user in the data store.
Do not use the search filter if you do not have a hierarchical structure.
A hierarchical structure is a datastore which can have multiple layers with subordinates like Organizational Units (OU's) or Containers (CN's)
Microsoft Active Directory and eTrust Directory (ps-ldap) can have additional OU's or CN's which would define them as hierarchical structures.
In general use the following as a guide.
Remote Microsoft Active Directory data store
(sAMAccountName=%s)

ps-ldap (Default eTrust Directory Datastore)
(cn=%s)
Note:
In this example for the ad-ca datastore (sAMAccountName=%s) was used.

4.3 Errors:

Error 256 or 2560 Failed to create user:

Figure 6

The PSA user could not be created in the ps-ldap user data store. It usually relates to the following entries.

  • Administrator Name : ps-admin

  • NOTE: ps-admin must be an administrator

  • Authhost : SSO_Authhost

  • DefaultUSER_DIR=

  • SSOAuthHostName=

See Settings to Note below for more detail:

1024 Permission Denied:

The user was prevented from being created in ps-ldap by a lack of permissions for ps-admin.
The below selang command will check that the ps-admin had admin permissions.
sr ROLE ADMIN
ps-admin should be listed.

4.4 Settings to Note:

If you have a problem or error that cannot be answered please obtain the following settings before calling Support.
IMPORTANT: Please get this information from each server in the Farm that may be referenced in the PWSA installation.

  1. The settings for the SSO_Authhost and/OR EAC_Authhost. From selang or the Policy Managers - "Tools" - "Execute Command" window run the following commands.

    • sr AUTHHOST SSO_Authhost

    • sr AUTHHOST EAC_Authhost

  2. The settings for AC user permissions. From selang or the Policy Managers - "Tools" - "Execute Command" window run the following commands.

    • su ps-pers

    • su ps-admin

    • sr role ADMIN

  3. The settings for Terminals and User Data Stores. From selang or the Policy Managers - "Tools" - "Execute Command" window run the following commands.

    • sr USER_DIR *

    • sr terminal *

  4. In the Policy Manger under "Resources" - "Configuration Resources" - "Policy Server Settings" - "General" check the following settings.

    • DefaultUSER_DIR= (default setting is ps-ldap)

    • SSOAuthHostName= (default setting SSO_Authhost)

    • DefaultContext= (default setting is blank)

4.5 Readme Known Issues

Windows Password Synchronization Agent - Known Issues

Here is a list of known issues for the Windows Password Synchronization Agent.

  • Uninstall requires the computer to be rebooted in order to fully uninstall the Password Synchronization Agent from Windows. Until this reboot, the agent will still be actively synchronizing passwords.

  • If the Password Synchronization Agent is connecting to a Server Farm, the servers will need to be listed in the registry of the Password Synchronization Agent computer. Failover for Policy Servers in a server farm will not function correctly.

  • A password change request for a user who doesn't exist will result in a misleading "success" message.

  • A password set request for an application that the user doesn't have in their application list will result in a misleading "success" message.

  • Due to Windows handling of password changes, you may notice several errors listed in the event log for one password change error.

4.6 Troubleshoot Password Change

If the user password does not properly update or change in the ps-ldap LoginInfos OU then we should take the following steps.

Policy Server Tracing

Configure tracing of the Policy Server and collect the Policy Server trace log covering a password change attempt

  1. Open the Registry editor. Type in regedit at the Windows Start - Run dialogue box.

  2. Locate the following registry key location.

    HKEY_LOCAL_MACHINE\SOFTWARE\ComputerAssociates\eTrustSSO\Password Agent NT\SSO

  3. Change the LogLevel value to Debug

  4. Next go to the following folder
    \Program Files\CA\eTrust Policy Server\

  5. Open and edit the pslog.ini file and remove the semi-colon ; from the beginning of the line

    [*.MST_TRACE.*]

  6. Then save the file.

  7. Restart the eTrust Policy Server 8.0 service in Windows services.

  8. Test using the 3.3 Testing procedures above.

  9. Gather the \Program Files\CA\eTrust Policy Server\log\PS_Trace.log file to find how far the password change went. Please provide this to support with the other Settings to Note above.

Password Sync Agent Debugging

Configure debugging of the SSO Password Sync Agent and collect the log file.

  1. Go to the \Program Files\CA\eTrust SSO\Windows Password Sync Agent folder on the DC.

  2. Open the ssopsant_log.cfg file with a text editor.

  3. Change the following INFO to DEBUG

    # SSO NT Password Sync Agent Logging Config file
    #
    BEFORE:
    log4cplus.rootLogger=INFO, ntsyncagent
    AFTER:
    log4cplus.rootLogger=DEBUG, ntsyncagent

  4. Restart the Domain Controller to activate the new setting.

  5. Run the tests in 3.3 Testing procedures again and then gather the SsoNTPSA.log file in the Program Files\CA\eTrust SSO\Windows Password Sync Agent folder

  6. We should now find more detailed information on the password change process on the DC.

Windows Event logs

  • You may also find useful information in the Windows Event Viewer Application Logs on the DC.

  • You can compare these messages in the Application logs to the Policy Server Trace file (PsTrace.log) and the Password Sync Agent log (SsoNTPSA.log) information logged at the same time.

This information should help track down the cause of the failures.


-- Last Reviewed: 2007.10.18