This section discusses how to use APS features to implement common site requirements. All of the information presented in this section exists elsewhere in this document in reference format. This section presents the information in a guideline format.
This chapter will often refer the reader to other parts of this document for further details.
This section contains the following topics:
Customize the change password form
Configure 3 Strikes and You are Out
Force Users to Change Password at Login
Determine why a User Authentication is Rejected
Enable an account that APS has Disabled
Retrieve the Date and Time a User Login
Limit Password Changes to One a Day
Remove the Current Password from the Change Password Form
Automatically login a User with FPS
Let a User Select their own Password during FPS
Retrieve Statistics about FPS Usage
Securely Support FPS Challenge Questions
Get the FPS Challenge Questions into the User Directory
Integrate the APSAdmin Interface into an Identity Management application
Make the APS API Return Error Codes
Assuming SiteMinder and APS are configured correctly (See Event Handling), setting up password expiration is easy. The event configuration is required to support the redirection of the user when the password actually expires.
To control password expiration, a site needs to specify the following settings in the APS Configuration File:
|
Password Expiration |
This setting controls how often users are expected to change their password. |
|
Expiration Warning |
This setting controls how long before the password expires that APS will start warning the user that the password will expire, thus giving the user a chance to change the password before it expires. |
|
Expiration Grace |
Once the password expiration period has passed, APS will attempt to force the user to change their password. This setting controls how long APS will make these attempts. Once the grace period has expired, the user will be disabled. |
|
Grace Logins |
This limits the number of logins that a user can attempt after the password expires before the user is disabled. |
|
Expired Redirect |
This setting tells APS where to send the user when the user's password actually expires (at the end of the grace period). |
|
Warning Redirect |
APS uses this setting to determine where to send the user when warning that the password will expire. This is usually a password change form. |
|
Expire Change Redirect |
APS uses this setting to determine where to send the user when the user must change their password. This is usually a password change form. |
|
Expired Password Mail |
This setting tells APS the name of a file to send to the user when the password actually expires. It is rarely used, since it is generally more use friendly to present a page to the user when this event occurs. |
|
Password Warning Mail |
This setting tells APS the name of a file to send to the user when APS must warn the user that the password will expire. It is not often used, but it is actually more user friendly to use this than a redirection (assuming that email addresses are accurate), since it does not interrupt the user's workflow. |
|
Force Change Mail |
This setting tells APS the name of a file to send to the user when the user must change their password. It is never used, since the user must change their password before accessing the site. |
Password expiration works as follows:
The password expiration date is calculated (by APS) from the following:
Starting Expiration Warning days before the Soft Password Expiration Date, but before the Hard Password Expiration Date, every time that the user attempts authentication, the user will be sent to the Warning Redirect page and the Password Warning Mail will be sent.
If the current date (and time) is after the Hard Password Expiration date, the user is disabled. When this happens, the user is redirected to the Expiration Redirect page, if specified, and the Expired Password Mail is sent. The user is not allowed to access the site (the authentication is rejected).
If the current date (and time) is after the Soft Password Expiration date, but before the Hard Password Expiration date (and no Grace Logins are allowed), the user's authentication is approved, but the user will be redirected to the Expire Change Redirect page (if this setting is missing, the Force Change Redirect setting will be used instead) and the Force Change Mail will be sent to the user.
If the current date (and time) is after the Soft Password Expiration Date and Grace Logins are allowed:
This topic is discussed in detail in Chapter 6, Change Password Interface (SmCPW).
Assuming that SiteMinder and APS are configured correctly (See Event Handling.), setting up this feature is easy. The event configuration is required to support the redirection of the user when the event actually occurs. You may also wish to review Special Case: Three Strikes, You're Out.
To control this feature, a site needs to specify the following settings in the APS Configuration File:
|
This setting controls how many sequential failures it takes to trigger this event. |
|
|
APS uses this setting to determine how long it should "remember" failures and, if Auto Reset Failure Count is specified, how long user account should be disabled before being automatically re-enabled. |
|
|
If this setting is specified, then users will be automatically reset after Failure Count Timeout minutes of inactivity. |
|
|
This setting tells APS where to send the user when the event occurs. It should not be used (the reasons are discussed in the text). |
|
|
|
This setting tells APS the name of a file to send to the user when the event occurs. This is the preferred method for notifying the user because it is more secure.
There is another setting, not implemented within APS, that seems to perform this function, but actually performs a completely different function. The two settings can be used together to make the system much user friendlier.
Form Login has a feature called Retries. This setting does not control when the user is disabled. It instead controls the number of consecutive attempts that can be made before the browser must be restarted (note that Basic Login has the same feature, but the number of attempts is hard-coded into browsers as the value "3").
The Retry setting only controls the browser, not user disabling. If the user attempts three different user id's, for example, the Retry setting will still take effect, though an APS setting will not. On the other hand, three attempts on three different browser instances will not invoke Retry, but may disable the user via APS.
The Retry setting is intended as a "speed bump" for programmatic password crackers. That is, the cracking program must handle the shut down/restart of the browser ever Retry attempts. The APS setting is a complete "stopper", absolutely closing off the user account to the cracking program.
The two settings should not have the same value. It is far user friendlier to set the Retry setting to a value of, say, 3 and the APS Failure Count setting to a larger value, say, 5 or 9.
In this way, a user that has legitimately forgotten his password will hit the Retry setting first. Presumably, the result of hitting this count presents the user with some message asking the user to call Customer Support. A legitimate user will do so. Since the user was never disabled, the reset is not needed.
However, a programmatic password cracker will ignore the "speed bump" message and will continue to attempt to crack the site. Eventually, the APS setting will be invoked and the user will actually be disabled (and an administrator notified?). The APS setting might be 9, but, with proper password policies, it is impossible to crack a password in 9 (or even 99) tries!
To perform this function, SiteMinder and APS must be configured correctly (See Event Handling.). The event configuration is required to support the redirection of the user when the event actually occurs.
To do this, the user's entry must be "flagged" to require the change. Under Windows NT, there is a checkbox within the user profile that can be changed using the User Manager for Domains utility supplied with Windows NT.
For LDAP directories, use the APSForcePWChg - Set Force Password Change Flag provided with APS, the SmBlob utility, or modify the smapsImmediateChange attribute in the user record to set this flag.
You can use the Auto Force Chang setting to have APS force the user to change their password when the password is changed by an external utility.
To control this feature, a site needs to specify the following setting in the APS Configuration File:
APS uses this setting to determine where to send the user when the user must change their password. This is usually a password change form.
Sometimes, user authentications seem to be rejected arbitrarily. Note that no action performed by a computer is completely arbitrary: there is always a reason. Sometimes the reasons are just not very obvious.
The first thing to do is to check the SiteMinder Authentication Server's console log. SiteMinder will log whether the initial authentication succeeded or failed. APS will always honor this determination first.
If SiteMinder successfully authenticated the user, but authentication still failed, APS probably rejected the authentication. Check the console log for APS' logging of the reason for rejection.
If further information is required, try turning on APS tracing (using the Trace setting). APS will then display considerably more information about why the user was rejected.
This is discussed in detail in User Directories: Schema, Storage and Capabilities.
If this information is to be displayed on administrator's screen, get the value of smapsLastLogin for the desired user. If the information is to be displayed on the user's own screen, use the value of the smapsPreviousLogin attribute (since the Last Login attribute contains the date/time of the current login).
Both of these dates are in Greenwich (ZULU) Time.
This feature seems to be a desirable feature of Advanced Password Services. However, upon further evaluation, it is not, for the following reasons:
This limit cannot be honored when the user is forced to change their password. For example, the user voluntarily changes their password in the morning, then forgets what it was changed to. The administrator then resets the password (through whatever means). The user would then typically be forced to change the password yet again when he next logs in. The limit cannot be honored in this case.
In order to be user friendly, the user should be prevented from requesting the password change, not just the actual change process. That is, the change password form should not be displayed; a warning message should be displayed instead.
The SiteMinder Policy for the custom form should pass the value of the smapsLastPasswordChange attribute to the form. The server-side code should check to ensure that the proper amount of time has elapsed for the user to (voluntarily) change their password. If not, the server-side code should display a user-friendly message instead of the change password form.
It is very important that the document's content expire immediately. This will prevent the user from pressing the "Back" button on the browser to access the form again. Browsers will recognize that the content has expired and will request new content from the server. This allows the server side code to execute again to check for the validity of the password change.
Note that the result of the Response should not be cached (this is defined within the Response definition).
Traditional operating systems will force a password change immediately after login. When this occurs, it makes no sense to ask the user to enter their current password, since the password was just entered during login.
In the Web environment, this does not work. Browsers provide a "Back" button that would allow the user to return to a previous panel to enter a new password again. A user could thus be forced to change their password, walk away from their keyboard, and another user press the "Back" button to change the password again (since the current password is not needed).
Because of this, APS requires that the current password be entered as part of all password changes. Even if a user presses the "Back" button, the password cannot be changed without re-entering the current password (browsers do not preserve the contents of password fields).
A site might wish to bypass this by supplying a hidden field with the current password value. This field would be used on the password post, but the user would not have to enter it. While the "Back" button problem is solved (since the older password is still there and won't match the just changed value), it creates several security holes:
Bottom line: This functionality should never be implemented.
See Fault Tolerance & Performance.
APS writes to the LDAP server on all authentications. The write includes not only login information, but may include setting the user as disabled.
For more information, see Fault Tolerance and Performance.
APS implements the Writeback settings (See LDAP Write Back Information) to handle this type of configuration quite efficiently. These settings will cause APS to do all reads from the satellite LDAP server and perform all writes to the primary server.
"FPS Misuse" is defined as:
To keep this from happening, use the Too Recently Used settings to prevent users from freely using FPS.
To detect this kind of misuse without restricting user access, use the Logging Attribute. You can create searches and reports to determine how often each account has used FPS and how frequently.
To keep this from happening, use the Too Recently Attempted settings to prevent hacker attacks. Also, many of the mail events can be used to send mail to internal security administrators when certain types of attacks are detected.
Use the Audit Log setting and monitor this log.
To lock users out of FPS, use the Lockout Count and related settings. If the user is to be locked completely out of your site and you have APS installed, use the Lockout Group DN setting to put the user in an APS disabled group.
If FPS is disabled due to Lockout, an administrator should delete the value of the smfpsLockoutCounter for that user account.
If the user cannot use FPS because of the Too Recently Used or Too Recently Attempted settings, the best bet is to let the user utilize the Help Desk to reset their password until the required time has elapsed.
If it is absolutely necessary to reset this information, delete the values stored in smfpsLog attribute in the user record. The side-effect is that all audit information about the use of FPS by this user is lost.
If the user cannot access FPS because the account is disabled, then the account must be re-enabled. This is discussed in detail in User Directories: Schema, Storage and Capabilities.
You should use the OneShotPassword functionality, so that you need not expose the "real" password. The setup required for using OneShotPassword is described in Confirm Pages.
Once again, this comes down to the BACK button on the browser. In order to change the password, the user must know his old password. Since, by definition, FPS is used when the user does not know their own password, standard APS change password services cannot be used. FPS provides a random password reset, then requires that the user utilize the standard APS service upon login. This prevents the BACK button security hole described in the previous section.
You can use the [FPS-Change] section to allow a user to do this securely, if it absolutely must be done. Keep in mind that this is not very secure.
FPS keeps a lot of information about its use. The two settings to maximize the log data are Audit Log and the smfpsLog attribute.
FPS records all activity in the file specified Audit Log in comma-delimited format. The fields logged are date, time, instance, state, user DN (if known) and message. The instance field is merely a one-up number that can relate two messages running for the same request. The instance number is not maintained between requests from the same user.
Since the file is recorded in comma-delimited format, it is easy to import this file into a number of applications, databases and report writers.
There is no provision within FPS for rotating or truncating this file, so your site should prepare for it.
smfpsLog provides a way of determining the FPS activity of a particular user.
The best way that we have determined to do this is something we call "the thousand questions". This mechanism requires that users select ten or more questions from a large list of questions (usually presented to the user as a series of drop-down boxes). Using the Special Instructions (see Special Instructions), FPS can select a subset of the entered questions to ask. Really secure sites will consume questions as they are asked, preventing them from being asked again, and will require that the user select additional questions in order to use FPS in the future.
"The Thousand Questions" refers to the long list of questions from which the user can choose. There need not actually be a thousand questions. Some questions can, indeed, be politically incorrect for some users; users need not select that question, so they need not answer it. Example questions appear below:
This is not a function of APS. While APSAdmin could be used to enter simple questions and answers as separate user attributes, it cannot handle the formatting described in Special Instructions.
A site should use its user maintenance application to perform this function. For LDAP User Directories, Delegated Management Services (DMS) is ideally suited for this purpose.
The CA Professional Services Deployment Group has experience creating and modifying such applications, for both DMS and non-DMS environments. Contact your CA Sales Representatives for details.
APSAdmin (See Help Desk Interface (APSAdmin).) is a help desk tool that can be used to allow administrators to enable/disable user accounts and, possibly, to reset their password. This "How Do I?" is assuming that a site wants to use the actual forms generated by APSAdmin.
An APSAdmin session consists of two parts:
Most of the configuration of APSAdmin is involved with the second part, which is described in Help Desk Interface (APSAdmin).
The user navigation portion of APSAdmin is very rudimentary and is really designed to allow developers to access user data for testing purposes. A full function user navigation tool would require considerable configuration and design, since only the site knows the logiv of how their users are organized in the directory.
However, the second part (the user form) can be invoked directly from any application. Very often during Proof of Concept or initial rollouts, sites can avoid writing a considerable amount of code by invoking the APSAdmin user form directly from within their Identify Management application (DMS2, CA Identity Manager, etc.).
The fastest way to do this is to modify your existing user management application on the user profile edit form:
After this is done, valuable time can be spent customizing the forms, rather than accessing data and performing edits.
Many sites use the APS Application Programming Interface (See Application Programming Interface). The API functions take, as arguments, the desired ISO language and country codes and returns errors as text, properly localized, rather than error codes. This can be a bit tricky if the application wishes to perform specific handling for specific errors.
The use of text, rather than codes, goes beyond simple translation issues. Many error messages, especially the password content messages, have values (parameters) inserted into them at run time. For example, one supplied (English) error message might come out "Your password must contain at least 2 numeric digit(s)". The "2" is inserted at run-time, based on what is actually configured in the APS Configuration File.
However, it is still not difficult for a site to set up the API to return error codes.
All server-side messages are stored in files called APS.lang under the Language subdirectory. There may be more than one APS.lang file, one for each language and/or language/country code.
The format of a language file is described in Internationalization. Essentially, each message is identified by a "key" and has an associated "value". The application (APS) requests the value of a "key" for a given language/country code. The translation library (APSXLate) loads the proper application language file (APS.lang) for the requested language/country code, then looks up the key.
For a given application, the keys are all constant, for all versions of the file, but the values associated with each key reflect the language for which that file is intended.
To make the APS API return error codes instead of text, copy the APS.lang file from the EN directory to a new directory called API (the "language code" will now be "API" rather than "EN"). Edit the file using the text editor of your choice and replace the value associated with each key with the numeric code that you wish APS to return for that particular message.
When your application wishes to make an APS API call, supply "API" as the language. APS will load the APS.lang file associated with the "API" language code. It will then return the message (value) associated with each key. In the "API" language file, these are numeric codes rather than text string.
The API will always return an error string, not a number. By following the instructions above, you can have APS return an error code, but it will still be returned in a string. Your application may have to convert it to a numeric value.
There is a way to take advantage of this for the purposes of testing/debugging. APS will log the returned error message to the SiteMinder Authentication Console Log. Logging numeric values will be rather cryptic.
When converting a string to a number, most languages will convert all characters in the string up to the first non-numeric character. One recommendation is to not replace the entire value in the language file with the desired error code: instead, insert the desired numeric code at the beginning of the value, followed by a colon. For example, replace:
key ERR_DICTIONARY val New password includes an embedded word that is disallowed.
With:
key ERR_DICTIONARY val 20:New password includes an embedded word that is disallowed.
Now, when this error is returned to your application and you convert the returned string, it will see "20". Yet the entire message is logged to the console log. Your application could then even peel off everything before the colon (including the colon) and still display the message to the user.
You could even treat "API" as a country code instead of a language code, allowing the text portion to change by actual language.
Your application may wish to preserve the inserted parameters (as decribed in the example above). This is also easy to do.
The replacement parameters are position independent, meaning that the order that they appear within the string is not important. A given parameter can even be inserted more than once.
Using the technique described above, you can still pass the important insertion parameters (note that insertion parameters differ by error message):
key ERR_MINIMUMLEN val New password must be at least %0 character(s) long.
Could become:
key ERR_MINIMUMLEN val 35 (%0)
When converting the error string to a number, your application will still see code 35. But the important insertion parameter (the minimum length) will get passed as well.
The two techniques can be combined, since a given parameter can be inserted more than once:
key ERR_MINIMUMLEN val 35 (%0):New password must be at least %0 character(s) long.
|
Copyright © 2014 CA.
All rights reserved.
|
|