This chapter discusses the various forms used by the Forgotten Password (FPS) Interface. A site must supply all FPS forms, though sample forms are provided in both JSP and ASP. CA Professional Services can be contracted to produce this custom code as a separate contract.
This section contains the following topics:
The example code provided in this section is presented in ASP (and JSP is provided with APS as well). However, FPS does not require the use of any specific web language. Some pages can actually be presented entirely in static HTML, others will require some sort of server-side scripting so that fields can be initialized.
Most fields can and should be edited on the client side using JavaScript. However, some browsers allow JavaScript to be disabled and others do not support JavaScript at all, so the process should not depend entirely on it. Additionally, a savvy user can save the source, edit the JavaScript, then post from the modified page. FPS will perform its own edits to ensure that the data is valid.
When building the pages for the FPS process, always consider the BACK button on the browser. If a user uses FPS to recover her password, what happens when that user leaves her terminal and another user goes over and presses the BACK button?
For this reason, all but the static pages should be set to expire and not be cached. In addition, many pages should also do whatever they can to prevent the redisplay of the page. This can be done using the following code. Note that this depends on JavaScript and is subject to the caveat above.
<input type="hidden" name="control" value="0">
<script language="JavaScript 1.1">
<!---
If document.forms[0].control.value == "0")
document.forms[0].control.value = "1";
else
window.location.replace("SomeplaceElse.html");
-->
</script>
The replace method causes the current page to be replaced in the browser history with the specified page.
FPS pages must exist on the same server as the FORGOT CGI program, since the requisite cookies will not be transmitted from FORGOT to the pages if they are not.
All FPS forms can and should be referenced using SSL (https). To do so, configure all of the URLs in the APS configuration file with the https: prefix (assuming that your Web Server is capable of handling SSL requests).
To start the Forgotten Password process, your site needs to direct the user to the Forgot CGI stub (supplied with FPS). The user will then be redirected into the FPS process.
Typically, this link exists in one of two places. It can exist on the site's public (unprotected) home page ("Forgot your user id or password?") or directly on the login form. In either case, the query string passed to Forgot should include the URL that the user should be returned to upon completion as a Target macro. For example:
<a href="/FPS/Forgot?Target=HomePage.html"> Forgot your user id or password? </a>
If placed on the login form, the target should be the URL that the user originally desired. From within an FCC, the following could be used:
<a href="/FPS/Forgot?Target=$$target$$"> Forgot your user id or password? </a>
When FPS is first invoked by a user, this is the page that FPS will 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, but must be on the same logical Web Server.
Technically, this could be a static page that merely presents a form. Each field on the page should be defined in the APS Configuration File in as either Optional or Required so that FPS will accept input.
The form must post to the Forgot CGI program.
In its simplest form:
<HTML> <HEAD> <TITLE> Please Identify Yourself </TITLE> </HEAD> <BODY> <b>Please Identify Yourself</b> <FORM method="post" action="/FPS/Forgot"> <b>First Name: </b> <INPUT type="text" name="FirstName"> <br> <b>Last Name: </b> <INPUT type="text" name="LastName"> <br> <INPUT type="submit" value="Submit"> <INPUT type="reset"> </FORM> </BODY> </HTML>
Note: On a Windows NT Web Server, the action attribute of the FORM tag must reference Forgot.exe.
That is all that is needed, bare bones. Additional features would include expiring the page (though it is not necessary in this case) and performing edits to ensure that no field is blank or contains invalid data when posting. Additional fields might also be desirable.
Additional code will be necessary if this form is also to be used as the Missing and Multiple URL forms.
If the user fails to fill in all of the required fields or one or more of the fields contains an invalid character, FPS will redirect the user to this URL. The URL will have a list of the 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.
The original fields values will be in a cookie called NPSFPSFields. This is useful in the event that you wish to repopulate the fields with original values.
Usually, this is the same form as the URL (see URL). Typically, two additional pieces of code are needed. First, near the top of the page, an error message should be displayed to the user:
<% If Request.ServerVariables("QUERY_STRING") <> "" Then %>
<font color="red">
Fields marked in red are either missing or invalid.
</font>
<% End If %>
Then any prompt associated with a field in error can be turned red.
<% ShowRed = (Instr(Problem, "&FirstName&") > 0) If ShowRed Then %> <font color="red"> <% End If %> <b>First Name: </b> <% If ShowRed Then %> </font> <% End If %>
Of course, there are other ways to do this - this is only one way.
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 URL 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. In this case, this page should be just a static HTML page reporting the (internal) error and referring the user to your customer support line.
If, on the other hand, your identify form has optional fields on it that can be used to further refine the user search, 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.
Typically, a site will use the same URL for this page as for basic identification, with the additional code:
<% If UCase(Request.ServerVariables("QUERY_STRING"))
= "MOREDATA" Then %>
<font color="red">
We are unable to uniquely identify you.
Please supply more information.
</font>
<% End If %>
Of course, this code would have to be ELSE'd with the equivalent code in Missing URL (see Missing URL) if the same page were to be used for both.
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.
This should generally be static HTML referring the user to a customer support number.
If the user is properly identified, but it turns out that the user is disabled (due to an APS disabled group only), 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. Lockout may also cause the user to become disabled (using the Lockout Group DN setting). The first time this occurs (when the user is originally locked out), the user will be sent to the Lockout URL. If the user attempts to use FPS again, they will be sent to this page instead of the Lockout URL, since the user is disabled.
This should generally be static HTML referring the user to a customer support number. Administrator intervention will be required, since the user account will have to be enabled.
If a user attempts to use FPS too soon after he has already recovered a password (based on the Max Success Frequency setting), the user will be sent to this page.
This case is detected using smfpsLog.
This should generally be static HTML referring the user to a customer support number. The user cannot use FPS until the requisite time has elapsed.
A customer service application could delete information contained in smfpsLog to make FPS available again, but this would be counter-productive. The user needs to call the Help Desk to recover the password; the administrator there can reset the password. There is no need to delete logged information; to do so would be deleting auditing information.
If a user attempts to use FPS too soon after any attempt to recover a password (based on the Max Attempts Frequency setting), the user will be sent to this page.
This case is detected using smfpsLog.
This should generally be static HTML referring the user to a customer support number. The user cannot use FPS until the requisite time has elapsed.
A customer service application could delete information contained in smfpsLog to make FPS available again, but this would be counter-productive. The user needs to call the Help Desk to recover the password; the administrator there can reset the password. There is no need to delete logged information; to do so would be deleting auditing information.
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 unless the Lockout Group DN specifies a disabled group, in which case the user will be considered disabled and will be redirected to the Disabled URL on subsequent attempts.
This case is detected using smfpaLockoutCounter.
This should generally be static HTML referring the user to a customer support number. The user cannot use FPS until smfpaLockoutCounter has been cleared.
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 he is (this process is highly recommended). If this is desired, the verify forms (defined in the Verify section) will be used. If verification is not desired, the Verify section will be omitted from the APS configuration file.
This URL is the form used to request verification from the user. Its input fields must be defined as Optional or Required and it must have a Lookup setting so that FPS will know what to do with the input data.
Just like the Identify form, this could very simply be an HTML form. If the verification data is fixed, such as "Enter your Phone Number, Middle Name, and Account Number", then this will suffice. However, this is not terribly secure (but may be secure enough for your site).
Most sites want to read a challenge (question) of some sort from the user record and present it to the user. To this end, the Verify form can have initial data passed to it using the Initial setting.
Use the Initial setting to define what the page will need. FPS will create a cookie called NPSFPSData that will contain the initial data. Each field will be named as in the Initial setting, followed by an equals sign ("="), followed by the field's value, URL encoded. Multiple fields will be separated by ampersands. Thus, an Initial setting of:
Initial=FirstName=givenname;Question=SmPINQ
might create the cookie:
NPSFPSData=FirstName=Eric&Question=What%20is%20the%20name%20of%20your%20dog
You will have to use a server-side scripting language to read the cookie and parse it. Each scripting language has its own capabilities for doing so.
FPS does not use the cookie after setting it, so you are free to destroy it (FPS will destroy it automatically when the form is posted).
In order to "see" this cookie, your page must reside on the same logical Web Server as the FORGOT stub.
If special instructions (see initial) are used such that multiple values are to be passed for the same field (the Pick keyword), then the multiple values will be passed, each URL encoded, separated by pipes, as in:
Initial=Question=SmPINQ[Format=A,Pick=3] NPSFPSData= Question=100|200|203
If a Pick clause is used in special instructions, all of the answer fields must have the same element name and must appear in the same order as presented to the page. FPS tracks the questions and the order in which they should be presented and expects the answers back in the same sequence.
If there is not enough data to satisfy a Pick clause (because of a consume or restrict clause), no data will be returned to the page for that field. If the field is not marked as required (by placing an asterisk before its name in the Initial setting), the Verify form will be displayed, but there will be no value for the field. If the item is marked as required, the No Data URL page will be displayed.
It is especially important that the Verify page expire and prevent reviewing using the BACK button. Without taking these preventative measures, after a user has successfully used FPS, another user can press the BACK button to view the answers to the questions.
Another way to solve this problem is to make the input fields password fields, since the entered text is masked by asterisks and is not retained when the BACK button is pressed. However, this makes the page harder for users to use.
If the user fails to fill in all of the required fields or one or more of the fields contains an invalid character, FPS will redirect the user to this form. 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.
The original fields values will be in a cookie called NPSFPSFields. This is useful in the event that you wish to repopulate the fields with original values. There is currently no way to tell if the fields in error were empty but required, or if they contained invalid data.
Usually, this is the same form as the Verify URL above. Typically, two additional pieces code are needed. First, near the top of the page, an error message should be displayed to the user:
<% If Request.ServerVariables("QUERY_STRING") <> "" Then %>
<font color="red">
Fields marked in red are either missing or invalid.
</font>
<% End If %>
Then any prompt associated with a field in error can be turned red.
<% ShowRed = (Instr(Problem, "&Answer&") > 0) If ShowRed Then %> <font color="red"> <% End If %> <b>Answer: </b> <% If ShowRed Then %> </font> <% End If %>
Of course, there are other ways to do this - this is only one way.
If a user answers the verification question(s) wrong, your site may decide to let the user try again. This is not recommended, but some sites wish to do so.
If your site still wishes to do this, supply a Retry URL setting to specify the form for FPS to use. This form must have the same fields as the Verify URL. Initial values are evaluated again, so random question selection (special instructions) may change.
Care should be taken when using this keyword to prevent an unlimited number of attempts (by a hacker). FPS puts no constraints on the number of retries that a user can make. smfpsLockoutCounter is only checked each time that the FPS process is started, not each time that a Verify form is displayed.
If the Retry URL is not specified and the user answers the question incorrectly, he will be transferred to the Invalid URL instead.
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.
This should generally be static HTML referring the user to a customer support number, since they are unable to verify their identity. The user is not locked out of FPS.
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).
In other words, this page is invoked when some data that is required from the user record is unavailable, either because it is blank, restricted, or consumed. This may be a temporary condition (because of some cases of consumed and the use of restrict) or it may be permanent and require that the user login and modify their own profile.
Typically, this is a page directing the user to a customer service representative and can be static HTML.
This setting specifies a page to send the user to if the user fails to answer the questions within the time 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).
This could be a static HTML page. It could also be Forgot itself (or an intervening page with a message) so that the user can restart the FPS process.
The user is not locked out of FPS.
At the end of the verify phase, FPS is certain of the identity of the user. Some sites may allow the user to change their password to a known value at this time. This is one of the big potential security holes in your site. If this functionality is desired, the Change forms (defined in the Change section) will be used. If change password is not desired, the Change section should be omitted from the APS configuration file.
This URL is the form used to request the password change from the user. It requires exactly two input fields called NewPassword and VerifyPassword. They should be password fields.
As usual, the form posts to the FORGOT stub.
Just like the Identify and Verify forms, this could very simply be an HTML form. However, since FPS will return the user to this URL when there is a problem with password content (the error message, localized, will be passed as the query string), a server-side scripting language is desirable in order to process (display) a query string, if one exists.
It is especially important that this page expire and prevent reviewing/reposting using the BACK button. Without taking these preventative measures, after a user has successfully used FPS, another user may be able to press the BACK button to change the password again.
This setting specifies a page to send the user to when the form is not submitted within the 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).
This could be a static HTML page. It could also be Forgot itself (or an intervening page with a message) so that the user can restart the FPS process.
The user is not locked out of FPS.
There are several different strategies to finishing the FPS process, all configured using the Confirm section of the APS configuration file.
One way to do confirmation at the end of the FPS process is to send the information to the user via email. If this is to be done, the confirm page should say something like "The information that you requested has been sent to the email addressuser@somesite.com".
To pass information to a custom Confirm page, specify the Initial setting in the Confirm section. Unlike the similar keyword in the Verify section, this information will not be passed in a cookie (there would be no way to destroy the cookie when weíre done with it). Instead, the information is passed to the Confirm URL in its query string (in exactly the same format as the cookie).
To pass the new password, use password in the Initial setting instead of userPassword (the actual LDAP attribute name), since userPassword will be encrypted (actually, hashed).
CA strongly recommends that the user id and password not be presented to the user in the same medium. Send one via mail and display the other.
Another option is to display HalfPassword1 on the custom page and send HalfPassword2 via email. These macros return, in clear text, either the first half or the second half of the user's password. Of course, either the mail or the custom page will have to instruct the user that the two halves must be put together before using.
If you do not wish this information appear in the query string, put the ultimate target URL in the confirm URL setting and put an asterisk in front of it. FPS will dynamically build a page to display the confirmation message (and the initial data will not be placed in the query string). The message will come from the translation for CONFIRM_MESSAGE (the title of the page coming from CONFIRM_TITLE). Macros will be replaced in the confirmation message, including Password, uid, HalfPassword1, HalfPassword2, and OneShotPassword.
It is possible to automatically log the user in at the completion of the process. There are several ways to do this. The easiest (but least secure) way to do it, that works with all releases of SiteMinder, is to take the Initial information, pre-populate input fields on a login form, and POST to an FCC. This is not very secure, in that the password appears not only in the query string, but in the initial values for the input fields as well. By pressing the BACK button and View Source, this information is very visible, even in an SSL environment. The exception would be to use OneShotPasswords.
Instead of using the "real" password, use the OneShotPassword instead. FPS creats a single-use password when the macro "OneShotPassword" is referenced in a mail file or in an initial setting for the confirmation page. The OneShotPassword requires special set up to use (See Authentication Scheme.) but it is more secure than using a multiple use password, even if you allow the user to select their own password (since you will never show the selected password).
SiteMinder FCCís support a special keyword called "@loginonget" which allows an fcc to be used to authenticate a user without displaying a form (simply a redirect). FPS fully supports this option, using the following steps:
This file should contain exactly the following text:
@target=/FPSOneShot/DoesNotExist @username=%uid% @password=%OneShotPassword% @loginonget
URL=/siteminderagent/forms/oneshotfps.fcc Initial=uid;OneShotPassword
The actual URL to the FCC should be used.
If different users are to go to different ultimate targets, then different policies can be used for the "FPS One Shot Redirect" rule, for different users, with different responses controlling the actual URL.
If FPS encounters any error during processing for which there is no specific setting to handle, the user will be redirected to the page identified as the Error URL. Most errors are of two types:
Actual error text will passed to the page in the query string (URL encoded).
Generally, the message should be displayed to the user, and the user should be referred to the Help Desk.
Support personnel can obtain additional information about the error from the Console Logs.
The Mail URL page exists only to prevent a problem where we are unable to send mail to the user that is required for the FPS process. The cause of the failure will be one of the following:
Note that a non-existent target address will not cause a failure in any case, since it wonít be detected at send time.
This URL should typically just display an internal error-style message, referring the user to the Help Desk.
|
Copyright © 2013 CA.
All rights reserved.
|
|