Configure authorization to control which users can perform specific actions on IBM® z/OS® Connect APIs or services using a SAF user
registry.
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 various authorization levels to
which APIs or services.
- Both the SAF user ID associated with any request, and the SAF groups assigned to the authorization levels 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 server.xml configuration file.
- You must have configured the IBM z/OS Connect
server to authenticate the SAF user IDs, and ensure that each of those user IDs is associated with a
group in the SAF registry. These tasks are described in How to configure basic authentication with a SAF user registry or, if
authenticating with a JWT whose subject claim is, or is mapped to, a SAF user ID, How to configure JWT authentication.
About this task
Configure a IBM z/OS Connect server to perform
authorization checks by using the IBM z/OS Connect
authorization interceptor. You assign SAF groups to each of the authorization levels:
admin, operations, invoke and reader globally
or for a specific API or service.
You configure the authorization interceptor at the global scope with SAF groups that are assigned
to each of the global authorization levels. The configuration examples demonstrate the following
options:
- How specific APIs or services can opt out of using the globally configured authorization
interceptor. See examples for "Api1" and "Service1" in step 5.
- How the authorization interceptor can be configured only for specific APIs or services instead
of at the global scope. See examples for "Api2" and "Service2" in step 6.
- How different SAF groups can be assigned to each of the authorization levels for specific APIs
or services. See examples for "Api3" and "Service3" in step 7.
Note:
- If the interceptor is configured for both an API and the service it calls, then an HTTP or HTTPS
request to invoke the API drives only the interceptor for the API. If the interceptor is configured
for a service, then it is only driven if that service is invoked directly by an HTTP or HTTPS
request.
- If you want to configure authorization for the RESTful administration actions such as deploy an
API, deploy a service, get a list of APIs, get a list of services, or get statistics for multiple
services, additional configuration is needed. For more information, see the API provider authorization.
Procedure
-
Configure the IBM z/OS Connect authorization
interceptor.
Add the following element to the
server.xml configuration
file:
<zosconnect_authorizationInterceptor id="zosConnectAuthorizationInterceptor"/>
For
more information about the
zosconnect_authorizationInterceptor
element see
zosconnect_authorizationInterceptor in the
Reference section.
- Configure which interceptors are to be called.
The
IBM z/OS Connect authorization interceptor is called by
referencing it in the following element of the
server.xml configuration
file:
<zosconnect_zosConnectInterceptors id="interceptorList1"
interceptorRef="zosConnectAuthorizationInterceptor"/>
In
this example,
zosConnectAuthorizationInterceptor is the
id
attribute value of the referenced
zosconnect_authorizationInterceptor
element.
For more information about the zosconnect_zosConnectInterceptors
element, see zosconnect_zosConnectInterceptors
in the Reference section.
- Optional: Configure the authorization interceptor at
the global scope.
Perform this step to assign the SAF groups that are authorized by
default to perform actions on all APIs and services. These global groups are also used to authorize
access to RESTful administration actions to deploy an API, deploy a service, list all APIs, list all
services, and get statistics for all services.
To configure the authorization interceptor
globally, add the
globalInterceptorsRef
attribute to the
zosconnect_zosConnectManager
element. For
example:
<zosconnect_zosConnectManager
globalInterceptorsRef="interceptorList1"
... />
In
this example,
interceptorList1 is the
id
attribute value of
the referenced
zosconnect_zosConnectInterceptors
element.
Perform step 4 only
if you have completed step 3.
- Optional: Configure the SAF groups and default groups
to be assigned to each authorization level at the global scope.
The SAF groups are
authorized by default to perform actions on all APIs and services. These global groups are also used
to authorize access to RESTful administration operations to deploy an API, deploy a service, list
all APIs, and list all services.
To configure the authorization level groups globally, add the
attributes to define the groups to the
zosconnect_zosConnectManager
element. For
example:
<zosconnect_zosConnectManager
globalInterceptorsRef="interceptorList1"
globalAdminGroup="GMADMIN"
globalInvokeGroup="GMINVOKE"
globalOperationsGroup="GMOPER"
globalReaderGroup="GMREADER, GMGUEST"
... />
The values of the group attributes must be one or more SAF group names. The values are
case-insensitive. To specify multiple groups for any role, use a comma-separated list, as
shown for the globalReaderGroup.
For more information about the zosconnect_zosConnectManager
element, see zosconnect_zosConnectManager in
the Reference section.
- Optional: Opt out of using the authorization interceptor's global scope for
an individual API or service.
If the authorization interceptor is configured at the
global scope, authorization checks are applied to all requests for APIs and services because, by
default, APIs and services run all the global interceptors, in addition to any interceptors
configured specifically at the API or service scope.
To opt out of running the authorization
interceptor for API Api1, ensure that a
zosConnectAPI
element for Api1 is
configured and add the
runGlobalInterceptors="false"
attribute to it. For
example:
<zosconnect_zosConnectAPIs>
<zosConnectAPI name="Api1"
runGlobalInterceptors="false"
... />
</zosconnect_zosConnectAPIs>
To opt out of running the authorization interceptor for service Service1, ensure there is a
service element for Service1 and add the
runGlobalInterceptors="false"
attribute
to it. For
example:
<zosconnect_services>
<service name="Service1"
runGlobalInterceptors="false"
.../>
</zosconnect_services>
- Optional: Configure the authorization interceptor for specific APIs or
services.
Perform this step only if you do not require the authorization interceptor to
be configured globally and only need to control authorization for specific APIs or services; or
because you wish to restrict the services returned by the RESTful administration actions to list all
services or get statistics for all services.
- Remove
globalInterceptorsRef="interceptorList1"
from the
zosconnect_zosConnectManager
element, if specified.
- Optional: Configure the authorization interceptor for the specific
API.
For example, for the API Api2, ensure that a
zosConnectAPI
element for Api2 is configured and add the
interceptorsRef
attribute to it. For
example:
<zosconnect_zosConnectAPIs>
<zosConnectAPI name="Api2" interceptorsRef="interceptorList1"
... />
</zosconnect_zosConnectAPIs>
In
this example,
interceptorList1 is the
id
attribute value of
the referenced
zosconnect_zosConnectInterceptors
element.
- Optional: Configure the authorization interceptor for a specific
service.
For example, for the service Service2, ensure that a
service
element for
Service2 is configured and add the
interceptorsRef
attribute to it. For
example:
<zosconnect_services>
<service name="Service2"
interceptorsRef="interceptorList1"
... />
</zosconnect_services>
In
this example,
interceptorList1 is the
id
attribute value of
the referenced
zosconnect_zosConnectInterceptors
element.
For more information about the API
and service
elements, see
zosConnectAPI and service in the Reference section.
- Optional: Assign the SAF groups to authorization levels at the API or service
scope.
These groups take precedence over the global groups except when controlling
authorization to the RESTful administration actions to deploy an API, deploy a service, list all
APIs, or list all services.
- Define either
globalInterceptorsRef="interceptorList1"
on the
zosconnect_zosConnectManager
element, or
interceptorsRef="interceptorList1"
on the zosConnectAPI
or
service
element.
- Optional: To configure the authorization level groups for the API Api3,
ensure that a
zosConnectAPI
element for Api3 is configured and add the attributes
to define the groups to it. For example:
<zosconnect_zosConnectAPIs>
<zosConnectAPI name="Api3"
adminGroup="A3ADMIN"
invokeGroup="A3INVOKE"
operationsGroup="A3OPER"
readerGroup="A3READER"
... />
</zosconnect_zosConnectAPIs>
In
this example, the values of the group attributes must be the SAF group names. The values are
case-insensitive.
- Optional: To configure the authorization level groups for service
Service3, ensure that a service element for Service3 is configured and add the attributes to
define the groups to it.
For
example:
<zosconnect_services>
<service name="Service3"
adminGroup="S3ADMIN"
invokeGroup="S3INVOKE"
operationsGroup="S3OPER"
readerGroup="S3READER"
... />
</zosconnect_services>
In
this example, the values of the group attributes must be the SAF group names. The values are
case-insensitive
Note: If a group is to be assigned to the same authorization level at all scopes, then it can be
specified at the global scope and inherited by all APIs and services. For example, to assign the
same group to the reader authorization level at all scopes, set the
globalReaderGroup
attribute of the zosconnect_zosConnectManager
element, and omit the readerGroup
attribute of each individual API or service
element that inherits it.
- Update the server configuration or restart the server.
Results
Your IBM z/OS Connect
server is configured to perform authorization checks by using the IBM z/OS Connect authorization interceptor, and SAF groups
are assigned to each of the authorization levels.