Advanced Password Services (APS) Guide › APS Configuration File › Setting Overrides

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:

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.

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.