Configuring audit logging to monitor user operations

Configure auditing in IBM® API Connect to monitor user operations such as who published which product and when.

Audit logging is useful when you want to monitor the create, update, and delete activity in your deployment; for example, who made changes, when, and what they changed.

Note: Actions performed by Portal administrators are not captured by the audit feature.

What events are audited?

All create, update, and delete operations that are done by users in the Admin UI, Manager UI, Toolkit, and REST API are captured by this feature. For Portal users, all create, update, and delete operations involving applications are captured. Generally, read operations are only audited if the calling user logged in with an OIDC Provider user registry.

Internal calls and calls between system components are not audited because they are part of the product functionality and are not executed by users.

How are audit events logged?

Audit events are logged by sending the information about operations to one or more endpoints of the following types: HTTP, Syslog UDP, Syslog TCP, or Syslog TLS.

  • HTTP endpoints:

    Audit logging messages are sent as HTTP/HTTPS requests and use the payload format defined by the Cloud Auditing Data Federation (CADF). If the endpoint requires authentication, you can configure a header that will be included in the audit logging request. Audit logging requests are issued once only, on the assumption that every endpoint is available to receive the requests. There is no error checking to ensure that requests are received and stored by the endpoints, and failed requests are not re-sent. If you suspect that audit logging requests are not successfully reaching an endpoint, you can check the server logs on the console, where any error messages are recorded.

    There are two modes that control how the auditing is sent to an endpoint: blocking and non-blocking. In non-blocking mode (the default), an audit event is sent to the endpoint and the system does not wait for a response from the endpoint. Non-blocking mode provides the best performance. Blocking mode should be used with caution: when an audit event is sent, the system pauses and waits for a response from the endpoint. Blocking mode has a negative impact on performance.

  • Syslog endpoints:

    Audit logging messages are sent as syslog messages. If the endpoint requires mutual TLS, you can configure a TLS profile to send the required client certificates. Audit logging requests are issued once only, on the assumption that every endpoint is available to receive the requests. There is no error checking to ensure that requests are received and stored by the endpoints, and failed requests are not re-sent. If you suspect that audit logging requests are not successfully reaching an endpoint, you can check the server logs on the console, where any error messages are recorded.

    All syslog messages are sent as non-blocking regardless of the auditing mode, since syslog messages are designed to be fire and forget (syslog was originally a UDP protocol, which by its nature does not have any acknowledgment). Blocking is only used for HTTP endpoints.

Note: 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's included in the audit logging request?

  • HTTP endpoints:

    The payload containing the audit logging record includes information about the user who executed the operation, the date and time of the call, the resource affected by the call, the operation performed, and the payload. To see the most recent set of fields that are included in the payload, refer to the OpenAPI schema for the audit logging request in the Provider API, which you can download at https://us-south.functions.cloud.ibm.com/api/v1/web/API%20Connect%20Native_apic-on-prem/default/v10-index.http.

    The following code example shows a sample payload for an audit logging message directed to an HTTP endpoint (IDs and users are not real):
    {
      "id": "f6fcacb5-e8eb-4e2c-0f67-53b6a792d7f0",
      "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
      "action": "update",
      "outcome": "success",
      "eventType": "activity",
      "reason": {
        "reasonCode": "200",
        "reasonType": "HTTP"
      },
      "eventTime": "2020-02-01T15:18:16.011Z",
      "initiator": {
        "id": "/api/user-registries/38385c9f-7837-583c-01f7-9d8c37a9a80d/10de0db0-27b5-35d7-b4b5-635eabb48b4a/users/24c6cddc-7a7e-5fc6-882d-5317d822048e",
        "name": "admin:default-idp-1/tjwatson",
        "typeURI": "service/security/account/user"
      },
      "target": {
        "id": "0beb6d21-6207-5381-b9a7-cc91a3e82c19",
        "typeURI": "tls_client_profile"
      },
      "observer": {
        "id": "target"
      },
      "requestPath": "/api/orgs/admin/tls-client-profiles/uma-tls/1.0.0",
      "requestData": {
        "url": "/api/orgs/admin/tls-client-profiles/uma-tls/1.0.0",
        "body": {
          "visibility": {
            "type": "public"
          },
          "namespace": "38385c9f-6726-472b-91f7-9d8c37a9a80d",
          "updated_at": "2020-02-01T15:18:15.924Z"
        }
      },
      "responseData": {
        "id": "0beb6d21-6207-5381-b9a7-cc91a3e82c19",
        "url": "https://my_host.example.com:3003/api/orgs/38385c9f-7837-583c-01f7-9d8c37a9a80d/tls-client-profiles/0beb6d21-6207-5381-b9a7-cc91a3e82c19",
        "name": "uma-tls",
        "version": "1.0.0",
        "title": "Uma TLS Client Profile"
      },
      "attachments": [
        {
          "timestamp": {
            "start": "2020-02-01T15:18:15.802Z",
            "end": "2020-02-01T15:18:16.011Z"
          },
          "cloud_name": "management.example.com",
          "request_id": "f6fcacb5-e8eb-4e2c-0f67-53b6a792d7f0",
          "method": "patch",
          "operation": "tls_client_profile_updateByNameVersion",
          "summary": "Update the TLS Client Profile object by name and version",
          "resource": "tls_client_profile",
          "user": {
            "url": "/api/user-registries/38385c9f-7837-583c-01f7-9d8c37a9a80d/10de0db0-27b5-35d7-b4b5-635eabb48b4a/users/24c6cddc-7a7e-5fc6-882d-5317d822048e",
            "context": "admin",
            "idp_name": "default-idp-1",
            "name": "tjwatson"
          },
          "registration": {
            "url": "/api/cloud/registrations/9d13c715-e3dc-55ef-92f1-1c2651c0a660",
            "type": "toolkit"
          }
        }
      ]
    }
    
  • Syslog endpoints:

    The nature of syslog messaging means that the information logged is less structured and shorter than information logged using structured HTTP endpoints. With syslog, the information is more of a summary.

    The following code example shows some sample payloads for an audit logging message directed to a syslog endpoint (IDs and users are not real):
    The user admin:default-idp-1/admin has deleted the resource Org 'alpha (Alpha title)', id 19cf81c7-7cb3-43de-b5e5-d92cdfb26214 and url https://localhost:3003/api/orgs/19cf81c7-7cb3-43de-b5e5-d92cdfb26214
    The user admin:default-idp-1/admin has deleted the resource Gateway Service 'webhook-gw-v5 (Webhook Gateway Service (v5) title)', id 08b87e25-616d-451e-8766-bad1c7b82a42 and url https://localhost:3003/api/orgs/69c878db-4f11-4c3e-9499-10daa25f04de/availability-zones/cb2caa3d-d619-4c2e-85f8-709956495a7b/gateway-services/08b87e25-616d-451e-8766-bad1c7b82a42
    The user provider:default-idp-2/steve@example.com has created the resource Catalog 'climbon:1.0.1 (The climbon product description)', id 665036df-28ad-447e-b8de-fe9d6967b66d and url https://localhost:3003/api/catalogs/19cf81c7-7cb3-43de-b5e5-d92cdfb26214/8641fda7-43f8-4e59-b405-58a4844016c9/products/665036df-28ad-447e-b8de-fe9d6967b66d

Verifying that the endpoint is receiving audit logging messages

By default, auditing operates in non_block mode to ensure best performance. In non_block mode, each audit logging message is sent immediately without waiting to ensure that the previous message was received. If you suspect that audit logging messages are not being received by the endpoint, download the server logs from the Kubernetes console and examine the apim microservices file for messages related to the connection state. Review the messages to validate that the connection was successful or to further diagnose issues.

For HTTP endpoints (not available for Syslog endpoints), you can test the connection by issuing a "test-connection" call using either the toolkit or a REST API. A response status of 204 indicates that the call was successful and the endpoint is available. The following example contains the payload from a connection test (IDs and users are not real):
{
  "id": "8d8eaaa2-1b46-4dcb-cadf-639d7d1f7f20",
  "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
  "action": "create",
  "outcome": "success",
  "eventType": "activity",
  "reason": {
    "reasonCode": "200",
    "reasonType": "HTTP"
  },
  "eventTime": "2020-01-30T15:51:18.254Z",
  "initiator": {
    "name": "admin:default-idp-1/tjwatson",
    "typeURI": "service/security/account/user"
  },
  "target": {
    "id": "test-connection",
    "typeURI": "cloud_setting"
  },
  "observer": {
    "id": "target"
  },
  "requestPath": "/api/cloud/settings/audit-endpoint/test-connection",
  "requestData": {
    "url": "/api/cloud/settings/audit-endpoint/test-connection",
    "body": {
      "message": "hello"
    }
  },
  "responseData": {
    "name": "world"
  },
  "attachments": [
    {
      "timestamp": {
        "start": "2020-01-30T15:51:18.160Z",
        "end": "2020-01-30T15:51:18.254Z"
      },
      "cloud_name": "management.example.com",
      "request_id": "8d8eaaa2-1b46-4dcb-cadf-639d7d1f7f20",
      "method": "post",
      "operation": "cloud_setting_auditEndpointTestConnection",
      "summary": "Test connection using one of the auditing endpoints",
      "resource": "cloud_setting",
      "user": {
        "id": "/api/user-registries/dd49cebf-d3ba-5fee-92eb-f895328bc9ef/d51fa599-a5f3-50e2-a786-fafcc76daca5/users/7ff5fff8-3d4b-3524-8687-524740580d0b",
        "context": "admin",
        "idp_name": "default-idp-1",
        "name": "tjwatson"
      },
      "registration": {
        "url": "/api/cloud/registrations/734c04f7-0fe2-3ffa-b745-81027a3b8c76",
        "type": "toolkit"
      }
    }
  ]
}
Tip: To ensure that audit logging messages are not lost due to an unavailable endpoint, verify each endpoint periodically.