Advanced Password Services (APS) Guide › Utilities

Utilities

APS includes a number of command line utilities and other tools to help in the configuration, maintenance and testing of APS. This section details the useful utilities. Other useful testing utilities are provided with the APS prerequisites (for example, SmPortalVfy). See the documentation for each subsystem for details of their use.

Every APS utility or tool that takes the LDAP administrator password (the -w option) now allows this password to be supplied in encrypted format. Use APSEncrypt to encrypt these passwords.

Each utility accepts, minimally, a command line switch of -? that can be used to display the utility's command line syntax. Those utilities that require command line options will display their syntax if run without them.

This section contains the following topics:

APSComplexity - Calculate Password Complexity

APSTestSettings - Check APS Configuration

APSEncrypt - Encrypt an Administrator Password

APSMailTest - Test Email Settings

APSPing - Test connectivity

APSVersion - Display Module Version Numbers

APSXlateTest - Test Translation Settings

SmCPW - Load Test Password Changes

APSForcePWChg - Set Force Password Change Flag

SmPortalVfy - Verify SmPortal Configuration

APSComplexity - Calculate Password Complexity

The password complexity algorithm used by APS may seem a little arcane. APS allows the user to fine-tune the scoring system that it uses.

Administrators can set the threshold, using the Complexity setting, that is required of all new passwords. Determining a value for this setting can be difficult, if not arbitrary.

APSComplexity is provided so that administrators can "get a feel" for the scoring mechanism, fine tune it, and to help them determine a proper setting for the required complexity.

APSComplexity is run with a single command line argument, the password to be analyzed. The utility will display the total complexity score and will also display how the score was determined.

APSComplexity is installed onto the SiteMinder BIN directory on a Policy Server and must be run from there (it requires access to the APS.cfg file).

APSTestSettings - Check APS Configuration

Modifying the APS Configuration File can be a daunting configuration task. When setting overrides are involved, the complexity is further increased. Add to that the fact that APS will use the most restrictive setting applicable, even if it is different from the most specific setting for the user. It can be very difficult to determine the exact setting that APS will use for a particular user.

APS is very consistent in how it handles configuration. It is very predictable. But it is easy for APS to wade through potentially hundreds of settings, determining limits, applicability and restrictiveness based on internal rules. It is not so easy for a human administrator.

APSTestSettings is provided to report the current configuration settings. Without a command line argument, APSTestSettings will report the default settings in effect. Output is grouped functionally. Each setting is flagged as to whether that setting supports overrides.

Command line arguments can be used to specify a particular user, in which case APSTestSettings will show the settings that are currently in effect for that user.

APSTestSettings calls into the APS libraries to obtain the settings. It does not use code separate from APS. Thus, barring output differences, APSTestSettings will always report what APS will actually see for a given user.

Command Line Options

APSEncrypt - Encrypt an Administrator Password

To use certain features of APS, specifically the LDAP Rebind and Write back features, the APS Configuration File must contain an LDAP administrator's password. Putting this in the file in clear text may be considered a security problem at some sites.

APS will read the password setting from the file. If the value of the setting is encrypted, APS will decrypt it before use. If the setting is not encrypted, it will be used as the administrator password verbatim.

The APSEncrypt utility will take a password on the command line, encrypt it and output it to the screen. It can then be cut and pasted into the APS Configuration File. Thus, LDAP administrator passwords will not appear in the configuration file in clear text.

Note that such encryption is only supported within the APS Configuration File. It is not supported by command line utilities.

There is no command line utility to decrypt resulting values.

APSMailTest - Test Email Settings

The APSMail library supports a utility called APSMailTest that can be used to test the CA Mail Service's capabilities when talking to your SMTP Mail server.

This utility can also be used to test the formats of your mail files.

APSPing - Test connectivity

APSPing, new with SmPortal 5.0, tests the connectivity between a client and a SiteMinder Policy Server. It is similar to the standard ping utility.

APSPing communicates using standard SiteMinder libraries to a library called APSTransponder, located on a SiteMinder Policy Server.

APSVersion - Display Module Version Numbers

Starting with APS Version 2.2 (and all of its supporting systems), every library and executable has a product and component version number embedded within it.

The APSVersion utility will display the version information for each module name provided on its command line. Wild cards are supported.

APSXlateTest - Test Translation Settings

This utility interactively allows you to test language translation. It is part of the APSXLate package and is documented there.

SmCPW - Load Test Password Changes

Prior to Version 3.0, a utility called SmCPWTest was provided for testing password changes from the command line. Starting in Version 3.0, this functionality has been merged with SmCPW itself.

SmCPW is the CGI interface for user password changes. If run from the command line, it can also do password changes and is useful for testing APS.

SmCPW can detect whether it is running under a Web Server.

If run with no arguments or just language arguments (-L and/or -C), SmCPW will act as it does under a Web Server satisfying a GET action: it will produce the HTML required for the default form (using the language identifiers, if specified).

If invoked with a User Path, old password and new password, it will post the password change through the APS API and display the result (without any HTML wrapped around the resulting message).

The format of the command (when run from the command line) is:

SmCPW <options> <userpath> <oldpassword> <newpassword>

<options> include:

The <userpath> must be in the format LDAP://<server>/User DN for LDAP users, WinNT://<server>/<userid> for Windows NT users and ODBC://<server>/<userid> for ODBC users.

SmCPW uses SmPortal to communicate with the Policy Server. It can be run on any machine where SmPortal is installed and properly configured. Neither it nor SmPortal require a Web Server or SiteMinder Web Agent.

APSForcePWChg - Set Force Password Change Flag

The APSForcePWChg utility allows the setting of the smapsImmediateChange attribute in an LDAP directory for specified users.

This program accepts one or more LDAP Distinguished Names (DN's) and sets the flag for each supplied DN. The program was designed to accept either one DN per line or a standard LDIF file.

Technically, this utility is no longer needed, since the APS Blob no longer exists. However, it is useful for bulk loaders and many sites have tied in user maintenance utilities to set the flag. It is, then, provided for backwards compatibility.

The command line arguments for this utility are as follows. Command line switches are case-sensitive. The space between the command line switch and its argument is optional.

Note the following:

• Continuation lines in the input file (by starting a line with spaces) are not supported, even though they are allowed in LDIF files.
• Leading and trailing spaces are not significant.
• Only one DN per input line is supported.
• If a colon (:) precedes the first equal sign (=) on any given line, an LDIF-style input line is assumed. If this is the case, the line is ignored unless the attribute name (before the colon) is dn (case-insensitive). This allows LDIF files to be used for input or just lists of DNs.
• If an LDIF-style input file is used, only those DN's that start with uid= will be processed. This is so that a full LDIF can be used, even those containing definitions for objects other than users (only users will be processed). If your directory uses an attribute other than uid for users, then LDIF-style input cannot be used.
• This program only supports LDAP directories.

  This utility was originally designed to be used to set the flag for users after a Directory load. That is, when a site bulk loads users into its LDAP directory, the same LDIF file used for the bulk loading can be fed to this utility so that the Force Change password flag can be set.

  At version 2.1 of APS, this utility has been modified so that the bindDN and password passed on the command line are set up for rebinding. This is a special feature of LDAP that allow this utility to support two features:

  • LDAP Referrals
  • LDAP communications breakdowns since the utility was started

  At Version 3.0 of APS, this utility has been modified to allow user DNs to be passed on the command line itself (this is obviously a low-volume solution). If so, APSForcePWChg will not go into an input loop. This is useful when the utility is to be invoked as a subprocess to another program.

SmPortalVfy - Verify SmPortal Configuration

SmPortalVfy is a new utility supplied with SmPortal/SmTransact Version 5.0. It tests the validity of the entire SmPortal.cfg file.

It requires no command line arguments.

It can be run either form the command line or under a web server (it does not require a SiteMinder Web Agent, nor does it need to be protected, though we recommend that it be protected if it will be exposed).