Managing Audit Logs with the PubSub+ Cloud REST API

In PubSub+ Cloud, the REST APIs allow you to retrieve the audit logs for only your user profile or for all users in your account (organization).

Audit logs provide records of user activity for security and compliance. You can view, monitor, and track the sequence of the following activities in PubSub+ Cloud:

  • IAM operation, such as user login activities
  • User management activities, such as user activation or role changes
  • Event broker service life-cycle events, such as event broker service creation, upgrades, or deletion

This tutorial shows you how to use the REST API in PubSub+ Cloud to retrieve the audit logs. Optionally, you can use parameters to filter and sort the audit logs that are retrieved. For more information about the REST API calls, see the following table:

REST API Description

 

GET https://api.solace.cloud/api/v2/audit/logs

Retrieves audit logs. Optionally, you can specify query parameters to filter the audit logs that are retrieved. For more information, see Retrieving Audit Logs Using the PubSub+ Cloud REST API.

For information about the response, see Details about the Audit Log Response.

 

GET https://api.solace.cloud/api/v2/audit/categories

Retrieves the event categories and available event types for each category. For more information, see Retrieving the Categories and Event Types Using the REST API.

Before You Begin

To use this tutorial, you require the following:

  • An account with PubSub+ Cloud and an event broker service.
    • Users with the Administrator role can access the audit logs for the whole organization. They can view and track actions performed by all other users and retrieve all audit logs within the account.
    • Users without the Administrator role can access only their own audit logs and retrieve them.
  • An API token must be available in the account with at least one of the following permissions to retrieve audit logs:
    • Retrieve my audit logs—permits you to retrieve the audit logs that pertain to you
    • Retrieve my organization's audit logs—permits you to retrieve the audit logs for the organization for which you belong

    For more information, see Creating an API Token.

  • Audit logs are collected that provide records for user access in PubSub+ Cloud and management activities of Event broker service. The audit logs are not used for the monitoring of the messaging statistics of the event broker services. If you require logs for the messaging activities on event broker services, see how to forward logs from an event broker service to a server or an external log monitoring system that you control. For more information, see Forwarding Logs to an External System or consider using PubSub+ Insights.

  • To run the commands, you require a REST client of your choice. For testing purposes, you can use Postman, which is a visual REST API development tool. At this time, there is no Solace Blog available. To use Postman for the Audit Log REST API, you can type the REST API call after you've set up Postman.

    After you've set up the environment in Postman to use your API token, you can simply make each call by specifying the REST API. To check that API token is set up correctly to use Bearer authorization in Postman, select the Headers tab to validate that it is using Bearer Authorization and set it to use the apiToken environment variable that you had set up earlier. For example, you can see that Authorization is set up to use Bearer and the apiToken in the following illustration:

Retrieving Audit Logs Using the PubSub+ Cloud REST API

You can use the PubSub+ Cloud REST API to retrieve the audit logs. Optionally, you can use query parameters to sort and apply filtering to the audit logs:

  1. Using Postman, enter a GET request to https://api.solace.cloud/api/v2/audit/logs.
  2. (Optional) In the GET request URL (or using the Params tab in Postman), specify query parameters to sort, control pagination, control the download format, or filter the audit logs:

    Query Parameters Description

     

    pageSize=<page-size>

    An integer for size that lists the number of audit logs for each page. The default is 25.

    For example, four results per page: https://api.solace.cloud/api/v2/audit/logs?pageSize=4.

    pageNumber=<page>

    An integer to specify the page to retrieve.

    For example: https://api.solace.cloud/api/v2/audit/logs?pageNumber=4.

    sort=<sortField>:<sortDirection>

    Specify the sort order of the results using one of the following parameters:

    • For sortField, you can use endTime or startTime.

    • For sortDirection, you can use asc for ascending order) or desc (descending order), which is the default option.

    For example, to sort the starting time by ascending order: https://api.solace.cloud/api/v2/audit/logs?sort=startTime:asc.

    startTime=<start-time>

    The start time of the audit log that is specified using ISO 8601 Date/Time format. Filters based on logs after the specified start time.

    For example: https://api.solace.cloud/api/v2/audit/logs?startTime=2022-08-22T18:36:23.830Z.

    endTime=<end-time>

    The end time of the audit log that is specified using ISO 8601 Date/Time format.  Filters based on logs prior to the specified end time.

    For example: https://api.solace.cloud/api/v2/audit/logs?endTime=2022-08-22T19:36:23.830Z.

    traceId=<trace-id>

    The trace identifier used for the audit log.

    For example: https://api.solace.cloud/api/v2/audit/logs?traceId=f558c08b86f6b291.

    eventCategory=<category>

    The category of the audit log. You can specify one of the following categories:

    • SERVICE—service life cycle and management activities that occur to the event broker services in the account
    • IAM—user access activities that occur to the account

    For example, to find all logs about access to the account, https://api.solace.cloud/api/v2/audit/logs?eventCategory=IAM.

    eventType=<type>

    Based on what you specified for the eventCategory parameter, you can further filter based on these type of activities:

    • For SERVICE, you can filter event types, such as SERVICE_CREATE, SERVICE_UPDATE, SERVICE_UPGRADE.

    • For IAM, you filter on event types, such as LOGIN, LOGOUT, USER_CREATION, USER_DELETION.

    You can use a REST API to determine the available event types for the SERVICE and IAM categories. For more information, see Retrieving the Categories and Event Types Using the REST API.

    For example, to find all logs for creating an event broker service, https://api.solace.cloud/api/v2/audit/logs?eventCategory=SERVICE&eventType=SERVICE_CREATE.

    downloadType=<format>

    The only valid value for <format> is json (for JSON-encoded format) at this time. If this parameter is used, the Content-Type header in the response is application/octet-stream instead of application/json.

    For example: https://api.solace.cloud/api/v2/audit/logs?downloadType=json

  3. In Postman, click Send to get the JSON response of the logs or click Send and Download to download the response as a JSON-encoded file.
    • If the call is successful, a 200 response confirms the request was successful and the audit logs are returned. For information about the audit log, see Details about the Audit Log Response.
    • If the call is not successful, a 400 response is returned that indicates the reason with one of the following in the response:
      • Invalid entity type specified for the query parameter.—The value is not a recognized value for the query parameter. The validationDetails object in the JSON response lists the valid values that can be used.

      • Invalid value <your-value> for query parameter <API query parameter>—The format of your time you've specified must use ISO 8601 Date/Time format. For example a valid Date/Time format string is 2022-08-22T19:36:23.830Z. The validationDetails object lists in the error message shows the internal error message.

      • Invalid query parameter <name-of-invalid-parameter-you-specified>—The query parameter that you specified does not exist for this REST call. Use one of the suggested parameters listed in the validationDetails object in the JSON response.

Details about the Audit Log Response

Audit logs are returned as JSON. Each audit log is an element in a JSON array. A JSON object in the array represents an audit log with a data (audit logs) and meta (metadata for the audit logs). For example:

{
    "data": [
        {
            "id": "10dri30cmj1",
            "source": "174.95.100.240",
            "userId": "qe6mvlb39c1",
            "resourceId": "mki3l8wy0m6",
            "status": "FAILURE",
            "eventCategory": "SERVICE",
            "eventType": "SERVICE_DELETE",
            "meta": {
                "msg_vpn_name": "firstapp",
                "service_class_id": "enterprise-kilo",
                "responseCode": "200"
            },
            "description": "Enterprise service FirstApp failed to delete in gke-gcp-us-central1-a with version DHP-V21.1",
            "shortDescription": "Enterprise service FirstApp failed to delete",
            "traceId": "1d6d9998f2bf9a7e",
            "duration": 906,
            "orgId": "custdocteam",
            "startTime": "2022-09-14T18:52:44.749Z",
            "endTime": "2022-09-14T18:52:45.655Z"
        },
        {
            "id": "10dri30cmhx",
            "source": "174.95.100.240",
            "userId": "qe6mvlb39c1",
            "resourceId": "mki3l8wy0m6",
            "status": "FAILURE",
            "eventCategory": "SERVICE",
            "eventType": "SERVICE_CREATE",
            "meta": {
                "msg_vpn_name": "firstapp",
                "service_class_id": "enterprise-kilo",
                "responseCode": "200"
            },
            "description": "Enterprise service FirstApp failed to create in gke-gcp-us-central1-a with version DHP-V21.1",
            "shortDescription": "Enterprise service FirstApp failed to create",
            "traceId": "5f67ba3ded5f4e8e",
            "duration": 933,
            "orgId": "custdocteam",
            "startTime": "2022-09-14T18:51:07.521Z",
            "endTime": "2022-09-14T18:51:08.454Z"
        },
...
...
...
        {
            "id": "10dri3031ff",
            "source": "45.72.193.70",
            "userId": "qe6mvlb39c1",
            "status": "FAILURE",
            "eventCategory": "SERVICE",
            "eventType": "SERVICE_CREATE",
            "meta": {
                "service_class_id": "enterprise-250-sa",
                "requestPath": "/api/v0/services",
                "requestMethod": "POST",
                "responseCode": "500"
            },
            "description": "Enterprise Standalone service Solace SA Service failed to create in gke-gcp-us-central1-a",
            "shortDescription": "Enterprise Standalone service Solace SA Service failed to create",
            "traceId": "3202c2193d5aa032",
            "duration": 1,
            "orgId": "solacedocs",
            "startTime": "2022-09-14T13:05:45.623Z",
            "endTime": "2022-09-14T13:05:45.624Z"
        }
    ],
    "meta": {
        "pagination": {
            "pageNumber": 1,
            "pageSize": 25,
            "nextPage": 2,
            "totalPages": 2,
            "count": 43
        }
    }
}

The data object is a JSON array where each object in the log represents an audit log. The following JSON describe the audit log as follows:

id
The identifier for the audit log.
source
The IP address of the where the activity originated.
userid
The identifier representing the user in the account that performed the activity.
resourceId
The service identifier or the user identifier. To determine the user, see Managing Users with the PubSub+ Cloud REST API
status
The status of the activity
eventCategory
The category, which can be SERVICE or IAM.
eventType
The type of activity that occurred.
meta
The metadata for the audit log. For SERVICE audit logs, you have:
  • msg_vpn_name—the name of the event broker service
  • service_class_id—the service class of the event broker service
  • responseCode—the response to the activity
For IAM audit logs, you have:
  • requestPath—the REST API URL that was used for the activity
  • requestMethod—the REST method used for the activity
  • responseCode—the response to the activity
description
The description for the activity and aligns with the event type. For SERVICE audit logs, this is the message of the activity. For IAM audit logs, this property is not returned.
shortDescription
For services, this is the short description message of the activity. For IAM audit logs, this SUCCESS or FAILED to indicate
traceId
An identifier useful for tracing related activities.
duration
The time in milliseconds for the activity to occur.
orgId
The organization identifier for the account. This value was assigned when you created the account.
startTime
The UTC time of when the activity started.
endTime
The UTC time when the activity completed.

The meta object after the JSON array describes the metadata for the audit logs and consists of a meta object that includes:

pagination
The pagination of the audit logs that includes the following information:
  • pageNumber—the current page number
  • pageSize—the number of entries on each page
  • nextPage—the next page
  • totalPages—the total number of pages
  • count—the total number of audit logs

Retrieving the Categories and Event Types Using the REST API

You can retrieve the available event categories and event types for audit logs using the REST API.

To do this, use a GET call to https://api.solace.cloud/api/v2/audit/categories.

The term messaging services in the audit logs refer to event broker services.

For example:

[
    {
        "category": "DISTRIBUTED_TRACING",
        "types": [
            {
                "name": "DISTRIBUTED_TRACING_LIMIT_CHANGE",
                "description": "Distributed Tracing Limit Change"
            }
        ]
    },
    {
        "category": "IAM",
        "types": [
            {
                "name": "UNKNOWN",
                "description": ""
            },
            {
                "name": "LOGIN",
                "description": "User Login"
            },
            {
                "name": "LOGOUT",
                "description": "User Logout"
            },
            {
                "name": "USER_CREATION",
                "description": "User Creation"
            },
            {
                "name": "USER_DELETION",
                "description": "User Deletion"
            },
            {
                "name": "USER_ACTIVATION",
                "description": "User Activation"
            },
            {
                "name": "ROLE_UPDATE",
                "description": "User Role Update"
            },
            {
                "name": "PASSWORD_RESET",
                "description": "User Password Reset"
            },
            {
                "name": "PASSWORD_CHANGE",
                "description": "User Password Change"
            },
            {
                "name": "USER_DELETE_ORGANIZATION",
                "description": "User Organization Deletion"
            },
            {
                "name": "USER_CREATE_ORGANIZATION",
                "description": "User Organization Creation"
            },
            {
                "name": "ROLE_MAPPING_UPDATE",
                "description": "Role-mapping Update"
            },
            {
                "name": "GROUP_MAPPING_UPDATE",
                "description": "Group-mapping Update"
            },
            {
                "name": "ENVIRONMENT_CREATE",
                "description": "Environment Creation"
            },
            {
                "name": "ENVIRONMENT_UPDATE",
                "description": "Environment Update"
            },
            {
                "name": "ENVIRONMENT_DELETE",
                "description": "Environment Delete"
            },
            {
                "name": "USER_GROUP_CREATE",
                "description": "User Group Creation"
            },
            {
                "name": "USER_GROUP_UPDATE",
                "description": "User Group Update"
            },
            {
                "name": "USER_GROUP_DELETE",
                "description": "User Group Delete"
            }
        ]
    },
    {
        "category": "SERVICE",
        "types": [
            {
                "name": "SERVICE_CREATE",
                "description": "Messaging Service Creation"
            },
            {
                "name": "SERVICE_CLONE",
                "description": "Messaging Service Clone"
            },
            {
                "name": "SERVICE_DELETE",
                "description": "Messaging Service Deletion"
            },
            {
                "name": "SERVICE_UPDATE",
                "description": "Messaging Service Configuration Change"
            },
            {
                "name": "SERVICE_FAILOVER",
                "description": "Messaging Service Active Node Switch"
            },
            {
                "name": "SERVICE_UPGRADE",
                "description": "Messaging Service Upgrade"
            },
            {
                "name": "SERVICE_SCALEUP",
                "description": "Messaging Service Scale Up"
            },
            {
                "name": "SERVICE_SHOW_PASSWORD",
                "description": "Unmask password on Manage Service Settings"
            },
            {
                "name": "SERVICE_SEMP_PASSWORD_CHANGE",
                "description": "Messaging Service SEMP Password Change"
            },
            {
                "name": "SERVICE_SEMP_USER_CHANGE",
                "description": "Messaging Service SEMP User Change"
            },
            {
                "name": "SERVICE_LIMIT_CHANGE_REQUEST",
                "description": "Service Limit Change Request"
            },
            {
                "name": "SERVICE_LIMIT_CHANGE",
                "description": "Service Limit Change"
            },
            {
                "name": "ENABLE_DISTRIBUTED_TRACING",
                "description": "Enable Distributed Tracing"
            },
            {
                "name": "DISABLE_DISTRIBUTED_TRACING",
                "description": "Disable Distributed Tracing"
            }
        ]
    }
]