Advanced Password Services (APS) Guide › Integrating APS with User Management Tools

Integrating APS with User Management Tools

Advanced Password Services does not perform User Management (Identity Management) functions. It is only involved with the application and enforcement of password content, password lifetimes and account lifetimes.

This section contains the following topics:

Integration

Delegated Management Services (DMS2)

CA Identity Manager

Integration

There are a number of places where APS and a User Management tool must integrate.

Out of the box, APS does provide the Help Desk Interface (See Help Desk Interface (APSAdmin).). However, this is not a full-function tool. It is really designed to simplify existing user management applications or to provide a tool to aid in APS testing.

Enabling and Disabling Accounts

APS provides a wealth of options for enabling and disabling user accounts. There are specific ways in which APS can disable accounts during processing and APS can recognize a large number of site-defined mechanisms. Any User Management application should recognize all of the reasons used by a site (including those configured for APS to use). These tools should be able to enable and disable accounts for those mechanisms in use at the site.

Strategies

A site can incorporate the Help Desk Interface (APSAdmin) as a pop-up or linked page to perform almost all of this integration. However, if the functionality Disable is in use, the application may need to take this into account.
A site can use the APSAdmin XML interface provided by the APSAPI to perform the same functions. This involves modifying the application to make the APSAPI calls, interpreting the XML and generating new XML for submission to the API.
A site can read/write all of the user attributes that APS uses to enable/disable account. These attributes are described in User Directories: Schema, Storage and Capabilities. This method is not trivial and is error-prone. It is also subject to changes to APS in the future.

Ensuring Password Validity

User passwords should always conform to the password content rules configured to APS in its Configuration File. This applies not only to ongoing user password changes, but to administrator password resets and initial passwords (during account registration) as well.

Normally, ongoing password changes are handled by the APS Change Password Interface (SmCPW) and CA highly recommends that it be used.

Out of the box, APS supports password change forms written in any language. It merely requires that the form POST to the Change Password Interface (SmCPW). Non-web based change password applications can call the APSAPI to perform this function.

Some sites want to put the change password fields onto another form, often the Change Profile form. This is usually very confusing to users. It is often better to put a "Change Password" link on a page rather than trying to incorporate both profile and password updates on the same form. Part of the problem is handling errors that might occur in one update or the other.

It is not possible for an application to perform all of its own password updates. The password history field is not accessible to applications; it is stored in encrypted, compressed format.

During user registration (account creation), the account's initial password should conform to the password content rules imposed at the site.

Initial registration creates some interesting problems for password validation:

The password content cannot be checked against user attributes, since the user record does not yet exist.
If the password settings are overridden in terms of user attributes or group membership, APS cannot determine the proper requirements for the new passwords' content.
Some sites modify their User Management tool to call the APSAPI's IsPasswordValid function to determine the initial password's validity, then just saves the password (possibly updating other APS attributes as well). Sites that do this need to be aware of the above limitations.

Another method, which has been used quite successfully, is to save the initial user record with a dummy (very random) password and a "state" flag, then call ChangePassword in the APSAPI to actually set the password. Once ChangePassword has been called successfully, the state is changed to enable the record. This bypasses the above limitations, but may leave your directory in an inconsistent state if the user abandons the process.

Another method is to set the initial password to some known (or random) value, then either give it to the user or use SiteMinder Auto-Login process (similar to how FPS can do it in the CONFIRM phase), then force the user to change their password immediately. If a site does this, it should use the smapsMustLoginBy attribute to ensure that this known password is used within a short timespan and the smapsImmediateChange attribute to cause APS to force the user to change this password (these attributes are described in Schema & Storage).

Maintaining Forgotten Password Services (FPS) Questions/Answers

The Forgotten Password Services (FPS) functionality of APS can use information stored in the user record to interactively help a user reset their own password. However, APS provides no interface that can be used by the Users to maintain this information.

APS must be configured to tell it the name of the attribute(s) to use for this customer interaction and, for certain configurations, how that information is stored.

It is important that the user management application allow users to maintain this data. It is critical that the APS configuration correspond to the actual method used.

Some information on strategies is contained in How Do I: Get the FPS challenge questions into the User Directory?.

Triggering APS Events Properly

APSExpire processes events based on the value of smapsNextAction. Every time APS touches a user record, it ensures that the value of this field is accurate at that time. Some of the settings in the APS configuration file used to calculate this date may be dependent on attributes in the user record. For example:

Password Expiration={userType="Admin"} 30

Password Expiration=60

If the user's type is changed to or from Admin, the effective password expiration date changes and APS may need to update the value of smapsNextAction.

However, any User Management tool should not need to be aware of the conditions that APS uses to make these determinations.

There is a very simple way to handle this issue. Every time a user management tool modifies a user entry, it should delete the contents of smapsNextAction. APSExpire, scheduled to run daily, will recalculate the date on its next execution. Since user management is an extremely low volume operation, the impact on performance should be nominal.

Delegated Management Services (DMS2)

Delegated Management Services (DMS2) is a CA product, which some sites use to maintain user entries in a Directory. It supports self-registration, self-service profile management and help desk functionality.

DMS2 has been superceded by a new product from CA called Identity Manager.

DMS Workflow Library

APS includes sample source code for a DMS workflow library called APSDMSWorkflow. This file can be built and configured into the SiteMinder Policy Server to intercept updates to the user's password. The library will ensure that no passwords are saved that do not conform to the formatting requirements imposed by APS.

The library is provided in source as a sample only. CA Support cannot support any custom code derived from this source.

DMS2 supports a single workflow library, yet many sites need to perform their own workflow. Thus, the APS workflow is provided as sample source to show how to make the APSAPI call. Sites can then incorporate this sample code into their own workflow libraries, if desired.

Note: Prior to APS Version 4.2, this library was only supplied in binary form. The APS installer does not delete the prior version to prevent destroying a working system. However, be aware that any pre-existing copy of APSDMSWorkflow.dll or libAPSDMSWorkflow.so are not part of the APS product.

Enabling and Disabling User Accounts

Please refer to DMS Manual Chapter 7 of "Using DMS" for managing any user account as a Super Administrator or as an Organizational Administrator.

In the Managing Users Screen, after selecting a user account, you can press the button "APS Information" for the APS Information (and also enabling & disabled users).

The field names and the handling (R= Read, W= Write, C= Clear) properties of each of the APS attributes of LDAP Schema and Storage are mentioned in the following table.

APS Attribute	Prompt	Handling Props.	Comment
smapsBaseDate	Base Date	RW	Can only set to the current date
smapsLastLogin	Last Login	R
smapsPreviousLogin	Previous Login	R
smapsImmediateChange	Immediate Change	RWC	Can clear or set to a string that will be a comment that includes the date set
smapsDisableUntil	Disable Until	RWC	Date, time and reason
smapsDisableAfter	Disable After	RWC	Date, time and reason
smapsLastPasswordChange	Last Password Change	R
smapsFailureCount	Failure Count	RW	Just clear, but clear is not to an empty value.
smapsLoginHistory	Login History	R	Will show number of entries and "Select to View" button
smapsExpirePasswordDays	Expire Password Days After	RWC	Number of days and comment
smapsAccountInactivityDays	Account Inactivity Days	RWC	Number of days and comment
smapsGraceLoginsUsed	Grace Logins Used	R
smapsMustLoginBy	Must Login By	RWC	Date, time and comment
smapsGenerationalRedirects	Generational Redirects	R	Shows the number of entries and a "Select to View" button.
smapsFailuresSinceLastLogin	Failures since Last Login	R
smapsFailuresSincePrevious Login	Failuressince Previous Login	R
smapsMaxFailures	Maximum Failures	R
smapsTotalLogins	Total Logins	R
smapsTotalFailures	Total Failures	R
smfpsLog	FPS Log	R	Shows number of entries and "Select to View" button
smfpsLockoutCounter	FPS Lockout Counter	RC	Cleared to re-enable FPS for accounts
smapsNextAction	APSExpire trigger	C	ALWAYS clear

Note: The prompts that appear in the default set up are for English-US Locale (as defined in the file dms_en_US.properties).

Enabling a Disabled User Account

If the user account is disabled, the screen will display a message "User is Disabled".

It will also show why the user account is disabled and that may happen in the following two ways.

The account may be disabled because it belongs to any Disabled Group. For example if the user is disabled due to Failure Count then it will be a member of the group called Disabled-FailureCount.
The account may be disabled due to the unsatisfied conditions (as mentioned in APS.cfg) of the following fields
- Must Login By
- Disable Until
- Disable After

If you want to enable the account, you can do it in either in the following ways:

Check the Enable User CheckBox and click on Submit button.
Check the Delete the user from the Disable Groups checkBox and modify the relevant fields as required.
On Successful modification of the LDAP attributes you will see a SUCCESS message or else you will get an ERROR message.

Note: The date and time displayed in the DMS UI pages are all in local time, though the date and time are stored as GMT in the LDAP.

Internationalization

The Field names that are appeared in the default set up are for English US Locale (as defined in the file dms_en_US.properties). If the users want to change it, they need to define their own locale and the locale file should be present in

working-dir/DMS/properties/default/locale

Integrating Forgotten Question and Answers

Please refer to DMS Manual, Chapter 8 of "User Registration with Forgotten Password Support," for setting up for self-registering a user.

If the user is redirected to the correct fcc file, upon clicking on the link "Click here to register as a new user", the registration form will open with the questions that are defined in the property.

Format for the Property File

The value for the key "pick" signifies the number of questions to be picked.

The value for the key "questions" signifies the number of questions needed to be displayed.

The rest has the structure like QID = The Actual Question where QID is the question identifier and could be any value.

If the admin need to restrict a question to be displayed for a user while registering a new user, the admin may put a "*" in the beginning of any QID.

Do not put a "*" in the beginning of the key pick and/or questions.

Please follow the sample property file as a guideline.

Customization Required for Supporting Internationalization

In the forgottenpassword.jsp file for Language=English and Country=USA, the default lines are as follows:

<jsp:setProperty name="table" property="language" value="en"/>
<jsp:setProperty name="table" property="country" value="US"/>

For example, if the user wants to customize for Language=French and Country=Canada, these lines would be like this:

<jsp:setProperty name="table" property="language" value="fr"/>
<jsp:setProperty name="table" property="country" value="CA"/>

Please note then the name of the property file would be questions_fr_CA.properties.

APS.cfg configuration

In the APS.cfg file under [Verify], for the keyword Initial specify the special instruction as format=B. For example,

Initial=*SecretQuestion=carlicense[format=B,Pick=2,sorted]

CA Identity Manager

At the time of this release, integration between Identity Manager and APS has not been developed by CA. It is, however, in the planning stage and may be available in the future.

Many CA customers have integrated Identity Manager themselves in a variety of ways. Many have used the DMS2 integration guidelines above quite successfully.