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
|
Copyright © 2014 CA.
All rights reserved.
|
|