API requester authorization

Learn how z/OS® Connect authorizes both access to z/OS Connect and the actions that can be performed on API requesters.

zosConnect-2.0 Applies to zosConnect-2.0.

Before you study this topic, you should be familiar with the information in Overview of IBM z/OS Connect security and API requester authentication and identification.

z/OS Connect authorization normally occurs after authentication completes successfully. The following checks are performed:

Authorization to access z/OS Connect. The server checks the requireAuth attribute value set in the server.xml configuration file. By default, this value is set to true. When true, an authorization check is performed to ensure that the authenticated user ID is assigned to the zosConnectAccess role. This behavior is described in Authorization to access z/OS Connect.
Authorization to perform specific actions on API requesters. IBM® z/OS Connect checks whether the authorization interceptor is enabled. If so, then it checks whether the authenticated user ID is a member of a user registry group, and whether that group is assigned to the appropriate authorization level. This behavior is described in Authorization to perform specific actions on API requesters.

Figure 1 shows the normal z/OS Connect authorization flow. In the diagram, z/OS application can be a CICS, IMS, or z/OS application.

The identity of the requester is checked if requireAuth is true and, if so, is the User ID in the Role. If not, the connection is rejected. — Figure 1. Authorization flow for API requester

Authorization to access z/OS Connect

The first authorization check that is performed by the IBM z/OS Connect server is to control whether the authenticated user ID is authorized to access IBM z/OS Connect. This check occurs when the server.xml configuration file attribute requireAuth is set to true. The attribute requireAuth can be set globally for all API requesters in the z/OS Connect server, or for individual API requesters. The requireAuth attribute is primarily used to control authentication, see API requester authentication and identification, but is also used for this authorization check.

This authorization is controlled by the zosConnectAccess role, and access is granted by assigning user IDs associated with requests to that role. The request user ID must be defined in the z/OS Connect server’s user registry. If a distributed ID is mapped to a user registry user ID, then the authorization check is performed against the mapped user ID.

There are two methods of assigning user IDs to the zosConnectAccess role:

The SAF EJBROLE class profile profilePrefix.zos.connect.access.roles.zosConnectAccess. This can be defined with users and groups given READ access to it. For more information, see How to configure the zosConnectAccess role with a SAF user registry.
The authorization-roles element defined in the server.xml configuration file. You can either assign individual users and groups to the role, or you can authorize all authenticated users to the role by using the <special-subject type="ALL_AUTHENTICATED_USERS"/>.

Authorization to perform specific actions on API requesters

You can use a more granular level of authorization to control which users can perform specific actions on API requesters. This authorization is implemented by the IBM z/OS Connect authorization interceptor.

The authorization interceptor defines four authorization levels. A comma-separated list of user registry groups can be assigned to each level. Both the authorization interceptor and the user registry groups can be defined at various scopes. Access to a specific authorization level is granted by ensuring that the user ID associated with the request is a member of the user registry group that is assigned to that authorization level at the appropriate scope. If a distributed identity is mapped to a SAF user ID, then the authorization check is performed against the mapped SAF user ID and its group in the SAF registry. When a SAF registry is used by the IBM z/OS Connect server, then OMVS segments must be defined for both the SAF user ID and group.

You can use existing user registry groups, or create new groups. If you create new groups, consider whether you want the group names to indicate the authorization level they control, and also the associated scope. For example, you can create separate groups to control API requesters that belong to different lines of business.

The authorization levels are as follows:

Admin: All z/OS Connect actions are allowed, including all Operations, Invoke, and Reader actions.
Operations: All z/OS Connect operations and actions are allowed except for Invoke.
Invoke: Ability to invoke APIs and services. Invoke authority does not provide access to z/OS Connect Operations actions.
Reader: Ability to obtain information about API requesters. Reader authority does not provide access to z/OS Connect Operations actions nor does it provide access to invoke API requesters.

See Table 1 for the authorization levels required to perform specific requests.

The z/OS Connect authorization interceptor can be configured at the following scopes:

Globally for the z/OS Connect server. By default, this configuration enables the authorization interceptor for all API requesters. An individual API requester can opt out of running the global interceptors.
For specific API requesters. If only required for a few API requesters, this configuration is an alternative to enabling the authorization interceptor globally.

The user registry groups assigned to each of the authorization levels can also be configured at the following scopes:

Globally for the z/OS Connect server. The user registry groups that are assigned at this scope become the default groups for actions that are performed on all API requesters.
For specific API requesters. If authorization is required for only a few API requesters, this configuration is an alternative to enabling the authorization interceptor globally.

The user registry groups assigned to each of the authorization levels can also be configured at the following scopes:

Globally for the z/OS Connect server. The user registry groups that are assigned at this scope become the default groups for actions that are performed on all API requesters.
For specific API requesters. The user registry groups that are assigned at this scope take precedence over the global groups.

If you require all or most API requester requests to be authorized, you can configure the authorization interceptor globally for the IBM z/OS Connect server and assign the default user registry groups. If you need to restrict specific API requesters to different users, you can then assign specific user registry groups to those individual API requesters, to override the global groups. See Table 1 for details of the authorization levels required to perform different requests.

Table 1. Authorization levels required to perform requests
Request type	Global authorization level configuration	Specific API requester level configuration (overrides global level)
Invoke an API requester. (See note).	Admin or Invoke.	Admin or Invoke.
Get a list of API requesters.	Admin, Operations, or Reader.	Only global authorization applies.
Get details of an API requester.	Admin, Operations, or Reader.	Admin, Operations, or Reader.
Deploy an API requester.	Admin or Operations.	Only global authorization applies.
Update an API requester.	Admin or Operations.	Admin or Operations.
Delete an API requester.	Admin or Operations.	Admin or Operations.
Change status of an API requester (start or stop).	Admin or Operations.	Admin or Operations.
Get z/OS Connect admin Swagger doc.	Admin, Operations, or Reader.	Only global authorization applies.

Note: When a user is authorized to invoke an API requester, the user is allowed to invoke all operations of the RESTful API as described in its Swagger document.

For more information about the authorization levels that are required to perform specific RESTful administration actions for API requesters, see How to use the RESTful administration interface to manage API requesters.