Configuring the audit interceptor

You can use the audit interceptor that is included with IBM z/OS Connect to write SMF 123 records, which contain data that can be used to audit and analyze requests.

zosConnect-3.0 Applies to zosConnect-3.0.

Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.

Enabling recording of SMF 123 records

To generate SMF 123 records, you must include record type 123 in your SMF configuration options, or the __smf_record function fails with return code JRSMFNotAccepting (0x406). For example, include 123 in your SYS(TYPE(...,123,...)) statement in PARMLIB. For more information, see A launch icon to indicate a link opens a new tab or window. Statements and parameters for SMFPRMxx in the z/OS documentation.

Note: For z/OS Connect to write to SMF, the user ID under which z/OS Connect runs, must have READ access to the RACF® BPX.SMF profile of the FACILITY class. For example,

PERMIT BPX.SMF CLASS(FACILITY) ACCESS(READ) ID(USERID)

For more information, see Defining z/OS UNIX users to RACF in the z/OS documentation.

Configuring the audit interceptor

Set the apiProviderSmfVersion and apiRequesterSmfVersion attributes to 2 to record version 2 records for the API provider and API requester. The audit interceptor can only be enabled globally for all APIs.

The following example shows how to enable the audit interceptor to capture SMF 123 version 2 records for API provider and API requester requests:

<featureManager>
   ...
   <feature>zosconnect:monitoring-1.0</feature> 
</featureManager>

<!-- Audit interceptor configuration --> 
<zosconnect_auditInterceptor id="auditInterceptor" apiProviderSmfVersion="2"  apiRequesterSmfVersion="2"/> 

<!-- Interceptor list configuration --> 
<zosconnect_zosConnectInterceptors id="interceptorList1" interceptorRef="auditInterceptor"/> 

<!-- Enable audit interceptor --> 
<zosconnect_monitoring apiProviderInterceptorsRef="interceptorList1" apiRequesterInterceptorsRef="interceptorList1"/>

Capturing request and response headers in SMF data

With apiProviderSmfVersion or apiRequesterSmfVersion set to 2, request and response headers can be captured for API provider or API requester requests. For API provider, only response headers that are defined in response data mapping can be captured. The following example shows how to specify a comma-separated list of three request header names and two response header names for API provider and API requester. A maximum of four header names can be specified for each. Replace the header names in this example with the names of the headers whose values that you want to capture:

<zosconnect_auditInterceptor id="interceptorList1" apiProviderSmfVersion="2"

apiProviderRequestHeaders="Request-Name-1, Request-Name-2, Request-Name-3" 
apiProviderResponseHeaders="Response-Name-1, Response-Name-2"
apiRequesterRequestHeaders="Request-Name-A, Request-Name-B, Request-Name-C" 
apiRequesterResponseHeaders="Response-Name-A, Response-Name-B"/>

If each specified header is present on the request or response, the header name and header value are stored in the relevant field of the SMF record: SMF123Sn_REQ_HDRn or SMF123Sn_RESP_HDRn in the following format:

<headerName>:<headerValue>

For more information, see zosconnect_auditInterceptor in the Reference section of this documentation.

Reducing the delay in writing SMF V2 records

By default, the audit interceptor writes SMF 123 V2 records when the maximum number of requests that can fit into a single SMF record is reached. This is ideal for systems that run with a high workload as the maximum number is reached quickly. However, for low workload systems such as in test and development, this might not be ideal as request data might take a long time to be written to SMF. You can use the apiProviderMaxDelay and apiRequesterMaxDelay attributes on the audit interceptor to reduce the delay in writing the SMF 123 V2 records to SMF.

The following example shows how to configure the audit interceptor to write SMF 123 subtype 1 version 2 records after a maximum of 5 seconds delay and API requester SMF 123 subtype 2 version 2 records after a maximum of 1 minute delay:

<zosconnect_auditInterceptor id="interceptorList1" apiProviderSmfVersion="2" apiRequesterSmfVersion="2" apiProviderMaxDelay="5s" apiRequesterMaxDelay="1m"/>

If the time value is set to 0 or less than 1 second, then no delay occurs and an SMF V2 record is written for each request. The default value is -1 that means that the audit interceptor waits for the maximum number of requests to be processed before it writes the SMF V2 records.

For more information, see zosconnect_auditInterceptor in the Reference section of this documentation.

Capturing SMF records for failures in early processing

If you set apiProviderEarlyFailure to true, then the audit interceptor captures data for requests that fail early in processing, for example authentication failures (401), authorization failures (403), or URI failures (404). Only URI failures that are for paths within the base paths of deployed APIs are captured. This data can be used to monitor requests that do not complete their processing and might indicate a problem that requires further investigation. The following example shows how to configure capturing request data for early failures for API provider:

<zosconnect_auditInterceptor id="interceptorList1" apiProviderSmfVersion="2" apiRequesterSmfVersion="2"/>

Early failure data cannot be captured for API requester.

For more information, see zosconnect_auditInterceptor in the Reference section of this documentation.