System Authorization Facility (SAF) directives

Home Operating Systems: z/OS

These configuration parameters control the System Authorization Facility (SAF) feature for IHS. Use the SAF directives to provide IBM HTTP Server with user authentication.

AuthSAFAuthoritative directive
AuthSAFExpiration directive
AuthSAFReEnter directive
SAFRunAs directive

AuthSAFAuthoritative directive

The AuthSAFAuthoritative directive sets whether authorization is passed to lower level modules.

Syntax AuthSAFAuthoritative on | off
Default on
Context directory, .htaccess
Module mod_authnz_saf
Values on or off

Setting the AuthSAFAuthoritative directive off allows for authorization to be passed to lower level modules (as defined in the modules.c files), if there is no user ID or rule matching the supplied user ID. If there is a user ID or rule specified, then the usual password and access checks will be applied and a failure will result in an Authentication Required reply.
If a user ID appears in the database of more than one module, or if a valid Require directive applies to more than one module, then the first module will verify the credentials, and no access is passed on, regardless of the AuthSAFAuthoritative setting.
By default, control is not passed on and an unknown user ID or rule will result in an Authentication Required reply. Not setting it thus keeps the system secure and forces an NCSA compliant behavior.
AuthSAFExpiration directive

The AuthSAFExpiration directive sets the value displayed in the browser prompt. The server sends the value specified for the AuthName directive and this short phrase in an HTTP response header, and then the browser displays them to the user in a password prompt window. The short phrase is subject to the same character limitations as the specified value for the AuthName directive. Therefore, to display a special character in the password prompt window, the server must translate the special character from the EBCDIC CharsetSourceEnc codepage to the ASCII CharsetDefault codepage. For example, if we want to display a lowercase 'a' with umlaut, and the httpd.conf file contains the German language EBCDIC codepage "CharsetSourceEnc IBM-1141" and the ASCII codepage "CharsetDefault ISO08859-1", then code the phrase using the hex value '43', which translates to the correct ASCII character.

Syntax AuthSAFExpiration short_phrase
Default off
Context directory, .htaccess
Module mod_authnz_saf
Values off or short_phrase

Setting the AuthSAFExpiration directive to a phrase allows IBM HTTP Server to prompt the user to update his SAF password if it expires. When the user enters a valid ID and SAF password but the password has expired, the server will return an Authentication Required reply with a special prompt to allow the user to update the expired password. The prompt consists of the realm (the value from the AuthName directive) followed by the short_phrase value from the AuthSAFExpiration directive. For example, consider the following configuration:
<Location /js>
AuthType basic
AuthName "zwasa051_SAF"
AuthBasicProvider saf
Require valid-user
Require saf-group SYS1 WASUSER
AuthSAFExpiration "EXPIRED! oldpw/newpw/newpw"
</Location>
If the user attempts to access a file whose URL starts with /js, then the server prompts for a SAF ID and password. The browser will display a prompt containing the realm. The realm is the value from the AuthName directive, which is zwasa051_SAF in this example.
When the user supplies a valid ID and password, if the password has expired, the server will repeat the prompt, but this time with the value zwasa051_SAF EXPIRED! oldpw/newpw/newpw. Whatever the prompt, the user must then re-enter the expired password, followed by a slash, the new password, another slash, and the new password again.
If the password update is successful, the server will send another Authentication Required reply with a distinct special prompt. This last interaction is necessary in order to force the browser to understand which password it should cache. The prompt this time will consist of the realm followed by the prompt Re-enter new password. In this example, it would be zwasa051_SAF Re-enter new password.
AuthSAFReEnter directive

The AuthSAFReEnter directive sets the value appended to realm after a successful password change. For information about coding special characters, see the BAuthSAFExpiration directive.

Syntax AuthSAFReEnter short_phrase
Default Re-enter new password
Context directory, .htaccess
Module mod_authnz_saf
Values off or short_phrase

Setting the AuthSAFReEnter directive explicitly to a phrase other than "Re-enter new password" allows the administrator to display an alternative message after an expired password has been updated successfully. If AuthSAFExpiration has been set to off, this directive has no effect. For example, consider the following configuration:
<Location /js>
AuthType basic
AuthName "zwasa051_SAF"
AuthBasicProvider saf
Require saf-user SYSADM USER152 BABAR
AuthSAFExpiration "EXPIRED! oldpw/newpw/newpw"
AuthSAFReEnter "Enter new password one more time"
</Location>
In this example, after the expired password is updated successfully, the server will send another Authentication Required reply with the value from the AuthSAFReEnter directive. This last interaction is necessary in order to force the browser to understand which password it should cache. The prompt this time will consist of the realm followed by a special phrase. In this example, it would be zwasa051_SAF Enter new password one more time.
SAFRunAs directive

The SAFRunAs directive sets the SAF user ID under which a request will be served.

Syntax SAFRunAs value
Default off
Context directory, .htaccess
Module mod_authnz_saf
Values off | %%CLIENT%% | %%CERTIF%% | %%CERTIF_REQ%% | <surrogate ID>
Off: The server will run the request under the Web server user ID.
%%CLIENT%%: The server will run the request under the ID supplied in the Authorization request header. Generally, the user supplies the ID and password in a pop-up window on the browser, and the browser creates the header. Requires that SAF is configured to authenticate the URL.
%%CERTIF%%: The server will run the request under the ID associated with the SSL client certificate in SAF. If there is no SSL certificate or if the SSL certificate has not been associated with an ID in SAF, the processing will continue as if %%CLIENT%% had been coded.
Does not require SAF authn or authz to be configured.
%%CERTIF_REQ%%: The server will run the request under the ID associated with the SSL client certificate in SAF. If there is no SSL certificate, or if the SSL certificate has not been associated with an ID in SAF, the server will not allow access. Does not require SAF authn or authz to be configured.
<surrogate ID>: The server will run the request under the ID associated with the SAF surrogate ID specified.

IHS can communicate with FastCGI applications using either TCP sockets or UNIX sockets. However, when using SAFRunAs for FastCGI requests, use TCP sockets for communication with the application. UNIX sockets that are created for FastCGI applications are accessible by the Web server user ID only. The alternate user ID controlled with the SAFRunAs directive does not have permission to access the UNIX sockets, so requests will fail.
To configure FastCGI to use TCP sockets, define the FastCGI application to the mod_fastcgi module using the FastCGIServer directive with the -port option or using the FastCGIExternalServer directive. Dynamic FastCGI servers that you do not configure with the FastCGIServer or FastCGIExternalServer are not usable with SAFRunAS.
If we do not enable SAFRunAs for FastCGI requests, TCP sockets are not required.

Example
To use SAF for authentication and authorization, consider the following example. This is the most common scenario for SAF users and groups and meets the requirements for web access.
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authnz_saf_module modules/mod_authnz_saf.so
LoadModule authz_default_module modules/mod_authz_default.so
...
<Location /saf_protected>
AuthType basic  
AuthName x1 
AuthBasicProvider saf 
# Code "Require valid-user" if we 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>
To use a SAF file for authentication, but use a non-SAF group file for authorization, consider the following example. In this example, users are authenticated using SAF, but authorized using a different mechanism.
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authnz_saf_module modules/mod_authnz_saf.so
LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
LoadModule authz_default_module modules/mod_authz_default.so
...
<Location /saf_password>
AuthType basic
AuthName "SAF auth with hfs groupfile"
AuthBasicProvider saf
AuthGroupFile /www/config/foo.grp
# Code "Require file-group" and a list of groups if we want
# a user in any of the groups in the specified group file to be able
# to access the resource.
# 
 Any authorization module, with its standard configuration, can be used here.
Require group admin1 admin2
</Location>
To allow access to a user if the user is authorized by SAF or by a group file, consider the following example.
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authnz_saf_module modules/mod_authnz_saf.so
LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
LoadModule authz_default_module modules/mod_authz_default.so
...
<Location /either_group>
AuthType basic
AuthName "SAF auth with SAF groups and hfs groupfile"
AuthBasicProvider saf
AuthGroupFile /www/groupfiles/foo.grp
Require saf-group WASGRP
Require saf-group ADMINS
AuthzGroupFileAuthoritative Off
AuthSAFAuthoritative Off
</Location>
To require a request to run using the SAF privileges associated wit the authenticated username, consider the following example.
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authnz_saf_module modules/mod_authnz_saf.so
LoadModule authz_default_module modules/mod_authz_default.so
...
<Location /runas_admin_bin>
AuthName "SAF RunAs client"
AuthType basic
Require valid-user
AuthBasicProvider saf
SAFRunAs %%CLIENT%%
</Location>
To support the changing of expired SAF passwords, consider the following example.
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authnz_saf_module modules/mod_authnz_saf.so
LoadModule authz_default_module modules/mod_authz_default.so
...
<Location /custom_password_change>
AuthType basic
AuthName "Support expired PW"
Require valid-user
AuthBasicProvider saf
AuthSAFEXpiration "EXPIRED PW: oldpw/newpw/newpw"
AuthSAFReEnter "New PW again:"
</Location>
To require a client certificate before a user can access a resource, use the mod_ibm_ssl directive. The mod_authnz_saf directive is not needed for this configuration. For additional information, see the documentation for the SSLClientAuth and SSLClientAuthRequire directives. If you want to use a client certificate to determine the user for whom request processing is performed, consider the following example. If the user does not have a valid certificate, access is denied.
LoadModule authnz_saf_module modules/mod_authnz_saf.so
LoadModule ibm_ssl_module modules/mod_ibm_ssl.so
...
<Location /certificate_required>
SAFRunAs %%CERTIF_REQ%%
</Location>
To require a request to run using the SAF privileges associated with a client certificate, but require username and password authentication if the client certificate is not mapped to a SAF user, consider the following example. If the user provides a certificate that SAF can map to a user ID, then the user ID must also pass any Require directives.
<Location /certificate_or_basic>
AuthName "SAF RunAs certif"
AuthType basic
Require saf-user USER84 USER103
AuthBasicProvider saf
SAFRunAs %%CERTIF%%
</Location>
To require a request to run using the SAF privileges associated with a surrogate ID, consider the following example.
<Location /runas_public>
SAFRunAs PUBLIC
# This can be combined with SAF or non-SAF authentication/authorization
</Location>
Related tasks

Authenticate with SAF on IHS (z/OS systems)

Related reference

FastCGI directives
SSL directives

Related information

Using the AuthBasicProvider directive for SAF password authentication

Syntax	AuthSAFAuthoritative on \| off
Default	on
Context	directory, .htaccess
Module	mod_authnz_saf
Values	on or off

Syntax	AuthSAFExpiration short_phrase
Default	off
Context	directory, .htaccess
Module	mod_authnz_saf
Values	off or short_phrase

Syntax	AuthSAFReEnter short_phrase
Default	Re-enter new password
Context	directory, .htaccess
Module	mod_authnz_saf
Values	off or short_phrase

Syntax	SAFRunAs value
Default	off
Context	directory, .htaccess
Module	mod_authnz_saf
Values	off \| %%CLIENT%% \| %%CERTIF%% \| %%CERTIF_REQ%% \| <surrogate ID> Off: The server will run the request under the Web server user ID. %%CLIENT%%: The server will run the request under the ID supplied in the Authorization request header. Generally, the user supplies the ID and password in a pop-up window on the browser, and the browser creates the header. Requires that SAF is configured to authenticate the URL. %%CERTIF%%: The server will run the request under the ID associated with the SSL client certificate in SAF. If there is no SSL certificate or if the SSL certificate has not been associated with an ID in SAF, the processing will continue as if %%CLIENT%% had been coded. Does not require SAF authn or authz to be configured. %%CERTIF_REQ%%: The server will run the request under the ID associated with the SSL client certificate in SAF. If there is no SSL certificate, or if the SSL certificate has not been associated with an ID in SAF, the server will not allow access. Does not require SAF authn or authz to be configured. <surrogate ID>: The server will run the request under the ID associated with the SAF surrogate ID specified.