In this blog, we discuss different options available for exporting WorkspaceONE Access audit events from the Workspace ONE Access console. There are many good reasons to use SYSLOG aggregators and alert tools with your software systems, mainly to streamline troubleshooting, monitor performance and capacity planning, enable proactive maintenance and enhance security by auditing changes, and in the case of Workspace ONE Access, monitor login events. As of the writing this article, there is no out‑of‑the box functionality available within Workspace ONE Access to integrate with a SYSLOG tool.
As an administrator, you have an option to view the audit events in the Workspace ONE Access console after logging in. You can utilize the feature available to export the audit events for the past 12 weeks. However, if you need to export it to a SYSLOG tool and retain it for longer periods of time, or do some analytics or dashboarding on the events data that was generated, then we recommend you utilize the Workspace ONE Access APIs.
Audit events export via Access console
To use Workspace ONE Access to export audit events:
- Log in to the Workspace ONE Access console, and click Monitor > Reports > Filter for Audit events.
- In Audit Events, click Show.
There is an option to Export as CSV to export the results:
Audit events export via APIs (using POSTMAN)
Working with the Workspace ONE Access APIs in scripts, we use the OAuth client credentials to create Access tokens to authorize the API calls. This section describes how to create the OAuth client in Workspace ONE Access and use it inside of Postman.
To use POSTMAN to export audit events via APIs:
- Log in to Workspace ONE Access console as an admin, and create an oAuth client in the environment so oAuth tokens can be generated to authenticate in the API process. For how to do this, see Getting Client Credentials access to VMware Identity Manager.
- Log in to Workspace ONE Access with an admin role account.
- Click Settings > oAuth 2.0 Management > Clients > Add client to set up a new oAuth client for fetching Audit events.
- Provide the following information in each field:
- Access Type: Service Client Token
- Client ID: Provide a name to the application
- Scope: Select Admin (the only option for the Service Client Token)
- Copy the Shared Secret to the clipboard, which is used in the next step.
- I used Postman to showcase the API execution in this step, but you can use another tool of your choice. Create an oAuth token with the help of the oAuth Client created in the previous step. The endpoint for oAuth Token creation is POST
https://<tenant-name>/SAAS/auth/oauthtoken. - Add Authorization to this API call by adding the Client ID and the Shared Secret to the Authorization tab.
- Under Body, set the body type to
x-www-form-urlencodedand add the key. - In the response, you get the access token of type Bearer to use with the reports endpoint.
- Pass the access token in the Authorization tab of a new request where you call the API GET
https://<tenant-name>/analytics/reports/audit(this is the Cloud hosted Access tenant API). - The response is formatted as shown below. It is JSON with the header specifying the fields in the data array. The response can be paginated. For each audit event, you will get the timestamp, the userdomain/directory and the event type, and finally, the event object. The event object is again an embedded JSON and can include even further layers of embedded JSON. When parsing the response in your syslog tool, you need to be aware of this when you want to get all values available out of the response.
Audit events export via APIs (using PowerShell script)
We created a PowerShell script to automate the process of exporting audit events. This continues to post to a syslog server by scheduling the script to run for a specific time interval.
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $clientID,$secret))) **base64 encoding of the oAuthClient and the secret, use securestring or vault solutions to securely store the secret**
$encodedString = "Basic "+$base64AuthInfo **create authorization header**
$CType = "application/x-www-form-urlencoded" **content type**
$Authheaders = @{"Authorization" = $encodedString; "Content-Type" = $CType} **Authorization headers for oAuth API **
$Authbody = "grant_type=client_credentials" **oAuth Access token API body**
$HZN = Invoke-RestMethod -Method POST -Uri "https://<tenant-name>/SAAS/auth/oauthtoken" -Headers $Authheaders -Body $Authbody **oAuth token generation**
$token = "Bearer " + $HZN.access_token **storing access token as “HZN accesstoken”**
$reportHeader = @{"Authorization" = $token}
- In the response for the access token is also a refresh token, with other grant types. This is used to request a new access token after the usually short (1 hour time to live) TTL of the access token runs out. In the client credential case, it can be used to check on the validity of the current access token before using, and request a new access token if required. This is the code you need to implement logic to generate a refresh token variable out of the previous response, and call the endpoint to confirm if the access token is valid or not. This is optional, based on your use case:
$refreshBody = "grant_type=refresh_token"
$refreshToken = $HZN.refresh_token
$refreshbody = "grant_type=refresh_token&refresh_token=$refreshToken" **oAuth token refresh API body**
$isValid = Invoke-RestMethod -Method GET -Uri "https://<tenant-name>/SAAS/API/1.0/REST/auth/token?attribute=isValid" -Headers $reportHeader
if (!($isValid)) {
$HZN = Invoke-RestMethod -Method POST -Uri "https://<tenant-name>/SAAS/auth/oauthtoken" -Headers $Authheaders -Body $refreshbody
$token = "Bearer " + $HZN.access_token
$reportHeader = @{"Authorization" = $token}
}
- Next, generate the Audit Events Report through Access APIs using the Access token created earlier:
$generate_report = Invoke-RestMethod -Method GET -Uri "https://<tenant-name>/SAAS/analytics/reports/audit " -Headers $reportHeader
- After receiving the report in Access format, you can parse it and provide it in a format that your Syslog tool understands. In this example, it’s parsed for Splunk:
$timeSpan = New-TimeSpan -Minutes 5
$EventSpan = (Get-Date).ToUniversalTime()
$EventSpan = $EventSpan - $timeSpan
$EventSpan = Get-Date $EventSpan -f "yyyyMMddHHmm"
$QuantumHeader = @{Authorization = "Splunk xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx"}
for ($counter = $REPORT.data.Count - 1; $counter -ge 0; $counter--) {
$data = $report.data[$counter]
$EventTime = $data[0]
$EventTime = Get-Date $EventTime -f "yyyyMMddHHmm"
if($EventTime -gt $EventSpan) {
$eventCount ++
$audit = $data[4] | ConvertFrom-Json
$fields = @{sealid = 85533}
$event = @{
Time = $data[0]
Source = $data[1]
EventType = $data[2]
Identity = $data[3]
baseType = $audit.baseType
uuid = $audit.uuid
timestamp = $audit.timestamp
organizationId = $audit.organizationId
tenantId = $audit.tenantId
actorId = $audit.actorId
actorUserName = $audit.actorUserName
actorDomain = $audit.actorDomain
actorUuid = $audit.actorUuid
clientId = $audit.clientId
deviceId = $audit.deviceId
workspaceId = $audit.workspaceId
sourceIp = $audit.sourceIp
objectType = $audit.objectType
objectId = $audit.objectId
objectName = $audit.objectName
objectAction = $audit.objectAction
recordType = $audit.recordType
recordAction = $audit.recordAction
values = $audit.values
oldValues = $audit.oldValues
linkedObjectType = $audit.linkedObjectType
linkedObjectId = $audit.linkedObjectId
linkedObjectName = $audit.linkedObjectName
}
$ReportData = @{
index = "workspaceone_logs"
sourcetype = "json"
source = "value_vidm"
fields = $fields
event = $event
}
$Object = New-Object PSObject -Property $ReportData
$body = $Object |ConvertTo-Json
- At this point, the Audit Events Report has been generated and ready to be sent to the Syslog server:
$SyslogHeader = @{Authorization = "Splunk xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx"}
$sendReport = Invoke-WebRequest -Method Post -Uri "https://syslog-server.com/services/collector/event" -Body $body -Headers $SyslogHeader
Things to note
Keep the following in mind:
- The API endpoint to fetch the Access logs for an On-Prem Access tenant is
https://<tenant-name>/SAAS/jersey/manager/api/reporting/reports/audit, which is different than the Cloud. - Each audit report can export a maximum of 10,000 records. If your audit events are larger than the maximum, you can index result set with additional API parameters, as described on the API help page.
-
To monitor the use of APIs in the cloud-hosted Workspace ONE Access tenant, see Monitoring Rate Limits and Concurrency Limits in Workspace ONE Access.