APS is configured using a standard text editor. Configuration settings are stored in a file called APS.cfg. Under Windows NT, this file must be located in the same directory as the SMAPS library (SmAPS.dll, installed under the SiteMinder/Bin directory). Under Solaris, this file is pointed to by an environment variable called APS_SETTINGS. This environment variable points to the file itself, not just the directory containing the file. The configuration file controls all behavior of APS.
Under Solaris, if the APS_SETTINGS environment variable is not set, APS will look for the file at $SMHOME/siteminder/bin/APS.cfg.
If the file does not exist, an error will be logged to the SiteMinder console and default settings will be used. If any parsing errors occur, such errors will be written to a file with the same name as the APS.cfg file, with the date and .LOG appended to the file name. This file will be placed in the same directory with the APS.cfg file. If the process does not have the rights to create this file, no file will be created. If errors are logged to this file, APS will display a warning in the SiteMinder console log identifying that such errors were logged.
The format of the APS configuration file is described, in detail in the chapter APS Configuration File (APS.CFG).
Users may become frustrated attempting to find a new password if they are not presented with all of the criteria that a password must meet ahead of time. It is possible to restrict permissible passwords such that it is extremely difficult or even impossible for users to randomly pick a valid password. For this reason, we do not recommend setting all Advanced Password Service password policy options without care and need.
SmCPW (SmCPW.EXE on Windows) is a CGI program that can be accessed through a Web Server so that end users can request a password change. This program can be installed on any Web-agent protected Web Server. The Web Agent need not be installed on the same Web Server with SmCPW. However, the Web Server upon which SmCPW resides must be protected by a Web Agent. This Web Agent may be plugged in to the local Web Server, may be the Secure Proxy Server or some similar configuration.
SmCPW communicates with the SmAPS library (running on a SiteMinder Policy Server) via the APS API, which uses CA’s SmPortal/SmTransact communications module.
When running under a Web Server, SmCPW runs in two modes: GET and POST, defined by the type of request from the client browser. In GET mode, SmCPW displays a default HTML form for changing the password. In POST mode, SmCPW calls the APS API, passing the data posted by the change password form (either the default form or a custom form). The APS API uses CA’s SmPortal/SmTransact module to communicate with the SmAPS library (running on the SiteMinder Policy Server). SmAPS checks the password and changes it, if allowed. If an error occurs, it will be returned (reversing the same communications path) to SmCPW and a message displayed to the user.
SmCPW can also be run from the command line (not under a Web Server). If run with no arguments (or just switches), SmCPW simulates a GET request from the browser, displaying the default form (command line arguments can be used to specify the language for the default form). Additional command line arguments can be used to simulate a POST operation. This allows a site to automate testing without using a browser.
If a new password is the same as the previous password, or the password is invalid, reused, insecure, or fails to pass APS’s many tests for any other reason, the user is presented with an error message and asked to try a different password. The error message is not a concatenated list of problems; rather, it presents the first encountered problem with the password, such as "New password exceeds maximum length". It is possible that a user will have to try several passwords before finding one that meets all of the criteria.
All text that is displayed by SmCPW is subject to translation using two different APSXlate translation files. SmCPW.lang exists as a file on the Web Server and contains translations for all locally generated messages (including password confirmation) and for text to be displayed on the default form. APS.lang exists on the Policy Server and it contains translations for all messages that can be generated during password validation and update.
By default, SmCPW displays error and confirmation messages in a JavaScript message box (or, for browsers that do not support JavaScript, on a standard HTML page). If the translated message looks like a URL (starts with "http:", "https:", or "/"), SmCPW will redirect the browser to the URL instead of displaying the message.
This URL can have replacement parameters contained within it. SmCPW will process its own argument list as a set of key/value pairs. A target URL is examined for values contained within angle brackets ("<" and ">"). The text between the brackets is used as a key and replaced, along with the angle brackets, with the value associated with the key. Thus, values, including the originally requested URL, or target, can be passed to the page that will display the message.
Specific examples are included later in this section.
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 The APS Configuration File).
SmCPW{.exe}?
[Optional] [&][DaysLeft=<daysleft>] [&][GraceLogins=<grace logins left>] [&][DaysRemaining=<days remaining>] [&][CancelTo=<cancelURL>] [&][Target=<targetURL>] [&][<additional args>]
The .exe component is required on Windows.
If "Optional" is specified, then the default form displayed by SmCPW will have a "Cancel" button. If the user clicks this button, the browser will be 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" will be displayed instead.
DAYSLEFT=<daysleft> may be supplied to indicate how long the password has left before it expires. There are two cases:
Example:
The TARGET=<target URL> argument identifies the page to which the user should be directed upon completion of the password change. The <target URL> 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 angle brackets ("<" and ">"). 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
would be 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 SiteMinder Web Agent protected Web Server. This directory must have execute privileges (under Microsoft’s Internet Information Server, use the Microsoft Management Console, under Netscape Enterprise Server, modify the obj.conf or magnus.conf file to create a CGI-bin directory). The installation program will usually place this file into a directory called
SiteMinder Web Agent/Bin/Web/CPW.
It is not necessary that the program actually be called SmCPW.EXE (though for troubleshooting purposes, it is desirable that it be so named). You may rename the program (maintaining the .EXE extension on Windows) to anything that you desire. For the remainder of this document, the program will be referred to 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 not needed (versions of APS prior to version 4 required this response). If SmCPW complains that it cannot identify the user, then this response will be required. If this response exists, SmCPW will use it, so it does not hurt to have it set up even when it is not needed.
See your 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.
Custom forms can be written for password changes. They can be written in any language that can display an HTML form. The form must POST to SmCPW 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.
Prior to APS version 2.1, custom forms had to pass their query string on to SmCPW during the posting process. Thus, such custom forms had to be written in some server-side scripting language or as a CGI program. Since version 2.1, this is no longer required; custom forms can be written in "vanilla" 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 user may enter password information.
SmCPW need not be used to produce the form. You may 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 text fields called "OldPassword", "NewPassword" and "VerifyPassword". The last two must contain identical values. Set up your form to post its data to SmCPW.EXE (or to whatever you have renamed that file).
An easy way to start is to run SmCPW.EXE through a browser and to select "View Source" from the browser’s menu. This will display the raw HTML used by the form. You can save this HTML into a file and modify it as desired.
As an alternative, SmCPW can be run from the command line with no arguments. In this case, the default HTML can be captured to a file and used.
SmCPW also supports a considerable amount of customization on the default form. It uses the SmCPW.lang file to determine all of the text to be displayed on the form. In addition, some keys exist in the language file that are used to inject arbitrary HTML into the default form at various places in the output.
Forgot (Forgot.EXE on Windows NT) is a CGI program that is accessed from a Web interface to drive the FPS process.
FPS requires many forms to be presented to the user. As supplied by CA, FPS does not include these forms, though sample forms are provided in both ASP and JSP. It is up to the site to create the production forms (though CA’s Professional Services can be contracted to produce these forms for you).
Furthermore, the architecture of FPS requires that these pages exist on the same Web Server as the FPS stub (FORGOT), since cookies are used extensively and they will only be visible to the pages served up from the same Web Server. All such forms must be installed on a web server, visible to the user base (inside or outside the DMZ) and must not be protected by SiteMinder (since unauthenticated users will be accessing these pages).
Note: Many sites use cascading style sheets (CSS) to standardize the look and feel of their forms. If cascading style sheets are to be shared with protected pages, they must be unprotected (or aliases or copies made) so that they will be accessible to unauthenticated users.
If a user is asked to authenticate during FPS operation, it is because either the target page itself or one of its components (graphic, frame or style sheet) is protected.
Note: FPS only works the user through the forgotten password process. It does not provide any mechanism for putting forgotten password questions into the user entry in the User Directory. It is up to the site to provide this mechanism. Delegated Management System (DMS) and CA Identity Manager are highly suited for this process. APS includes sample code to do this with DMS2.
APSAdmin (APSAdmin.EXE on Windows NT) is a CGI program that is accessed from a Web interface to provide help desk access to APS data in the users’ entries.
APSAdmin uses the APSAdmin portion of the APS API. It does not access APS in any other way. All APSAdmin functionality can be duplicated by custom code, if desired.
For full details of all customizations possible and the configuration it requires, please refer to the APSAdmin utility chapter in this manual.
|
Copyright © 2014 CA.
All rights reserved.
|
|