In
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
apiTokenenvironment variable that you had set up earlier. For example, you can see that Authorization is set up to use Bearer and theapiTokenin 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:
- Using Postman, enter a GET request to
https://api.solace.cloud/api/v2/audit/logs. -
(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 useendTimeorstartTime. -
For
sortDirection, you can useascfor ascending order) ordesc(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 lifecycle and management activities that occur to the event broker services in the accountIAM—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
eventCategoryparameter, you can further filter based on these type of activities:-
For
SERVICE, you can filter event types, such asSERVICE_CREATE,SERVICE_UPDATE,SERVICE_UPGRADE. -
For
IAM, you filter on event types, such asLOGIN,LOGOUT,USER_CREATION,USER_DELETION.
You can use a REST API to determine the available event types for the
SERVICEandIAMcategories. 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>isjson(for JSON-encoded format) at this time. If this parameter is used, the Content-Type header in the response isapplication/octet-streaminstead ofapplication/json.For example:
https://api.solace.cloud/api/v2/audit/logs?downloadType=json -
- 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
200response 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
400response 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. ThevalidationDetailsobject 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 is2022-08-22T19:36:23.830Z. ThevalidationDetailsobject 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 thevalidationDetailsobject in the JSON response.
- If the call is successful, a
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
SERVICEorIAM. 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 serviceservice_class_id—the service class of the event broker serviceresponseCode—the response to the activity
- For IAM audit logs, you have:
requestPath—the REST API URL that was used for the activityrequestMethod—the REST method used for the activityresponseCode—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
SUCCESSorFAILEDto 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 numberpageSize—the number of entries on each pagenextPage—the next pagetotalPages—the total number of pagescount—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": "RESOURCE_ASSIGNMENT",
"description": "Resource Assignment"
},
{
"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": "USER_GROUP_ASSIGNMENT",
"description": "User Group Assignment"
},
{
"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"
}
]
}
]