Configuring the audit log to track API calls
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.
What events are audited?
The audit focuses on "who" did "what" and "when", including the request payload and the result of the operation. All create, update, and delete operations are audited. 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 not executed by users.
How are audit events logged?
Audit events are logged by sending the information about API calls (the requests) to one or more 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.
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?
When an API call is made, the system injects a request header to capture information, including the request URL and the payload (with sensitive information redacted), plus a subset of the data returned in the response to that call. The system injects additional information to describe the "who", "what", and "when" of the call.
The payload containing the audit logging record includes information about the user who issued the API call, 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/index.http.
{
"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"
}
}
]
}
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.
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"
}
}
]
}