How to activate and configure the SAF user registry

Activate the System Authorization Facility (SAF) user registry and configure it to use z/OS® authorized services.

Before you begin

You should be familiar with the following topics:
- API provider authentication and identification when IBM z/OS Connect is acting as an API provider.
- API requester authentication and identification when IBM z/OS Connect is acting as an API requester.
You must have write access to the server.xml configuration file.

About this task

You activate and configure the SAF user registry in the IBM z/OS Connect server. This user registry has access to the user IDs and groups that are defined to SAF on the same z/OS LPAR as the IBM z/OS Connect server, so they can be used for authentication and authorization.

By default, the SAF user registry uses unauthorized UNIX System Services services such as __passwd to perform authentication. For better performance, you can configure the SAF user registry to use authorized services such as initACEE to perform authentication by configuring the SAFCRED resources.

Procedure

Define the SAFCRED resources and permit the IBM z/OS Connect server access to use z/OS authorized services.
For more information, see Configuring the Liberty Angel process and z/OS authorized services.
Define a SAF user ID to act as the SAF user registry's unauthenticated user (the default value is WSGUEST).
For more information, see SAF unauthenticated user ID.
Define the SAF APPL profile to be used by the server and permit the SAF unauthenticated user ID and all SAF user IDs that are to be authenticated, READ access to that profile.
See Authenticating a user in the topic Accessing z/OS security resources using WZSSAD of the WebSphere® Application Server for z/OS Liberty documentation.
Activate the SAF user registry.
Add the zosSecurity-1.0 feature into the featureManager element in the server.xml configuration file.
```
<featureManager>
    ...
    <feature>zosSecurity-1.0</feature>
</featureManager>
```
Configure the SAF user registry.
Add a safRegistry element in the server.xml configuration file:
```
<safRegistry/>
```
For more information about the safRegistry element, see the Server configuration section in the IBM WebSphere Application Server for z/OS Liberty documentation.
Configure the server to control the operations of the SAF credentials.
The server uses the SAF APPL profile and SAF unauthenticated user ID that you defined in steps 2 and 3.
The default profile prefix value is BBGZDFLT. If you chose a custom value, you must specify that value on profilePrefix attribute of the safCredentials element in the server.xml configuration file.

The default SAF unauthenticated user ID value is WSGUEST. If you chose a custom value, you must specify that value on the unauthenticatedUser attribute of the safCredentials element in the server.xml configuration file.
For example, to use a custom profile prefix value of "MYPROFILE" and a custom SAF unauthenticated user ID of "MYGUEST", add the following element to the server.xml configuration file.
```
<safCredentials 
    profilePrefix="MYPROFILE" 
    unauthenticatedUser="MYGUEST"/>
```
If unauthorized users attempt to access the WLP z/OS System Security Access Domain (WZSSAD) and attribute suppressAuthFailureMessages="false" is specified, SAF authorization messages such as RACF ICH408I are displayed. For more information about safCredentials, see the Server configuration section in the IBM WebSphere Application Server for z/OS Liberty documentation.

To use the default values, omit the safCredentials element.
Ensure that the Liberty profile angel process is running.
To use z/OS authorized services, the server must be able to connect to the Liberty profile angel process. You created a started task to run the Liberty angel process and permit the IBM z/OS Connect server to access it in step 1.
To start the angel process, start the associated started task by entering the following MVS command from SDSF:
/S BAQZANGL

For more information about starting the angel process and checking that it started successfully, see Configuring the Liberty Angel process and z/OS authorized services.
Configure the IBM z/OS Connect server to require an angel process.
Set com.ibm.ws.zos.core.angelRequired to true to require a successful connection to an angel process for the server startup to continue. For more information, see Configuring named angels.
Ensure that the SAFCRED authorized service is available to the IBM z/OS Connect server.
If you specify the bootstrap.properties property com.ibm.ws.zos.core.angelRequiredServices, ensure that SAFCRED is included in the value list. For more information, see Process types on z/OS in the WebSphere Application Server for z/OS Liberty documentation.
Start the IBM z/OS Connect server.
Start, or restart the server if it was already running, so that it connects to the angel process. The following messages are written to the messages.log file:
```
CWWKB0122I: This server is connected to the default angel process.
CWWKB0103I: Authorized service group KERNEL is available.
CWWKB0103I: Authorized service group SAFCRED is available.
```
Other authorized services, as defined in previous steps of this task, are also listed as available.

Results

The SAF user IDs and groups are now available to the SAF user registry and can be used by the IBM z/OS Connect server, for authentication and authorization.