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:

Hostname

The hostname for the Audit Logs APIs is as follows:

URI

The HPE GreenLake Audit Logs APIs are available in two versions: v1beta1 (beta version) and v1. Below are the URIs for each version:

Beta version (v1beta1)

  • Fetch all audit logs : /audit-log/v1beta1/logs
  • Fetch additional details of a specific audit log : /audit-log/v1beta1/logs/{audit-id}/detail
Deprecated

The v1beta1 version is deprecated and will be fully deprecated soon. It is recommended to transition to the v1 version to ensure continued access to the latest features and support.

V1 version (v1)

  • Fetch all audit logs : /audit-log/v1/logs
  • Fetch additional details of a specific audit log : /audit-log/v1/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/v1/logs/{id}/detail
  • GET /audit-log/v1/logs
  • GET /audit-log/v1beta1/logs/{id}/detail
  • GET /audit-log/v1beta1/logs

You can find out more in the HPE GreenLake Cloud 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:

Generating a token

You must create a personal API client and generate an access token to make API calls. HPE GreenLake APIs use OAuth-based access tokens used as an authorization bearer token. To do this:

  1. Create a personal API client.
    • Select the HPE GreenLake Cloud Platform service.
  2. Generate an access token.
  3. Use the access token as an authorization bearer token to make secure REST API calls.

Getting an access token for V1 APIs

With the client ID and client secret, the access token can be fetched programmatically. Run the CURL command to get the token from the response["access_token"]:

  • Using CURL:
    Copy
    Copied
    curl -X POST https://<HPE_Cloud_Base_URL>/authorization/v2/oauth2/<WORKSPACE_ID>/token -H
"Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id=$YOUR_CLIENT_ID&client_secret=$YOUR_CLIENT_SECRET"

This access token is used as the bearer token for the authentication of the Audit Logs v1 APIs.

Getting an access token for v1beta1 APIs

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 v1beta1 APIs.

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.

Sample requests:

v1

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

v1beta1

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.

v1

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}}'

v1beta1

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.

The v1beta1 and v1 versions of the HPE GreenLake Audit Logs APIs return a 200 status code with a paginated response. For more details, see the API references for:

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.

Sample requests:

v1

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

v1beta1

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.