SAF Expired Password Information

Provide feedback on the IBM HTTP Server forum on IBM developerWorks.

z/OS Questions

Information related to IHS on z/OS can be found in the z/OS questions page.

Known Issues with Updating SAF Password via the AuthSAFExpiration Directive

Users of mod_authnz_saf are only affected by these issues when the AuthSAFExpiration or AuthSAFReEnter directives are set. For those looking for an alternative way to notify users of their password expiration, please look at AuthSAFExpiredRedirect directive or using form-based authentication instead.

Expired Password Loop Mitigation

To mitigate the number of authentication requests that hit the server, the session cookie saf_auth_limit was introduced. The cookie is added on the first expired password update request and is decremented for each subsequent expired password update request. Once the expired password update request limit has been reached (2 by default), a 403 Forbidden will be returned, stopping Firefox from sending any more authentication requests using cached credentials. This feature is available in fixpacks 9.0.0.5, 8.5.5.12, 8.0.0.14, 7.0.0.45 and above.

The 403 error page will display general instructions that the user can follow to successfully update their password. Furthermore, a custom message (either text or HTML) can be added to the error page to provide or link to additional information using the AuthSAFUpdateFailedMessage directive.

The enviornment variable SAF_AUTH_LIMIT was added to change the limit of expired password update requests that is allowed before a 403 occurs. By setting the environment variable SAF_AUTH_LIMIT to -1, this feature can be disabled entirely. A few examples are provided below.


# Increase the limit of expired password update requests allowed for Firefox user agents
BrowserMatch Firefox SAF_AUTH_LIMIT=3

# Disable this feature for all browsers except Firefox
BrowserMatch . SAF_AUTH_LIMIT=-1
BrowserMatch Firefox SAF_AUTH_LIMIT=2

# Disable this feature entirely
BrowserMatch . SAF_AUTH_LIMIT=-1

Using AuthSAFExpiredRedirect instead of AuthSAFExpiration

It is suggested that the SAF password update via AuthSAFExpiration not be used as there are usability issues with both Chrome and Firefox. AuthSAFExpiration can be disabled by commentting or removing the following directives from the httpd configuration file:


# Remove these lines from the configuration
AuthSAFExpiration custom-text
AuthSAFReEnter custom-text

Informing users that their SAF password has expired can be done by redirecting to an error page defined by the AuthSAFExpiredRedirect directive. An example of such a configuration is as follows:


<Location "/saf_protected/">
  AuthName "SAF Basic Authentication"
  AuthType Basic
  AuthBasicProvider saf
  Require valid-user
  AuthSAFExpiredRedirect /error/saf_expired.html
</Location>

It is also important to verify that the redirect target is not protected! If the error page is protected, it can be unprotected using one of the following stanzas:


# IHS 9.0 and above
<IfModule authn_core_module>
  <Location "/error">
    Require all granted
  </Location>
</IfModule>

# IHS 8.0 and 8.5.5
<IfModule authz_default_module>
  <Location "/error">
    Order allow,deny
    Allow from all
    Satisfy any
  </Location>
</IfModule>

Form-Based SAF Password Update Utility

A feature has been added with PI81602 to allow users to update their passwords using a form. It also allows users to use a custom form instead of the default form that mod_authnz_saf provides. PI81602 is targeted for IBM HTTP Server fixpacks: 9.0.0.5, 8.5.5.12, 8.0.0.14, and 7.0.0.45.

The feature can be enabled by adding the mod_authnz_saf handler saf-change-pw and redirecting to the handler when a user's password has expired using the AuthSAFExpiredForm directive. A basic configuration will look similar to the following stanza:


# Enable and configure the mod_authnz_saf module
LoadModule authnz_saf_module modules/mod_authnz_saf.so

<Location "/saf_protected/">
  AuthName "SAF Basic Authentication"
  AuthType Basic
  AuthBasicProvider saf
  Require valid-user

  # Redirect to the saf-change-pw handler to handle expired passwords.
  AuthSAFExpiredForm /change-saf-password
</Location>


# Enable the saf-change-pw handler. It is important to make sure this location
# is not protected! An example of unprotecting a certain location is given
# in the previous section.
<Location "/change-saf-password">
  SetHandler saf-change-pw

  # The IBM-1047 character set encoding is required if using the default form provided
  # by the handler. This is to make sure the correct encoding is set in case the user
  # switches CharsetSourceEnc to a value other than IBM-1047.
  CharsetSourceEnc IBM-1047
</Location>

Using a Custom SAF Password Update Form

Using a custom form page [example] is also an option instead of using the default one. There are certain requirements that must be followed, however, so that mod_authnz_saf can process the form's data:

Errors are passed back as an ID to the client using the query string variable error. The list of error IDs and their meanings can be found in the linked example form above.

The custom form page can be enabled by telling mod_authnz_saf to redirect to it when an expired password is found using the AuthSAFExpiredForm directive:


# Enable and configure the mod_authnz_saf module
LoadModule authnz_saf_module modules/mod_authnz_saf.so
 
<Location "/saf_protected/">
  AuthName "SAF Basic Authentication"
  AuthType Basic
  AuthBasicProvider saf
  Require valid-user

  # Redirect to the custom form page to handle expired passwords.
  AuthSAFExpiredForm /my-custom-form.html
</Location>
 
# Enable the saf-change-pw handler. It is important to make sure this location
# is not protected! An example of unprotecting a certain location is given
# in the previous section.
<Location "/change-saf-password">
  SetHandler saf-change-pw
</Location>