APS is configured using a standard text editor. Configuration settings are stored in a file called APS.cfg. Under Windows, this file must be located in the same directory as the SmAPS library. Under Solaris, this file is pointed to by the APS_SETTINGS environment variable. This environment variable points to the file itself, not just the directory containing the file.

Under Solaris, if the APS_SETTINGS environment variable is not set, APS will look for the file at $SMHOME/siteminder/bin/APS.cfg.

The configuration file controls all of the behavior of APS and the required formation of passwords during the password change function.

If the file does not exist, an error is logged and default settings will be used. If any parsing errors occur, 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 location as the APS.cfg file. If the process does not have the rights to create this file, no file will be created.

The APSTestSettings utility will display the settings from this file that apply to a specific user (or, if no argument is supplied to APSTestSettings, the general configuration settings). If the file is changed, APSTestSettings can be used to test the new file, since the file will be parsed and any errors encountered will be logged.

Note: The decision to use a flat file for configuration was a deliberate one. In the years of working in these environments, we have discovered that password policies are essentially static, they very rarely change and when they do, they are changed in a development environment, fully verified, then rolled out into production. By using flat files, this rollout and all of the associated change control becomes trivial to implement.

Format

Within the file, all blank lines are ignored and any line beginning with two forward slashes ("//"), a pound sign ("#") or a semicolon (";") is considered a comment. Embedded and trailing comments are not supported.

For the most part, each operational line consists of a keyword (or words) followed by an equal sign, followed by zero or more spaces, followed by the setting for that keyword. This chapter contains a detailed listing of all of the keywords and their expected arguments. In addition, the sample APS.CFG file supplied contains a considerable amount of discussion for each keyword. If discrepancies exist between this document and comments in the file, use the comments in the file.

Keywords are not case-sensitive. The settings for the keywords usually are case-sensitive.

By default, almost all options are disabled in the sample file. Options should be enabled as needed. Options should be set with care, as it is possible to create situations where no password exists that can satisfy all conditions. Even if combinations are possible, you should be careful: complex rules can confuse users.

If the file is modified while APS is running, the changes will apply to the next user accessing the system or changing their password. There is no need to restart SiteMinder services. APS checks the last modification time of the file each time that a user is processed. If the file has changed, it is read in by APS and used for the new user request and for all future requests, until the file is changed.

There is slight performance degradation due to the large number of comments in the configuration file. However, because of file caching, it is only noticeable during startup and when the file actually changes. Thus, we highly recommend that the comments be left intact.

The configuration is intentionally stored in a flat file rather than in some distributed data store. This gives us a much higher degree of configuration flexibility and portability. For example, if the Primary SiteMinder server always accesses a Primary LDAP server, there may be no need for Write Back settings, whereas a Backup SiteMinder Server (that might be accessing a backup LDAP Server) might need to use the Write Backs.

If multiple SiteMinder Policy Servers are used, a copy of this file must exist on all of them. If the same configuration is to be used on all, the site can use one of the many file replication utilities available on the market. Thus, changing the file on one server would cause that change to be replicated to all other servers. CA does not supply, support, or recommend any particular utility to perform this function.

Define Macros

Most settings in the configuration file are site-dependent, not machine- or environment- (DEV, QA, STAGE, PRODUCTION) specific. However, there are a few things in the file that may vary from Policy Server to Policy Server or between environments.

New at Version 4, APS supports define macros. These are simply replacement values that can be defined once, anywhere in the file, then used as many times as necessary, by referencing a name, rather than a value.

To define such a macro, for example, use the following syntax:

define X Y

After this definition, anywhere that <X> appears will be replaced with Y. For example:

define LDAP_SERVER 127.0.0.1
LDAP Writeback Server=<LDAP_SERVER>

In this case, the actual value used for the LDAP write back Server setting will be 127.0.0.1

This is incredibly useful for separating environment-specific settings, reducing the errors which occur when an APS.cfg file is copied from one environment to another (such as DEV to QA to PROD). For example:

define CPW_SERVER myserver.security.com
Failure Redirect=http://<CPW_SERVER>/Failure.htm

Macro names are not case sensitive. If a macro is referenced, but not defined, APS will look into the process environment variables for a match on the macro name. If one is found, its value will be used as the value of the macro. If no matching environment variable is found, the reference is left intact.

Macros are processed during file load. They are not evaluated per user, so there is little performance impact.

Macros take effect only from the point where they are defined forward into the file.

If a macro has the same name (case-insensitive) as a previously defined macro, the new value replaces the old one from that point down.

Define macros can also be used with user classes and overrides (explained in the next section) to make definitions environment independent:

define LDAP_SUFFIX o=dev.Airius.com
@Admin=IsInGroup("cn=Admin,<LDAP_SUFFIX>")

When the file is promoted into QA, only the DEFINE line needs to change.

Comment checking is performed after macro expansion, so the following method can be used to make conditional (not overridden) settings:

define NO_MAIL ##
<NO_MAIL>Server=127.0.0.1

When NO_MAIL is set to a comment character, the setting is turned off. If NO_MAIL has no value (blank), then the mail server setting is valid. A very useful environment-specific setting (don't send email in DEV). Note that if NO MAIL is undefined (does not appear as a macro), an error would result.

External Macro File

Define macros need not be stated in the APS Configuration File. They can also be defined in a separate file called APS-Macros.cfg located on the same directory as the APS.cfg file.

However, the external macro file will not automatically be loaded. It will only be loaded when the Use External Macros keyword is used in the APS.cfg file. Note that the external macro file can be loaded more than once (which might be useful if you want to change a value temporarily). It requires explicit loading in order to maintain backward compatibility.

For example, the APS.cfg file might contain:The external macro file can be extremely useful. It allows a site to define machine-specific settings externally to the APS.CFG file. Thus, as an APS.cfg file is copied between Policy Servers, either from environment to environment (DEV to QA, for example) or within an environment, settings can "adapt" to the proper machine.

@QA_Users=<QA_DEF>

In the DEV and QA environments, the APS-Macros.cfg file might contain:

define QA_DEF IsInGroup("cn=QA,o=Airius.com")

Whereas, in the production environment, the APS-Macros.cfg file might contain:

define QA_DEF FALSE

Another example, used with multiple Policy Servers within the same environment, might be (in the APS.cfg file):

LDAP Writeback Server={<USE_WRITEBACK>}127.0.0.1

On a policy server that directly accesses the master, the APS-Macros.cfg file would contain:

define USE_WRITEBACK TRUE

On a policy server that does not access the master by default, the APS-Macros.cfg file might contain:

define USE_WRITEBACK FALSE

Note that macros can be defined anywhere in this file, but it is most useful (and avoids confusion) if they are defined at the top of the file.

Setting Overrides

Almost all settings can be overridden, meaning that an expression can be supplied with the setting that describes the users to which the setting applies.

Overrides are always defined within curly braces ("{" and "}") and appear immediately after the equal sign for a setting. For example, to provide an override for the Minimum Length setting, use the following:

Minimum Length={<override expression>}5

If the current user satisfies the specified override definition, the setting will be considered for use.

When specifying an override, note that it may not always be used, even if it applies. APS will examine all values for a given setting, using all that apply for the current user. If multiple values apply, including a default value, then the most restrictive value will be used. For example, suppose the following two settings were specified:

Minimum Length=5
Minimum Length={givenname="Eric"} 4

Users with a first name of Eric would have a minimum length of 5, not 4, since both settings apply and 5 is more restrictive than 4.

When multiple string settings might apply, usually the last applicable setting will be used (sometimes something other than the last will be used, as noted in the text describing the specific setting).

Override expressions are logical (boolean) expressions. Expressions can compare a user's attribute value with a constant, test certain functions, test a context macro against a constant or some combination.

Individual expressions may be connected using logical operators. The following logical operators are supported:

NOT or !	Logical NOT
AND or & or &&	Logical AND
OR or \| or \|\|	Logical OR
XOR or ^	Logical Exclusive OR
TRUE	Constant TRUE
FALSE	Constant FALSE

Logical operators are optimized to short-circuit (not evaluate a second operand if the result of the operator is already decided).

The following comparison operators are supported. Note that there are both case-sensitive and case-insensitive versions of each.

=	Case sensitive equality compare
~=	Case insensitive equality compare
>	Case sensitive greater than compare
~>	Case insensitive greater than compare
<	Case sensitive less than compare
~<	Case insensitive less than compare
>=	Case sensitive greater than or equal compare
~>=	Case insensitive greater than or equal compare
<=	Case sensitive less than or equal compare
~<=	Case insensitive less than or equal compare
STARTS_WITH	First operand must start with second (case sensitive)
~STARTS_WITH	First operand must start with second (case insensitive)
ENDS_WITH	First operand must end with second (case sensitive)
~ENDS_WITH	First operand must end with second (case insensitive)
CONTAINS	First operand must contain second (case sensitive)
~CONTAINS	First operand must contain second (case insensitive)

All comparison operators require an (unquoted) attribute name as the first operand and a (quoted) constant for a second operand. Furthermore, the first operand (the attribute) can be qualified by SOME or ALL. SOME indicates that if at least one value of the (assumed multivalued) attribute compares true, the result is true. If ALL is specified, then all values of the (multivalued) attribute must compare true in order for the condition to be true. SOME is the default. For example:

givenname~="Eric"

If givenname is a multivalued attribute, then if any (because SOME is the default) value of the givenname attribute is Eric (case-insensitive), the result is TRUE. This is equivalent to:

SOME:givenname ~= "Eric"

On the other hand,

ALL:givenname ~= "Eric"

would require that all of the values of givenname match Eric (case-insensitive). While this is not a viable example, the following might be:

ALL:givenname ~STARTS_WITH "E"

This, of course, could be further qualified as:

NOT ALL:givenname ~STARTS_WITH "E"

Note that new users have no attribute values at evaluation time, so these compares are essentially useless in those cases. This typically applies to the self-registration process (additionally, APS cannot check the password against user attributes, since the user record does not yet exist). This problem is typically solved by assigning the new user a random password during the registration process and then forcing the user to change their password at first login (when the user is no longer a new user - the user record exists in the directory).

Some "built-in functions" are also supported. Almost all functions take a single constant, quoted argument. Most function calls will work with new users (IsInGroup is an exception, new users cannot be in a group). All functions return TRUE or FALSE.

At("<some DN>") or In("<some DN>")
Above("<some DN>") or Over("<some DN>")
Below("<some DN>") or Under("<some DN>")
IsInGroup("[set the product group or family]")
IsNull("<attribute Name>")
IsInNamespace("<namespace>")
IsInDirectory("<directory id>")
IsNew()
IsLDAP()
IsODBC()
IsInWindows() or IsWin() or IsWinNT()
Self()
AnyBitsSet(<attribute>,<bitmask>)
AllBitsSet(<attribute>,<bitmask>)

The Self function can only be used in the APSAdmin section of the APS.cfg file.

Thus, the following might be useful:

IsInGroup("cn=Administrators,o=Airius.com")

Parentheses can be used to change the order of evaluation. For example:

(IsLDAP() AND IsInGroup("cn=Admin,o=Airius.com"))
OR (IsODBC() AND IsInGroup("Admin"))

Since the evaluator short circuits, ODBC users will never evaluate the LDAP IsInGroup call.

Nothing outside of quotes is case sensitive (attribute names, function names, textual operators, etc.)

User Classes

The evaluator supports user classes as well. A user class can be defined anywhere in the configuration file, using the format:

@classname=<expression>

Such as:

@Administrator=IsInGroup("cn=Admin,o=Airius.com")

User classes can be referenced anywhere in an override, such as:

Minimum Length={@Administrator} 12
Minimum Length={@Administrator AND givenname="Eric"} 14

User class names are not case-sensitive. They are very useful for defining classes of users just once in the file, then referencing the override in many places.

User classes must be defined before they are used. Duplicate definitions are not allowed.

The class definition (like all override expressions) is parsed at load time, but not evaluated until run time.

Context Macros

Context Macros (not to be confused with define macros) can be passed from an Active Expression (in its param field) or exist only within the context of a specific setting. They are typically used to pass REALM or APPLICATION information at run-time.

Context macros can appear anywhere that an attribute name can appear.

Context macro names are prefixed with a percent sign ("%").

For example:

Immediate Change Redirect={@Administrator AND %App~="Main"} SmCPW.exe

A note about "Old Style" overrides

Prior versions of APS (before version 4) supported a different override notation (using square brackets) that only applied to the user's location in an LDAP DIT. This notation is no longer supported and, if used, may cause APS to operate in unexpected ways. Such syntax should be manually converted as soon as possible.

Performance

The evaluator has been highly optimized and is very fast. All results, both intermediate and final, are cached for each user, so that identical clauses will not be re-evaluated. In other words, once a given comparison is made, it will not be made again (regardless of the use of classes), the cached result will be used instead.

While user classes might appear to improve performance, they have very little impact (either way). However, they improve readability of this file and will reduce data entry error, since overrides can be defined for classes, rather than repeating a complex definition.

Testing Expressions

APSTestSettings is a utility provided with APS for testing both the contents of this file (as described above), for testing the lexer (the part of code that breaks up an expression) and the parser (the part of code that evaluates an expression). It can run in 3 modes. See page 270 for the complete description of APSTestSettings and its operation.

File Sections

The APS Configuration File is divided into sections. Each section starts with a single line identifying the name of the section, surrounded by square brackets.

The sections supported in the configuration file are:

[APSAdmin]	Defines behavior of the APSAdmin utility and API
[APSExpire]	Defines job parameters for the APSExpire utility
[Complexity]	Used for tuning password complexity parameters
[Custom]	Settings for the custom extension module SmAPSEx
[Dictionary]	Lists words that are disallowed in passwords
[FPS]	General Forgotten Password Support settings
[FPS-CHANGE]	Defines how FPS allows changes to the user password
[FPS-CONFIRM]	Defines how FPS confirms password changes
[FPS-ERRORS]	Defines how FPS handles errors
[FPS-IDENTIFY]	Defines how FPS identifies users
[FPS-NOMAIL]	Defines how FPS handles mail errors
[FPS-VERIFY]	Defines how FPS verifies user identity
[Logging]	Settings for the custom logging module SmAPSLog
[Mail]	Defines how APS communicates with a mail server
[Mappings]	Maps APS field names to attribute/column names in the underlying directory
[ODBC]	Specifies the SQL queries used to access an ODBC User Directory

There are General settings that must appear before any section in the APS.cfg file. These settings are the most commonly changed and actually control the core functionality of APS.

There are a few (very few) settings that can appear anywhere in the configuration file. All of these were discussed previously in text, but will be presented here for reference as well.

Settings That Can Appear Anywhere

These settings can appear anywhere in the APS configuration file. They affect the processing of the configuration file, not really the behavior of APS itself.

These settings can appear anywhere because they are positional, in that they take effect from the point at which they are defined to the end of the file. Entries defined "above" them in the configuration file are not affected.

Define

Range: n/a

Default: none

Recommended: Yes

Complexity Level: Intermediate

This keyword is used to create define macros as described on page 41.

Define macros are used to create symbolic names for textual strings that can be used, by name, in later parts of the APS Configuration File. The symbol will only be replaced when it appears surrounded by angle brackets ("<" and ">").

This keyword can appear anywhere in the file. Text replacement occurs only after the point of definition. If the same keyword is defined again, its new definition will overwrite any prior definition.

define FPS_SERVERhttp://www.myserver.com/
[FPS-IDENTIFY]
URL=<FPS_SERVER>Identify.jsp

Use External Macros

Range: n/a

Default: no

Recommended: Yes

Complexity Level: Intermediate

Define macros need not be defined in the APS Configuration File. They can also be defined in a separate file called APS-Macros.cfg located on the same directory as the APS.CFG file.

The use of this keyword is described starting on page 42.

This keyword can appear more than once in the file. If so, the external definitions will be reloaded.

@<classname>

Range: n/a

Default: none

Recommended: Yes

Complexity Level: Intermediate

This "keyword" allows the site to define User Classes.

A site may define as many user classes as it requires. User classes may reference other user classes, as long as the referenced classes are already defined (thus you cannot have circular references).

General Settings

Trace

Range: n/a

Default: off

Recommended: Yes

Complexity Level: Basic

If this keyword appears, then tracing is turned on within APS. Traces appear in the Policy Server console log. To turn tracing off, comment out or delete this keyword from the file. This affects tracing of authentication and authorization time processing only. To enable tracing for FPS and SmCPW, use the Trace keyword in the SmPortal.cfg file.

This keyword cannot be overridden per user.

Example:

Trace

Timeout

Range: 0-300

Default: 0

Recommended: No

Complexity Level: Advanced

This setting controls how long to wait for a User Directory to respond to a call. This value is for each call, not overall time. If this time limit is exceeded for a single call, a timeout error will result.

The default is zero (no limit or limit enforced by driver). In general, this setting should be used only with great care, since it may cause timeout failures.

This setting is specified in seconds. The maximum is 300 (5 minutes), but should never be used, since a browser session will time out long before the interaction with the directory server.

If an override is required, it must be a restricted override. That is, it can reference the Directory, but not the user.

This setting is supported for ODBC and LDAP directories only. It does affect LDAP Writeback connections.

Example:

Timeout=30

Poll

Range: 10-1000

Default: 100

Recommended: No

Complexity Level: Advanced

This setting controls how long to sleep between checks to see if an ODBC User Directory call has completed. Lower numbers indicate that the driver should be checked more frequently. This may improve response time for the current user, but will increase overall CPU utilization. Higher numbers will decrease user responsiveness, but will use less CPU.

This setting is specified in thousandths of a second. The minimum value is 10 milliseconds (1/100 second) and the maximum is 1000 milliseconds (1 second). Default is 100 milliseconds (1/10 second).

If an override is required, it must be a restricted override. That is, it can reference the Directory, but not the user.

This setting is supported only for ODBC directories. LDAP directories support the Timeout keyword only.

Example:

Poll=500

LDAP Write Back Information

The write back settings indicate where APS should write back information when writing to the LDAP directory. This is used primarily for when SiteMinder is reading from a replicant (consumer) and APS must write back to a master (producer). Instead of attempting the write to the (by definition: read-only) replicant, which will always fail, APS will always write to the Write Back server instead (it will still read from the replicant).

If you know that you are going to be doing referrals on writebacks (if SiteMinder reads from a replicant), use these settings.

Whenever APS needs to write information to an LDAP Directory, it looks for a writeback setting for the current user. If one exists, APS will perform the write to the writeback server instead of to the original server. When the LDAP Directory is configured as a Producer/Consumer (rather than Primary/Backup), this is much more efficient than writing back to the consumer, failing, then referring the write to the producer.

All write backsettings can be overridden. It is not necessary to use the IsLDAP() function with these overrides, since they will only ever be used for LDAP User Directories.

Be careful when using overrides with these settings, since they each override separately. Make sure that there are no "overlaps" in the overrides, where one setting is overridden separately from the others.

When SiteMinder supports referrals in all cases, these keywords will technically no longer be needed; however, they may still be desirable, since performance may be greatly enhanced (since APS will apply changes directly to the master, rather than "bouncing" all writes off of the replicant).

A list of writable servers can be provided, separated with a space. APS will treat the list as a list of LDAP servers for fail over purposes. All must be writable. In this way, APS supports multi-mastering.

It may be desirabled to load-balance APS writes across multiple masters. APS will not do this automatically, but sites may do it in either of two ways. Note that both methods provide the same level of fault tolerance.

If multiple SiteMinder Policy Servers are running in round-robin mode, vary order of the list of servers specified as Writeback servers on each Policy Server. Each Policy Server will then use the failover list in a different sequence, obtaining somewhat random round-robining. This is easy to implement and requires little tuning.
For better LDAP performance, you can specify multiple writeback settings in each APS.cfg file, using overrides to partition your data. You might, for example, send users whose UID starts with A-M to servers "A", then "B" and all other users to "B", then "A". You might be able to get better performance out of the LDAP servers (due to improved cache utilization), but you may need to do a considerable amount of tuning to make any significant impact.

LDAP Writeback Server

Range: n/a

Default: none

Recommended: no

Complexity Level: Advanced

This setting controls the server to which writebacks will be directed. It can be overridden. To use writebacks, both the Server and a Password must be specified (the DN is not required because it has a default).

LDAP Writeback Server=127.0.0.1
LDAP Writeback Server={IsAt("o=security.com"} 10.24.86.177

LDAP Writeback DN

Range: n/a

Default: cn=Directory Manager

Recommended: cn=Directory Manager

Complexity Level: Advanced

This is the Distinguished Name (DN) of the administrator account to use to log into the writeback server. It is not required to use writebacks, since there is a default.

LDAP Writeback DN=cn=Directory Manager
LDAP Writeback DN={IsAt("o=security.com"}uid=Admin, o= security.com

LDAP Writeback Password

Range: n/a

Default: none

Recommended: no

Complexity Level: Advanced

This is the password to use for binding to the writeback server. If both this setting and a server are supplied, it indicates that writebacks should be used, even if the Writeback DN (above) is not supplied.

The writeback Password can be supplied either in clear text or encrypted. To encrypt the password, use the APSEncrypt utility.

LDAP Writeback Password=[NDSEnc-A]68SExOCvk(MrHfSSY) cuDHfuyG2
LDAP Writeback Password={IsAt("o=security.com"}password

LDAP Writeback Use SSL

Range: n/a

Default: no

Recommended: if needed

Complexity Level: Advanced

If writebacks are used, this setting tells APS that LDAPS (LDAP over SSL) should be used for the writeback connection.

LDAP Writeback Use SSL=true

Other LDAP Settings

LDAP Disabled Groups

Range: n/a

Default: Search Base defined in SiteMinder User Directory

Recommended: no

Complexity Level: Advanced

By default, APS will search for and create (if necessary) disabled groups in the root of the user account's directory. If APS will not have rights to this location, the root is not identified by o=xxx, or your site wishes these groups to appear elsewhere in the directory tree, you can specify their exact location using this keyword. Note that this is the location, not the names of the groups themselves.

This affects only where such groups are created, not where they are searched for. APS will always search the entire search base as defined in the SiteMinder User Directory entry.

This setting can be overridden, but the IsLDAP function is not required, since the setting will only be used for LDAP User Directories.

APS does not create groups for ODBC directories, so this setting does not apply to them.

LDAP Disabled Groups=ou=Groups,o=nds.com

LDAP Blob

Range: n/a

Default: audio

Recommended: audio

Complexity Level: Advanced (upgraded sites only)

Prior to APS Version 3.0, APS maintained user information for LDAP users in an attribute called the APS Blob. This keyword allowed the site to specify the attribute in which to store this information. However, at Version 3.0, the APS blob no longer exists.

This keyword exists only for backwards compatibility. Users converting from pre-version-3.0 APS should contact CA for the proper data conversion tool.

If this site did not upgrade from a prior version of APS or it is no longer maintaining old Blob information, then this keyword is not needed and should not be specified.

Check LDAP Password Existence

Range: n/a

Default: off

Recommended: off

Complexity Level: Advanced

This keyword will cause APS to check for the existence of an LDAP password before expiring it or requiring it to be changed. It should be used at sites where some users will be accessing the system using authentication schemes that do not use passwords (and thus the user record may or may not actually have a password).

Note that this was a new feature at version 2.0 and requires that the Directory Manager credentials be entered into the SiteMinder policy GUI for each LDAP directory (it only impacts LDAP User Directories). It may also impact performance.

This functionality requires that the existing password be readable from the directory (at least the encrypted/hashed value). For iPlanet Directories, this requires that the administrator be cn=Directory Manager. Other implementations of LDAP servers may have different requirements. Some implemented, most notably Microsoft Active Directory, do not allow this information to be read in any case and thus this functionality is not supported in those environments.

Check LDAP Password Existence

LDAP Password Attribute

Range: n/a

Default: userPassword

Recommended: no

Complexity Level: Advanced (Deprecated)

This keyword causes APS to use an attribute other than userPassword as the password attribute within an LDAP directory. The standard LDAP schemas use userPassword; however, some may use a different attribute. Use this keyword to specify a different attribute.

This setting may be overridden (but that would be unusual).

At APS Version 4.0, this setting is deprecated (a warning will be output to the log, if the keyword is encountered). If something other than userPassword should be used, specify it in the new Mappings section.

LDAP Password Attribute=userPassword

Use Internal Disables

Range: n/a

Default: off

Recommended: true

Complexity Level: Advanced

If this setting is enabled, when APS disables an LDAP user account (it only applies to LDAP User Directories), it will NOT put the user account into a Disabled group. Instead, it will set the Disable Until date to FOREVER, effectively disabling the user account forever.

This feature was new at APS Version 3.0. It provides a considerable performance improvement for very large sites, in that large groups are not used for disabling user accounts. However, it is a change to existing functionality and may impact user administration tools (the tools used to reset the user).

In addition, if this setting is enabled, a user account can only be disabled for a single reason at a time. This may impact how some of the security policies at your site are to be architected.

ODBC User Directories always use internal disables (Disabled groups are honored, but APS will never create one or put a user account into one).

Use Internal Disables

Ignore

Range: n/a

Default: off

Recommended: no

Complexity Level: Advanced

APS functionality is accessed in many ways. For the two secured client mechanisms (Change Password Interface and Help Desk Interface), access is controlled by SiteMinder Policies. FPS is configured separately to allow or disallow access for particular users. The APSAPI is accessed by the applications that call it and thus access can be controlled using any of a variety of methods.

However, APS is involved with all SiteMinder authentications. SiteMinder calls APS, regardless of User Directory or the success or failure of an authentication.

The Ignore keyword can be used to tell APS when to ignore a user during the authentication process. While this is rarely used, it does have a purpose. For example, when rolling out a new User Directory, it can be desirable to ignore all of the users in that new directory until the schema is set up and the users are initialized.

The value of this setting is either true or false. However, this setting is almost always overridden, defining the user cases where the user should be ignored.

Ignore={IsODBC()} true

Disable

Range: n/a

Default: off

Recommended: no

Complexity Level: Advanced

APS has a wealth of mechanisms for enabling/disabling user accounts, but they are mostly geared for APS' own use. Sometimes (especially in legacy directories), other mechanisms are used to disable accounts.

This setting allows sites to specify other conditions under which APS is to consider that an account is disabled. The override of the setting specifies the condition; the value of the setting is used as the "Disabled Reason" passing such codes to redirects or email.

APS will never actually disable an account with this mechanism. However, if the override is true for a particular account, that user will not be allowed to log into the system.

Disable={employeeStatus="Terminated"} Term
Disable={customerStatus="IN LEGAL"} Litigation

Password Content Settings

These settings allow the administrator to control what a new password must look like. For example, a policy could require passwords to contain all numbers, at least three letters, or at least two numbers and at least four punctuation characters.

Use caution with these settings, as it is possible to set requirements that no passwords could ever satisfy. For instance, should the Maximum Password Length field be set to 8 characters, the Letters field set to 6 and the Digits field set to 6, all passwords would implicitly be required to contain at least 12 characters (6 letters and 6 digits), but no passwords this length are allowed. Thus, all passwords would be rejected.

Because of setting overrides, APS cannot detect such impossible combinations when the configuration file is read. When a password is validated, however, APS will determine if the combination of settings that apply to that user is possible. If it is not, an error is displayed to the user. While APS can detect many such combinations (at run-time), it may not be able to detect all of them.

All settings can be overridden.

These settings are used only when the user changes their password, they may not impact an Administrator changing user passwords except as provided by APSAdmin (see page 210) or if the APS API is called.

Passwords can be tested using the IsMyPasswordValid and IsPasswordValid functions in the APS Application Programming Interface (API).

Password Length

Minimum Length

Range: 4-32 characters

Default: 4

Recommended: 6-8

Complexity Level: Basic

Controls the minimum length allowed for passwords. Any setting below four will be ignored. The minimum may not exceed the maximum. Attempting to set this value outside of the allowed range will cause parsing error and the setting will be ignored.

Minimum Length=4
Minimum Length={@Employees}6

Maximum Length

Range: 4-32 characters

Default: 32

Recommended: 32

Complexity Level: Basic

Controls the maximum required length of a password. Any setting above 32 will be ignored and a parsing error will be logged. The Minimum Length must be less than or equal to the maximum length.

Maximum Length=20

"~" (tilde)	"@" (at)	"#" (number)
"$" (dollar)	"%" (percent)	"^" (circumflex)
"&" (ampersand)	"*" (asterisk)	"(" (open parenthesis)
")"(close parenthesis)	"_" (underscore)	"-" (hyphen)
"+" (plus)	"=" (equals)	"{" (open brace)
"}" (close brace)	"[" (open bracket)	"]" (close bracket)
"<" (less than)	">" (greater than)	"/" (virgule)
"\" (back slash)	"\|" (vertical bar)

and all extended ASCII characters, including diacritical marks. Note that some browsers do not support the entry of extended ASCII characters and some LDAP directories do not support them as part of an LDAP attribute.

Minimum Symbols=1
Minimum Symbols={@Partners} 2

Minimum Other

Range: 0-32 characters

Default: 0

Recommended: 1-2

Complexity Level: Intermediate

This setting requires that the password contain a specified minimum number of non-alphanumeric characters. This includes punctuation marks and other symbols located on the keyboard.

Similar to the Minimum Alphanumeric field above, a given character can satisfy this requirement in addition to "Punctuation" or "Symbols".

Minimum Other=1

Combinations of Character Types

Using the above settings, a site can require certain combinations. However, the use of those settings is fairly inflexible, in that a new password must satisfy all of those settings.

APS can allow a site to specify a series of settings, then require that a new password satisfy a minimum number of them.

The easiest way to think of this is as a "point system". The site specifies the conditions required to get each "point", then the minimum number of "points" that a new password must have.

The Combination Xxxx settings (below) specify the conditions required to earn a "point". The Minimum Combinations setting tells APS how many points are required by new passwords.

For example, if a site wants to require an uppercase letter, a lowercase letter, a digit, and a punctuation mark, they would use the following settings:

Minimum Uppercase=1
Minimum Lowercase=1
Minimum Digits=1
Minimum Punctuation=1

However, if they only wanted to require any three of the four (instead of requiring all four), a site would use:

Combination Uppercase=1
Combination Lowercase=1
Combination Digits=1
Combination Punctuation=1
Minimum Combinations=3

APS will log a warning to the SiteMinder console log if:

One or more Combination Xxxx Settings is in effect, but there is no Minimum Combinations setting.
There are not enough Combination Xxxx settings defined to satisfy the Minimum Combinations in effect.

Combination Letters

Range: 0-32 characters

Default: 0

Recommended: 0

Complexity Level: Advanced

This setting defines the number of letters (upper- and lower-case) needed to satisfy one of the possible Minimum Combinations of character types required in the password.

Combination Letters=1

Combination Uppercase

Range: 0-32 characters

Default: 0

Recommended: 0

Complexity Level: Advanced

This setting defines the number of uppercase letters needed to satisfy one of the possible Minimum Combinations of character types required in the password. Care should be taken in non-standard character set environments, since APS detection of upper case letters only applies to standard ASCII letters.

Combination Uppercase=1

Combination Lowercase

Range: 0-32 characters

Default: 0

Recommended: 0

Complexity Level: Advanced

This setting defines the number of lowercase letters needed to satisfy one of the possible Minimum Combinations of character types required in the password. Care should be taken in non-standard character set environments, since APS detection of lower case letters only applies to standard ASCII letters.

Combination Lowercase=2

Combination Digits

Range: 0-32 characters

Default: 0

Recommended: 0

Complexity Level: Advanced

This setting defines the number of numeric digits ("0" to "9") needed to satisfy one of the possible Minimum Combinations of character types required in the password.

Combination Digits=1

Combination Alphanumeric

Range: 0-32 characters

Default: 0

Recommended: 0

Complexity Level: Advanced

This setting defines the number of alphanumeric characters ("A"-"Z" or "0"-"9") needed to satisfy one of the possible Minimum Combinations of character types required in the password. If this setting is used along with one of the settings above, characters can satisfy both requirements. For example, if Digits is four and this setting is four, the password 1234 satisfies both requirements.

Combination Alphanumeric=1

Combination Punctuation

Range: 0-32 characters

Default: 0

Recommended: 0

Complexity Level: Advanced

This setting requires that the password contain a certain minimum number of punctuation marks in order to satisfy one of the Minimum Combinations of character types required in the password. These can be periods, commas, exclamation marks, etc.

Combination Punctuation=1

Combination Symbols

Range: 0-32 characters

Default: 0

Recommended: 0

Complexity Level: Advanced

This setting requires that the password contain a certain minimum number of symbol characters in order to satisfy one of the character types required by the Minimum Combinations setting. Symbol characters are defined within APS as the characters:

"~" (tilde)	"@" (at)	"#" (number)
"$" (dollar)	"%" (percent)	"^" (circumflex)
"&" (ampersand)	"*" (asterisk)	"(" (open parenthesis)
")"(close parenthesis)	"_" (underscore)	"-" (hyphen)
"+" (plus)	"=" (equals)	"{" (open brace)
"}" (close brace)	"[" (open bracket)	"]" (close bracket)
"<" (less than)	">" (greater than)	"/" (virgule)
"\" (back slash)	"\|" (vertical bar)

Combination Symbols=1

Combination Other

Range: 0-32 characters

Default: 0

Recommended: 0

Complexity Level: Advanced

This specified that the password contain a specified minimum number of non-alphanumeric characters in order to satisfy one of the character types required by the Minimum Combinations setting. This includes punctuation marks and other symbols located on the keyboard.

Similar to the Combination Alphanumeric field above, a given character can satisfy this requirement in addition to "Punctuation" or "Symbols".

Combination Other=1

Minimum Combinations

Range: 0-7 types

Default: 0

Recommended: 0

Complexity Level: Advanced

This setting tells how many different character types must be represented in the new password. In order for a given character type to be counted, one of the Combination Xxx settings (above) must be satisfied.

If any Combination Xxx setting is not zero and this value is not set (or zero), a warning will be issued in the SiteMinder Authentication Log.

If there are not enough Combination Xxx settings defined to possibly satisfy this setting, then this setting will be ignored and a warning will be logged to the SiteMinder Authentication Log.

Minimum Combinations=3

Password Reuse

The password reuse policy determines when and whether previously used passwords may be reused by the same user. These fields allow an administrator to dictate the minimum number of passwords a user may use in a password cycle. If both values are set, APS uses the higher of the two. In other words, if the settings are a count of 12 and a delay of 365 days, the user may not reuse passwords used in the last year. After a year, if only six passwords have been used, another six would have to be used before the user can go back to the first password.

Values are checked both forwards and backwards, and are not case-sensitive. To turn password reuse checking off, set both values to zero or do not put the keywords into the file (comment them out).

APS will always keep the larger of the Count or one year, regardless of these settings. This is so that these settings can be turned on later without repercussions.

There is an internal restriction on the length of the password history. APS will keep a maximum of only 24K of information (dates and values, encrypted). Thus, programmatic password changers (that might be used for load/volume testing) might be able to re-use a password before these restrictions are satisfied. Only an automated password changer can change a password frequently enough. The password history has duplicate compression, so changing it and changing it back programmatically will not overly enlarge the history.

APS cannot limit users to changing their password once per day. However, the purpose of such a limitation is to prevent users from setting a new password, then setting it back immediately. To accomplish the same purpose, set Reuse Delay to 1. The user can then change their password as many times as they want, but will not be able to set it back for 1 day. See page 67 for a further discussion of this feature.

Reuse Count

Range: 0-500

Default: 0

Recommended: 12

Complexity Level: Intermediate

This controls how many passwords must be used before they can be reused.

Reuse Count=12
Reuse Count={@Customers} 500

Not supported on Windows NT Domain User Directories.

Reuse Delay

Range: 0-3650

Default: 0

Recommended: 365

Complexity Level: Intermediate

Controls how much time must elapse before a password can be reused.

Note that there is no need for a setting limiting how often a user may change their password. If this setting is set to one, then the user may change their password as many times as they want, but won't be able to reuse a password for 24 hours.

Reuse Delay=1
Reuse Delay={@Employees} 365

Not supported on Windows NT Domain User Directories.

Change Required

These settings are used to require that the user change a certain amount of his password each time that it is changed. Thus, the user can be prevented from changing their password from ABCD1 to ABCD2 if you wish.

There are two settings here. To turn off this checking, set Percentage to zero or comment it out.

Percentage checking takes two forms:

If Percentage Sequencing is OFF (not specified), then the percentage checking is on overall character counts. APS counts the number of each character and the new password cannot share Percentage percent of common characters. 100% could make life difficult for users.
If Percentage Sequencing is ON (specified), then the percentage checking is on a character by character basis. Percentage percent of each character position must change. This does not detect a change between BASEBALL12 and 12BASEBALL.

Percentage

Range: 0-100

Default: 0

Recommended: 0

Complexity Level: Advanced

This setting determines the percentage of the characters within a new password that must be different from the last one. A setting of 100% would require that all characters be different from one password to the next change.

Percentage=0
Percentage={@Customers} 50

Percentage Sequencing

Range: Yes or No

Default: No

Recommended: Yes

Complexity Level: Advanced

If this option is selected, the actual position of the characters in the new password is used when Password Services determines the actual percentage difference.

Percentage Sequencing

Restricting Words from the User's Profile

These settings, along with the password dictionary (see Dictionary keyword), control what sequences are not allowed in a password.

Attribute Match Maximum

Range: 0-32 characters

Default: 0

Recommended: 4

Complexity Level: Intermediate

Probably the worst passwords are those that are based in whole or in part on personal information about the user, such as their phone number or zip code. This setting controls the minimum sequence length checked by APS against attributes in the user's Directory entry.

If this value were set to four, the user could not include, for example, the last four digits of their phone number in a password.

You can turn this checking off by setting it to zero or commenting it out.

Any value less than 4 can be troublesome to your users.

For LDAP directories, organizational Units and other containers above the user are not checked. However, the user's DN *is* checked. For LDAP users, the objectClass attribute is automatically ignored.

This setting is used for both LDAP and ODBC directories. It is not supported for Windows NT User Directories.

Prior to Version 4.0, this setting was called "LDAP Attribute Match Maximum". At Version 4.0, it was changed to reflect support for ODBC directories. If the older name is found by APS, its value will be used, but a warning will be issued to the APS log.

Attribute Match Maximum=4

Parse Attributes

Range: n/a

Default: none

Recommended: cn (for LDAP), FullName (or equivalent for ODBC)

Complexity Level: Intermediate

When APS checks passwords against user attributes, this keyword specifies that certain attributes should be parsed. When parsing, each "word" in the attribute value greater than two characters in length will be matched against the requested password (it is not subject to the Match Maximum above).

No attributes will be checked at all if the match maximum is zero.

Parsing is the process of breaking up the value into words (or tokens). Words are considered any sequence of consecutive letters or numbers.

All attributes for a given setting must be placed on the same line, separated by commas.

Prior to Version 4.0, this setting was called "Parse LDAP Attributes". At Version 4.0, it was changed to reflect support for ODBC directories. If the older name is found by APS, its value will be used, but a warning will be issued to the APS log.

Parse Attributes=cn,title
Parse Attributes={IsLDAP()} cn
Parse Attributes={IsODBC()} FullName

Exclude Attributes

Range: n/a

Default: none

Recommended: none

Complexity Level: Intermediate

This keyword specifies the names of attributes that are to be excluded from all matching (parsed or matched). Regardless of this setting, the LDAP attribute objectclass will always be excluded.

All attributes for a given setting must be placed on the same line, separated by commas.

If an attribute is specified as both excluded and parsed, it will be excluded.

Prior to Version 4.0, this setting was called "Exclude LDAP Attributes". At Version 4.0, it was changed to reflect support for ODBC directories. If the older name is found by APS, its value will be used, but a warning will be issued to the APS log.

Exclude Attributes=uid,description
Exclude Attributes={IsLDAP()} uid

Run-time Password Checking

These settings are used during the Authentication process to determine if the user can log in or if APS must force the user to do or see something.

Range: Yes or NoReset Password

Default: No

Recommended: No

Complexity Level: Basic

SiteMinder may not be the only application that uses an LDAP directory for authentication. APS can obfuscate the user's password when it disables an LDAP user account. This prevents a disabled LDAP user account from using any application, not just SiteMinder protected ones. This means that when the account is to be enabled, not only must he be removed from the disabled group, but the password must be reset as well.

This also means that the administrator who resets the user's account will know the password after it is reset, however. By removing this setting, the administrator needs only to enable the account to allow authentication; the password will remain intact. Note that the administrator cannot tell the user what the password was, so it is assumed that the user really does know his original password.

The default is do not reset passwords.

Prior to APS Version 3.0, there were implications to turning off this setting. These implications no longer exist.

This setting applies to LDAP directories only.

Reset Password

Auto Force Change

Range: Yes or No

Default: No

Recommended: Yes

Complexity Level: Intermediate

Starting with Version 3.0, APS can detect if an LDAP (or ODBC at Version 4.0) user's password was changed using an interface other than an APS interface. If this setting is enabled, then if the password has been changed externally, the user will be required to change their password upon their next login.

This is useful for Help Desk applications. For Administrator Password Reset, they need only change the user's password. Once done, and this setting is enabled, the user will automatically be forced to change their password.

To enable this capability for accounts stored in an ODBC directory, the query Set Password Checksum and the query Test Password Checksum must be defined and implemented.

For LDAP implementations, this functionality requires that the underlying LDAP server allow APS to read back the user password attribute in a consistent manner (usually hashed or encrypted). For iPlanet LDAP Directories, this can only be done if the administrator is cn=Directory Manager. For some LDAP implementations, most notably Microsoft Active Directory, there is no way to read this information.

Auto Force Change

Reset FPS Lockout

Range: Yes or No

Default: No

Recommended: Yes

Complexity Level: Basic

When a user successfully authenticates and this setting is enabled, any FPS Lockout Counter will be reset to zero.

Reset FPS Lockout

Failure Tracking

Max Failures

Range: 0 or 3-9

Default: 0

Recommended: 5 or 9

Complexity Level: Basic

Password cracking programs attempt to log into accounts by trying various combinations of passwords until one works. A counter to this kind of attack is to disable a user account after a specific number of invalid passwords have been entered consecutively.

This setting tells APS how many consecutive failed passwords must be supplied before an account is disabled.

APS keeps this counter in memory and stores it in a user's LDAP or ODBC entry (Windows users are kept in memory only). The value stored for a user contains a date/time (in GMT) in addition to the actual number of failures. Whenever APS needs the count for a user, it examines the in-memory counter and any value read from disk and uses the one tagged with the latest date/time. This is so that APS can continue to support Max Failures lockout even if a primary LDAP server is unavailable. Note that user accounts cannot be disabled in this case, but will be locked out in memory anyway.

Each server also keeps a date/time stamp on each counter in memory. If there has been no activity for a particular user after a specified time, the counter is cleared. This timeout value is configurable.

This setting should not be confused with the retry count supported by SiteMinder's Form Login capability or with the retry count supported by most browsers. Those retry counts control how many attempts can be made in a single session before the user must either shut down the browser or reselect the URL. This has no impact on the user's entry in the directory. Password cracking programs understand this capability and can shut down, then restart, browsers as required.

The Failure Count setting should usually be higher than any retry count (the Form Login retry count is configurable; most browsers use a value of 3 and cannot be changed). This allows a user a chance to realize that they have forgotten their password before being locked out by APS. Only a determined user (or a password cracker) would continue to make attempts and thus cause the user record to become disabled.

Further discussion of this issue is described in the section entitled Special Case: Three Strikes, You're Out.

The Max Failures setting must be used with great care when using complex LDAP or multiple directories. To understand why, you must understand how SiteMinder locates users in its directories:

SiteMinder usually receives an unqualified user ID. It does not know which directory the user is stored in, nor where, for hierarchical (LDAP) directories, the user exists within the directory. For example, a site might have three different users called JSMITH, one in the NT domain, and two in LDAP as uid=JSMITH,ou=employees,o=Airius.com and uid=JSMITH,ou=customers,o=Airius.com. SiteMinder only receives the id JSMITH and a password.

SiteMinder searches through its directories looking for a match to the supplied user id. When a match is found, the server attempts to log into (bind to) that account using the supplied password. If the password matches, then it has found the correct user, otherwise it continues its search to the next match on the user id.

If no userid is found with the supplied password, the authentication request is denied.

Now consider how APS works. Each time that a user entry is found, SiteMinder notifies APS and tells it whether the entry was authenticated or not. If authenticated, APS resets any counter associated with the name and checks for to see if the account is disabled, etc.

However, if the authentication for this entry has failed, APS increments the failure count for the entry. If the count exceeds this setting, the user account is disabled and the specified actions (mail, redirection) take place.

This can cause real problems when multiple accounts exist with the same id. In our above example, each time that JSMITH logs in, if it is the third JSMITH found, then the first two will each have their counts incremented and, possibly, be inadvertently disabled.

Consider also the case where one of the JSMITHs has forgotten her password. After three attempts, all three JSMITH accounts will be disabled. This is probably not what an administrator wants, but is the action that APS must take. A cracker program in this case is more likely to succeed, since there are three passwords that might work instead of just one. Also consider that APS does not know which instance of that user actually forgot their password.

Keep these issues in mind when using this setting. If duplicate user ids are possible in your directories, it might not be a good idea to use this setting or it might be a good idea to set this to a higher value.

Max Failures=5

Max Failures On Change

Range: 0 or 3-9

Default: 0

Recommended: 3

Complexity Level: Basic

This setting controls how many unsuccessful attempts to change the password are allowed (unsuccessful because the old password is not correct). If this setting is not specified, the Max Failures setting above will be used.

Note that these two settings use the same counter, but set different thresholds for failure.

Max Failures on Change=5

Failure Count Timeout

Range: 0 or 5-30 minutes

Default: 0

Recommended: 5

Complexity Level: Intermediate

If an account is disabled because of a failure count, this setting determines how long the user account will be disabled (if Auto Reset Failure Count, below, is enabled). If the user does not attempt to login for this amount of time, the user will be allowed to login. If the user is disabled (Auto Reset is off), he remains disabled. If not set and Auto Reset Failure Count is enabled, this value will be internally set to 5 minutes. This setting is in minutes. This value will be ignored if it is less than 5 minutes.

This setting must be larger than the Failure Count Retention setting below. This number should be set higher than 30 minutes only with great care.

If a user attempts to login within the period, regardless of success or failure, the time period will restart. Thus, it is impossible for a programmatic password cracker to break a password, even if this setting is as low as 5, since 5 minutes must pass between attempts (to test one million passwords would take approximately 9.5 years.

Failure Count Timeout=10

Auto Reset Failure Count

Range: Yes or No

Default: No

Recommended: Yes

Complexity Level: Basic

If this setting is specified, users will not be permanently disabled when they reach the failure count (Max Failures), but will not be allowed to login until the timeout (specified by Failure Count Timeout above) occurs. Any attempt to login (good password or bad) will reset the timer. This feature is off by default. If the keyword appears, then the feature is turned on.

Auto Reset Failure Count

Failure Count Retention

Range: 0 or 5-30 minutes

Default: 0

Recommended: 5

Complexity Level: Advanced

APS keeps track of the failure count for each user both in memory and on disk (for ODBC and LDAP users). This setting tells APS how long to remember these counts. This is different than the Failure Count Timeout setting (above) that controls how long an account will be disabled before automatically re-enabling it.

If no failed attempts occur within this period, APS will reset the counter to zero.

This setting must be lower than (or equal to) the Failure Count Timeout setting above. This number should be set higher than 30 minutes only with great care.

If a user fails a login attempt within the period the time period will restart. Thus, it is impossible for a programmatic password cracker to break a password, even if this setting is as low as 5, since 5 minutes must pass between attempts (to test one million passwords would take approximately 9.5 years.

If this setting is less than 5 or not set, APS will use 5 minutes.

Failure Count Retention=10

APS Configuration File (APS.CFG)

Overview

Format

Define Macros

External Macro File

Setting Overrides

User Classes

Context Macros

A note about "Old Style" overrides

Performance

Testing Expressions

File Sections

Settings That Can Appear Anywhere

Define

Use External Macros

@<classname>

General Settings

Trace

Timeout

Poll

LDAP Write Back Information

LDAP Writeback Server

LDAP Writeback DN

LDAP Writeback Password

LDAP Writeback Use SSL

Other LDAP Settings

LDAP Disabled Groups

LDAP Blob

Check LDAP Password Existence

LDAP Password Attribute

Use Internal Disables

Ignore

Disable

Password Content Settings

Password Length

Minimum Length

Maximum Length

Required Content

Minimum Letters

Minimum Uppercase

Minimum Lowercase

Minimum Digits

Minimum Alphanumeric

Minimum Punctuation

Minimum Symbols

Minimum Other

Combinations of Character Types

Combination Letters

Combination Uppercase

Combination Lowercase

Combination Digits

Combination Alphanumeric

Combination Punctuation

Combination Symbols

Combination Other

Minimum Combinations

Other Content Requirements

Maximum Repeat

Complexity

Force Case

Match

NoMatch

Allowed Characters

Disallowed Characters

Password Reuse

Reuse Count

Reuse Delay

Change Required

Percentage

Percentage Sequencing

Restricting Words from the User's Profile

Attribute Match Maximum

Parse Attributes

Exclude Attributes

Run-time Password Checking

Auto Force Change

Reset FPS Lockout

Failure Tracking

Max Failures

Max Failures On Change