Advanced Password Services (APS) Guide › Daily Processing (APSExpire)

Daily Processing (APSExpire)

This section contains the following topics:

APSExpire

APSExpire is a command line utility that can be run as an AT process on Windows or a cron job on Unix. This means that the execution of APSExpire will take place on a timed, periodic basis. APSExpire examines users to determine if any of the following events applies:

The user is not initialized (smapsNextAction is not set).
A user's password will expire within a number of days.
A user's password has expired, but a grace period or grace logins remain.
A user's password has expired, no grace period or grace logins remain and the user record will be disabled.
A user's account has remained inactive for too long and will be disabled shortly.
A user's account has remained inactive for too long and will be disabled now.
A user's account is eligible for purging (deletion).

Each execution of APSExpire processes a single User Directory or part of a User Directory, defined as a job in a special APSExpire section of the APS Configuration file. (See Chapter APS Configuration File (APS.CFG) for options on how to define these processing jobs).

When executed, APSExpire will search the specified directory for users who either have a blank smapsNextAction or a value for smapsNextAction that is prior to the current date and time. For each user found, APSExpire determines what actually must be done for that user.

There will be occasions where no action should be taken for the user. When this occurs, a new value for smapsNextAction will be calculated, the user record modified, and APSExpire will continue to the next user entry.

The key to APSExpire is the value of smapsNextAction. APSExpire will only process those user records with a value of before right now or blank. If the smapsNextAction attribute for a user is wrong for any reason, APSExpire will "pick up" the user record at the wrong time. If the date is too early, little will happen, since a new date will be calculated and stored back, essentially correcting itself.

If the date is too late, APSExpire will not process the record until the later date. This may cause the user record to not be processed in a timely manner.

Note that all of the "real time" functionality (expiring passwords and user accounts) can also take place in "Just In Time" mode. That is, if one of these events is detected during user login, APS will take action immediately. Thus, if the Next Action date is not correct, it only affects the asynchronous action of APS, it does not create a security hole; the event will be processed the next time that the user logs in or when the Action Date comes up.

Every time APS handles a user's record, it recalculates smapsNextAction, based on the current settings in APS.cfg and other dates in the user's record (such as the last login date). APS figures out the next thing that has to be done for the user and saves the date of that event.

Sometimes, during normal processing, conditions change that impact this Next Action date. This could be for three different reasons:

The user record is modified outside of APS, usually by user maintenance applications.
The recommended way to handle this is to blank out the smapsNextAction field for the user. The next time that APSExpire runs for that directory, a new value will be calculated.
A setting in APS.cfg has changed. This means that the settings used for a calculation have changed and some or all users need to have the date recalculated.
Depending on the change, the amount of work in this case can be different. If the change causes dates to be moved farther into the future (such as Password Expiration changes from 60 to 90), a site does not have to do anything, since, after 60 days, all of the users with invalid dates will be examined, a new date calculated and then stored. The data will clean itself up.

However, if the date moves closer to today (such as Password Expiration changes from 90 to 60), there will be user records with a date too far into the future. A site can take one of two actions:
- Do nothing. Existing users will not be processed until the date shows up and there will be inconsistencies, but the data will eventually clean itself up.
- Run APSExpire with the -A option to process all users. APSExpire will recalculate the next action date for all users defined in the processing job.
Several settings exist within APS.cfg, each with a different override. Something about a user's record changes such that a different override applies to the record. This is essentially the same as point 1 above. However, the case may not be as obvious because the override may be based on conditions entirely independent of APS variables.

Sites will need to examine these cases and blank out smapsNextAction if such a change is made to a record.

APSExpire Event Log

APSExpire keeps a log of events that it detects. The location of this log is controlled by APSExpire command line parameters (if the location is not specified, APSExpire writes the log to the screen).

Log entries are formatted specifically so that they can be processed by standard desktop tools, such as Microsoft Excel or Seagate Crystal Reports. The logs conform to a file format called Comma Delimited Format (CDF). This format requires that each field be separated from others using a comma, each record terminated by a carriage return and linefeed, and string fields should be quoted.

Each entry in the log appears as:

<Event>, <As Of Date>, <User Path>

The event is the event that APSExpire detected. The As Of Date is the date (and time) at which the event occurred. This may not be the same as the current date (if APSExpire has not run for a period of time). The User Path identifies the user for whom the event was detected.

By default, APSExpire also outputs headers for each column. This is standard for a CDF file. These headers can be suppressed using command line options.

Event Processing

APSExpire is only concerned with seven conditions (Events) that affect user records. The events and the action taken by APSExpire are described in this section.

In all cases, APSExpire will calculate a new value of smapsNextAction and save it back to the user record.

If no action is required for a user record, smapsNextAction will be set to 99999999999999Z CYCLE COMPLETE so that APSExpire will no longer process the record.

The following conditions (events) concern ASPExpire:

The user is not initialized (smapsNextAction is not set).
APSExpire will check to see if any other event should also occur. The user's date will be updated. This event is never logged to the log file.
A user's password will expire within a number of days. This is useful, for example, when a typical user only logs in, say, every 90 days. Users may never see the on-line password change warnings.
APSExpire will send email if a template is specified for this event. The mail can contain the date that the password will expire and the number of days remaining before expiration.

This event will be logged with an event id of PASSWORD WARNING.
A user's password has expired, but a grace period or grace logins remain.
APSExpire will send email if a template is specified for this event. The mail can contain the date that the password expired and the number of days remaining before the user is disabled.

This event will be logged with an event id of PASSWORD SOFT EXPIRE.
A user's password has expired, no grace period or grace logins remain and the user record will be disabled.
APSExpire will send email if a template is specified for this event. The mail can contain the date that the password expired.

APSExpire will disable the user account.

This event will be logged with an event id of PASSWORD HARD EXPIRE.
A user's account has remained inactive for too long and will be disabled shortly.
APSExpire will send email if a template is specified for this event. The mail can contain the date that the account will expire and the number of days remaining before expiration.

This event will be logged with an event id of ACCOUNT WARNING.
A user's account has remained inactive for too long and will be disabled now.
APSExpire will send email if a template is specified for this event. The mail can contain the date that the account expired. Typically, this mail is sent internally.

APSExpire will disable the user account.

This event will be logged with an event id of ACCOUNT EXPIRE.
A user's account is eligible for purging (deletion).
This event will be logged with an event id of ACCOUNT PURGE. No other action will be taken.

Command Line Parameters

APSExpire supports a number of command line arguments to control its processing:

<job>	The name of job to run as defined in APS.cfg.
-v	Verbose mode (tracing output on).
-q	Quiet mode (logging off).
-A	Process all users (for initialization).
-H or -?	Display usage information.
-T	Do not output column titles.
-m	Turn off mail (default with -A).
+m	Turn on mail (default without -A).
-l logfile	Path to write tracing and processing information to.
-o outfile	Path to write activity to (the "log").
-e errfile	Path to write errors to.

Performance Adjustments/Job Definitions

The APSExpire section of the APS configuration file controls the operation of APSExpire.

A site defines jobs by name. Each setting is the name of a job and the values define the criteria for the job. When APSExpire executes, a job name must be specified. The program will look for the definition of this job in this section of the file.

Each job defines a user directory or subset of a user directory. The syntax for ODBC and LDAP directories are different.

LDAP Directories

For LDAP directories, jobs are defined using this syntax:

<job name>= <LDAP directory>
			READ(<ip>)
			BASE(<base DN>)
			SCOPE(<scope>)
			FILTER(<filter>)

<job name> is an arbitrary name for the job.

<ip of LDAP directory> is the ip address, the network name, or the SiteMinder User Directory name of an LDAP directory defined to SiteMinder through the Policy Interface (it cannot contain spaces if used here). If it is an ip address, it may contain the port address as well. This must match up with the definition of a User Directory in the SiteMinder Policy Store (APSExpire will attempt to look up the directory using this value).

READ(<ip>) is an optional clause that tells APSExpire to read from a different directory than the base directory. In some cases, much higher performance can be achieved by reading from a dedicated replicant directory that either SiteMinder does not use at all or is the last directory in a failover chain. If specified, however, the alternate directory must be a replicant of the "real" directory.

BASE(<search Base>) is optional and defines the scope of the search. If it is not specified, APSExpire searchs the entire directory using the search base defined in the SiteMinder User directory entry. This is useful when an entire LDAP directory is not to be processed as a single job. Sites do this when the LDAP directory is very large and APSExpire processing is to be spread over multiple servers or jobs.

SCOPE(<scope>) is optional and is generally used with the BASE option above. <scope> can either be base or sub. It specifies how the LDAP search should be processed.

FILTER(<extra filter>) is another optional setting that allows a site to further refine a job. This filter is ANDed with any filters that APSExpire uses for its own operations. Once again, this is intended to segregate an LDAP directory into smaller jobs for performance reasons.

When using BASE, SCOPE and FILTER, it is the responsibility of the site to make sure that every user will be processed. APSExpire does not examine the sum of all defined jobs to ensure that all users get processed.

ODBC Directories

For ODBC directories, jobs are defined using this syntax:

<job name>= <ODBC directory>
			WHERE(<extra WHERE clause>)

<job name> is an arbitrary name for the job.

<ODBC directory> is the DSN name or the SiteMinder User Directory name of an ODBC user directory (neither can have embedded spaces in this context) defined to SiteMinder through the Policy Interface. This must match up with the definition of a User Directory in the SiteMinder Policy Store (APSExpire will attempt to look up the directory using this value).

WHERE(<extra WHERE clause>) is another optional setting that allows a site to further refine a job. This clause is ANDed with any WHERE clause that APSExpire uses for its own operations. This is intended to segregate an ODBC directory into smaller jobs for performance purposes.

When using WHERE, it is the responsibility of the site to make sure that every user will be processed. APSExpire does not examine the sum of all defined jobs to ensure that all users get processed.

Performance

Each User Directory should be processed by APSExpire on a periodic basis, preferably daily, even if the special processing for the events is not desired. This ensures that new user records will be initialized properly.

APSExpire must run on the Policy Server machine.

The time that it takes to process a single user is relatively fixed (though based on the platform). However, the time required to find users to process is a function of the size of the directory. It may be obvious, but it must be said: Larger directories will take more time to process than smaller directories.

At APS Version 4.0, APSExpire was completely redesigned to handle larger User Directories. The amount of time required to process each user could not be reduced significantly (in fact, other required enhancement increased the per-user time slightly). However, the change to use smapsNextAction has significantly improved performance for locating users to be processed (which, prior to Version 4.0, was where APSExpire spent most of its time).

The use of smapsNextAction, however, introduced the restrictions presented earlier in this chapter. The performance improvement was so dramatic that the restrictions were deemed acceptable.

In an additional performance-enhancing effort, APSExpire jobs need not define an entire User Directory; they can define a subset of a directory. In this way, a site can load-balance multiple APSExpire executions across multiple Policy Servers and/or spread the processing over a period of time.

When dividing a User Directory into subsets, it is the responsibility of the site to ensure that all users are covered. For example, it would be an error (undetected by APS) to create two jobs, one to handle users whose last names start with the letters "A" through "M" and another job for user names starting with "O" through "Z", since users whose names start with "N" would never be processed.