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 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:
- Getting an access token ( short lived )
- Get all the audit logs of an application instance or platform logs
- Get additional details related to an audit log
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:
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:
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.
curl --location --request GET '{{Hostname}}/audit-log/v1beta1/logs' --header 'Authorization: Bearer {{ACCESS_TOKEN}}'
Sample API response:
{
"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.
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.
curl --location --request GET '{{Hostname}}/audit-log/v1beta1/logs/{id}/detail'
Sample response:
{
"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:
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:
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:
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.