System Authorization Facility (SAF) directives
These configuration parameters control the System Authorization Facility (SAF) feature for IBM® HTTP Server. Use the SAF directives to provide IBM HTTP Server with user authentication.
- AuthSAFAuthoritative directive
- AuthSAFExpiration directive
- AuthSAFExpiredRedirect directive
- AuthSAFReEnter directive
- AuthSAFStatusHeader directive
- SAFAPPLID directive
- SAFRunAs directive
- SAFRunAsEarly directive
AuthSAFAuthoritative directive
The AuthSAFAuthoritative directive sets whether authorization is passed to lower-level modules.
Directive | Description |
---|---|
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 you 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 you must code the phrase using the hex value '43', which translates to the
correct ASCII character.
Directive | Description |
---|---|
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.
<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.
AuthSAFExpiredRedirect directive
The AuthSAFExpiredRedirect
directive specifies a URL that a request should be
redirected to if your password is expired when you are using mod_authnz_saf for authentication on
z/OS®.
This is an alternative to using AuthSAFExpiration
.
Directive | Description |
---|---|
Syntax | AuthSAFExpiredRedirect url |
Default | off |
Context | directory, .htaccess |
Module | mod_authnz_saf |
Values | off or url |
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.
Directive | Description |
---|---|
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.
<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.
AuthSAFStatusHeader directive
Allow details of SAF authentication to be added to a custom response header and to the body of the 401 responses. The header is specified by the AuthSAFStatusHeader directive.
Directive | Description |
---|---|
Syntax | AuthSAFStatusHeader header name |
Default | not specified |
Context | server, directory, .htaccess |
Module | mod_authnz_saf |
Values | not specified , off , or valid header
name
|
SAFAPPLID directive
Overrides the application id APPLID parameter passed to operating systems
pthread_security_applid_np()
configuration subroutine with
SAFRunAs
.
The SAFAPPLID
directive depends on z/OS APAR OA54407 to check the
APPLID
when using %%CERTIF or %%CERTIF_REQ.
Directive | Description |
---|---|
Syntax | SAFAPPLID application-id |
Default | None (Some OS configurations implicitly treat it as
OMVSAPPL ) |
Context | directory, .htaccess |
Module | mod_authnz_saf |
Values | application-id |
When the SAFRunAs
directive is used, from some security product configurations
where the APPL
class is active, the security product will verify the authenticated
user has access to the OMVSAPPL
class. If SAFAPPLID
is configured,
the specified application-id is used instead.
SAFRunAs directive
The SAFRunAs directive sets the SAF user ID that serves the request.
Directive | Description |
---|---|
Syntax | SAFRunAs value |
Default | off |
Context | directory, .htaccess |
Module | mod_authnz_saf |
Values | off | %%CLIENT%% | %%CERTIF%% | %%CERTIF_REQ%% | %%CERTIF%% /prefix |
surrogate-username /prefix | <surrogate ID>
|
IBM HTTP Server can
communicate with FastCGI applications using either TCP sockets or UNIX sockets. However, when using
SAFRunAs
for FastCGI requests, you must 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 you do not enable SAFRunAs
for FastCGI requests, TCP sockets are not
required.
<Location /context-root-A/>
SAFRunAS %%CLIENT%%
</Location>
Requests
to paths that contain the /context-root-A/* parameter run as the remote user.
# Process *.phtml with the "php-script" handler.
AddHandler php-script .phtml
# Define the "php-script" handler as an existing CGI.
Action php-script /cgi-bin/php-cgi
The Action directive turns a request for the /context-root-A/hello.phtml file
into a request for a path that contains the /cgi-bin/php-cgi parameter with a
command line argument of /context-root-A/hello.phtml.<Location /cgi-bin/php-cgi>
SAFRunAS %%CLIENT%%
</Location>
If you need multiple SAFRunAs settings, forgo the Action directive entirely or create multiple Action directives with different second parameters.
SAFRunAsEarly directive
The SAFRunAsEarly
directive allows SAFRunAs
to run before any
directories are accessed.
Directive | Description |
---|---|
Syntax | SAFRunAsEarly on | off |
Default | off |
Context | location |
Module | mod_authnz_saf |
Values | on | off |
SAFRunAs
set to %%CLIENT%%
, IHS
attempts to access the file to be served in the response before switching user IDs. This can cause
problems when there are directories/files which are inaccessible to the user which IHS is running
with, but are accessible to the %%CLIENT%%
user. An error like this would occur
when attempting such a directory:
[Tue Aug 11 14:03:16 2015] [error] [client x.x.x.x] (111)EDC5111I Permission denied. (errno2=0x5B4B0002): access to /saf/privileged/index.html deniedIf SAFRunAsEarly is set to on with SAFRunAs set to %%CLIENT%%, IHS will switch user before any directory/file access are attempted.
If SAFRunAsEarly
is set to on with SAFRunAs
set to
%%CLIENT%%
, IHS will switch user before any directory/file access are
attempted.
SAFRunAsEarly
must be used in <Location> contexts, or the global context. It
cannot be used in <Directory> contexts.
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 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>
LISTGRP NOGIDGRP OMVS NORACF
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 you want
# a user in any of the groups in the specified group file to be able
# to access the resource.
# Note: Any authorization module, with its standard configuration, can be used here.
Require group admin1 admin2
</Location>
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>
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>
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>
If you want 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.
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>
<Location /certificate_or_basic>
AuthName "SAF RunAs certif"
AuthType basic
Require saf-user USER84 USER103
AuthBasicProvider saf
SAFRunAs %%CERTIF%%
</Location>
<Location /runas_public>
SAFRunAs PUBLIC
# This can be combined with SAF or non-SAF authentication/authorization
</Location>