The z/OS Connect EE interceptor framework enables you to deploy additional processing on each HTTP request. You can use one of the z/OS Connect EE provided interceptors (audit, authorization and file system logger), a third-party interceptor (such as Omegamon for JVM for monitoring) or write your own. The authorization interceptor is used for controlling which roles are allowed to make different types of requests, the audit interceptor records SMF 123 records and the file system logger interceptor captures request payload data, primarily for debugging purposes. API requesters support only the authorization and audit interceptors. This article answers the most frequently asked questions about interceptors.
- Why is the configured interceptor not called?
- Can I configure interceptors globally for all APIs?
- Why is the interceptor that is configured for a service not called for an API request?
- Is interceptor sequencing important?
- How do I configure an interceptor?
- How should the authorization interceptor be configured for API toolkit users?
Why is the configured interceptor not called?
The most common reason for not getting the expected behavior from your z/OS Connect EE server is a spelling or capitalization error in server.xml. In many cases if you misspell a configuration element or attribute, you will not get an error in messages.log, the unrecognized element or attribute is just ignored. This is standard Liberty behavior and a consequence of its extensible design, which enables the addition of other product and user features. This means that to check whether your configuration is correct, you need to look for information messages that indicate the configuration has been successfully processed, rather than just error messages, in the messages.log file.
When configuring interceptors, in particular, be aware of the following:
- The zosconnect_zosConnectInterceptors element has an interceptorRef attribute, whereas other elements have an interceptorsRef attribute, note the presence or absence of the âsâ.
- All z/OS Connect EE specific elements have the prefix “zosconnect_
“, with a lowercase ‘c’, whereas some names include “zosConnect” with an uppercase ‘c‘, for example zosconnect_zosConnectInterceptors .
For the correct syntax, always refer to the z/OS Connect EE Configuration Reference.
If you have z/OS Connect EE V18.104.22.168 or later, messages are written to the log to indicate when global, and API and service-specific interceptors have been enabled. For example:
BAQR7096I: z/OS Connect EE interceptor list globalInterceptorList is active with interceptors: auditInterceptor
Can I configure interceptors globally for all APIs?
There are two levels at which you can configure an interceptor to be invoked:
- Global configuration for all requests
Interceptors configured at the global level are invoked for all types of request, API, service and API requester.
- Specific configuration for APIs, services and API requesters
Interceptors can be configured for individual APIs, but there is no global interceptor configuration for all APIs, you need to list every API and set the interceptor configuration for each one. The same applies if you want to configure interceptors for all services or all API requesters, they must all be listed individually.
You can use the runGlobalInterceptors attribute to specify whether any globally defined interceptors are called in addition to the specific interceptors.
Why is the interceptor that is configured for a service not called for an API request?
Interceptors are designed to be driven at entry to, and on exit from, z/OS Connect EE, and therefore interceptors that are configured for a service are only invoked by direct requests to that service, not by API requests that utilize that service.
Is interceptor sequencing important?
The order in which interceptors are run is important if you are using an interceptor that is designed to prevent a request from continuing, such as the authorization interceptor. If you have an interceptor that is performing a monitoring or auditing capability, you need to decide whether you want to capture requests that are failed by another interceptor. For example, if you deploy the authorization interceptor and the audit interceptor, and want to capture SMF records for requests that fail authorization, the audit interceptor must be configured to run before the authorization interceptor.
For any request, the order in which interceptors are invoked is as follows:
- Any interceptors configured at the global level are invoked before any configured at a specific level. This order of processing cannot be changed.
- For any list of interceptors, all interceptors configured with a sequence number greater than zero are invoked before any interceptors with no sequence number, or a sequence number of zero.
- Interceptors with a sequence number greater than zero are invoked in order, starting with the lowest number.
- Interceptors with no sequence number, or a sequence number of zero, are invoked in an undefined order that might vary over time.
- Two or more interceptors with the same sequence number are invoked in an undefined order.
It is advisable to always specify non-zero sequence numbers for interceptors to ensure consistent behavior.
How do I configure an interceptor?
The audit interceptor is used in the following example.
- Configure the audit interceptor:
- Configure an interceptor list:
<zosconnect_zosConnectInterceptors id="interceptorList" interceptorRef="auditInterceptor"/>
You can have multiple zosconnect_zosConnectInterceptors elements, so you can define a global interceptor list and separate lists for APIs and services.
- Configure one of the following sets of requests that will invoke interceptor.
- For all requests:
- For one or more APIs:
<zosconnect_zosConnectAPIs> <zosConnectAPI name=âabcAPIâ interceptorsRef=âinterceptorList"/> <zosConnectAPI name=âxyzAPIâ interceptorsRef=âinterceptorList"/> </zosconnect_zosConnectAPIs>
- For one or more services specified by a service archive file:
<zosconnect_services> <service name="abcSarService" interceptorsRef=âinterceptorList"/> <service name="xyzSarService" interceptorsRef=âinterceptorList"/> </zosconnect_services>
- For one or more old style services, i.e. services which use bind files and JSON schema:
<zosconnect_zosConnectService id=âservice1â serviceName=âmyServiceâ interceptorsRef=âinterceptorList"/> <zosconnect_zosConnectService id=âservice2â serviceName=âmyServiceâ interceptorsRef=âinterceptorList"/>
- For one or more API requesters:
<zosconnect_apiRequesters> <apiRequester name="abcAPIRequester" interceptorsRef=âinterceptorList"/> <apiRequester name="xyzAPIRequester" interceptorsRef=âinterceptorList"/> </zosconnect_apiRequesters>
- For all requests:
â¨If configuring multiple interceptors, refer to Is interceptor sequencing important?
How should the authorization interceptor be configured for API toolkit users?
When the API toolkit is connected to a z/OS Connect EE server, the API toolkit makes various requests to discover the APIs and services deployed in the server and determine their status in order to populate the z/OS Connect EE Servers view. An API toolkit user requires authorization roles as follows:
- To list APIs and services, a user must be in either the Reader, Operations or Admin role for each API or service.
- To start or stop an API or service, a user must be in either the Operations or Admin role.
- To test an API using the Swagger UI, a user must be in the Invoke role, plus one of the roles listed in point 1 to get the details of the API, to enable the option to test in the Swagger UI.â¨
If restricting which APIs and services users can see, it is important to understand the difference between the authority required to list APIs compared to that required to list services. A request to list APIs will return all the deployed APIs, even if the user does not have permission to read information for all APIs, whereas a request to list services will return only those services that the user has read access to.
To enable all users to see all the APIs and services available, configure a global authorization interceptor to give Reader access to all users. Then, you could restrict who can invoke the APIs by configuring Invoke authority at the API level. It can be important for developers to be able to see all the APIs and services deployed to the server to ensure that APIs or services are not created with duplicate names, unless a naming convention is in place to avoid this.
From z/OS Connect EE V22.214.171.124, multiple registry groups can be specified for Reader, Operations and Invoke access, as well as Admin access.
In the following example, everyone in the groups DEV01 and DEV02 has read access to all APIs, services and API requesters but only members of group DEV01 can invoke abcAPI and only members of group DEV02 can invoke xyzAPI. Members of group SYSPROG have admin level authority. Note: if you do not specify any group for a particular authority level, then by default, nobody has that authority, rather than everyone. In this example, after you enable the authorization interceptor, there is nobody who has Operator level authority.
<zosconnect_auditInterceptor id="auditInterceptor" sequence="1"/> <zosconnect_authorizationInterceptor id="authorizationInterceptor" sequence="2"/> <zosconnect_zosConnectInterceptors id="interceptorList" interceptorRef="authorizationInterceptor, auditInterceptor"/> <zosconnect_zosConnectManager globalAdminGroup="SYSPROG" globalReaderGroup="DEV01, DEV02" globalInterceptorsRef="interceptorList" requireAuth="true" requireSecure="false"/> <zosconnect_zosConnectAPIs> <zosConnectAPI name="abcAPI" invokeGroup="DEV01"/> <zosConnectAPI name="xyzAPI" invokeGroup="DEV02"/> </zosconnect_zosConnectAPIs>