Advanced Password Services (APS) Guide › APS Configuration File › Event Redirection

Event Redirection

When events occur during the authentication process, APS can redirect the user to specific pages (URLs). This section contains descriptions of the settings that specify the URLs to redirect users for each event.

During authentication, APS records the fact that the event has occurred and which event it was. It cannot perform the redirection at that time.

In order to actually perform the redirection, additional configuration settings must be created within the Policy Database. This configuration is described in the configuration section of this document.

Two different actions can be taken for each event:

• The user can be redirected to another page (or a message displayed),
• Email can be sent to the user and/or an arbitrary user (administrator)

Various notes apply to redirection when used as an action associated with an event:

Active Expression Parameters

The parameter field for the Active Expressions used for redirection (SmApsRedirect and AZRedirect) can be used for some very powerful functionality.

The parameter field is in the form:

<key>=<value>;<key2>=<value>;...;<default redirect>

All fields are optional and the system works fine without specifying any parameters.

The <default redirect> parameter, if required, must be the last section in the parameter list. It cannot contain an equal sign or a semicolon (it is possible to escape such characters with a backslash "\"). If no redirection is to be performed by APS, this is where the user will be redirected to instead. This is used when you want to use one of the redirect events, but it would conflict with APS.

You can specify as many Key/Value pairs as required. APS will save these values. The character case for keys is ignored. If the same key is specified more than once, only the last value will be used.

Values may contain user attribute names surrounded by curly braces ("{" and "}"). Such attribute names (and the braces) will be replaced by the attribute value from the user's directory entry. If the first part of the value will reference an attribute in this way and a setting override is not to be used, you must specify an override of "{TRUE}" in order not to confuse the APS.cfg parser (so it recognizes the attribute reference and can differentiate it from an override).

Event redirection can be overridden using the standard override syntax. In addition, context macros are also available. The <key> values passed through the Active Expression are used as context macros whose values are the <value> passed for the key. Some other event-specific context macros are also available (discussed with each event definition).

When a redirect must be determined, APS will evaluate all redirects of the correct type in the order in which they appear. The last one that applies will be used.

To override a redirection setting, specify a Key/Value pair after the equal sign, within square brackets, such as:

Failure Redirect={%LANG="EN"}http:/EnglishFailure.htm

If the parameter of the redirect response defined in the Policy were LANG={preferredLanguage}, then there will be a key called LANG with a value of the user's preferred language (from their LDAP entry). If the value from the user's entry were EN (for English), then the LANG key will have a value of EN, thus this setting would be selected (assuming it is not superceded by another setting later).

This is most useful to select redirections based on Realm. APS does not support this directly, but it can easily be performed using this feature by specifying a Key called REALM in each response, with a value appropriate for that realm. Overrides can then be defined in this file for each Realm. Realize that this is not truly tied to the realm, it is only a key supplied as a parameter to the redirect.

For example:

Failure Redirect={%Realm="AppA"} http:/AppA.htm

Will be fired if invoked by an active expression such as the following (presumably defined only in the ApplicationA realm):

<@ lib="smaps" func="SmApsRedirect" param="Realm=AppA" @>

But would not be fired in other realms where the REALM keyword was not set to AppA.

URL Translation

Once a redirection URL has been selected, APS will perform additional translations on that URL. In addition to the keys supplied in the Active Expression parameter, the following Keys will also be defined:

If the user context is defined (the user is authenticated), these keys will be defined as well:

APS will take the resulting URL (or the default one specified in the parameter field) and replace any references to any key with its value. References to keys should be placed in the URL surrounded by angle brackets ("<" and ">"). To continue the example above:

http://www.mysite.com/TargetPage?Language=<LANG>

would be translated to:

http://www.mysite.com/TargetPage?Language=EN

Key names are NOT case-sensitive and values will be URL-encoded (so TARGET will be encoded).

In addition, any text between curly braces ("{" and "}") will be replaced (along with the braces) with equivalent values from the user's directory entry. Note that this processing is only possible if the user has been successfully authenticated. An example might be:

http://www.mysite.com/TargetPage? Language=<LANG>&Name={FirstName}

would translate (for me) to:

http://www.mysite.com/TargetPage? Language=EN&Name=Eric

SmCPW

For some of these redirects, the setting will probably be SmCPW, that component of APS that allows users to change their passwords. SmCPW recognizes many arguments in its URL (as described on page 272), including:

Target=<target>
DaysLeft=<DaysLeft>
Optional

Multiple arguments should be separated by an ampersand ("&"), thus a warning redirect might be:

/CPW/SmCPW.exe?DaysLeft=<DaysLeft>&Target=<Target>

Additional arguments (either from keys or hard-coded) may be supplied. SmCPW will ignore them, but will pass them on to its own target in the same manner.

Failure Redirect

Default: none

Recommended: no

Complexity Level: Intermediate

When the user reaches Max Failures consecutive failures, where should APS send the user? This must be an unprotected page, since the user will not be allowed to login. It is not recommended that this redirect be used (use the mail notification instead), since by using it, your site acknowledges that a valid user id has been discovered and thus you open yourself to a denial of service attack.

Failure Redirect= http://www.yoursite.com/maxfails.htm

Disable Redirect

Default: none

Recommended: no

Complexity Level: Intermediate

If a user is already disabled when a login attempt occurs, APS will send the user to the specified page. This must be an unprotected page, since the user will not be allowed to login. This redirect should not be used for the same reasons as stated for the Failure Redirect setting above.

This redirection supports an additional macro called DisabledReason. This contains the reason code(s) associated with why the user is disabled.

Disable Redirect= http://www.yoursite.com/disabled.htm? Disabled=<DisabledReason>

Inactive Redirect

Default: none

Recommended: Yes

Complexity Level: Intermediate

If a user has not logged in for Max Inactive days (or the number of days specified by smapsAccountExpirationDays), where should APS redirect the user (after disabling him)? This must be an unprotected page, since the user will not be allowed to login.

This redirection is safe to use. In order for this event to occur, the user has supplied a valid user id and password (he just has not done it for too long). Using this setting does not open a security hole.

If the APSExpire utility is utilized, this redirection may never occur (it may occur if the user attempts to log in on the same day as he would expire and APSExpire has not yet run). APSExpire will disable the user in its batch process instead, so this event does not occur. Instead, the Disabled Redirect setting would apply.

Inactive Redirect= http://www.yoursite.com/inactive.htm

Expired Redirect

Default: none

Recommended: Yes

Complexity Level: Intermediate

If a user has not changed his password for Password Expiration (or the value stored in smapsPasswordExpirationDays) plus Expiration Grace days or has used up all available Grace Logins, where should APS redirect the user (after disabling him)? This must be an unprotected page, since the user will not be allowed to login.

This redirection is safe to use. In order for this event to occur, the user has supplied a valid user ID and password (he just has not changed it for too long). Using this setting does not open a security hole.

Expired Redirect= http://www.yoursite.com/expired.htm

Force Change Redirect

Default: none

Recommended: [path]SmCPW[.exe]?Target=<target>

Complexity Level: Basic

If a user is required to change his password immediately because the Force Password Change flag is set, where should APS redirect the user? This should be a protected page (probably the change password page).

This page may also be used if the Expire Change Redirect is needed but not specified.

Force Change Redirect= http://www.yoursite.com/CPW/SmCPW.exe? Target=<target>

Warning Redirect

Default: none

Recommended: [path]SmCPW[.exe]?Target=<target>& DaysLeft=<daysleft>

Complexity Level: Basic

If the user is being warned that his password will expire (starting Expiration Warning days before Password Expiration), where should APS redirect the user? This should be a protected page (probably the change password page).

Warning Redirect= http://www.yoursite.com/CPW/SmCPW.exe? Target=<target>&DaysLeft=<daysleft>

Expire Change Redirect

Default: none

Recommended: [path]SmCPW[.exe]?Target=<target>

Complexity Level: Basic

If a user is required to change his password immediately because his password has expired and he is still in the grace period, where should APS redirect the user? This should be a protected page (probably the change password page).

If this setting is not specified, but needed, the Force Change Redirect will be used.

Expire Change Redirect= http://www.yoursite.com/CPW/SmCPW.exe?
Target=<target>