Configuring interceptors

IBM® z/OS® Connect provides a framework that enables interceptors (exit programs) to be invoked for API, service, API requester, and administration requests. Interceptors are OSGi services that implement the com.ibm.zosconnect.spi.Interceptor Service Provider Interface (SPI) that is provided by z/OS Connect.

About this task

zosConnect-2.0 Applies to zosConnect-2.0.

Interceptors can be configured either globally in a z/OS Connect Server by setting the globalInterceptorsRef attribute of the zosConnectManager element, or specifically for APIs, services, or API requesters by setting the interceptorsRef attribute on the appropriate zosConnectAPI, service, zosConnectService, or apiRequester element. If interceptors are configured globally, by default they apply to all APIs, services, and API requesters, because the zosConnectAPI, service, zosConnectService, and apiRequester elements all have the default setting of runGlobalInterceptors="true". To prevent global interceptors run for an individual API, service, or API requester, specify runGlobalInterceptors="false" on the relevant element.

Note:
  1. Interceptors that are configured for services are only triggered if the service is invoked directly from an HTTP or HTTPS request, they are not triggered if the service is invoked from an API.
  2. If an interceptor is configured at both the global level and specifically for an API, service, or API requester, then the interceptor is called twice. For example, if this configuration is used for the audit interceptor, then two SMF 123 records are written for each request.
z/OS Connect provides three interceptors:
  1. The file system logger interceptor enables z/OS Connect users to log information about API and service requests in a file. This interceptor is not called for API requester invocations.
  2. The audit interceptor is used to audit and track requests. For more information, see Using SMF records to monitor requests
  3. The authorization interceptor controls access to z/OS Connect artifacts by assigning users one of four authorization levels, Admin, Operations, Invoke and Reader. These authorization levels are set in the global, API, service, or API requester configuration elements. For more information, see Overview of IBM z/OS Connect security and the subtopics relating to security authorization.

You can use interceptors for many purposes. z/OS Connect provides the same information to all interceptors regardless of their purpose. For example, an interceptor might be written to perform some infrastructure setup that is based on the message payload before the request is processed. z/OS Connect provides a copy of the input request payload to all interceptors.

This task describes how to configure custom z/OS Connect interceptors and how to enable those interceptors globally for the z/OS Connect Server.

If defined, interceptors are called in a specific order:
  1. Global interceptors preInvoke methods
  2. API, service, or API requester interceptors preInvoke methods
  3. The requested API, service, or API requester operation is performed.
  4. API, service, or API requester interceptors postInvoke methods
  5. Global interceptors postInvoke methods
Within each category, the sequence attribute determines the order in which the interceptors run. For preInvoke methods, the lowest number runs first. For postInvoke methods, the lowest number runs last. If the sequence numbers are the same, there is no set order. If the sequence is not defined or incorrectly defined, these interceptors run their preInvoke methods after all other interceptors of the same type, and their postInvoke methods before all other interceptors of the same type. For example, if you want the audit interceptor to capture failed authorization requests then you need to ensure that the sequence number of the audit interceptor is lower than that of the authorization interceptor. For more information, see com.ibm.zosconnect.spi.Interceptor.

Procedure

Create a global interceptor list and enable it in the zosconnect_zosConnectManager element.
The globalInterceptorsRef attribute is the ID of the configuration element that describes the list of z/OS Connect interceptors that apply globally within the server. The interceptorsRef attribute is a comma-separated list of the interceptors to be applied. In this example, two user-created interceptors are configured.
<zosconnect_zosConnectManager globalInterceptorsRef="globalInterceptors"/> 

<!-- User Interceptor definitions -->
<usr_userInterceptorOne id="userI1" sequence="1"/> 
<usr_userInterceptorTwo id="userI2" sequence="2"/> 

<!-- Global interceptor definitions -->
<zosconnect_zosConnectInterceptors id="globalInterceptors" interceptorRef="userI1, userI2"/>