Configure authorization to control which users can perform specific actions on IBM® z/OS® Connect APIs or services using a basic 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 users and groups are to be granted various authorization levels to which
APIs or services.
- You must have write access to the server.xml configuration file.
- You must have configured the IBM z/OS Connect
server to authenticate the users, and ensure each of those users is associated with a group in the
basic user registry. These tasks are described in How to configure basic authentication with a basic user registry.
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 basic registry 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 basic user registry 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 basic user registry 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 if you want to control authorization to the RESTful
administration actions to deploy an API, deploy a service, list all APIs, list all services, and get
statistics for all services. It also sets the default authorization for all APIs and 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:
Assign the basic user registry groups to each authorization level at the global
scope.
The basic user registry 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="administrators"
globalInvokeGroup="students"
globalOperationsGroup="opsStaff"
globalReaderGroup="librarians, guests"
... />
The values of the group attributes must be one or more basic user registry 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 that a service
element for Service1 is configured 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. Instead, use this configuration to control authorization only 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 basic user registry 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="a3Operations"
readerGroup="a3Reader"
... />
</zosconnect_zosConnectAPIs>
In
this example, the values of the group attributes must be the basic user registry 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="s3Operations"
readerGroup="s3Reader"
... />
</zosconnect_services>
In
this example, the values of the group attributes must be the basic user registry 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 should inherit 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 basic user
registry groups are assigned to each of the authorization levels.If a request fails an
authorization check, messages are written to the
messages.log file. For
example, if a user attempts to invoke an API, but has reader access only, the following messages are
written:
BAQR0409W: User RoseMoubinou is not authorized to perform the request.
BAQR0428W: The zosConnectAuthorization interceptor encountered an error while processing a request for API myAPI under request URL http://myhost.company.com:9080/myAPI/mydata.
The following messages are returned in the HTTP response
body:
BAQR0409W: User RoseMoubinou is not authorized to perform the request.
BAQR0436W: The zosConnectAuthorization interceptor encountered an error while processing a request for API myAPI.