Verify that the separate maximum attempt failure threshold that you have defined for a realm that is configured with OTP authentication is correctly configured.
The following procedure assumes the following conditions:
Follow these steps:
The account should not be locked.
The account should not be locked.
The account should be locked.
You have successfully configured a separate maximum attempt threshold for one-time password authentication.
Range: 0 or 30-180 days
Default: 0
Recommended: 90
Complexity Level: Basic
If a security breach does occur because a password becomes known, the breach is immediately closed when the password changes. By requiring your users to periodically change their passwords, you can close any breaches that you don't even know about.
This setting controls how often users must change their passwords.
When a password fully expires, the user is disabled and the configured action taken (email, redirection).
This setting controls the amount of time that can pass between when the user last changed his password (or was created) and when the password must be changed. Related settings, described below, control warnings and grace periods.
For users stored in a Windows NT Directory, Expiration Delay is not honored. APS honors the password expiration date set in the NT User record. Expiration Warning is honored as described below, though it is relative to the expiration date set in the NT user record. Expiration Grace and Grace Logins are not honored for NT users, thus, when an NT user's password expires, that user is immediately disabled.
Password Expiration=90
Password Expiration={@Employees} 60
Note: For users stored in LDAP or ODBC directories, the administrator can modify some of the behavior of APS when doing a password expiration check. Before using this setting, APS will check the user's record for a value for the attribute smapsExpirePasswordDays. If set, APS will use the number of days so specified. This feature should be rarely, if ever, used, since it causes a performance hit and creates maintenance problems. It is intended to override specific users, such as administrators, whose password should never expire.
Range: 0-99 days
Default: 0
Recommended: 7
Complexity Level: Basic
When a password expires, the user's access to the system is revoked. It is far user-friendlier to warn the user that their password will expire shortly. This setting determines how long before a password expires should the user be warned.
The warning takes the form of email and/or redirection (which must be configured for this setting to work) occurring each time that the user logs in during this period.
Expiration Warning=7
Expiration Warning={@Customers} 10
Range: 0-99 days
Default: 0
Recommended: 7
Complexity Level: Basic
If a user logs in during the Expiration Warning period, defined as the Password Expiration Date less the number of days specified by the Expiration Warning setting above, an event fires and the system takes immediate action (redirection and/or mail sent). However, this process is triggered by an actual authentication attempt.
This setting allows a site to send email warning users of password expiration even if the user does not authenticate. The APSExpire utility will send email to users before their password expires using this setting.
Note that this setting may appear more than once. If so, APSExpire will send the email each time within the period that it is run. Thus, a site can send email 15, 10 and 5 days before the password actually expires.
Offline Expiration Warning=15 Offline Expiration Warning=10 Offline Expiration Warning=5
Range: 0-99 days
Default: 0
Recommended: 7-14 days
Complexity Level: Intermediate
Once password expiration is reached, APS no longer treats password changes as optional (it becomes required). How many days after the password expires should APS actually disable the user?
This setting is not honored for users in a Windows NT Domain Directory.
Expiration Grace=30
Expiration Grace={@Employees} 7
Range: 0-5
Default: 0
Recommended: no
Complexity Level: Advanced
Once password expiration is reached, APS no longer treats password changes as optional (it becomes required). This setting indicates how many times the user will be allowed to login after the password expires and before the user is disabled.
All but the last grace login are optional. The last grace login will not be optional (using the default form and AZRedirect).
If both Grace Logins and Expiration Grace settings are used, the first value to be used up will cause the user to be disabled. In other words, if the Expiration Grace period expires before the user has consumed all of the available Grace Logins, the user is disabled. If all Grace Logins are consumed, the user is disabled, even if the Expiration Grace period has not expired.
Note that the user will be allowed to login when this value is reached. However, if the password is not changed, the next login attempt will cause the user to be disabled.
This setting is not honored for users in a Windows NT Domain Directory.
Grace Logins=3
Grace Logins={@Employees} 2
Range: 0-365 days
Default: 0
Recommended: 90 days
Complexity Level: Basic
This setting controls the maximum amount of time that can occur between user logins. A user attempting to log into an account that has remained dormant for more than this amount of time will cause the account to become disabled. Thus, an old, dormant account that may have been overlooked will be less of a security threat.
For example, one of your employees leaves the company to join one of your competitors. Your Human Resources department does not notify you of the separation. Since the account remains unused for 30 days (before the employee attempts to reconnect), when the attempt is made, the account is disabled (and, optionally, mail can be sent to the administrator).
By default, this setting is reactive, meaning that the account is not actually disabled until it is used, not when the time limit expires. To be proactive, that is, to have APS disable users (LDAP and ODBC users only) when the account actually expires, use the APSExpire utility.
When APSExpire is used, if the user eventually logs in (after being disabled), APS cannot do special redirection to notify the user that he has been disabled due to inactivity, only that the user is disabled.
If APSExpire is used, then you can send warning mail to expiring users several days before the account actually expires. This functionality is controlled by the Inactivity Warning setting below.
For Windows NT Directories, APS honors the Account Expiration date set in the NT User record rather than this setting.
Max Inactivity=90
Max Inactivity={@Admins} 180
Note: For users stored in LDAP and ODBC directories, the administrator can modify some of the behavior of APS when doing this check. Before using this setting, APS will check the user's record for a value for the attribute smapsAccountInactivityDays. If set, APS will use the number of days so specified. This feature should be rarely, if ever, used, since it causes a performance hit and creates maintenance problems. It is intended to override specific users, such as administrators, that are accessed rarely and should never be disabled due to inactivity.
Range: 0-99 days
Default: 0
Recommended: 7-10 days
Complexity Level: Intermediate
If the APSExpire utility is used, then you can send warning mail to expiring users several days before the account actually expires. This setting controls how long before the user record expires such mail is sent.
The mail may not actually be sent this number of days before expiration, since the APSExpire utility may not run. The utility will generate mail when a user's record will expire within this number of days and such mail has not already been sent.
Since APSExpire can only be used for LDAP or ODBC users, this setting does not apply to users in a Windows NT directory.
Inactivity Warning=5
Inactivity Warning={@Customers} 10
Range: 0-730 days
Default: 0
Recommended: 30 days
Complexity Level: Advanced
An account disabled due to inactivity will remain in the User Directory, theoretically forever. The APSAdmin utility will report all users that have been disabled (due to Account Inactivity) for this many days as "eligible for purge". Note that APS will never actually delete a user.
Since APSExpire can only be used for LDAP or ODBC users, this setting does not apply to users in a Windows NT directory.
Purge After=30
Purge After={@Customers} 365
When events occur during the authentication process, APS can redirect the user to specific pages (URLs). This section contains descriptions of the settings that specify the URLs to redirect users for each event.
During authentication, APS records the fact that the event has occurred and which event it was. It cannot perform the redirection at that time.
In order to actually perform the redirection, additional configuration settings must be created within the Policy Database. This configuration is described in the configuration section of this document.
Two different actions can be taken for each event:
Various notes apply to redirection when used as an action associated with an event:
The parameter field for the Active Expressions used for redirection (SmApsRedirect and AZRedirect) can be used for some very powerful functionality.
The parameter field is in the form:
<key>=<value>;<key2>=<value>;...;<default redirect>
All fields are optional and the system works fine without specifying any parameters.
The <default redirect> parameter, if required, must be the last section in the parameter list. It cannot contain an equal sign or a semicolon (it is possible to escape such characters with a backslash "\"). If no redirection is to be performed by APS, this is where the user will be redirected to instead. This is used when you want to use one of the redirect events, but it would conflict with APS.
You can specify as many Key/Value pairs as required. APS will save these values. The character case for keys is ignored. If the same key is specified more than once, only the last value will be used.
Values may contain user attribute names surrounded by curly braces ("{" and "}"). Such attribute names (and the braces) will be replaced by the attribute value from the user's directory entry. If the first part of the value will reference an attribute in this way and a setting override is not to be used, you must specify an override of "{TRUE}" in order not to confuse the APS.cfg parser (so it recognizes the attribute reference and can differentiate it from an override).
Event redirection can be overridden using the standard override syntax. In addition, context macros are also available. The <key> values passed through the Active Expression are used as context macros whose values are the <value> passed for the key. Some other event-specific context macros are also available (discussed with each event definition).
When a redirect must be determined, APS will evaluate all redirects of the correct type in the order in which they appear. The last one that applies will be used.
To override a redirection setting, specify a Key/Value pair after the equal sign, within square brackets, such as:
Failure Redirect={%LANG="EN"}http:/EnglishFailure.htm
If the parameter of the redirect response defined in the Policy were LANG={preferredLanguage}, then there will be a key called LANG with a value of the user's preferred language (from their LDAP entry). If the value from the user's entry were EN (for English), then the LANG key will have a value of EN, thus this setting would be selected (assuming it is not superceded by another setting later).
This is most useful to select redirections based on Realm. APS does not support this directly, but it can easily be performed using this feature by specifying a Key called REALM in each response, with a value appropriate for that realm. Overrides can then be defined in this file for each Realm. Realize that this is not truly tied to the realm, it is only a key supplied as a parameter to the redirect.
For example:
Failure Redirect={%Realm="AppA"} http:/AppA.htm
Will be fired if invoked by an active expression such as the following (presumably defined only in the ApplicationA realm):
<@ lib="smaps" func="SmApsRedirect" param="Realm=AppA" @>
But would not be fired in other realms where the REALM keyword was not set to AppA.
Once a redirection URL has been selected, APS will perform additional translations on that URL. In addition to the keys supplied in the Active Expression parameter, the following Keys will also be defined:
|
Server |
The server component of the requested Resource URL. |
|
Resource |
The resource component of the requested Resource URL. |
|
Action |
The action component of the requested Resource URL. |
|
Target |
The full URL of the requested resource. |
If the user context is defined (the user is authenticated), these keys will be defined as well:
|
UserName |
The user's full DN |
|
UserPath |
The user's full path, including directory type and name. |
|
DirPath |
The path to the directory server. |
|
DirServer |
The directory server. |
|
DirNamespace |
LDAP:, ODBC: or WinNT:, depending on the origin of the user. |
APS will take the resulting URL (or the default one specified in the parameter field) and replace any references to any key with its value. References to keys should be placed in the URL surrounded by angle brackets ("<" and ">"). To continue the example above:
http://www.mysite.com/TargetPage?Language=<LANG>
would be translated to:
http://www.mysite.com/TargetPage?Language=EN
Key names are NOT case-sensitive and values will be URL-encoded (so TARGET will be encoded).
In addition, any text between curly braces ("{" and "}") will be replaced (along with the braces) with equivalent values from the user's directory entry. Note that this processing is only possible if the user has been successfully authenticated. An example might be:
http://www.mysite.com/TargetPage? Language=<LANG>&Name={FirstName}
would translate (for me) to:
http://www.mysite.com/TargetPage? Language=EN&Name=Eric
For some of these redirects, the setting will probably be SmCPW, that component of APS that allows users to change their passwords. SmCPW recognizes many arguments in its URL (as described on page 272), including:
Target=<target> DaysLeft=<DaysLeft> Optional
Multiple arguments should be separated by an ampersand ("&"), thus a warning redirect might be:
/CPW/SmCPW.exe?DaysLeft=<DaysLeft>&Target=<Target>
Additional arguments (either from keys or hard-coded) may be supplied. SmCPW will ignore them, but will pass them on to its own target in the same manner.
Default: none
Recommended: no
Complexity Level: Intermediate
When the user reaches Max Failures consecutive failures, where should APS send the user? This must be an unprotected page, since the user will not be allowed to login. It is not recommended that this redirect be used (use the mail notification instead), since by using it, your site acknowledges that a valid user id has been discovered and thus you open yourself to a denial of service attack.
Failure Redirect= http://www.yoursite.com/maxfails.htm
Default: none
Recommended: no
Complexity Level: Intermediate
If a user is already disabled when a login attempt occurs, APS will send the user to the specified page. This must be an unprotected page, since the user will not be allowed to login. This redirect should not be used for the same reasons as stated for the Failure Redirect setting above.
This redirection supports an additional macro called DisabledReason. This contains the reason code(s) associated with why the user is disabled.
Disable Redirect= http://www.yoursite.com/disabled.htm? Disabled=<DisabledReason>
Default: none
Recommended: Yes
Complexity Level: Intermediate
If a user has not logged in for Max Inactive days (or the number of days specified by smapsAccountExpirationDays), where should APS redirect the user (after disabling him)? This must be an unprotected page, since the user will not be allowed to login.
This redirection is safe to use. In order for this event to occur, the user has supplied a valid user id and password (he just has not done it for too long). Using this setting does not open a security hole.
If the APSExpire utility is utilized, this redirection may never occur (it may occur if the user attempts to log in on the same day as he would expire and APSExpire has not yet run). APSExpire will disable the user in its batch process instead, so this event does not occur. Instead, the Disabled Redirect setting would apply.
Inactive Redirect= http://www.yoursite.com/inactive.htm
Default: none
Recommended: Yes
Complexity Level: Intermediate
If a user has not changed his password for Password Expiration (or the value stored in smapsPasswordExpirationDays) plus Expiration Grace days or has used up all available Grace Logins, where should APS redirect the user (after disabling him)? This must be an unprotected page, since the user will not be allowed to login.
This redirection is safe to use. In order for this event to occur, the user has supplied a valid user ID and password (he just has not changed it for too long). Using this setting does not open a security hole.
Expired Redirect= http://www.yoursite.com/expired.htm
Default: none
Recommended: [path]SmCPW[.exe]?Target=<target>
Complexity Level: Basic
If a user is required to change his password immediately because the Force Password Change flag is set, where should APS redirect the user? This should be a protected page (probably the change password page).
This page may also be used if the Expire Change Redirect is needed but not specified.
Force Change Redirect= http://www.yoursite.com/CPW/SmCPW.exe? Target=<target>
Default: none
Recommended: [path]SmCPW[.exe]?Target=<target>& DaysLeft=<daysleft>
Complexity Level: Basic
If the user is being warned that his password will expire (starting Expiration Warning days before Password Expiration), where should APS redirect the user? This should be a protected page (probably the change password page).
Warning Redirect= http://www.yoursite.com/CPW/SmCPW.exe? Target=<target>&DaysLeft=<daysleft>
Default: none
Recommended: [path]SmCPW[.exe]?Target=<target>
Complexity Level: Basic
If a user is required to change his password immediately because his password has expired and he is still in the grace period, where should APS redirect the user? This should be a protected page (probably the change password page).
If this setting is not specified, but needed, the Force Change Redirect will be used.
Expire Change Redirect= http://www.yoursite.com/CPW/SmCPW.exe? Target=<target>
Generational Redirects only apply to LDAP and ODBC User Directories.
Starting with Version 3.0, APS supports Generational Redirects. This type of redirect is distinctly different from the event redirects described in the previous section.
While Generational Redirects are not strictly in the purvey of APS, APS already has the infrastructure in place to provide this useful functionality.
Generational Redirects are redirections that are to be applied to the user base at least once. The generational nature is because there can be multiple generations for a specific URL, each user is required to "see" all known generations of that target.
Each generational redirect has a name that is used as a key to describe that redirect. Two typical uses of generation redirects might use PROFILE and LICENSE, in order to force each user to see the user profile and the on-line access agreement.
In addition to a name, each redirect also needs a generation, which is a number and a URL.
Default: none
Complexity Level: Advanced
When a user accesses a site, APS looks at values stored in the smapsGenerationalRedirects attribute of the user. This attribute is multi-valued (on LDAP) and will contain key/value pairs, such as:
LICENSE=2 <comment info, usually date & IP> PROFILE=1 <comment info, usually date & IP>
APS compares the number associated with a specific key with the generation specified in the APS configuration file. If the number is less in the user record (or the key does not exist), the user will be redirected to the URL specified in the configuration file and the user's value for the smapsGenerationalRedirects attribute is updated with the new value.
Under normal conditions, only version 1 would ever be used. However, some sites might require, for example, that all users see an On-Line Access Agreement every time changes. In this case, merely update the version number in APS.cfg and all users will be sent to the associated URL (since new users have no value and existing users will have a stored generation of 1 instead of the new value, 2).
Unlike most settings in APS.CFG, all generational redirects will be processed, in the order in which they appear in the file.
Note that APS can only redirect the user to the URL, it cannot force the user to actually take an action once there.
APS will redirect the user to any applicable generational redirection pages after processing any applicable events. If multiple generational redirects are triggered, the user will be redirected to each, in the order that they appear in the APS.cfg file.
Generational Redirect=LICENSE=1 http://www.yoursite.com/Profile.jsp Generational Redirect=PROFILE=1 http://www.yoursite.com/Profile.jsp
Default: none
Complexity Level: Advanced
This setting will show the designated page to all applicable users the first (and only the first) time that they log in each day.
This setting uses the smapsGenerationalRedirects attribute to "remember" whether a user has been redirected on any given day, with a key value of APS_MOTD. The generation number will be the current date.
The user will be redirected to the message of the day after all APS events and all applicable generational redirects.
If multiple Message of the Day settings exist, the last which applies will be used.
Message Of The Day = http://www.yoursite.com/motd.htm
Message Of The Day ={@Employees} http://www.yoursite.com/EmpMotd.htm
Message Of The Day ={@Customers} http://www.yoursite.com/CustMotd.htm
Default: none
Complexity Level: Advanced
This setting will show the designated page to all applicable users every time that the user authenticates.
This setting does not use the smapsGenerationalRedirects attribute.
If multiple Always Redirect settings exist, the last that applies will be used.
Always Redirect=http://www.yoursite.com/notices.htm
Always Redirect={@Employees} http://www.yoursite.com/EmpNotices.htm
Always Redirect={@Customers} http://www.yoursite.com/CstNotices.htm
Default: none
Complexity Level: Advanced
This setting will show the designated page to all applicable users every time that the user accesses a page. This setting should be used very carefully, since users will be unable to access all or part of your site.
It is often used to temporarily present a page to users that are trying to access part of your site that is being upgraded.
This setting does not use the smapsGenerationalRedirects attribute.
If multiple Always Redirect settings exist, the last that applies will be used.
This setting requires the use of the AZRedirect Active Expression.
Always Redirect AZ = {NOT @Tester AND %Realm="AppA"} http://www.yoursite.com/offline.htm
These settings specify the files that are to be sent by APS when the associated event occurs. There is no such thing as "most restrictive" setting in these cases; the last applicable setting will be used.
File names may contain full or relative paths or no path at all. APS will use the Directory setting in the [MAIL] section to locate files, if required.
File names may contain attribute replacement specifications, such as /Mail/{preferredLanguage}/Disabled.email.
Multiple files may be specified, separated by a semicolon (";"). If so, APS will send all of them, if possible. This is useful when one file should be sent to the user and another to an administrator.
The format of these files is described in the section entitled Email Templates.
If no mail is to be sent for a specific event, comment out or leave the setting blank.
If your User Directory does not have valid email addresses, you should not use these settings, except to send mail to internal personnel (fixed email addresses).
For Windows NT users, APS looks at the Description field in the user's entry. Within that field, APS looks for the string Email:. The text immediately following, up to the end of the description field or the next space, will be used as the user's email address.
Default: none
Recommended: Yes, to user
Complexity Level: Intermediate
This setting specifies the file(s) to send when a disabled user tries to authenticate. This is useful to tell the user that they have entered correct information, but their user record is currently disabled. Note that if passwords are reset (see the Reset Passwords setting on page 71) users will fail authentication and not see this mail. This is only sent when they successfully authenticate, then are rejected by APS because the record is disabled.
This event supports a macro called DisabledReason. This will contain the reason code(s) associated with why the user is disabled.
Disabled User Mail=Disabled.email
Default: none
Recommended: Yes, to user and administrator
Complexity Level: Intermediate
This setting specifies the file(s) to send when the maximum failure count is exceeded and the user is not going to be allowed to login. This is a very secure way to notify a user (or administrator) of a possible attack on the system, since a hacker will not receive the mail (and thus the user id is not confirmed and the hacker will continue attempts that can never succeed). The user will be notified why his mistaken logins do not work and that his account is disabled.
Administrators can be notified of the attack. This is often very usefully overridden for Administrator accounts, since it can be used to notify system or security administrators of attempts to access the system (most sites will not want System Administrator notification for all Max Failure events, only attacks on administrator accounts).
When this mail is sent, a macro called FailureCount can be included in the mail text itself. Its value is the actual number of failed attempts.
Max Failures Mail=MaxFailures.email
Max Failures Mail={@Administrators} MaxFailures.email; AdminMaxFailures.email
Default: none
Recommended: Yes, to administrator
Complexity Level: Advanced
When an account is under programmatic attack and the Max Failures setting is in effect, APS disables the user and sends the Max Failures Mail when the failure count first reaches the value of Max Failures. Presumably, Max Failures Mail will be sent to the user.
This setting, Ongoing Failures Mail, specifies the file(s) to send as the attack continues. Each Max Failures attempts will trigger the sending of the file(s) indicated in this setting. Under normal circumstances, this mail is sent to an internal administrator to notify that person that the attack continues.
Often, sites will configure this mail to go through an SMTP/Pager gateway so that the administrator is notified in real-time.
When this mail is sent, a macro called FailureCount can be included in the mail text itself. Its value is the actual number of failed attempts. It is often useful to include {SM_USERSESSIONIP} (note the braces) in the body of the mail so that the client IP address (the source of the attack) can be identified. This address is not necessarily trustworthy; it can be spoofed.
Ongoing Failures Mail=MoreAttacks.email
Default: none
Recommended: Yes, to user and administrator
Complexity Level: Intermediate
If the user is disabled because he is inactive, this setting is used to find the file to send as mail. This setting is used during the authentication process and by the APSExpire utility.
Inactive User Mail=InactiveOnline.email
Inactive User Mail={%APSExpire="YES"} NotifyInactiveUsers.email
Default: none
Recommended: no
Complexity Level: Advanced
This setting controls the mail file sent when a user's password actually expires (not when he enters the grace period). This is sent when the user is disabled because of password expiration. It can be used both for online expiration and by APSExpire.
Expired Password Mail= ExpiredPasswordOnline.email
Expired Password Mail={%APSExpire="YES"} NotifyExpiredPassword.email
Default: none
Recommended: no
Complexity Level: Advanced
If the user will be forced to change his password, this setting specifies the file that will be sent as email. It is not very useful, since redirection will actually force the password to be changed. It is not used by APSExpire.
Force Change Mail=ForceChangePassword.email
Default: none
Recommended: Yes
Complexity Level: Intermediate
If the user must be warned that his password will expire, but does not yet have to change the password, the file specified by this setting is sent.
This is actually a very useful setting. Consider, for your site, using this setting instead of redirecting the user. By using email (presumably either containing the URL that the user can use to change their password or instructions as to where a link can be located on your site), you will not interrupt the user's workflow to request an optional password change.
This setting can be used by APSExpire. If, for example, a typical user of your site only is expected to log in quarterly, but password expiration warnings are given 10 days before expiration, users will rarely ever actually see such a warning at login time. You can use this setting with APSExpire to warn users even when they are not logging in frequently.
Password Warning Mail={%APSAdmin!="YES"} PasswordWarningOnline.email
Password Warning Mail={%APSAdmin="YES"} NotifyPasswordWarning.email
Default: none
Recommended: Yes
Complexity Level: Intermediate
If the Max Inactivity and Inactivity Warning settings are specified, APSExpire can send a user email before the user's account actually expires. For very important customers, mail could be sent to an administrator instead of (or in addition to) the user. This setting specifies the file(s) to send.
This mail is only sent by APSExpire and only if a user will expire and warnings are to be sent.
Inactivity Warning Mail=InactivityWarning.email
Default: none
Recommended: Yes
Complexity Level: Advanced
If APSExpire actually disables a user for inactivity, this setting specifies the mail file(s) that it should send. This is a separate setting from the mail sent if user expiration is detected during the login process, but is often the same file.
Inactivity Disabled Mail=InactivityDisabled.email
Default: none
Recommended: No
Complexity Level: Advanced
When a user changes their password, the change is confirmed on the screen. As an option, APS can also send mail to confirm the password change. This is generally unnecessary.
A special macro is available for this mail only. This macro contains the user's new password and may be inserted into the mail using the text %PASSWORD%. It is generally not a good idea to do this, however.
Change Confirmation Mail=ChangeConfirmation.email
When Advanced Password Services needs to send mail, it must communicate with a Simple Mail Transfer Protocol (SMTP) mail server.
The original design of APS used Microsoft's MAPI to send mail. This had advantages and disadvantages. The biggest advantages included the fact that you could use your existing mail address book and that you could send mail internally when an SMTP gateway server did not exist. However, MAPI is limited to interfacing to Microsoft Exchange servers only when server programs are sending mail. Also, MAPI does not exist within the Unix environment.
Since an SMTP interface is used to send mail, addresses must be Internet mail addresses in the form of username@domain.com, rather than an internal mail system address. Multiple addresses may be the target of email, separated by commas. White space (spaces) is ignored.
To control the message sent for each event, create a file for the event, and identify that file (or files) in the APS configuration file using the settings detailed in the previous section. In APSMail parlance, these are called mail templates.
Email is sent to the SMTP server immediately. However, the SMTP server may not send the mail to the target address right away. Thus, if a delivery error occurs, such as the target address is invalid, APS is not notified (since it has long since moved on). To detect and process these cases, a site should either regularly check the SMTP error logs or use a Reply On Error address so that sending errors are returned to the sender
The template file format is described starting on page 287.
All of the Mail Settings appear in a special Mail section in the APS Configuration File. The section starts when the text [MAIL] (case does not matter) appears in the file and continues until the end of the file or another section starts. All of the previously described keywords do not appear in a section and therefore must appear in the file before any other section starts.
No keywords in this section support overrides.
Default: none
Recommended: Yes
Complexity Level: Basic
This is the name or IP address of your SMTP gateway. APS will communicate with this server using port 25, which is assigned to SMTP. This can be either the name (such as MAIL.MYDOMAIN.COM) or the IP address (performance will be slightly faster using the IP address). You may need to obtain this information from your mail administrator.
If this field is blank or not supplied, APSMail will determine the applicable mail server using its own methods. If no server can be determined, no mail will be sent.
APSMail looks up the port number for the smtp service. If it is not explicitly configured for your machine, it will use port 25. To use a different port, configure the smtp service in your protocols file to the correct port number.
The SMTP server must support mail relaying.
Server=127.0.0.1
Default: none
Recommended: During testing or for auditing purposes
Complexity Level: Intermediate
APSMail can log all mail files to a log file, along with the result returned by the SMTP server at the time that the mail was submitted. This setting specifies if and where such logging should occur. Just because a message is logged does not mean that it was sent. It is useful for testing where either a mail server is not available or mail should not really be sent, such as in a development environment that uses production data.
APSMail supports a number of alternate ways to set this value if it is not specified here. See the chapter entitled Using Email for complete details.
Log Path=APSMail.Log
Default: none
Recommended: Yes
Complexity Level: Advanced
The Directory setting is similar to the PATH environment variable; it can contain one or more directories on which mail files can reside.
Multiple directories are separated by semicolons on Windows NT, colons on Unix.
Directory names can contain replacement/lookup references. One of the easiest ways to internationalize email is to specify a directory like:
/mail/{preferredLanguage}
In this case, the current (LDAP) user's value for the attribute called preferredLanguage will replace the reference in the path.
Directory=/mail/{preferredLanguage}
Directory=/mail
APSMail supports a number of alternate ways to set this value if it is not specified here. See the chapter entitled Using Email for complete details.
APS supports two different extension libraries, SmAPSEx and SmAPSLog. These libraries allow the extension of APS functionality without modifying the base APS modules.
SmAPSLog is a library that can be used to provide custom logging of APS activity. It might be useful, for example, to produce summarized statistics. The source code for the SmAPSLog library is supplied with the installation kit. However, this code is provided "as is", without warranty and without support.
The APS Configuration File can contain settings for SmAPSLog. Any such settings are automatically passed to SmAPSLog for use by that library.
All of the SmAPSLog settings appear in a special Logging section in the APS Configuration File. The section starts when the text [Logging] (case does not matter) appears in the file and continues until the end of the file or another section starts. All general keywords do not appear in a section and therefore must appear in the file before any sections start.
Custom logging settings appear after this keyword in the same type of format supported in the rest of the file.
No setting in this section supports overrides.
APS supports two different extension libraries, SmAPSEx and SmAPSLog. These libraries allow the extension of APS functionality without modifying the base APS modules.
SmAPSEx is a library that can be used to provide custom functionality for APS. It can be used to change the behavior of APS without modifying APS itself. However, SmAPSEx must be a secure module, since it can see passwords in clear text (so, for example, it can implement custom password content rules). Thus the library is not made directly available to developers outside of CA. Contact CA Professional Services for information if you think that you need a custom SmAPSEx module.
The APS Configuration File can contain settings for SmAPSEx. Any such settings are automatically passed to SmAPSEx for use by that library. See the documentation provided with your version of SmAPSEx to determine what the valid settings are if you have a copy of SmAPSEx.
All of the SmAPSEx settings appear in a special Custom section in the APS Configuration File. The section starts when the text [Custom] (case does not matter) appears in the file and continues until the end of the file or another section starts. All general keywords do not appear in a section and therefore must appear in the file before any sections start.
Custom logging settings appear after this keyword in the same type of format supported in the rest of the file
No custom setting support overrides.
Dictionary checking is used to prevent common words from being embedded in passwords. Administrators often put words in the dictionary that are common to the type of business of the site. For example, a bank may wish to disallow words like "Account", "Savings", "Checking", and "Money".
All of the dictionary words appear in a special Dictionary section in the APS Configuration File. The section starts when the text [Dictionary] (case does not matter) appears in the file and continues until the end of the file or another section starts. All general keywords do not appear in a section and therefore must appear in the file before any sections start.
All entries in this section are disallowed words (all comparisons are case-insensitive and checked both forwards and backwards). Comments and blank lines ARE allowed in this section. Note that words less than four (4) characters will be ignored.
Example:
[Dictionary]
Customers Accounts Baseball Password
APS can calculate a password's complexity and compare it to a specified threshold to determine if the password should be allowed.
There are three metrics that APS uses to evaluate password complexity:
Each character has a value. APS adds up the values assigned to each character. Characters that appear more than once (case-insensitive) do not count multiple times.
Longer passwords are better. APS gives points for longer passwords.
Mixed case passwords are better. Every time that the password "switches case" (goes from lower to upper or upper to lower), a value is added to the complexity.
APS has a utility called APSComplexity that calculates the complexity of a given password. It may be useful to try various passwords to get a feel for these calculations.
The weight of each metric can be adjusted in the complexity section of the APS.cfg file. This section begins with a single line in the configuration file that looks like:
It is very unusual for sites to make changes to this section. The defaults are suitable for most sites. This section exists so that a site can fine-tune the calculations still further.
Normally, this section is not needed, since there are default values for all possible complexity settings. This section can be used to fine-tune the weightings used for these calculations.
Note that no settings in this section can be overridden by user.
Default: not sorted
Recommended: Yes
Complexity Level: Advanced
When calculating the character values, APS ignores repeating characters. If this keyword appears, the characters will be sorted before this calculation. For example, without the Sorted keyword, "Passwords" gets credit for the letter "s" twice (the second appearance does not count, since it repeats the prior character). If Sorted appears, "Passwords" receives credit for the letter "s" only once.
To turn this setting off, comment it out of the configuration file.
Sorted
Default: 2
Recommended: use the default
Complexity Level: Advanced
When calculating complexity, APS will add this value to the complexity score each time that the case switches from lower to upper or upper to lower case. Thus, using the default value of 2, "Passwords" would receive 2 points for a case switch and "PassWords" would receive 6. Intervening non-alphabetic characters are ignored in these calculations, so "Pass2W4ords" still received 6 points.
If case switching should not be considered during complexity calculations, set this value to zero.
Case Switch=0 Case Switch=4
Default: +2
Recommended: use the default
Complexity Level: Advanced
This is actually 29 different keywords: Length4, Length5, through Length32. Each value specifies the score applied to passwords of that length. If no length values are specified, length is scored at zero for length 4, plus two points for each additional character (length 5=2, length 7=6, etc.).
If only some length values are specified, the default ("+2") is used up to the first specified value, then the specified value is used for all lengths up to the next specified value and so on. For example, if the following is specified:
Length4=0 Length8=4 Length12=6
Would be the same as:
Length4=0 Length5=0 Length6=0 Length7=0 Length8=4 Length9=4 Length10=4 Length11=4 Length12=8 Length13=8
(and so on).
Default: 0-10
Recommended: Yes
Complexity Level: Advanced
There are 256 characters in the ASCII character set. Every character can have its own score and these scores can be overridden in APS.cfg. The default scores are:
Letter scores are shown in the following table. Lower case characters, by default, have the same value as their upper-case equivalents.
|
A |
1 |
|
J |
8 |
|
S |
1 |
|
B |
3 |
|
K |
5 |
|
T |
1 |
|
C |
3 |
|
L |
1 |
|
U |
1 |
|
D |
2 |
|
M |
3 |
|
V |
4 |
|
E |
1 |
|
N |
1 |
|
W |
4 |
|
F |
4 |
|
O |
1 |
|
X |
8 |
|
G |
2 |
|
P |
3 |
|
Y |
3 |
|
H |
4 |
|
Q |
10 |
|
Z |
10 |
|
I |
1 |
|
R |
1 |
|
|
|
There are three ways to set the score for a specific character. For displayable characters, either of the following methods will work. The examples below set the score for the capital letter "A":
A=5 'A'=5
Obviously, this mechanism does not work for non-displayable characters. Instead, the hexadecimal value of the character can be specified. For example, the score for Control-Z could be set to 5 using:
\x1A=5
If only one case of a character is explicitly set, then the other case will automatically be set to the same value.
Default scores for international (multibyte) characters are:
APS supports Windows NT, LDAP and ODBC User Directories. For LDAP and ODBC User Directories, APS requires that certain attributes or columns be available in each user entry so that it can store operational information.
Internally, APS knows each of these attributes by a certain name (described in the chapter entitled User Directories: Schema, Storage and Capabilities). However, CA recognizes that, in some cases, these names cannot be used in a directory, either because of the implementation or because of column naming policies required by the site.
An additional problem is that some attributes/columns will have a different name in different directories. It is highly desirable to be able to reference only a single name when building mail templates, settings overrides and performing attribute replacement within the APS.cfg file.
This section, the [Mappings] section, is used to remap a "known" name of an attribute (or column) to the underlying name.
Every setting in this section can be overridden. However, the expressions that can be used are restricted in that they cannot reference any user information, such as attribute values or group membership (the IsInGroup function). Attempts to do so will be rejected.
Mapping is rarely required. If a "known" name does not exist (at all) within this section, APS will assume that the name in the underlying User Directory is the same as the "known" name.
Note: Certain remappings are required in the APS.cfg file to identify and process Microsoft Active Directories. The following two lines are the minimum required to support an Active Directory as a user store (in the [Mapping] section of the APS.cfg file):
userPassword={IsInDirectory("<dirname>")} unicodePwd
inetOrgPerson={IsInDirectory("<dirname>")} user
smapsPassword ={ IsInDirectory("<dirname>") }
Note: <dirname> is the name of the User Directory entry in your Policy Store.
Note: If the only User Directory is an Active Directory, then the following two lines can be used:
userPassword=unicodePwd inetOrgPerson=user smapsPassword=
To map a standard attribute, use the format:
<logical-name>={<restricted-override>} <physical-name>
Where <logical name> is the name by which the attribute/column is know to APS by. <physical-name> is the underlying LDAP attribute or ODBC column name and <restricted-expression> is an override expression that is expressed in User Directory, not user or context, terms.
For example, under LDAP, users' full names are stored in an attribute called cn. Under ODBC, this is often a column called FullName. These can be mapped to a common name:
Name={IsLDAP()} cn
Name={IsODBC()} FullName0
Now, Name can be referenced in mail templates and override expressions without worrying about the differences between User Directories.
Some of the information maintained by APS is purely informational; it exists simply for reporting purposes. Sites can suppress this information by mapping the "known" name to a blank name. The descriptions of the APS attributes starting on page 140 tell which of these attributes can be suppressed in this way.
Supressing attributes this way does not significantly improve write performance. APS groups all writes into a single server request. For writes, the performance hits are primarily in the network portion of the request, in the record (index) lookup, and in the fault tolerance (journaling) portion of the update. The difference between updating two attributes and four, for example, is normally not even measurable, as long as the updates are performed on the same request.
However, for very large directories, the savings in disk space may be significant enough to be desirable. For example, with 100 million users, not saving smapsPreviousLogin, which might average 24 characters, would save at least 2.4 GB of disk space.
Of course, the saving of this storage should be balanced against the loss of this information for reporting purposes.
smapsPreviousLogin=
This section must be used to rename LDAP groups so that they can be used by APSAdmin as described on page 157. APSAdmin cannot use full DN names in its references, it needs a single name. This section is used to map a single name to a full LDAP DN for those purposes.
FailureGrp=cn=FailureCount,o=Airius.com
This is only used by APSAdmin. You cannot change the name of a group that APS will use as a disable group.
If LDAP Reverse Groups are required (as described on page 164), they are defined in this section.
To have APS treat all LDAP groups as reverse groups, use:
LDAP.ReverseGroups=*
An asterisk should not be considered a wildcard. It can only be used in the above manner to indicate that all groups are reverse groups.
To specify a single group as a reverse group:
LDAP.ReverseGroups=cn=Disabled-NoCredit, o=nds.com
Multiple such lines can exist, one for each reverse group.
Wherever possible, APS will use the queries defined in the SiteMinder ODBC Query Scheme associated with the User Directory. However, there are some additional queries that APS needs and there will be times that it is not appropriate for APS to use queries defined to SiteMinder.
In addition to the APS-specific queries, every query defined in the SiteMinder Query Scheme can be overridden for use by APS.
Each query has replacement parameters, or placeholders, embedded within them that indicate where APS (or SiteMinder) is to place values before using the query. Each query will replace these parameters with specific values in the order defined by the query. Thus, the first parameter for a given query may be replaced by the User's ID. It is not possible to change the order of the parameters (the choice of placeholders and their order is defined by SiteMinder's Query Schemes). Placeholders are indicated in a query by "%s".
All of these queries are defined or overridden in the APS.cfg file in this section.
Default: ' + CHAR(39) + '
Recommended: not used
Complexity Level: Advanced
This keyword can be used to specify the exact sequence that single quotes (apostrophes) should be replaced with when embedded inside of other quotes in a SQL query. By default, APS will use
' + CHAR(39) + '
This is the standard supported by SQL. However, some SQL implementations may use other sequences (Microsoft Access, for example, wants CHR instead of CHAR).
Default: off
Recommended: If needed
Complexity Level: Advanced
This setting was created to work around a problem with the base release of SiteMinder 5 and only affects ODBC User Directories. If you are getting "Invalid Handle" errors in your Authentication Log, put this setting into your APS.cfg file. APS will then test any handle passed to it from SiteMinder. If the handle is invalid, APS will open its own handle to the ODBC directory.
Default: n/a
Recommended: not used
Complexity Level: Advanced
The Enumerate query overrides the query by the same name defined to SiteMinder. APS does not use this query at this time.
Default: n/a
Recommended: not used
Complexity Level: Advanced
The Get Object Info query overrides the query by the same name defined to SiteMinder. APS does not use this query at this time.
Default: n/a
Recommended: not used
Complexity Level: Advanced
The Lookup query overrides the query by the same name defined to SiteMinder. APS does not use this query at this time.
Default: n/a
Recommended: not used
Complexity Level: Advanced
The Init User query overrides the query by the same name // defined to SiteMinder. APS does not use this query at this time.
Default: SELECT Name FROM SmUser
WHERE Name='%s' AND Password='%s'
Recommended: Defaults from SiteMinder, required
Complexity Level: Basic
The Authenticate User query overrides the query by the same name defined to SiteMinder. APS uses this query to determine if the old password entered during a password change is valid.
The first parameter is the user's name (entered to SiteMinder) and the second value is the (clear-text) old password as entered during the change password process.
This query can be a stored procedure, but the replacement parameters must retain their order and meaning. If the password is encrypted, then this query almost must be a stored procedure.
Default: SELECT %s FROM SmUser
WHERE Name='%s'
Recommended: Defaults from SiteMinder, required
Complexity Level: Basic
The Get User Property query overrides the query by the same name defined to SiteMinder. APS uses this query to retrieve the attribute values defined for the user.
The first parameter is always replaced with an asterisk (retrieve all defined columns), the second parameter is the user's id. If all columns should not be returned, this query should be overridden to reference a stored view in the database that returns fewer columns. Note that only columns returned on this query can be used in overrides or as macros in mail or redirections.
The first parameter is always replaced as a constant asterisk. A query could be defined with this, but then APS could not use the query defined to SiteMinder (which contains a replacement parameter in this position).
This query can be a stored procedure (if the underlying RDBMS supports rows returned from stored procedures), but the replacement parameters must retain their order and meaning.
Default: UPDATE SmUser
SET %s='%s'
WHERE Name='%s'
Recommended: Defaults from SiteMinder, required
Complexity Level: Intermediate
The Set User Property query overrides the query by the same name defined to SiteMinder. APS uses this query to set attribute values for the user.
The first parameter is the (mapped) name of the attribute (column) to modify, the second is the value to set it to. The third parameter is the user's name.
APS does special processing when using this query. If the query defined to APS (or SiteMinder) uses UPDATE, then APS will build a query to update all columns at once, using standard SQL syntax.
If, however, a stored procedure is used for this query, APS will call the stored procedure for each change. Parameters must appear in the same order for stored procedures.
The use of the UPDATE query is for higher performance.
If column access is to be restricted, create a stored VIEW in the database and use an UPDATE query to the stored view.
Default: n/a
Recommended: not used
Complexity Level: Advanced
The Get User Properties query overrides the query by the same name defined to SiteMinder. APS does not use this query at this time.
Default: n/a
Recommended: not used
Complexity Level: Advanced
The User Properties setting overrides the setting by the same name defined to SiteMinder. APS does not use this query at this time.
Default: SELECT Name, 'User' AS Class
FROM SmUser
WHERE %s
Recommended: Defaults from SiteMinder, required
Complexity Level: Basic
The Lookup User query overrides the query by the same name defined to SiteMinder. FPS and APSExpire use this query to locate users in the directory.
The parameter is the WHERE clause built up by FPS or APSExpire.
Default: See Description
Recommended: Defaults from SiteMinder, required
Complexity Level: Basic
The Get User Groups query overrides the query by the same name defined to SiteMinder. APS uses it to return the list of group in which the current user is a member. The default query is:
SELECTSmGroup.Name FROMSmGroup, SmUser, SmUserGroup WHERE SmUser.Name='%s' AND SmUser.UserID=SmUserGroup.UserID AND SmGroup.GroupID=SmUserGroup.GroupID
The parameter is the user's name.
Each row returned represents a group name of which the user is a member.
Default: See Description
Recommended: Defaults from SiteMinder, required
Complexity Level: Basic
The Is Group Member query overrides the query by the same name defined to SiteMinder. APS uses it to determine if the user is in a specific group, both for internal purposes and to determine the result of IsInGroup() calls in an override expression. The default query is:
SELECT ID FROMSmUserGroup WHERE UserID= (SELECT UserID FROM SmUser WHERE Name='%s') AND GroupID= (SELECT GroupID FROM SmGroup WHERE Name='%s')
The first parameter is the user's name, the second is the name of the group of interest.
If the result of the query contains any rows or data, the user is considered a member of the group.
Default: See Description
Recommended: Defaults from SiteMinder, required
Complexity Level: Basic
The Set Password query overrides the query by the same name defined to SiteMinder. APS uses it to actually change the user's password. Typically, it is a stored procedure, but it need not be. The default query is:
UPDATE SmUser SET Password='%s' WHERE Name='%s'
The first parameter is the new password, the second is the name of the user.
Note that the password may be encrypted, if SmAPSEx encrypted it.
This query can be a stored procedure (and should be), but the replacement parameters must retain their order and meaning.
Passwords will always be set using this query, never the Set User Properties query above.
Default: None
Recommended: Required if login history to be kept
Complexity Level: Intermediate
The Get Login History query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if Login History is to be maintained.
Login History contains an entry for each login attempt by a user. Typically, it will be a separate table containing two fields, the history entry and the user's name.
The next three queries are also used to manipulate login history.
The query has one parameter that is the user's name.
The Get Login History query must return a single column with the login history entry. Its name is irrelevant. The entries should be returned in date order.
The actual names of the table and columns are defined by the query and do not matter to APS.
An example query might be:
SELECT smapsLoginHistory FROM LoginHistory WHERE Name='%s' ORDER BY smapsLoginHistory
Default: None
Recommended: Required if login history to be kept
Complexity Level: Intermediate
The Set Login History query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if Login History is to be maintained.
Login History contains an entry for each login attempt by a user. Typically, it will be a separate table containing two fields, the history entry and the user's name.
The query has two parameters. The first is the Login History value and the second is the user's name.
The actual names of the table and columns are defined by the query and do not matter to APS.
An example query might be:
INSERT INTO LoginHistory (smapsLoginHistory, Name) VALUES ('%s','%s')
Default: None
Recommended: Required if login history to be kept
Complexity Level: Intermediate
Note: The Delete Login History query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if Login History is to be maintained.
Login History contains an entry for each login attempt by a user. Typically, it will be a separate table containing two fields, the history entry and the user's name.
Delete Login History query is used by APS to clean out old history values (before a specific date and time).
The query has two parameters. The first is the date and time to delete before and the second is the user's name.
The actual names of the table and columns are defined by the query and do not matter to APS.
An example query might be:
DELETE FROM LoginHistory WHERE LEFT(smapsLoginHistory, 15)<'%s' AND Name='%s'
Default: None
Recommended: Required if login history to be kept
Complexity Level: Intermediate
The Clear Login History query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if Login History is to be maintained.
Login History contains an entry for each login attempt by a user. Typically, it will be a separate table containing two fields, the history entry and the user's name.
The Clear Login History query is used by APSAdmin to clean out all of the login history for a specific user.
The query has a single parameter used to identify the user.
The actual names of the table and columns are defined by the query and do not matter to APS.
An example query might be:
DELETE FROM LoginHistory WHERE Name='%s'
Default: None
Recommended: Required if FPS log to be kept
Complexity Level: Advanced
The Get FPS Log query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if FPS Logging is to be maintained.
The FPS Log contains an entry for each FPS usage attempt by a user. Typically, it will be a separate table containing two fields, the log entry and the user's name.
The next two queries defined are also used to manipulate the FPS Log.
The query has one parameter that is the user's name.
The Get FPS Log query must return a single column with the log entry. Its name is irrelevant. The entries should be returned in date order.
The actual names of the table and columns are defined by the query and do not matter to APS.
An example query might be:
SELECT smfpsLog FROM FPSHistory
WHERE Name='%s'
ORDER BY smfpsLog
Default: None
Recommended: Required if FPS log to be kept
Complexity Level: Advanced
The Add FPS Log query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if FPS Logging is to be maintained.
The FPS Log contains an entry for each FPS usage attempt by a user. Typically, it will be a separate table containing two fields, the log entry and the user's name.
The query has two parameters. The first is the FPS Log value and the second is the user's name.
The actual names of the table and columns are defined by the query and do not matter to APS.
An example query might be:
INSERT INTO FPSHistory (smfpsLog, Name) VALUES ('%s','%s')
Default: None
Recommended: Required if FPS log to be kept
Complexity Level: Advanced
The Clear FPS Log query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if FPS Logging is to be maintained.
The FPS Log contains an entry for each FPS usage attempt by a user. Typically, it will be a separate table containing two fields, the log entry and the user's name.
The query has a single parameter used to identify the user.The Clear FPS Log query is used by APSAdmin to clean out all of the FPS Log entries for a specific user.
The actual names of the table and columns are defined by the query and do not matter to APS.
An example query might be:
DELETE FROM FPSHistory WHERE Name='%s'
Default: None
Recommended: Required if Auto Force Change used
Complexity Level: Advanced
Note: The Set Password Checksum query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if Auto Force Change functionality is required.
The Auto Force Change keyword in this file tells APS to check for password changes outside of APS and, if detected, force the user to change their password at next login. It is used to automatically treat external (administrative) password changes as Force Immediate Change situations without requiring changes to the administration utility.
Under LDAP, APS uses the smapsPassword attribute to handle this functionality. Under ODBC, this is not necessarily possible. Databases are typically protected so that passwords cannot be read back.
If Auto Force Change is to be used, this and the following query must be defined. They are almost always stored procedures.
The query has a single parameter used to identify the user (the user's password has already been changed).
Typically, the implementation of this functionality uses some special attribute to store the checksum (or the entire password value, for that matter).
An example query might be:
CALL SetPasswordChecksum('%s')
Default: None
Recommended: Required if Auto Force Change used
Complexity Level: Advanced
Note: The Test Password Checksum query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if Auto Force Change functionality is required.
The Auto Force Change keyword in this file tells APS to check for password changes outside of APS and, if detected, force the user to change their password at next login. It is used to automatically treat external (administrative) password changes as Force Immediate Change situations without requiring changes to the administration utility.
Under LDAP, APS uses the smapsPassword attribute to handle this functionality. Under ODBC, this is not necessarily possible. Databases are typically protected so that passwords cannot be read back.
If Auto Force Change is to be used, this and the previous query must be defined. They are almost always stored procedures.
The query has a single parameter used to identify the user. The function should return a numeric or boolean value, where non-zero indicates that the checksum is invalid.
Typically, the implementation of this functionality uses some special attribute to store the checksum (or the entire password value, for that matter).
An example query might be:
?=CALL TestPasswordChecksum('%s')
Default: None
Recommended: Required if FPS Answers are encrypted
Complexity Level: Advanced
Note: The Compare FPS Answer query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if FPSí ODBC Encrypt functionality is required.
The answers to FPS questions can be encrypted in an ODBC database. This is indicated to APS using the ODBC Encrypt keyword in the [FPS-Verify] section of the APS.cfg file. This query is one way that sites can implement this encryption.
There is no default for this query. If not defined and ODBC Encrypt was specified in APS.cfg, FPS will generate an error, since it won't know how to compare an encrypted answer (this is assuming that the encryption is not being performed by SmAPSEx).
The query must be a stored procedure that takes three arguments (or, at least, three substitution parameters) and return a numeric or boolean value (non-zero indicates that the compare is true).
The first parameter is the user name. The second parameter is the name of the attribute, as configured to APS. The third parameter is the user-entered answer (in clear text).
The implementation of this function usually encrypts (or hashes) the user supplied value (the third parameter) and compares it to the value stored in the user entry.
An example query might be:
?=CALL CompareFPSAnswer('%s', '%s', '%s')
Default: None
Recommended: Required if groups maintained by APSAdmin
Complexity Level: Advanced
Note: The Add To Group query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if the APSAdmin API is to be used to maintain group memberships.
The APSAdmin API functions use this query to add users to an existing group (creation of groups is not supported).
There is no default query for this purpose. If not specified and a user must be added to a group, an error will be logged and the update will fail.
An example query might be:
INSERT INTO SmUserGroup (UserID, GroupID) VALUES ('%s', '%s')
Default: None
Recommended: Required if groups maintained by APSAdmin
Complexity Level: Advanced
Note: The Remove From Group query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if the APSAdmin API is to be used to maintain group memberships.
The APSAdmin API functions use this query to remove users from an existing group.
There is no default query for this purpose. If not specified and a user must be removed from a group, an error will be logged and the update will fail.
An example query might be:
DELETE FROM SmUserGroup
WHERE UserID='%s' AND
GroupID='%s'APSAdmin
Default: None
Recommended: Required in certain APSAdmin scenarios.
Complexity Level: Advanced
Note: The Admin Translation query does not exist in the SiteMinder Query Scheme and has no default. Therefore, a query must be defined if the APSAdmin API is to be used in certain scenarios.
This query takes a single parameter that is the value entered by the administrator on the APSAdmin user selection form. The query is expected to return a single record with at least one column that is the user's name (the one used in all of the other queries). If not specified, then the query is not used and the data entered is expected to be the user's name. If multiple records or no records are returned, a "User record could not be found" error is displayed to the administrator. If multiple records are returned, an error is issued to the console log as well.
This query is typically used if the administrator is expected to identify users to APSAdmin using something other than userid, such as membership number.
An example query might be:
SELECT Name FROM Users WHERE MemberID='%s'
The [APSExpire] section of the APS configuration file controls the operation of the APSExpire utility, described in the chapter entitled Daily Processing (APSExpire).
In the APS Configuration File, a site defines jobs by name. Each setting is the name of a job and the values define the criteria for the job. When APSExpire executes, a job name must be specified on its command line. The program will look for the definition of this job in this section of the configuration file.
Each job defines a user directory or subset of a user directory. The syntax is different for ODBC and LDAP directories.
Overrides are not supported in this section.
For LDAP directories, jobs are defined using this syntax:
<job name>= <LDAP directory> READ(<ip>) BASE(<base DN>) SCOPE(<scope>) FILTER(<filter>)
<job name> is an arbitrary name for the job.
<ip of LDAP directory> is the ip address, the network name, or the SiteMinder User Directory name of an LDAP directory defined to SiteMinder through the Policy Interface (it cannot contain spaces if used here). If it is an ip address, it may contain the port address as well. This must match up with the definition of a User Directory in the SiteMinder Policy Store (APSExpire will attempt to look up the directory using this value).
READ(<ip>) is an optional clause that tells APSExpire to read from a different directory than the base directory. In some cases, much higher performance can be achieved by reading from a dedicated replicant directory that either SiteMinder does not use at all or is the last directory in a failover chain. If specified, however, the alternate directory must be a replicant of the "real" directory.
BASE(<search Base>) defines the scope of the search. It is entire optional. If not specified, APSExpire will search the entire directory using the search base defined in the SiteMinder User directory entry. This is useful when an entire LDAP directory is not to be processed as a single job. Sites do this when the LDAP directory is very large and APSExpire processing is to be spread over multiple servers or jobs.
SCOPE(<scope>) is optional and is generally used with the BASE option above. <scope> can either be "base" or "sub" (without quotes). It specifies how the LDAP search should be processed.
FILTER(<extra filter>) is another optional setting that allows a site to further refine a job. This filter is ANDed with any filters that APSExpire uses for its own operations. Once again, this is intended to segregate an LDAP directory into smaller jobs for performance reasons.
When using BASE, SCOPE and FILTER, it is the responsibility of the site to make sure that every user will be processed. APSExpire does not examine the sum of all defined jobs to ensure that all users get processed.
For ODBC directories, jobs are defined using this syntax:
<job name>= <ODBC directory>
WHERE(<extra WHERE clause>)
<job name> is an arbitrary name for the job.
<ODBC directory> is the DSN name or the SiteMinder User Directory name of an ODBC user directory (neither can have embedded spaces in this context) defined to SiteMinder through the Policy Interface. This must match up with the definition of a User Directory in the SiteMinder Policy Store (APSExpire will attempt to look up the directory using this value).
WHERE(<extra WHERE clause>) is another optional setting that allows a site to further refine a job. This clause is ANDed with any WHERE clause that APSExpire uses for its own operations. This is intended to segregate an ODBC directory into smaller jobs for performance purposes.
When using WHERE, it is the responsibility of the site to make sure that every user will be processed. APSExpire does not examine the sum of all defined jobs to ensure that all users will be processed.
All FPS settings appear in the APS configuration file after the keyword [FPS]:
Value: File Path
Default: off
Recommended: yes
Complexity Level: Basic
FPS can log all attempts, successful or failed, to an audit log. This log is written to a flat file in comma-delimited format (suitable for import into many database and spreadsheet applications).
To specify the location of this log file, use this setting.
There is no way to control the format or content of this log, nor is there provision for wrapping or deleting the file. If this setting does not appear in the configuration file, no audit log will be written. Please be sure that the user under which the SiteMinder Policy Server processes are running can create and write to this file.
This file is not terribly useful. A site should check its contents to determine if the information is worth keeping.
Audit Log=/usr/Netegrity/SiteMinder/Logs/FPS.log
Value: Server name or ip address for LDAP,
SN name for ODBC
Default: 127.0.0.1:389
Recommended: required
Complexity Level: Basic
This keyword tells FPS which directories to search when FPS is invoked.
Each instance specifies one or more SiteMinder user directories.
After the list of directories, an optional condition can be defined that tells FPS when that particular set of directories should be searched. This condition is surrounded by square brackets ("[" and "]") and can contain a partial URL (or stem) of the Forgot stub This URL must contain the port number, if other than 80, and cannot contain the "http:" or "https:" prefix. FPS will use the full URL of the FORGOT stub that invoked the process and, if the specified stem is included entirely, that directory or set of directories will be used.
If multiple lines exist with the Directory keyword and apply, all lines will be used.
If the same directory appears in more than one line, it will only be searched once.
Directories are specified as the ip address and port of an LDAP directory server or servers OR the DSN name of an ODBC directory.
If a nonstandard LDAP port (not 389) is used, it must be appended to each ip address in the list that it applies to, separated from the ip address by a colon.
Directory=127.0.0.1 Directory=DSN_CNA DSN_SCA [//www.acme-calif.com] Directory=DSN_TX [//www.acme-texas.com]
If the user requesting FPS came in from www.acme-calif.com, FPS will search the local LDAP directory (127.0.0.1) and the ODBC directories with the DSN's of DSN_NCA and DSN_SCA.
If the user arrived from www.acme-texas.com, then the LDAP directory and DSN_TX will be searched.
The directories will be searched in the order that they appear.
FPS looks into the list of User Directories stored in the SiteMinder Policy Store, looking for an entry that references the server identified by this setting. FPS will use the first entry that matches to obtain administrator credentials and the search base (for LDAP directories).
Some sites will define multiple User Directory entries that reference the same physical LDAP server, each User Directory defining a different search base (or, in rare situations, credentials). This can confuse FPS, causing it to read the wrong portion of these LDAP directories.
To get around this problem, a site should trick SiteMinder (and FPS) into thinking that the multiple User Directory entries are implemented on separate servers. This is easily done using the hosts file on the Policy Server (it can be done using DNS as well, though that is a little more complicated) to define multiple names for the same physical IP address. Each User Directory should then reference a different alias for the same physical LDAP server. In the APS.cfg file, this setting, Directory, can then uniquely identify the proper User Directories.
Value: Standard override expression
Recommended: If required
Complexity Level: Basic
The Allowed keyword is used to define which users in a directory are allowed to use FPS. If no Allowed keyword exists in this section, all users in the directory will be allowed to use FPS. If a single instance of this keyword exists, then rights must be explicitly granted to this functionality.
The Allowed keyword may appear as many times as necessary.
Allowed=true
Under APS 3.0, there was a section called [LDAP] that was used to define the LDAP directory to be processed by FPS. This entire section has been eliminated from the APS Configuration File in APS Version 4.0.
The Server keyword has been replaced with the Directory keyword in the prior section. If APS finds the Server keyword, its value will be used as though presented in the [FPS] section using the Directory keyword and a warning will be issued.
The Administrator, Password, Search Base, ObjectClass and Lockout Group DN keywords are ignored. A warning is issued if these settings are encountered. APS now gets this information from the SiteMinder User Directory definition.
The Disallowed keyword is no longer supported. If encountered, it will be processed as though it appeared in the [FPS] section with the Allowed keyword, with a prefixed NOT operator and a warning will be issued.
The Allowed keyword is no longer supported in this section. If encountered, it will be processed as though it appeared in the [FPS] section and a warning will be issued.
The first thing that FPS must do when invoked by a user is to attempt to identify the user. All of the information that FPS needs to do this is defined in a section headed by a single line in the FPS configuration file containing the text:
Everything appearing after this line and before the start of another section is considered part of the identification section.
Prior to APS Version 4.0, this section was called [Identify]. In Version 4, this was renamed to [FPS-Identify]. The old name is still recognized and will be processed correctly, but a warning will be issued about the use of the deprecated name.
This section specifies the form(s) required to identify the user, how the forms are to be used, and how to handle various typical error conditions.
Value: URL
Default: none
Recommended: required
Code Description: URL
Complexity Level: Basic
When FPS is first invoked by a user, this is the page that FPS will first cause to be displayed. It is expected to present a form to the user. It must be a page that is not protected by SiteMinder. It need not be on the same directory as the Forgot stub.
URL=/FPS/Identify.jsp
Value: URL
Default: the value of URL above
Recommended: yes
Code Description: Missing URL
Complexity Level: Intermediate
If the user fails to fill in all of the required fields or one or more of the fields contain an invalid character, FPS will redirect the user to this URL. The URL will have a list of this missing or invalid fields appended to it, separated with ampersands ("&"). A question mark will be appended before the field names, if required.
There is currently no way to tell if the fields in error were empty but required, or if they contained invalid data.
Missing URL=/FPS/Identify-Missing.jsp
Value: URL
Default: the value of Missing URL above, with ?MoreData
appended
Recommended: yes
Code Description: Multiple URL
Complexity Level: Intermediate
If the user filled out the form presented by the URL, but multiple users were found matching the input criteria, this page is displayed. Depending upon your site, one of two cases may be in effect, in which case, this form must handle the correct case.
First, if the required fields on the identify form must absolutely define a single user, then you have a data or login error in your flow and this page must handle the error case.
If, on the other hand, your identify form has optional fields on it, this page might just request further information. For example, if your identification form requires first name and last name, but mail is optional, there may be more than one "Bill Smith" on file. This page could then request that one or more of the optional fields be supplied to further refine the search.
Multiple URL=/FPS/Identify.jsp?MoreData
Value: URL
Default: the value of Missing URL above, with ?NotFound appended
Recommended: yes
Code Description: Not Found URL
Complexity Level: Intermediate
If no user matches the input criteria, this page will be presented to the user. This is a terminating case (the FPS process is done, since no user can be identified).
If not supplied, the value of Missing URL is used, with ?NotFound appended.
Not Found URL=/FPS/Unknown.jsp
Value: URL
Default: none
Recommended: yes
Code Description: Disabled URL
Complexity Level: Basic
If the user is properly identified, but it turns out that the user is disabled for any reason, the user will be redirected to this page. This is a terminating case, since the FPS process cannot continue.
Note that this case is different, but related to, the Lockout case. Typically, this page refers the user to a customer server center.
Disabled URL=/FPS/Disabled.jsp
Value: Mail file(s)
Default: none
Recommended: if your site has email addresses on file
Complexity Level: Advanced
If the user is properly identified, but it turns out that the user is disabled for any reason, FPS can send mail. This setting specifies the files to send. If possible, mail should be sent to the actual user, since the user accessing FPS might not be the owner of the account.
This setting is optional and has no default.
Disabled Mail=Disabled.email
These settings describe the identification form, its fields, and its requirements. FPS uses these settings to ensure that the entered data is valid.
It may seem possible to perform these edits using JavaScript. In fact, it is highly recommended that a site do so to reduce round trips to the server. However, JavaScript processing can be turned off by some browsers and can be modified by a savvy user, so FPS performs these edits as well.
Value: HTML field names
Default: none
Recommended: required
Complexity Level: Basic
This setting contains a list of the HTML fields on the identify (and missing and multiple) forms that are required. If any field identified by this setting is posted without a value, FPS will redirect the user to the page identified by the Missing URL setting above.
Names are not case sensitive, may appear in any order and are separated by semicolons. Multiple fields with the same name are not supported.
An FPS configuration error will occur if a field is posted that is neither required nor optional.
Required=FirstName;LastName
Value: HTML field names
Default: none
Recommended: if needed
Complexity Level: Intermediate
Some fields on the identification forms can be optional; that is, the user need not provide a value. Usually, these fields are only used to further refine the user identification process (see the example under the description for the Multiple URL setting).
This setting contains a list of HTML fields that are optional.
Names are not case sensitive, may appear in any order and are separated by semicolons. Multiple fields with the same name are not supported.
An FPS configuration error will occur if a field is posted that is neither required nor optional.
If the Submit button has a name (is renamed), then its value will be posted. In this case, its name must be defined as an Optional field.
Optional=Phone;City;State;UserID;phonenow;Mail
Value: special (see text)
Default: none
Recommended: required
Complexity Level: Basic
Once the identify form is posted and all of the fields validated (required fields not blank and no fields contain invalid characters), this setting is used to determine how to look up the user.
This setting consists of HTML Field/attribute mappings, separated by either an equal sign ("=") or a equal sign/tilde ("=~"). Each pair is separated from the others by a semicolon. Names are not case-sensitive, but the order that they appear can have a significant performance impact.
A pair is only used if there is non-blank input for the HTML field.
For each combination, FPS builds a search string for the user, comparing the attribute/column with the value supplied on the form. If an equal sign is used, then the value must compare exactly (but may be subject to the comparison rules of the underlying Directory). If the tilde ("~") is used, then a case-insensitive match is performed.
Basically, you want the most specific items first in the list, with less specific items appearing later.
Multiple attributes can be specified for the same HTML field, separated from each other by commas. This indicates that the value of the field could be in any of the supplied attributes. This is typically used for phone numbers, where the supplied number could be in the telephone, homePhone, or mobile attributes. FPS will create an OR condition in this case that will be ANDed with all other clauses.
Not all fields need to appear in the Lookup setting, but a field in this setting that is neither Required nor Optional will never be used for lookup. A field that does not appear in this setting could be used in mail, for example (in some examples, the user can enter a "Phone number where you can be reached right now" that could be sent as mail to a customer service desk in the event of an error case).
Lookup=UserID=uid;FirstName=givenname; LastName=sn;Mail=mail; Phone=telephoneNumber,homePhone; City=~l;State=st
Value: number of days
Default: none
Recommended: 7
Complexity Level: Advanced
Some sites may wish to limit the use of FPS to prevent misuse. Some users may use FPS instead of their password, if the password content policies make memorable passwords too difficult. This setting can be used to prevent a user from successfully using FPS too frequently.
This setting specifies, in days, how much time must elapse after a successful use of FPS before a user can use FPS again.
For example, if the user uses FPS today to recover his password, he cannot use FPS again for a week if this value is seven. If he attempt to do so, he will be redirected to the Too Recently Used URL below.
For this feature to work with ODBC correctly, the FPS Logging queries (starting on page 107) must be defined.
Max Success Frequency=7
Value: URL
Default: none
Recommended: required if Max Success Frequency is set above
Code Description: Too Recently Used URL
Complexity Level: Advanced
If a user attempts to use FPS too soon after he has already recovered a password (based on the Max Success Frequency above), the user will be sent to this page.
For this feature to work with ODBC correctly, the FPS Logging queries (starting on page 107) must be defined.
Too Recently Used URL=/FPS/TRU.jsp
Value: mail file(s)
Default: none
Recommended: ignored unless Max Success Frequency is set above
Complexity Level: Advanced
If the user is sent to the Too Recently Used URL above, any mail files specified in this setting are also sent, if possible.
For this feature to work with ODBC correctly, the FPS Logging queries (starting on page 107) must be defined.
Too Recently Used Mail=TRU.email
Value: number
Default: none
Recommended: 1
Complexity Level: Advanced
FPS is a weak link in your site's security. A user's account can be attacked and entered without using a password using FPS. If a site uses questions to verify the user, the answers to those questions can often be socially engineered or obtained from other sources.
In order to improve security against such a hacker attack, this setting can control how often APS can be used by an account. It specifies, in days, how much time must elapse after any use of FPS (success or failure) before a user can use FPS again.
For example, if Jane Doe uses FPS today to recover John Smith's password today, but either fails to answer the question correctly or leaves the process without answering the question, nobody can use FPS against John Smith's account again for a day if this value is one. If someone attempts to do so, they will be redirected to the Too Recently Attempted URL below.
For this feature to work with ODBC correctly, the FPS Logging queries (starting on page 107) must be defined.
Max Attempts Frequency=1
Value: URL
Default: none
Recommended: required if Max Attempts Frequency is set above
Code Description: Too Recently Attempted URL
Complexity Level: Advanced
If a user attempts to use FPS too soon after any attempt to recover a password (based on the Max Attempts Frequency above), the user will be sent to this page.
For this feature to work with ODBC correctly, the FPS Logging queries (starting on page 107) must be defined.
Too Recently Attempted URL=/FPS/TRA.jsp
Value: mail file(s)
Default: none
Recommended: ignored unless Max Attempts Frequency is set
Complexity Level: Advanced
If the user is sent to the Too Recently Attempted URL above, any mail files specified in this setting are also sent, if possible.
For this feature to work with ODBC correctly, the FPS Logging queries (starting on page 107) must be defined.
Too Recently Attempted Mail=TRA.email
Value: number
Default: none
Recommended: 3
Complexity Level: Intermediate
Adept hackers will attempt to access your system using FPS. Even if your site uses validation questions, a hacker can gain access by socially engineering the answers to questions.
This setting essentially sets a "3 strikes, you're out" policy on FPS. This setting identifies the number of failed attempts to use FPS that occur before FPS is locked out for that account.
Each time that a user fails to complete an FPS session, this counter is incremented by one. Once the count reaches Lockout Count, FPS is no longer available for this account.
This number is only reset upon successful completion of an FPS session. Note that this means that if the account is locked out, there is no way for the user to reset this value. The only way for this value to be reset is for an administrator to clear smfpsLockoutCounter using a User Administration tool such as APSAdmin or CA Identity Manager.
This setting can automatically be reset upon successful SiteMinder authentication if the Reset FPS Lockout setting is turned on.
Lockout Count=3
Value: URL
Default: none
Recommended: 3
Code Description: Lockout URL
Complexity Level: Intermediate
If the user is locked out due to the Lockout Count, the user will be redirected to this page. The user will always be redirected to this page the first time that the count is reached. Further attempts to use FPS will also redirect the user to this page.
Lockout URL=/FPS/Lockout.jsp
Value: mail file(s)
Default: none
Recommended: if possible
Complexity Level: Advanced
If the user is locked out of FPS when attempting to recover a password, the files specified by this setting will be sent as email, if possible.
This is useful to detect intruders, in that the mail could be sent to an administrator account.
It is also useful to send mail to the user, if possible, since the user will not see the Lockout URL if the account is disabled by a hacker.
Lockout Mail=Lockout.email
Value: 0 to 365 * 24 * 60
Default: 0
Recommended: if possible
Complexity Level: Advanced
If the user is locked out of FPS when attempting to recover a password, FPS normally locks out the user permanently. This setting specifies a delay to use instead. The user will not be allowed to use FPS for this many minutes.
Lockout Timer=60
At the end of the Identify phase, FPS knows the identity of the user. Some sites may wish to attempt to verify that the user is who he claims to be (this process is highly recommended). If this is desired, the settings in the FPS-Verify section should be used.
All of the information that FPS needs to do this is defined in a section headed by a single line in the FPS configuration file containing the text:
Everything appearing after this line and before the start of another section is considered part of the verify section.
Prior to APS Version 4.0, this section was called [Verify]. In Version 4, this was renamed to [FPS-Verify]. The old name is still recognized and will be processed correctly, but a warning will be issued about the use of the deprecated name.
This section specifies the form(s) required to verify the user, how the forms are to be used and how to handle various common error conditions.
These settings define the forms that FPS should use to query the user for verification information.
Value: URL
Default: none
Recommended: yes
Code Description: URL
Complexity Level: Intermediate
If verification is to be used, this setting must be specified. This setting tells FPS where to send the user for verification. It is a form.
URL=/FPS/Verify.jsp
Value: URL
Default: the value of URL above
Recommended: yes
Code Description: Missing URL
Complexity Level: Intermediate
If the user fails to fill in all of the required fields or one or more of the fields contain an invalid character, FPS will redirect the user to this URL. The URL will have a list of this missing or invalid fields appended to it, separated with ampersands ("&"). A question mark will be appended before the field names, if required.
There is currently no way to tell if the fields in error were empty, but required, or if they contained invalid data.
URL=/FPS/Verify.jsp
Value: URL
Default: none
Recommended: no
Code Description: Retry URL
Complexity Level: Intermediate
If the user fails to answer the questions properly, he can be sent to one of two places. If this setting is not specified, the user will be sent to the page identified by the Invalid URL setting below, otherwise this setting will be used.
If set, the user will be sent to the Retry URL to re-attempt verification. Depending on the values in the Initial setting, the initial values may or may not differ. It is up to the site to control the number of times that retries can occur. Usually, this is controlled using the Restrict or Consume special instructions so that initial values are not reused and eventually run out (sending the user to the No Data URL below).
The use of this keyword is in no way affected by, nor affects, the Lockout Count settings, since Lockout Count only affects entry to the entire process, not looping within the process.
The use of this keyword significantly reduces the security of FPS, so we do not recommend its use.
Retry URL=/FPS/RetryVerify.jsp
Value: URL
Default: the value of URL above
Recommended: yes
Code Description: Invalid URL
Complexity Level: Intermediate
If the user answers the verification wrong, FPS will direct the user to this page. This is a terminal condition; the FPS process is terminated.
Invalid URL=/FPS/Unverified.jsp
Value: mail file(s)
Default: none
Recommended: yes
Complexity Level: Advanced
If the user answers the verification wrong, FPS will send these files, if possible, via email.
Invalid Mail=NoVerify.email
Value: URL
Default: none
Recommended: yes, if required
Code Description: No Data URL
Complexity Level: Intermediate
The Initial setting (described below) specifies the initial field settings that the URL is to receive before processing. In the Initial setting, some values may be marked required. If so, and no value (or not enough values) can be determined, the user will be sent to this page instead. This is a terminal condition (FPS processing terminates - the user cannot use FPS).
Typically, this is a page directing the user to a customer service representative.
No Data URL=/FPS/NoData.jsp
Value: mail file(s)
Default: none
Recommended: yes, if required
Complexity Level: Advanced
If the user will be redirected to the No Data URL above, the file(s) specified by this setting can also be sent via email.
No Data Mail=NoData.email
Value: URL
Default: none
Recommended: yes
Code Description: Timeout URL
Complexity Level: Intermediate
This setting specifies a page to send the user if the user failed to answer the questions within the period specified by the Timeout setting ("You did not answer quickly enough"). This reduces the ability of a hacker to socially engineer the answers to the verification question(s).
This is a terminal condition (FPS processing terminates - the user cannot use FPS at this time).
Timeout URL=/FPS/Timeout.jsp
These settings describe the verify form, its fields, and its requirements. FPS uses these settings to ensure that the entered data is valid.
It may seem possible to perform these edits using JavaScript. In fact, it is highly recommended that a site do so to reduce round trips to the server. However, JavaScript processing can be turned off by some browsers and can be modified by a savvy user, so FPS performs these edits as well.
Value: HTML field names
Default: none
Recommended: required
Complexity Level: Basic
This setting contains a list of the HTML fields on the verify (and retry) forms that are required. If any field is posted without a value, FPS will redirect the user to the page identified by Missing URL setting above.
Names are not case sensitive, may appear in any order and are separated by semicolons. Multiple fields with the same name are only supported using special instructions (see the Initial setting below). If the special instruction field requires multiple values, the correct number of values must be specified by the user.
An FPS configuration error will occur if a field is posted that is neither required nor optional.
Required=SecretAnswer
Value: HTML field names
Default: none
Recommended: if needed
Complexity Level: Intermediate
Some fields on the verify form can be optional; that is, the user need not provide a value. For example, if the Submit button has a name (is renamed), then its value will be posted. In this case, its name must be defined as an Optional field.
This setting contains a list of HTML fields that are optional.
Names are not case sensitive, may appear in any order and are separated by semicolons.
An FPS configuration error will occur if a field is posted that is neither required nor optional.
Optional=SubmitButton
Value: special (see text)
Defalt: none
Recommended: required
Complexity Level: Advanced
Once the verify form is posted and all of the fields validated (required fields not blank and no fields contain invalid characters), this setting is used to determine how to look up the user.
This setting consists of HTML Field/attribute mappings, separated by either an equal sign ("=") or an equal sign/tilde ("=~"). Each pair is separated from the others by a semicolon. Names are not case-sensitive, but the order that they appear can have a significant performance impact.
A pair is only used if there is non-blank input for the HTML field.
For each combination, FPS builds an evaluation expression for the user, comparing the attribute with the value supplied on the form. If an equal sign is used, then the value must compare exactly (in this case, the comparison defined by the underlying User Directory is irrelevant, FPS will require the exact match). If the tilde ("~") is used, then a case-insensitive compare is performed.
All such expression are combined with an AND operator, then checked against the user previously identified.
Multiple attributes can be specified for the same HTML field, separated from each other by commas. This indicates that the value of the field could be in any of the supplied LDAP attributes. This is typically used for phone numbers, where the supplied number could be in the telephone, homePhone, or mobile attributes. FPS will create an OR condition in this case that will be ANDed with all other clauses.
Not all fields need to appear in the Lookup setting, but a field in this setting that is neither Required nor Optional will never be used for lookup. A field that does not appear in this setting could be used in mail, for example (in some examples, the user can enter a "Phone number where you can be reached right now" that could be sent as mail to a customer service desk in the event of an error case).
If a field has special instructions (see the Initial setting below) that require multiple values, the query will be built appropriately (varies by special instruction).
Lookup=SecretAnswer=~personalAnswerLookup=SecretAnswer=QuestionList
Value: special (see text)
Deault: none
Recommended: as needed
Complexity Level: Intermediate
Usually, the verify page will need data from the user's record for display (see the chapter entitled Presentation Forms for details as to how this information is passed to the form). This setting controls what information is passed to the form. This is not required if the page does not need information about the user.
Sometimes, this is as simple as putting the identified user's name on the form. Other times, displaying the verification question selected by the user is required.
The format of this setting is as name/value pairs, separated by an equal sign ("="). Multiple pairs are separated by semicolons.
The name in each pair is the name that the page uses to identify the data element. It need not correspond to an HTML element. It is used inside the data cookie to name the field.
The second part of the pair identifies the name of the attribute from which FPS is to read the data value. Multiple values are not supported, except as defined by a Special Instruction.
If the name is prefaced by an asterisk, then the field must have a value. If, after looking up the attribute, the field does not have a value, the user will be redirected to the No Data URL.
Initial=*Name=cn;*Question=secretQuestion
Special Instructions
After the attribute name, special instructions can be specified for the field. Special instructions are surrounded by square brackets ("[" and "]") and immediately follow the attribute name.
Special instructions define special processing or formatting required for the field.
Special instructions consist of keywords separated by commas. Every special instruction requires a Format keyword. Other keywords vary by format. At the time of this writing, only Format=A and Format=B are supported. Additional formats may be supported in the future.
Format A requires that the underlying attribute be multi-valued. Since only LDAP directories support multi-valued attributes, Format A is only supported on LDAP User Directories. However, Format B, which is virtually identical to Format A, is supported on ODBC directories.
Format A indicates that the attribute is stored in the format:
<control data>|<question id>|<answer>
The following items exist as instances of the attribute:
When FPS returns the value(s) from the attribute, it only returns the <question id>. When it compares the returned answer, it compares the combination of the <question id> with the supplied answer.
Every time the question is asked, the <control data> is updated with the current date and time.
Only questions that have never been asked (those with no <control data>) and valid dates in <control data> can be selected. Keywords can be specified to further control which questions can be asked.
When using Format A, do not use approximate matching (the tilde sign). Since the question id is included in the match, almost anything that the user enters will come up as a match.
Pick=<number>
The Pick keyword tells FPS to select more than one value from the list of values stored in the attribute. If this keyword is not specified, only one value will be selected from the list.
If multiple values are specified, they will be supplied in separated by the pipe character ("|").
Note that if the name is prefixed by an asterisk and not enough values can be selected to satisfy the requirement, no values will be sent to the page. If the No Data URL is specified, the user will be sent to that page.
Questions are first qualified for selection using the <control data> and the keywords below. Once a qualified list has been produced, the questions are selected at random.
Restricted
If specified, this keyword indicates that no question can be selected if it has been used since the user last logged in. That is, if the date in <control data> is more recent than the last login date, the question cannot be selected. The use of this keyword requires that APS be installed and operational (since the last login date is tracked by APS).
Consume=<number>
This keyword indicates that a question cannot be selected if it has been asked within the last <number> days.
Consume
This keyword, which is mutually exclusive of the Consume=<number> option above, indicates that a question cannot be selected if it has ever been selected (<control data> is not blank).
Sorted
Once the possible values have been qualified (those items not available for selection have been removed from an in-memory list), the list is sorted. Those items that have already been selected today retain their full date/time for sorting. Those items selected more than 30 days ago have their date/time removed and the rest are sorted only by date (the time is removed). Please note that the adjustments are made internally for the purposes of sorting and are not saved to the directory.
The items are sorted in increasing order (oldest to newest). Those items without a date are sorted first.
FPS then looks down the list until it finds enough to satisfy the Pick requirement. If there is a "tie" on the effective date after reading enough items, FPS continues to count down the list until the "tie" is broken. From this list, FPS randomly picks the requisite number of items.
Format B is identical in every way to Format A, with one exception: Instead of storing each of question as a separate value of a multi-valued attribute, all question strings are stored in a single instance of the attribute, separated by a caret ("^"). In all other respects, Format=B is identical to Format=A.
Initial= *SecretQuestion=QuestionList [format=A,Pick=2,sorted]
Value: Attribute list, comma separated
Default: none
Recommended: as required
Complexity Level: Advanced
This setting specifies one or more attributes that must be encrypted or hashed before comparison. FPS will call the Compare FPS Answer query, if that query is defined.
If the Compare FPS Answer query is not defined, it will attempt to call a stored procedure on the User Directory called ODBCEncrypt_<attribute> with two parameters, the user name and the value for the attribute entered by the user. The procedure is expected to return a single Boolean (or integer) result. A non-zero return indicates that the value compared successfully.
ODBC Encrypt=SecretAnswer
Value: Number
Default: none
Recommended: 300
Complexity Level: Intermediate
This setting controls how much time (in seconds) is allowed to elapse before the user submits the verify form. If the user waits too long, the user will be redirected to the Timeout URL when the page is finally posted.
Timeout=300
Once the user is verified, you site may allow the user to set their password or may want to generate random passwords. If you wish to allow users to select their own passwords, specify this information in a section starting with:
Everything appearing after this line and before the start of another section is considered part of the change password section.
Prior to APS Version 4.0, this section was called [Change]. In Version 4, this was renamed to [FPS-Change]. The old name is still recognized and will be processed correctly, but a warning will be issued about the use of the deprecated name.
This section specifies the form(s) required to gather a password change from the user, how the forms are to be used and how to handle various common error conditions.
Value: URL
Default: none
Recommended: yes
Code Description: URL
Complexity Level: Basic
If the user will be allowed to select a password, this setting must be specified. This setting tells FPS where to send the user for the input form. It is a form.
URL=/FPS/ChangePassword.jsp
Value: URL
Default: none
Recommended: yes
Code Description: Timeout URL
Complexity Level: Intermediate
This setting specifies a page to send the user to if the user fails to submit the form within the time period specified by the Timeout setting ("You did not answer quickly enough").
This is a terminal condition (FPS processing terminates - the user cannot use FPS at this time).
Timeout URL=/FPS/Timeout.jsp
Value: Number
Default: none
Recommended: 300
Complexity Level: Intermediate
This setting controls how much time (in seconds) is allowed to elapse before the user submits the form. If the user waits too long, the user will be redirected to the Timeout URL when the page is finally posted.
Timeout=300
At the end of the FPS process, after the user has been identified and perhaps verified, FPS must give the user the information desired. This may include a new password and sometimes includes the user ID.
All of the information that FPS needs to do this is defined in a section headed by a single line in the FPS configuration file containing the text:
Everything appearing after this line and before the start of another section is considered part of the confirm section.
Prior to APS Version 4.0, this section was called [Confirm]. In Version 4, this was renamed to [FPS-Confirm]. The old name is still recognized and will be processed correctly, but a warning will be issued about the use of the deprecated name.
This section specifies the form(s) required to confirm information to the user, how the forms are to be used and how to handle various common error conditions.
Value: URL
Default: none
Recommended: yes, if required
Code Description: URL
Complexity Level: Basic
Under normal circumstances, this is the URL of a page to use to confirm the FPS process. Any data identified by the Initial setting (below) will be passed to this URL on its query string.
Some sites may consider this a security hole, so if this value is prefixed by an asterisk, FPS will display its own (internal) form for confirmation and will instead redirect the user to this URL upon completion. If this is the case, no query string will be used (since FPS can build the page dynamically).
If a password and user ID are to be recovered, only one should be displayed on this page (the other should be sent via mail), since both together open a larger security hole.
URL=/FPS/Confirm.jsp URL=*/HomePage.jsp
Value: mail file(s)
Default: none
Recommended: yes, if required
Complexity Level: Advanced
At the completion of the FPS process, one or more files can be sent, via email, using this setting.
If the user will be redirected to the No Data URL above, the file(s) specified by this setting can also be sent via email.
If both a password and user id are to be recovered, only one should be sent via mail (the other should be displayed on a page), since both together opens a larger security hole.
There are several special macros available to this mail.
|
Macro Name |
Purpose |
|
Password |
Clear text password that was randomly generated or that the user selected. |
|
HalfPassword1 |
The first half of the new password, in clear text. Useful for mailing half and displaying half. |
|
HalfPassword2 |
The second half of the new password, in clear text. Useful for mailing half and displaying half. |
|
OneShotPassword |
Only generated if the macro is requested, this is a random, 32-character password that can be used within 5 minutes (not-configurable) of generation to log this user in ONCE. Useful to automatically log in the user. Requires the APS Authentication Scheme to be installed. |
Mail=Confirm.email
Value: special (see text)
Default: none
Recommended: as needed
Complexity Level: Intermediate
The confirm page needs the information that it will display (usually the password and/or uid). This setting identifies the information that should be passed to the confirm page.
The format of this setting is as name/value pairs, separated by an equal sign ("="). Multiple pairs are separated by semicolons.
The name in each pair is the name that the page uses to identify the data element. It need not correspond to an HTML element. It is used in the query string to name the field.
The second part of the pair identifies the name of the attribute from which FPS is to read the data value. Multiple values are not supported. You cannot use userPassword, as this is a hashed field. Use password instead.
All of the macros defined in the table under the Mail keyword are available as additional attributes.
Initial=User=uid;PWD=password
Default: none
Recommended: yes
Complexity Level: Intermediate
When FPS sets the user's password, it can optionally set the force change password flag in the user's directory entry. FPS will only do this if this setting appears in the FPS configuration file.
Force Change
Value: -32
Default: 8
Complexity Level: Intermediate
At the completion of the process, FPS can reset the user's password. This setting controls the length of the new password. If specified out of the valid range, a length of 8 will be used.
If the user is allowed to change her own password (as described in the [FPS-Change] section), this setting has no effect.
New Password Length=10
Value: 0 or 60-3000 seconds
Default: none
Recommended: 90 seconds
Complexity Level: Intermediate
If non-zero, FPS will set the Must Login By date and time to the current time plus this value. If the user does not login to your site within this period, the user will not be allowed to login.
Timeout=90
Range: Character list
Default: none
Complexity Level: Advanced
The Allowed Characters keyword specifies a list of characters that are used in a generated password. Only characters listed with this keyword are used in generated passwords, subject to restriction by the Disallowed Characters and Force Case settings.
Each instance of this keyword can specify a list of characters. They may or may not be surrounded by double quotes. Since leading and trailing blanks in a setting value are ignored, these quotes may be necessary. If the value is surrounded by quotes, they will be removed from the list of allowed characters (though any contained quotes will be retained).
Multiple instances of this keyword may exist and may apply. APS will use the characters listed with every applicable instance of this setting.
If no Allowed Characters keyword is valid, then all characters will be used (subject to the Disallowed Characters setting below).
APS does not use characters that are both allowed and disallowed (they will be disallowed).
For example,
Allowed Characters=abcdefABCDEF01234
Range: Character list
Default: none
Recommended: none
Complexity Level: Advanced
The Disallowed Characters keyword specifies a list of characters that are not allowed in a generated password. Characters listed with this keyword are not used in generated passwords.
Each instance of this keyword can specify a list of characters. They may or may not be surrounded by double quotes. Since leading and trailing blanks in a setting value are ignored, these quotes may be necessary. If the value is surrounded by quotes, they will be removed from the list of allowed characters (though any contained quotes will be retained).
Multiple instances of this keyword may exist and may apply. APS uses the characters listed with every applicable instance of this setting.
If no Disallowed Characters keyword is valid, then all characters are allowed (subject to the Allowed Characters setting above).
APS does not use characters that are both allowed and disallowed (they are disallowed).
Disallowed Characters=xyzXYZ56789
Range: upper, lower, or none (default)
Default: none
Recommended: none
Complexity Level: Advanced
Controls whether alphabetic characters in generated passwords must be upper or lower case.
Default is "none" (characters may be either upper or lower case).
If Force Case is set to "upper" then a non-zero value for the Minimum Lower Case keyword cannot be satisfied. If Force Case is set to "lower" then a non-zero value for the Minimum Upper Case keyword cannot be satisfied.
For example:
Force Case=none
Range: 0 to 32
Default: 4
Complexity Level: Intermediate
This setting determines the minimum length of the generated password. If specified out of the valid range, a length of 4 is used.
For example:
Minimum Length=8
Range: 0 to 32
Default: 32
Complexity Level: Intermediate
This setting determines the maximum length of the generated password. If specified out of the valid range, a length of 32 is used.
For example:
Maximum Length=10
Range: 0 to 32
Default: 0
Complexity Level: Intermediate
This setting determines the minimum number of upper case characters in a generated password.
Note: Any upper case character generated also contributes toward the required number of characters that are defined in the Minimum Letters and Minimum Alphanumeric keywords.
For example:
Minimum Upper Case=1
Range: 0 to 32
Default: 0
Complexity Level: Intermediate
This setting determines the minimum number of lower case characters in a generated password.
Note: Any lower case character generated also contributes toward the required number of characters that are defined in the Minimum Letters and Minimum Alphanumeric keywords.
For example:
Minimum Lower Case=4
Range: 0-32 characters
Default: 0
Complexity Level: Intermediate
This setting requires that the generated password contain a certain minimum number of alphabetic letters. Alphabetic characters are defined as the letters in the alphabet, regardless of case.
For example:
Minimum Letters=2
Range: 0-32 characters
Default: 0
Complexity Level: Intermediate
This setting requires that the generated password contain a minimum number of numeric digits ("0" to "9").
For example:
Minimum Digits=1
Range: 0-32 characters
Default: 0
Complexity Level: Intermediate
This setting specifies that a generated password contains a certain minimum number of alphanumeric characters ("A"-"Z" or "0"-"9").
Note: If this setting is used together with one of the Minimum Letters or Minimum Numbers settings, characters can satisfy both requirements. For example, if Minimum Digits is 4 and this setting is 4, the password 1234 satisfies both requirements.
For example:
Minimum Alphanumeric=1
Range: 0-32 characters
Default: 0
Complexity Level: Intermediate
This setting specifies that a generated password contain a certain minimum number of punctuation marks. These can be periods, commas, exclamation marks, and so on.
Note: If this setting is used together with the Minimum Other setting, punctuation characters satisfy both requirements.
For example:
Minimum Punctuation=1
Range: 0-32 characters
Default: 0
Complexity Level: Intermediate
This setting specifies that a generated password contain a certain minimum number of symbol characters. Symbols are defined within APS as the following characters and all extended ASCII characters, including diacritical marks:
|
"~" (tilde) |
"@" (at) |
"#" (number) |
|
"$" (dollar) |
"%" (percent) |
"^" (circumflex) |
|
"&" (ampersand) |
"*" (asterisk) |
"(" (open parenthesis) |
|
")"(close parenthesis) |
"_" (underscore) |
"-" (hyphen) |
|
"+" (plus) |
"=" (equals) |
"{" (open brace) |
|
"}" (close brace) |
"[" (open bracket) |
"]" (close bracket) |
|
"<" (less than) |
">" (greater than) |
"/" (virgule) |
|
"\" (back slash) |
"|" (vertical bar) |
|
Note: If this setting is used together with the Minimum Other setting, symbol characters satisfy both requirements.
For example:
Minimum Symbols=1
Range: 0-32 characters
Default: 0
Complexity Level: Intermediate
This setting specifies that a generated password contains a specified minimum number of non-alphanumeric characters. This includes punctuation marks and other symbols located on the keyboard.
For example:
Minimum Other=1
Range: 0-32 characters
Default: 0
Complexity Level: Basic
This setting specifies maximum number of identical characters that can appear consecutively in a generated password. For example, if this setting is four, then aaaa should not appear anywhere in the password.
Note: This setting is advisory; the password generation algorithm makes every effort to satisfy this limitation but might not be able to, depending on the other settings. For example, if Maximum Repeat is set to 2, the password "A2bbc9j" would satisfy this guidance but "A2bbb9j" would not.
For example,
Maximum Repeat=3
FPS may encounter an unexpected error during processing. This may be a missing configuration setting (one of the ìexpected errorî pages is not configured), or it may be an error which occurred when communicating with the User Directory. This section defines how such errors are to be reported to the user. Note that all errors arealso written to the SiteMinder Authentication Console Log. In most cases, the Console Log will contain more detailed information about the error that is not useful to the user (or should not be revealed to the user).
All of the information that FPS needs to do this is defined in a section headed by a single line in the FPS configuration file containing the text:
Everything appearing after this line and before the start of another section is considered part of the errors section.
Prior to APS Version 4.0, this section was called [Errors]. In Version 4, this was renamed to [FPS-Errors]. The old name is still recognized and will be processed correctly, but a warning will be issued about the use of the deprecated name.
Value: URL
Default: none
Recommended: highly
Code Description: URL
Complexity Level: Basic
This is the page used to display errors. The error text will be in the query string (URL encoded).
URL=/FPS/Errors.jsp
Value: mail file(s)
Default: none
Recommended: highly
Complexity Level: Advanced
When such an error occurs, this setting indicates the file(s) to send via email. The actual error message can be included in the text using the message macro. Typically, this is used to notify an administrator that an error has occurred.
Mail=Errors.email
This section defines how FPS is to handle the case where a mail file is specified but cannot be sent. This does not occur if the mail cannot be delivered. It only occurs if the mail file(s) cannot be found or if the mail server refuses to accept the message.
All of the information that FPS needs to do this is defined in a section headed by a single line in the FPS configuration file containing the text:
Everything appearing after this line and before the start of another section is considered part of this section.
Prior to APS Version 4.0, this section was called [No Mail]. In Version 4, this was renamed to [FPS-No Mail]. The old name is still recognized and will be processed correctly, but a warning will be issued about the use of the deprecated name.
Value: URL
Default: none
Recommended: highly
Code Description: URL
Complexity Level: Basic
This is the page used to display mailing errors. The error text will be in the query string (URL encoded).
URL=/FPS/NoMail.jsp
Value: mail file(s)
Default: none
Recommended: highly
Complexity Level: Advanced
When such an error occurs, this setting indicates the file(s) to send via email. The actual error message can be included in the text using the message macro. Typically, this is used to notify an administrator that an error has occurred.
There is no guarantee that this mail can be sent either.
Mail=NoMail.email
|
Copyright © 2013 CA.
All rights reserved.
|
|