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
For previous releases, the AuthSAFAuthoritative directive sets whether authorization is passed to lower-level modules. Due to changes in the Apache HTTP Server API in this release, AuthSAFAuthoritative is no longer needed or accepted.
Directive | Description |
---|---|
Syntax | AuthSAFAuthoritative on | off |
Default | on |
Context | directory, .htaccess |
Module | mod_authnz_saf |
Values | on | off |
For previous releases, the AuthSAFAuthoritative directive sets whether authorization is passed to lower-level modules. Due to changes in the Apache HTTP Server API in this release, AuthSAFAuthoritative is no longer needed or accepted. If used in a previous release, it should be removed from the configuration.
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 |
Set 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.
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 |
Set 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.
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 that is passed to operating systems pthread_security_applid_np() subroutine by using configurations with SAFRunAs.
Attention: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 with some security product configurations where the APPL class is active, the security product verifies that 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 is used to process 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.
Avoid trouble: We can configure the SAFRunAS directive for resources that are processed with the Action directive. You must configure the SAFRunAS directive in a scope that covers the second parameter of the Action directive instead of the path to the original resource.A typical use of the SAFRunAs directive is in the Location directive. See the following example:<Location /context-root-A/> SAFRunAS %%CLIENT%% </Location>
Requests to paths that contain the /context-root-A/* prefix run as the remote user. However, when you also use the Action directive, the server overrides the context root that it uses for matching:
# 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. When you include the Action directive, also include a SAFRunAs directive in the Location directive. See the following example:
<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 |
[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.
Note:SAFRunAsEarly must be used in <Location> contexts, or the global context. It cannot be used in <Directory> contexts.
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 # mod_authz_core typically loads by default LoadModule authz_core_module modules/mod_authz_core.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, we can provide a list of specific SAF users # who may access the resource. # Require saf-user USER84 USER85 # # Alternatively, we can provide a list of specific SAF groups # whose members may access the resource. # Require saf-group WASGRP1 WASGRP2 </Location>
Avoid trouble: The SAF group must have a group identification number (GID) defined in the OMVS segment to restrict access based on SAF group membership. Use the following Time Sharing Option (TSO) command to determine whether an OMVS GID is defined for a SAF group.
LISTGRP NOGIDGRP OMVS NORACF
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 # mod_authz_core typically loads by default LoadModule authz_core_module modules/mod_authz_core.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>
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 # mod_authz_core typically loads by default LoadModule authz_core_module modules/mod_authz_core.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 </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 # mod_authz_core typically loads by default LoadModule authz_core_module modules/mod_authz_core.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 # mod_authz_core typically loads by default LoadModule authz_core_module modules/mod_authz_core.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.
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
- Use the AuthBasicProvider directive for SAF password authentication
- FastCGI directives
- Secure Sockets Layer (SSL) directives