API provider authorization

Learn how IBM® z/OS® Connect authorizes both access to IBM z/OS Connect and the actions that can be performed on APIs or services.

You should be familiar with the information in Overview of IBM z/OS Connect security and API provider authentication and identification.

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

Authorization to access IBM 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 IBM z/OS Connect.
Authorization to perform specific actions on APIs or services. 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 APIs or services.

Figure 1 shows the IBM z/OS Connect authorization flow.

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

Authorization to access IBM 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 APIs and services in the IBM z/OS Connect server, or for individual APIs or services. The requireAuth attribute is primarily used to control authentication, see API provider 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 IBM 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 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"/>. For more information, see How to configure the zosConnectAccess role with a basic user registry and How to configure the zosConnectAccess role with an LDAP user registry.
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.

Authorization to perform specific actions on APIs or services

You can use a more granular level of authorization to control which users can perform specific actions on APIs or services. 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 the global, API or service scope. A specific authorization level is granted by ensuring that the authenticated user ID 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 SAF mapped 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 APIs and services that belong to different lines of business.

The authorization levels are as follows,

Admin: All IBM z/OS Connect actions are allowed, including all Operations, Invoke, and Reader actions.
Operations: All IBM 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 IBM z/OS Connect Operations actions.
Reader: Ability to obtain information about APIs and services. Reader authority does not provide access to IBM z/OS Connect Operations actions nor does it provide access to invoke APIs or services.

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

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

Globally for the IBM z/OS Connect server. By default, this configuration enables the authorization interceptor for all APIs and services. An individual API or service can opt out of running the global interceptors.
For specific APIs or services. If required for only a few APIs or services, 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 IBM 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 APIs and services.
For specific APIs or services. The user registry groups that are assigned at this scope take precedence over the global groups.

If you require all or most API or service 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 APIs or services to different users, you can then assign specific user registry groups to those individual APIs or services, 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 or service level configuration (overrides global level except where specified)
Invoke an API. (See note 1 ).	Admin or Invoke.	Admin or Invoke (See note 2 ).
Invoke a service.	Admin or Invoke.	Admin or Invoke.
Get a list of APIs.	Admin, Operations, or Reader.	Only global authorization applies.
Get a list of services.	Admin, Operations, or Reader.	Admin, Operations, or Reader required in addition to global authorization. (See note 3 ).
Get details of an API or service.	Admin, Operations, or Reader.	Admin, Operations, or Reader.
Get Swagger document for an API.	Admin, Operations, or Reader.	Admin, Operations, or Reader.
Get request and response schema for a service.	Admin, Operations, or Reader.	Admin, Operations, or Reader.
Deploy an API or service.	Admin or Operations.	Only global authorization applies.
Update an API or service.	Admin or Operations.	Admin or Operations.
Delete an API or service.	Admin or Operations.	Admin or Operations.
Change status of an API or service (start or stop).	Admin or Operations.	Admin or Operations.
Get statistics for all services.	Admin or Operations.	Admin or Operations required in addition to global authorization. (See note 3 ).
Get statistics for a service.	Admin or Operations.	Admin or Operations.
Get IBM z/OS Connect admin Swagger doc.	Admin, Operations, or Reader.	Only global authorization applies.

Note:

When a user is authorized to invoke an API, the user is allowed to invoke all operations of the API as described in its Swagger document.
If an interceptor is driven for an invoke API request, then any interceptor that is configured for the service it calls is not driven. If an interceptor is configured for a service, then it is driven only if that service is invoked directly by an HTTP or HTTPS request.
To authorize the RESTful administration action to get a list of services, the authorization interceptor must be configured globally and the authenticated user ID must be a member of an appropriate global group. This configuration returns a list of all deployed services. However, this action can be further refined by additional authorization checks to restrict the list of services that are returned to only those services for which the authenticated user ID is authorized. This is achieved by further configuring the authorization interceptor at the service scope, and assigning the appropriate service-specific groups. If a service is configured in this way, then it is only included in the list of services that are returned if the authenticated user ID is a member of one of these global groups and one of these service-specific groups. The same behavior applies to using the RESTful administration action to get statistics for all services.

For more information about the authorization levels that are required to perform specific RESTful administration actions for APIs, see Using the RESTful administration interface.

For more information about the authorization levels that are required to perform specific RESTful administration actions for services, see Administering services with the administration interface.