How to define SAF profiles for authorization roles

Define SAF EJBROLE profiles for each of the roles defined in your OpenAPI definitions and authorize the appropriate SAF users and groups to those profiles.

This topic is applicable to: z/OS Connect server on
z/OS

This task is applicable when IBM® z/OS® Connect is used as an API provider.

Before you begin

You should be familiar with the information in API provider authorization.
You need to know which user IDs and groups are to be granted authorization to which APIs roles.
The SAF user IDs and SAF groups permitted access to the EJBROLE profiles must have OMVS segments. If you use RACF®, specify the following OMVS segment parameters:
- AUTOGID or GID(group-identifier) on the ADDGROUP or ALTGROUP command.
- AUTOUID or UID(user-identifier), HOME and PROGRAM on the ADDUSER or ALTUSER command. For example: OMVS(AUTOUID HOME(/u/user) PROGRAM(/bin/sh)).
You must have write access to the configuration file.
You must have configured IBM z/OS Connect to authenticate the SAF user IDs either directly or by mapping a JWT or TLS client certificate to a SAF user. See the following tasks:
- How to configure basic authentication with a SAF user registry.
- If authenticating with a JWT whose subject claim is, or is mapped to, a SAF user ID, How to configure JWT authentication mapped to SAF.
- If authenticating a client certificate mapped to a SAF user, How to configure client certificate authentication with RACF.

About this task

Define SAF EJBROLE profiles for each of the roles defined in the OpenAPI definitions and permit the appropriate RACF users and groups READ access to those profiles.

The users and groups permitted READ access to the EJBROLE profiles are authorized to invoke the corresponding API operations protected with the OpenAPI definitions specification extension x-ibm-roles-allowed values.

This task uses RACF as the security manager for IBM z/OS Connect. If you are using an alternative External Security Manager, refer to the appropriate product documentation for the equivalent commands.

Procedure

Configure IBM z/OS Connect to use SAF for authorization.
For example, add the following to the configuration file:
```
<safAuthorization/>
```
To display SAF authorization messages such as RACF ICH408I, when unauthorized users attempt to access IBM z/OS Connect, specify the attribute racRouteLog="ASIS".

For more information about the safAuthorization element, see the Server configuration section in the WebSphere® Application Server for z/OS Liberty documentation.
Optional: Customize the prefix used for SAF profiles.
This is specified by the profilePrefix attribute of the safCredentials element in the configuration file.
The default value is profilePrefix="BBGZDFLT".

For more information, see safCredentials in the WebSphere Application Server for z/OS Liberty documentation.
Optional: Customize the SAF EJBROLE profile name for API roles.
This is specified by the profilePattern attribute of the safRoleMapper element in the configuration file. The default value is profilePattern="%profilePrefix%.%resource%.%role%".
where:
- %profilePrefix% value is the value of the profilePrefix attribute on the safCredentials element, by default "BBGZDFLT".
- %resource% is either the value of the name attribute of the webApplication element for the API .war file. If not specified, then the file name of the API .war file.
  For example,
  
  If the configuration file contains <webApplication name="Employees" location="${server.config.dir}/apps/api.war"> then the %resource% value will be Employees.
  
  If the configuration file contains <webApplication location="${server.config.dir}/apps/api.war"> then the %resource% value will be api.
- %role% is a value from the x-ibm-zcon-roles-allowed OpenAPI definition specification extension for the API operation or globally for the API.
For more information, see safRoleMapper in the WebSphere Application Server for z/OS Liberty documentation.
Define the SAF EJBROLE profile.
For example, to define a SAF EJBROLE profile for the Employees API role Manager using the default profilePrefix value, issue the RACF command:
```
RDEF EJBROLE BBGZDFLT.Employees.Manager UACC(NONE)
```
Repeat for each API role requiring authorization.
Note: RACF supports the use of generic profile names. See Creating resource group profiles and Other rules for generic profile names.
Activate the EJBROLE class.
Issue the following RACF command:
```
SETROPTS CLASSACT(EJBROLE)
```
Permit access to the SAF EJBROLE profile.
For example, to permit RACF user SALLY to the Employees API role Manager, issue RACF command:
```
PERMIT CLASS(EJBROLE) BBGZDFLT.Employees.Manager ACCESS(READ) ID(SALLY)
```
Repeat for each API role requiring authorization and each user or group requiring access.
Note: The ID value can be either a RACF user or RACF group.
Refresh the EJBROLE class.
Issue the following RACF command:
```
SETROPTS RACLIST(EJBROLE) REFRESH
```
Ensure the user IDs and groups have also been granted READ access to the profilePrefix APPL profile.
This is described in the task How to activate and configure the SAF user registry.
For example, to permit user SALLY access to the default profilePrefix BBGZDFLT, issue the following RACF command:
```
PERMIT BBGZDFLT CLASS(APPL) ACCESS(READ) ID(SALLY)
```

Results

SAF EJBROLE profiles have been defined for the API roles and appropriate RACF users and groups have been permitted access to those profiles. These users are authorized to invoke the API operations.