How to configure authorization levels with a basic user registry

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

  1. 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.
  2. 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.

  3. 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.

  1. 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.

  2. 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>
  3. 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.
    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.

  4. 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.
    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="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.
    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="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.
  5. 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.