<-
Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authnz_saf

Description:RACF/SAF authentication and Authorization modules
Status:Extension
Module Identifier:authnz_saf_module
Source File:mod_authnz_saf.c

Summary

This module provides support for authentication and authorization based on RACF/SAF.

Directives

Topics

top

Examples

The examples below all require the following modules to be loaded:

LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authnz_saf_module modules/mod_authnz_saf.so
LoadModule authz_core_module modules/mod_authz_core.so

Basic authentication and authorization example

<Location /saf_protected>
AuthType basic  
AuthName "example corp login"
AuthBasicProvider saf 
# Code "Require valid-user" if you want any valid
# SAF user to be able to access the resource.
Require valid-user
#
# Alternately, you can provide a list of specific SAF users
# who may access the resource.
# Require saf-user USER84 USER85
#
# Alternatively, you can provide a list of specific SAF groups
# whose members may access the resource.
# Require saf-group WASGRP1 WASGRP2
</Location>

SAF/RACF authentication, with the webserver assuming the users identity

<Location /runas_admin_bin>
AuthName "example corp login"
AuthType basic
Require valid-user
AuthBasicProvider saf
# Use client identity
SAFRunAs %%CLIENT%%
# Additional configuration if webserver ID can't access users directories
# SAFRunAsEarly
</Location>

Run a CGI as a dedicated surrogate userid

<Location /cgi-bin/report.cgi>
SAFRunAs bob 
</Location>

Same as the above, but switch userids earlier if the webserver has no accsess to cgi-bin/ or report.cgi

SAFRunAs bob /cgi-bin/report.cgi

Enable the SAF change password form handler

<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>

<Location "/change-saf-password">
  SetHandler saf-change-pw

  # AuthSAFExpiredForm should also be specified here to ensure that 
  # mod_authnz_saf can redirect back to the form if there was an
  # error when trying to update the password.
  AuthSAFExpiredForm /change-saf-password
</Location>
top

AuthSAFAuthoritative Directive

Description:Dummy directive, no longer required as of 9.0.0.0
Syntax:n/a
Default:n/a
Context:directory
Status:Extension
Module:mod_authnz_saf
Compatibility:9.0.0.0-PI49954 and later

This directive no longer has any effect, but is accepted for backwards compatibility.

top

AuthSAFExpiration Directive

Description:Value appended to HTTP Basic Auth realm on password expiration
Syntax:AuthSAFExpiration custom-text|"OFF"
Default:AuthSAFExpiration OFF
Context:directory
Status:Extension
Module:mod_authnz_saf
Compatibility:Deprecated
This directive is being deprecated because of browser usability issues. AuthSAFExpiredForm or AuthSAFExpiredRedirect should be used instead.

If this module is used for authentication, and an expired password is detected, the custom text listed in this directive is added to the HTTP Basic Auth realm that the client will be prompted with. Typically, the custom prompt specified by this directive would prompt the user to change their password using normal RACF/SAF syntax, e.g. "EXPIRED ! oldpw/newpw/newpw".

For more information regarding the browser usability issues, please read Known Issues with Updating SAF Password via the AuthSAFExpiration Directive.

top

AuthSAFExpiredForm Directive

Description:Specifies a redirection URL to send users with an expired password to.
Syntax:AuthSAFExpiredForm URL
Default:n/a
Context:directory
Status:Extension
Module:mod_authnz_saf
Compatibility:9.0.0.5 and later

Redirects to the specified URL with additional information passed in the query string:

After 9.0.5.8, the error query parameter is only set when AuthSAFSetErrorReason is enabled.

Error identifiers (and their meanings) returned by saf-change-pw handler:

top

AuthSAFExpiredRedirect Directive

Description:Specifies a redirection URL to send users with expired password to.
Syntax:AuthSAFExpiredRedirect fully-qualified-URL
Default:n/a
Context:directory
Status:Extension
Module:mod_authnz_saf

Specifies a redirection URL to send users with expired password to

top

AuthSAFReEnter Directive

Description:Value appended to HTTP Basic Auth realm after password change
Syntax:AuthSAFReEnter custom-text
Default:AuthSAFReEnter OFF
Context:directory
Status:Extension
Module:mod_authnz_saf
Compatibility:Deprecated
This directive is being deprecated because of browser usability issues. AuthSAFExpiredForm or AuthSAFExpiredRedirect should be used instead.

If this module is used for authentication, and the user submits a password change in the form of oldpw/newpw/newpw, the custom text listed in this directive is added to the HTTP Basic Auth realm that the client will be prompted with (to log in with "newpw"). Typically, the custom prompt specified by this directive would guide the user to enter their new password to continue, e.g. "New password one more time, please"

For more information regarding the browser usability issues, please read Known Issues with Updating SAF Password via the AuthSAFExpiration Directive.

top

AuthSAFSetErrorReason Directive

Description:Provides reason for SAF authentication failure
Syntax:AuthSAFSetErrorReason ON|OFF
Default:OFF
Context:virtual host, server config
Status:Extension
Module:mod_authnz_saf
Compatibility:9.0.5.8 and later

Caution

Enabling this reveals the existence of the provided username on the system.

This directive controls whether the SAF authentication failure reason is included in the following:

  1. HTTP 401 error response
  2. HTTP 403 error response when password update limit was reached
  3. the error query parameter when using AuthSAFExpiredForm
top

AuthSAFUpdateFailedMessage Directive

Description:Message added to an error page if too many attempts to password update have failed.
Syntax:AuthSAFUpdateFailedMessage message
Default:n/a
Context:directory
Status:Extension
Module:mod_authnz_saf
This directive is only used when AuthSAFExpiration is specified and AuthSAFSetErrorReason is enabled.

Add a message to the 403 error page generated when updating a user's password fails after too many unsuccessful attempts. The message may include HTML.

top

SAFAPPLID Directive

Description:Specifies an alterate SAF/RACF "APPLID" for authentication purposes.
Syntax:SAFAPPLID APPLID-name
Default:SAFAPPLID OMVSAPPL
Context:directory
Status:Extension
Module:mod_authnz_saf

Specifies an alternate SAF/RACF "APPLID" for authentication purposes. When omitted, "OMVSAPPL" is used by the underlying z/OS authentication routines.

top

SAFRunAs Directive

Description:Change webserver thread identity to authenticated web user
Syntax:SAFRunAs %%CLIENT%%|%%CERTIF_REQ%%|%%CERTIF%%|surrogate-username [/URL-path-prefix]
Default:n/a
Context:directory, virtual host, server config
Status:Extension
Module:mod_authnz_saf

This directive configures the server to assume an alternate identity for the duration of request processing. It can assume the authenticated users identity, or that of a surrogate ID it has been given access to.

The first parameter takes one of the following values:

%%CLIENT%%
The webserver changes userid to the user authenticated with HTTP Basic Authentication. This requires that this module be specified as the AuthBasicProvider.
%%CERTIF_REQ%%
The webserver changes userid to the TLS client certificate identity. The mapping between certificates and username is performed via RACF. The current request is authenticated as a result.
%%CERTIF%%
Like %%CERTIF_REQ%%, but if no TLS client certificate is provided, or the certificate does not map to any z/OS username, %%CLIENT%% is used instead.
surrogate-username
The webserver changes userid to the named surrogate user map to any z/OS username, %%CLIENT%% is used instead. The webserver ID must have read access to BPX.SRV.surrogate-username or BPX.SRV.*.

Notes:

top

SAFRunAsEarly Directive

Description:Specifies that %%CLIENT%% userid change should run early
Syntax:SAFRunAsEarly ON|OFF
Default:SAFRunAsEarly OFF
Context:directory
Status:Extension
Module:mod_authnz_saf
Compatibility:Requires PI45005

When SAFRunAsEarly is set to "ON", userid changes due to SAFRunAs with %%CLIENT%% and %%CERTIF_REQ%% occur earlier in processing. This helps avoid problems when the users own credentials are needed for the webserver to access the directory containing files being served