June 12, 2023

How to export Workspace ONE Access audit events to a SYSLOG tool

In this blog, we discuss different options available for exporting WorkspaceONE Access audit events from the Workspace ONE Access console. 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.

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:

  1. Log in to the Workspace ONE Access console, and click Monitor > Reports > Filter for Audit events.
  2. In Audit Events, click Show.
    There is an option to Export as CSV to export the results:
    Graphical user interface, text, application, email</p>
<p>Description automatically generated
     

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:

  1. 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.
  2. Log in to Workspace ONE Access with an admin role account.
    Graphical user interface, application</p>
<p>Description automatically generated
  3. Click Settings > oAuth 2.0 Management > Clients > Add client to set up a new oAuth client for fetching Audit events.
    Graphical user interface, text, application, chat or text message</p>
<p>Description automatically generated
  4. Provide the following information in each field:Graphical user interface, text, application
<p>Description automatically generated
    1. Access Type: Service Client Token
    2. Client ID: Provide a name to the application
    3. Scope: Select Admin (the only option for the Service Client Token)
  5. Copy the Shared Secret to the clipboard, which is used in the next step.
    Graphical user interface, text, application</p>
<p>Description automatically generated
  6. 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.
  7. Add Authorization to this API call by adding the Client ID and the Shared Secret to the Authorization tab.A screenshot of a computer
<p>Description automatically generated
     
  8. Under Body, set the body type to x-www-form-urlencoded and add the key.
    A screenshot of a computer</p>
<p>Description automatically generated with medium confidence
  9. In the response, you get the access token of type Bearer to use with the reports endpoint.
    A screenshot of a computer</p>
<p>Description automatically generated with medium confidence
  10.  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).
    A screenshot of a computer</p>
<p>Description automatically generated
  11. 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.
    A picture containing text, screenshot, multimedia software</p>
<p>Description automatically generated

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}
  1. 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}
}
  1. 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
  1. 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
  1. 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:

  1. 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.
  2. 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.
  3. 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.

Filter Tags

Workspace ONE Workspace ONE Access Workspace ONE UEM Blog Announcement Intermediate