HPE GreenLake for Audit Logs developer guide

The details and examples in this guide will help you get started using the HPE GreenLake Audit Logs APIs.

Prerequisites

Environment

The audit logs service is hosted at the following environment:

https://common.cloud.hpe.com

Hostname

The hostname for the audit logs APIs is as follows:

https://global.api.greenlake.hpe.com

URI

The URIs for the audit logs APIs are as follows:

/audit-log/v1beta1/logs
/audit-log/v1beta1/logs/{audit-id}/detail

Access and permissions

You need the correct role and permissions to use the HPE GreenLake Audit Logs API. A role is a group of permissions that you can specify and assign to users in your HPE GreenLake workspace. There are 3 basic role types distinguished by the privileges defined in the authorization service:

Administrator---has view, edit, and delete privileges in the workspace.
Operator---has view and edit privileges in the workspace.
Observer---has only view privileges in the workspace. The Observer role with view permissions for Audit Trail ( ccs.audit-trail.view ) is sufficient to make the following Audit Log API calls:
GET /audit-log/v1beta1/logs/{id}/detail
GET /audit-log/v1beta1/logs

You can find out more in the HPE GreenLake Edge to Cloud Platform User Guide. You can:

Find a list of preconfigured roles and the permissions they have.
Learn how to create custom roles.
Discover how to assign roles to users.

Making it all Work

The steps to fetch audit logs are as follows:

These steps are described in more detail in the following sections.

Generating a token

You must configure API credentials and generate an access token to make API calls. HPE GreenLake APIs use OAuth-based access tokens used as an authorization bearer token.

To access this HPE GreenLake Audit Log API, proceed as follows:

Connect to the HPE GreenLake edge-to-cloud platform UI workspace.
Go to Manage > API > Create Credentials .
Select  HPE GreenLake platform  in the list of values for Applications  to create the credentials and then generate access tokens for HPE GreenLake platform service APIs. If you do not see HPE GreenLake Platform as an option when configuring API client credentials, see the Getting Started Guide for more information.

Getting an access token

With the client ID and client secret, there are two ways to fetch the access token programmatically. They are as follows:

Run the cURL command or the Python script below get the token from the response["access_token"]:

Using CURL:

Copy

Copied

curl -X POST https://sso.common.cloud.hpe.com/as/token.oauth2 -H
"Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id=$YOUR_CLIENT_ID&client_secret=$YOUR_CLIENT_SECRET"

Using Python:

Copy

Copied

from oauthlib.oauth2 import BackendApplicationClient
from requests.auth import HTTPBasicAuth
from requests_oauthlib import OAuth2Session

client = BackendApplicationClient(YOUR_CLIENT_ID)


oauth = OAuth2Session(client=client)
auth = HTTPBasicAuth(YOUR_CLIENT_ID, YOUR_CLIENT_SECRET)


token = oauth.fetch_token(token_url='https://sso.common.cloud.hpe.com/as/token.oauth2', auth=auth)
print(token["access_token"])

This access token is used as the bearer token for the authentication of the Audit Logs APIs. The token is valid for two hours.

Get all the audit logs of an application instance or platform logs

By default, the API will return the all audit logs. Run the below API with the bearer token from the previous step to get all the audit logs related to your workspace.

info

Audit logs for the past three months can be retrieved using this API.

Copy

Copied

curl --location --request GET '{{Hostname}}/audit-log/v1beta1/logs' --header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Sample API response:

Copy

Copied

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "type": "/audit-log/logs",
      "user": {
        "username": "example@test.com"
      },
      "application": {
        "id": "59812345678904f7861"
      },
      "region": "us-west",
      "category": "User Management",
      "description": "User test@dummy.com logged in via ping mode.",
      "workspace": {
        "id": "565c6efa-6276-4993-31t4-aa345h3a9803",
        "workspaceName": "HPE GreenLake"
      },
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z",
      "additionalInfo": {
        "ipAddress": "104.36.311.11"
      },
      "hasDetails": true,
      "generation": 1
    }
  ],
  "count": 1,
  "offset": 0,
  "total": 10,
  "remainingRecords": false
}

To retrieve audit logs for a particular application instance, include the application ID and region code in which application is provisioned in the API query filter parameters.

Copy

Copied

curl --location --request GET '{{Hostname}}/audit-log/v1beta1/logs?filter=application/id eq '{APPLICATION_ID}' and region eq '{REGION_CODE}' --header 'Authorization: Bearer {{ACCESS_TOKEN}}'

The search API supports several query parameters. Refer to the API reference for supported query parameters.

Audit logs can be filtered using filter query, refer to filtering for more details.

APIs return a 200 status code with a paginated response. For more details, see api-spec.

Get additional details of audit log

Many audit logs will have additional information. If an audit log's hasDetails field is true, the details API fetches the additional details.

Copy

Copied

curl --location --request GET '{{Hostname}}/audit-log/v1beta1/logs/{id}/detail'

Sample response:

Copy

Copied

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "type": "audit_details",
  "header": "configuration",
  "body": [
    "Updated configuration from level 1 to level 2"
  ]
}

Filtering

Filters allow you to limit the resources involved in a REST call. They are specified using the query parameter filter. In this case, filter filters the audit logs based on the parameters listed below.

category
description
user/username
createdAt
ipAddress
target
workspace/workspaceName
application/id
region

Requirements

Queries will be separated by and .
Queries will have 'equality', 'contains' and 'in' comparison.
Each query must follow below format for different operators.
- key eq 'value' for an equality operation.
- contains(key, 'value') for a contains operation.
- key in ('value1', 'value2') for an in operation.
createdAt value should have the format 'yyyy-mm-ddTHH:mm:ssZ' .

A simple example

Here is a simple example of filtering audit logs based on a category:

Copy

Copied

curl --location --request GET <URI>?filter=category eq 'User Management'

In this example, the API call returns the audit logs with the category User Management.

An example of filtering for a month:

Copy

Copied

curl --location --request GET <URI>?filter=createdAt ge '2023-05-01T12:00:00.00Z' and createdAt lt '2023-06-01T12:00:00.00Z'

In this example, the API call returns all audit logs from May 2023.

An example of filtering logs based on user/username:

Copy

Copied

curl --location --request GET <URI>?filter=user/username eq 'example@test.com'

In this example, the API call returns all audit logs related to 'example@test.com'

OData filtering reference

This filtering is a subset of OData 4.0 filtering.