Configuring the audit settings

Use the Cloud Manager UI or the toolkit CLI to enable auditing and configure settings.

About this task

The audit feature tracks platform-level changes in API Connect through the use of platform APIs, CLI, and Web UI. For information on tracking run-time API execution, see API Analytics.

You can configure audit settings using either the Cloud Manager UI, or the Toolkit CLI.

Using the Cloud Manager UI to configure audit settings

Use the Cloud Manager user interface to enable auditing of customer API calls.

Before you begin

Configure one or more audit endpoints where logging data can be directed, and validate that every endpoint is available by testing the connection as explained in Configuring audit logging to monitor user operations.

About this task

By default, auditing is disabled. If you enable auditing, the API Connect management node emits audit events as messages and sends them to the endpoint for storage.

Note: Auditing for read operations can only be enabled and configured using the CLI.

Procedure

In the Cloud Manager, click Settings > Audit Setting > Edit.
Click Enable to enable the audit feature, or Disable to disable it.
Select an audit mode:
- Non-blocking - Default value, offers the best performance. Each request is passed immediately without waiting for a response to the previous request. This is susceptible to errors if a request is dependent on the results of an earlier request whose response is not received before the new request is sent.
- Blocking - If you select this mode, expect a degradation in performance. Each request is allowed to finish execution before the next request is sent. This mode results in fewer errors when requests are dependent on the responses of earlier operations, but the delayed requests slow the network.
  Note: Blocking mode is only applied to HTTP endpoints and is ignored for Syslog endpoints.
Click Add and select the type of endpoint that you want to add (you must add at least one endpoint).

Endpoints can be of the following types: HTTP, Syslog UDP, Syslog TCP, or Syslog TLS.
In the Endpoints section, fill in the fields to describe the new endpoint:
HTTP
- URL - Required, must not be empty. The URL of the server where audit logging messages will be sent.
  If you previously saved the audit settings with an empty URL and experienced problems, you can edit the URL to correct it.
- TLS client profile - Optional. The URL of the server where the endpoint's TLS client profile is stored.
- Header name and Header value - Optional. Multiple headers are allowed (click Add to add another header). For each header, specify the header name and the header value.
Syslog UDP
- Host name - Required, must not be empty. The host name of the server where audit logging messages will be sent; for example: www.example.com.
  Do not include the syslog:// protocol with the host name. When audit logging messages are directed to the host server, the protocol is added to the host name programmatically.
- Port - Optional. The port number where audit logging messages should be directed.
Syslog TCP
- Host name - Required, must not be empty. The host name of the server where audit logging messages will be sent; for example: www.example.com.
  Do not include the syslog:// protocol with the host name. When audit logging messages are directed to the host server, the protocol is added to the host name programmatically.
- Port - Optional. The port number where audit logging messages should be directed.
Syslog TLS
- Host name - Required, must not be empty. The host name of the server where audit logging messages will be sent; for example: www.example.com.
  Do not include the syslog:// protocol with the host name. When audit logging messages are directed to the host server, the protocol is added to the host name programmatically.
- Port - Optional. The port number where audit logging messages should be directed.
- TLS client profile - Optional. The URL of the server where the endpoint's TLS client profile is stored.
Verify that you can reach the endpoint by clicking Test.
To specify another endpoint, click Add at the beginning of the "Endpoints" section.
When you finish adding endpoints, click Save to save your settings.

Results

With the microservices nature of API Connect, any changes to the audit settings can take up to five minutes to be fully honored by all of the microservices supporting it.

What to do next

If you suspect that audit logging messages are not being received by the endpoint, see Verifying that the endpoint is receiving audit logging messages for information on validating the connection.

Using the CLI to configure audit settings

Use the IBM API Connect toolkit CLI to enable auditing of API calls.

Before you begin

About this task

By default, auditing is disabled. If you enable auditing, the API Connect management node emits audit events as messages and sends them to the endpoint for storage.

Use the following audit_setting options to enable auditing with the CLI toolkit:

enable - Boolean, defaults to false (no audit). Set to true if you want to enable auditing.
mode - Enumerated, defaults to non_block. The audit mode determines how audit requests are timed when they are sent to the endpoint:
- non_block - Default value, offers the best performance. Each request is passed immediately without waiting for a response to the previous request. This is susceptible to errors if a request is dependent on the results of an earlier request whose response is not received before the new request is sent.
- block - If you select this mode, expect a degradation in performance. Each request is allowed to finish execution before the next request is sent. This mode results in fewer errors when requests are dependent on the responses of earlier operations, but the delayed requests slow the network.
  Note: Block mode is only applied to HTTP endpoints and is ignored for Syslog endpoints.
audit_reads - Use this setting to enable auditing of read operations:
- enable - Boolean, defaults to false and no audit events are sent to the endpoint for read operations. Set to true if you want to enable audit logging for read operations.
- response_data_to_http_endpoints - Configure additional settings for HTTP endpoints only (the settings do not apply to Syslog endpoints).
  - enable - Boolean, defaults to false and audit events for GET operations are sent to the HTTP endpoint with no response data in the event. Set to true if you want to include the response data.
    Attention: If you choose to include the response data, be aware that the response might return large payloads, and might contain sensitive information.
  - list_results_limit - Integer, must be 0 or larger. Use this setting to specify the maximum number of results of GET list operations to include in the audit message (default is 0 results).
    
    If audit_reads is enabled, then the audit message for a GET of a single object (for example, GET /orgs/admin) always includes all of the properties of the response object.
    
    If the list_results_limit is set to 0, then the audit message for a GET to list objects (for example, GET /orgs) does not include any objects from the GET response. If you set the list_results_limit to a value greater than 0, then the audit message includes all properties from the first list_results_limit number of objects from the GET /orgs response.
endpoints - Array of strings. You must specify at least one endpoint where the audit logging messages are sent. Endpoints can be of the following types: HTTP, Syslog UDP, Syslog TCP, or Syslog TLS.
For HTTP and Syslog TLS endpoints, you can optionally include a TLS client profile URL. For HTTP endpoints, you can additionally include one or more optional headers. For example, if the endpoint requires an authorization header, you can include it in the endpoint setting.
- endpoint_type - String. Required. Allowed values are: http, syslog_udp, syslog_tcp or syslog_tls.
- endpoint - String. Required, must not be empty or blank. The URL of the server where audit logging messages will be sent. Include the protocol (http:// or syslog://) and the port, if applicable. For example, syslog://<hostname>:<port>.
- tls_client_profile_url - String. Optional; supported only for HTTP and Syslog TLS endpoints. The URL of the server where the endpoint's TLS client profile is stored.
- headers - String. Optional; supported only for HTTP endpoints. Multiple headers are allowed. For each header, specify the header name and the header value using the format shown in the example.

The endpoint setting can be lengthy, so uploading the settings in a file helps to avoid errors. Format the settings as a .yaml file (you can choose the file name) and upload the file using the toolkit CLI. The following example enables auditing in non-blocking mode with multiple endpoints to demonstrate how the settings should be formatted.

audit_setting:
  enabled: true
  mode: non_block
  audit_reads:
    enabled: true
    response_data_to_http_endpoints:
      enabled: true
      list_results_limit: 0
  endpoints:
    - endpoint_type: syslog_udp
      endpoint:
        endpoint: syslog://syslog-audit-endpoint.example_1.com:514 
    - endpoint_type: syslog_tls
      endpoint:  
        endpoint: syslog://syslog-tls-audit-endpoint.example_1.com:1601
        tls_client_profile_url: https://security.tls_example.com/api/orgs/d8eac736-b4e2-3aa6-c7ff-978a4cd19d0b/tls-client-profiles/19d0f087-b4e2-3aa6-926b-9f6d51d028c3
    - endpoint_type: http
      endpoint:  
        endpoint: https://mutt-audit-endpoint.example_1.com/auditing
    - endpoint_type: http
      endpoint:  
        endpoint: https://auditing-endpoint.example_1.com/inputs/64e38c02-acd9-6530-76f8-dd0f336d7b11
        tls_client_profile_url: https://security.tls_example.com/api/orgs/d8eac736-b4e2-3aa6-c7ff-978a4cd19d0b/tls-client-profiles/19d0f087-b4e2-3aa6-926b-9f6d51d028c3
      headers:
        authorization: Basic c3Bvb246c2ltb25rYXRpZXVtYQ==
    - endpoint_type: http
      endpoint:  
        endpoint: https://auditing-endpoint.example_2.com/inputs/64e38c02-acd9-6530-76f8-dd0f336d7b11
      headers:
        authorization: Basic c3Bvb246c2ltb24=
        x-header: ForYourEyeOnly

Procedure

Create a YAML file with the audit settings as shown in the example.

For information on using input files with the toolkit CLI, see Reading input from the command line.
Run the following command to log in to a management server as a member of the cloud administration organization:
```
apic login --server mgmt_endpoint_url --username user_id --password password --realm admin/identity_provider
```
Cloud settings are stored on a management server and you must log in to the server before you can access the settings with the CLI.
You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):
```
apic identity-providers:list --scope admin --server mgmt_endpoint_url --fields title,realm
```
For example:
```
apic identity-providers:list --scope admin --server myserver.com --fields title,realm
total_results: 2
results:
  - title: Cloud Manager User Registry
    realm: admin/default-idp-1
  - title: Corporate LDAP user registry
    realm: admin/corporate-ldap
```
The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default Cloud Manager Local User Registry for login as a member of the cloud administration organization is default-idp-1.
For more information on logging in, see Logging in to a management server.
Upload the YAML file with the auditing settings by running the following command:
```
apic cloud-settings:update --server mgmt_endpoint_url my_audit_settings.yaml
```
Run the following command to log out of the management server:
```
apic logout --server mgmt_endpoint_url
```

Results

With the microservices nature of API Connect, any changes to the audit settings can take up to five minutes to be fully honored by all of the microservices supporting it.

What to do next

If you suspect that audit logging messages are not being received by the endpoint, see Verifying that the endpoint is receiving audit logging messages for information on validating the connection.