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

AuthSAFAuthoritative
AuthSAFExpiration
AuthSAFExpiredForm
AuthSAFExpiredRedirect
AuthSAFReEnter
AuthSAFSetErrorReason
AuthSAFUpdateFailedMessage
SAFAPPLID
SAFRunAs
SAFRunAsEarly

Topics

Examples

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>

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.

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.

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:

uri is the original URI to redirect back to once the password has successfully been updated.
error is set to an error identifier only if the password update failed. The list of errors is described below.

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:

MISSING_USERNAME: The username needs to be specified.
MISSING_OLDPW: The old password needs to be specified.
MISSING_NEWPW: A new password needs to be specified.
MISSING_NEWPW_CONFIRM: Confirm the new password.
MISMATCHED_NEWPW: New passwords should match.
USER_NOT_FOUND: SAF user not found.
INVALID_OLDPW: Old password is invalid.
INVALID_NEWPW: New password is invalid.
USER_REVOKED: User has been revoked.
UNKNOWN_ERROR: An unknown error has occurred.

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

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.

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:

HTTP 401 error response
HTTP 403 error response when password update limit was reached
the error query parameter when using AuthSAFExpiredForm

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.

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.

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:

The optional /URL-path-prefix parameter can only be specified when this directive occurs in server or virtualhost scope, and only when the first parameter is %%CERTIF%% or surrogate-username.
If you are using SAFRunAs, permit the IBM HTTP Server userid to the BPX.SERVER FACILITY class profile in RACF, and provide the target userid with an OMVS segment.
If the APPL class is active in the security product (SAF), users who authenticate via this module must be permitted to the OMVSAPPL application ID.
If the webservers ID cannot access files and directories being served, additional steps need to be taken to configure the server to switch userids early.
- If the first parameter is %%CERTIF%% or surrogate-username, use the alternate syntax that takes a second parameter for a prefix.
- If the first parameter is %%CLIENT%% or %%CERTIF_REQ%%, see SAFRunAsEarly
If using SAFRunAS with IBM Multi Factor Authentication (MFA), UPDATE access to both BPX.SERVER and BPX.DAEMON are required
If you have defined resources in the CSFSERV class to protect cryptographic services, users that the web server will switch identity to with SAFRunAs will need access to CSF1SKD and CSF1SKE.

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