How to configure authorization levels with an LDAP user registry

Configure authorization to control which users can perform specific actions on IBM® z/OS® Connect APIs or services by using an LDAP 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 LDAP 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 use an LDAP user registry to authenticate and authorize the users. For example, you can use one of the following methods:
- Use basic authentication as described in the task How to configure basic authentication with an LDAP user registry.
- Authenticate with a JWT where the identity in the claim is an LDAP user ID.
- Use client certificate authentication where the distinguished name of the client certificate subject has been mapped to an LDAP user ID.

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 LDAP 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 LDAP 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 LDAP 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: Configure the LDAP groups to be assigned to each authorization level at the global scope.
The LDAP 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="cn=admins\,ou=groups\,o=mop\,c=fr"
    globalInvokeGroup="cn=customers\,ou=groups\,o=mop\,c=fr"
    globalOperationsGroup="cn=employees\,ou=groups\,o=mop\,c=fr"
    globalReaderGroup="cn=partner1\,ou=groups\,o=mop\,c=fr, cn=guests\,ou=groups\,o=mop\,c=fr"
    ... />
```
The values of the group attributes must be one or more LDAP group distinguished names (DNs), with the commas within the names escaped with a backslash. The values are case-insensitive. To specify multiple groups for any role, use a comma-separated list, as shown for the globalReaderGroup, with the commas separating the groups not escaped.
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.
Do not perform this step if you require the authorization interceptor to be configured globally. Use this configuration to control authorization for specific APIs or services only, or to restrict the services that are returned by the RESTful administration actions to "list all services" or "get statistics for all services".
1. Remove globalInterceptorsRef="interceptorList1" from the zosconnect_zosConnectManager element if specified.
2. 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.
3. 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 LDAP groups to authorization levels at the API or service scope.
These groups take precedence over the global groups. However, there are additional considerations for the RESTful administration actions to deploy an API, deploy a service, list all APIs, or list all services. For more information, see API provider authorization.
1. Define either globalInterceptorsRef="interceptorList1" on the zosconnect_zosConnectManager element, or interceptorsRef="interceptorList1" on the zosConnectAPI or service element.
2. 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="cn=admins\,ou=groups\,o=bank\,c=fr"
        invokeGroup="cn=customers\,ou=groups\,o=bank\,c=fr"
        operationsGroup="cn=ops\,ou=groups\,o=bank\,c=fr"
        readerGroup="cn=appdev\,ou=groups\,o=bank\,c=fr, cn=auditors\,ou=groups\,o=bank\,c=fr"
    ... />
</zosconnect_zosConnectAPIs>
```
  The values of the group attributes must be one or more LDAP group distinguished names (DNs), with the commas within the names escaped with a backslash. The values are case-insensitive. o specify multiple groups for any role, use a comma-separated list, as shown for the globalReaderGroup, with the commas separating the groups not escaped.
3. 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="cn=admins\,ou=groups\,o=sales\,c=fr"
        invokeGroup="cn=customers\,ou=groups\,o=sales\,c=fr"
        operationsGroup="cn=ops\,ou=groups\,o=sales\,c=fr"
        readerGroup="cn=managers\,ou=groups\,o=sales\,c=fr"
    ... />
</zosconnect_services>
```
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 LDAP 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.