[z/OS]

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.

AuthSAF directive

The AuthSAF directive sets whether basic authentication is performed using the operating system's SAF.

Syntax AuthSaf on | off
Default off
Context directory, .htaccess
Module mod_auth_saf
Values on or off

Set the AuthSAF directive on to use any of the SAF facilities: SAFRunAs, SAFRequire, or SAF authentication. When you set AuthSAF on, you should also set AuthType Basic.

You must set a Require directive for valid-user or for a list of users.

Example: valid-user
Require valid-user 
With valid-user, the server will not allow access unless the ID and password belong to a user who is registered in SAF and has an OMVS segment.
Example: list of users
Require user SYSADM USER152 BABAR 

With a list of users, the server will not allow access unless the ID is authenticated and is one of the users listed. You must code user names with upper case letters in the httpd.conf file, regardless of how the user enters the user names at the browser.

You can optionally add a Require directive for a group.

Example: list of groups
Require group SYS1 WASUSER 

In this example, the groups SYS1 and WASUSER must be defined in SAF and must have OMVS segments. Access is denied unless the ID and password belong to a user registered in SAF and in one of the groups listed.

AuthSAFAuthoritative directive

The AuthSAFAuthoritative directive sets whether authorization and authentication are passed to lower level modules.

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

Setting the AuthSAFAuthoritative directive off allows for both authentication and 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's prompt.

Syntax AuthSAFExpiration short_phrase
Default off
Context directory, .htaccess
Module mod_auth_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"
AuthSAF on
Require valid-user
Require 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.

Syntax AuthSAFReEnter short_phrase
Default Re-enter new password
Context directory, .htaccess
Module mod_auth_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"
 AuthSAF on
 Require 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.

SAFRequire directive

The SAFRequire directive determines whether mod_auth_saf will process the Require directive.

Syntax SAFRequire on | off
Default off
Context directory, .htaccess
Module mod_auth_saf
Values on or off

Setting the SAFRequire directive on allows mod_auth_saf to process the user names and group names in the Require directive. If you use groups defined in SAF, you must set the directive on, but if you use groups defined elsewhere, you should set the directive off or omit the directive.

For example, mod_auth_saf can process the Require directive if you code the AuthGroupFile directive instead of coding SAFRequire on. Do not code both.

If you set SAFRequire on, list all user names in upper case letters because this is how SAF maintains the user names. The user can enter the user name and password in any case letters at the browser. If you do not use mod_auth_saf to process the Require directive, then you might need to code each user name in every assortment of case letters in which you expect the user might enter them at a browser.

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

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

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

<surrogate ID>: The server will run the request under the ID associated with the SAF surrogate ID specified.

For %%CERTIF%%, %%CERTIF_REQ%%, and all other forms of SAF authentication or authorization, you must code a Require directive and set the AuthSAF directive on.

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.

Example [Fix Pack 11 or later]

If you want to use basic SAF authentication, consider the following container definition.
<Location /x1>
AuthType Basic  
AuthName x1  
Require valid-user  
SAFRequire On  
AuthSAF on
</Location>
If you want to limit access to a short list of users, consider the following container definition.
Note: The AuthAuthoritative directive must be used when you use the Require user directive, and the list of names must contain uppercase letters only.
<Location /x2>
	AuthType Basic  
	AuthName x2  
	Require user ALICE123 BOB456 CAROL789 
	SAFRequire On  
	AuthSAF on
	<IfModule mod_auth.c>
# If mod_auth is loaded, ensure that it allows other 
# modules to authenticate in case mod_auth runs first.
	AuthAthoritative off
	</IfModule>
</Location>
If you want to limit access to a group defined in SAF, consider the following container definition.
<Location /x3>
AuthType Basic  
AuthName x3  
Require group WASUSER  
SAFRequire on  
AuthSAF on
</Location>
If you want to use SAF authentication with either the AuthUserFile or the AuthGroupFile directive, consider the following container definition.
Note: If you set the value of the SAFRequire directive to on, you cannot use the AuthUserFile or AuthGroupFile directives. The list of users must be set by the Require user directive or in the SAF group. If the SAFRequire directive is set to off, you can use a user list or group defined by either the AuthUserFile or the AuthGroupFile directive, but the name matches are case-sensitive for IBM HTTP Server.
<Location /x4>
	AuthType Basic  
	AuthName x4  
	Require group wasuser  
# File x4.grp contains this line: wasuser: alice123 ALICE123 	guest3 GUEST3  	AuthGroupFile /usr/lpp/config/x4.grp
	AuthBasicProvider saf
</Location>



Related tasks
Authenticating with SAF on IBM HTTP Server (z/OS systems)
Related reference
FastCGI directives
Reference topic Reference topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Aug 31, 2013 6:08:30 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=ihs-dist&topic=rihs_safdirs
File name: rihs_safdirs.html