This chapter discusses how to use and customize the Change Password Interface (SmCPW). There is a default form supplied with APS for changing passwords. This form can, within limits, be customized by a site with no HTML programming. If further customization is required, the entire form can be replaced easily with minimal Web programming.
This section contains the following topics:
While APS provides a default form for doing so, custom forms can be written for password changes. They can be written in any language that can display a form. The form must POST to the SmCPW program (SmCPW.EXE on Windows) and may pass any or all command line arguments to it. If command line arguments are passed, the TARGET=<targetURL> should be passed, so that SmCPW knows where to send the user when the process is complete.
Note: Tests have shown that Netscape Communicator Version 4.70 may not support HTTP_REFERER correctly, so that HTML forms may not work correctly. No other browsers have yet been identified that have this same failing.
Prior to APS version 2.1, custom forms had to pass their query string to SmCPW during the posting process. Thus, such custom forms had to be written in a server-side scripting language, such as JSP or ASP, or as a CGI program. Since version 2.1, this is no longer required; custom forms can be written in HTML, if desired. If SmCPW receives a POST without any query string (the HTML form posts just to SmCPW), it will use its caller’s (referrer’s) query string.
SmCPW, when presented with an HTTP GET request, will generate an HTML form so that a user may enter password information.
SmCPW need not be used to produce the form. Instead, provide your own HTML for the form, if special processing is desired.
Any form that you desire can be used, as long as it provides three input fields: OldPassword, NewPassword and VerifyPassword. The last two must contain identical values. Set up your form to post its data to SmCPW or to whatever you have renamed that file.
An easy way to start is to run SmCPW through a browser and to select View Source from the browser’s menu. This action displays the raw HTML used by the form. You can save this HTML into a file and modify it as desired.
You can also run SmCPW from the command line and save its output. When run from the command line with no arguments (other than command line switches), SmCPW outputs the HTML to produce the form. From the command line, you can specify the -L and -C switches to make SmCPW produce the HTML in other languages; however, this approach requires that you have set up the proper translation files.
A single change password page may not be sufficient for your site. There aretwo types of password changes: Required and Optional. You can detect the difference using query string values (which is how SmCPW identifies the case) or you can use completely different forms. The different forms can be linked into your site separately through the APS configuration file and/or your home page (for voluntary password changes).
Additionally, password change warnings can invoke the page. You may wish tobuild an entirely separate page for this case that displays the number of days left to change the password (the number of days is available using the <DaysLeft> macro).
SmCPW gets some of its text from the SmCPW.lang files located in the language directories on your Web Server. This includes not only the text to display for each prompt, but limited control of HTML tags as well.
You can modify these values in the lang file to perform some substantial customization of the default form without writing any web code.
By default, SmCPW displays any error message (including content violations and communications errors) and forces the browser back to the form (using JavaScript). You can easily override this behavior, but it will require more work and more maintenance for your site. If you wish to use custom forms, no need exists to override this error handling, nor do you need to use a custom form to override this behavior.
All content and LDAP error messages are stored in files called APS.lang, located in the language directories on your Policy Server. Any of these messages can be modified using a standard text editor.
The password change confirmation and all communications error messages are located in the SmCPW.lang files stored in the language directories on your Web Server.
If any message to be displayed starts with http:, https: or /, SmCPW assumes that the message is a URL. After performing macro substitution (including replacing macros arriving in SmCPW’s query string), SmCPW redirects the user to the URL instead of displaying the message.
An easy test is to put the URL into the language file as desired, but put the text msg: in front of it. When you invoke the error, SmCPW displays the message with all macros replaced within the normal message box. Remove the msg: and SmCPW redirects the user to the page.
You can selectively redirect for some errors and use the standard messages for others.
If you are using internationalization as well, duplicate the URLs or specify different URLs for each supported language.
When running under a Web Server, the syntax of SmCPW is as follows. Note that APS can and will automatically construct these arguments if the redirection events are properly configured (see Chapter 3, APS Configuration File (APS.CFG).
SmCPW{.exe}?
[Optional]
[&][DaysLeft=<daysleft>]
[&][GraceLogins=<grace logins left>]
[&][DaysRemaining=<days remaining>]
[&][CancelTo=<cancelURL>]
[&][Target=<targetURL>]
[&][<additional arguments>]
The .exe component is required on Windows.
If Optional is specified, then the default form displayed by SmCPW has a Cancel button. If the user clicks this button, the browser is redirected back to the page that invoked the form (or <cancelURL>, if specified). The Cancel button is dependent on JavaScript support by the browser. If the Browser does not support JavaScript, a standard hyperlink labeled Cancel appears instead.
DAYSLEFT=<daysleft> may be supplied to indicate how long the password has left before it expires. There are two cases:
http://www.xyz.com/CPW/SmCPW.exe?DAYSLEFT=3
The TARGET=<targetURL> argument identifies the page to which the user should be directed upon completion of the password change. The <targetURL> should be passed in a URL-encoded format to avoid problems with embedded characters.
GRACELOGINS and DAYSREMAINING are used when the password has expired, but a grace period or a number of grace logins is configured. SmCPW will modify its displayed text to communicate these values to the user.
Additional key/value pairs may also be supplied, each set separated from its predecessor by an ampersand ("&"). These key/value pairs will be parsed and saved by SmCPW.
When SmCPW redirects to the next page, either by redirecting the specified target or to a custom message page, these key/value pairs will be used to replace macros in the target of the redirection. The URL is examined for text between < and > (angle brackets). The text and the angle brackets are replaced by the value associated with the text.
For example, if the SmCPW invocation is:
SmCPW?Target=%2FMyPage%2Easp%3F<lang>&Lang=EN
The user is redirected to:
/MyPage.asp?EN
When APS builds the redirection because of an event, it can construct complex URLs with such query strings and can include user attributes in that query string. See the section about Redirections later in this document.
SmCPW must be placed into a directory that is visible to a Web Server tha is protected by a SiteMinder Web Agent. This directory must have execute privileges. To create a CGI-bin directory if the web server is Microsoft’s Internet Information Server, use the Microsoft Management Console. If the web server is Netscape Enterprise Server, modify the obj.conf file to create this directory. The installation program usually places this file into this directory:
SiteMinder Web Agent/Bin/Web/CPW.
It is not necessary that the program actually be called SmCPW.EXE (though for troubleshooting purposes, this name is desirable). You may rename the program as needed; however, include the .exe extension on Windows. The remainder of this document refers to the program as SmCPW.
A response attribute may be required to be passed when posting to SmCPW. This attribute explicitly identifies the user changing the password. With normal Web Agent configuration, this response is unnecessary (before APS version 4, this response was required). If SmCPW issues a message that it cannot identify the user, this response is required. If this response exists, SmCPW uses it, so no disadvantage exists to setting up the response even it is unnecessary.
See SiteMinder documentation for how to set up Response Attributes. The active expression required is as follows:
<@ lib="smaps" func="SMCPW" param="" @>
This is set up as a standard HTTP-Variable type of attribute, though you do not specify an attribute name. You must select Active Expression as the attribute type, then select the Manual Entry page in order to create this Active Response, since there is no variable name.
This attribute is only required on the POST rule for the SmCPW program. The GET rule does not need it.
|
Copyright © 2013 CA.
All rights reserved.
|
|