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.

Procedure

  1. In the Cloud Manager, click Settings Settings > Audit Setting > Edit.
  2. Click Enable to enable the audit feature, or Disable to disable it.
  3. 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.
  4. 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.

  5. 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.
  6. Verify that you can reach the endpoint by clicking Test.
  7. To specify another endpoint, click Add at the beginning of the "Endpoints" section.
  8. 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

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.

Use the following settings 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.
  • 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
  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

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

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

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