Cloudera Octopai API: UserEvents documentation for user audit trails

Learn about how to interact with the Cloudera Octopai API, covering the /api/UserAccount/Login and /api/UserAccount/UserEvents endpoints. The utilization of these endpoints can serve various business use cases including User Behavior Analysis, Security and Fraud Detection, Compliance and Auditing, System Monitoring and Performance, Customer Support, and Product Development.

An audit trail is a security-relevant chronological record that provides documentary evidence of the sequence of activities that have affected a specific operation, procedure, or event. In the context of this API, it records the sequence of user activities or events.

Audit trails are a crucial aspect of security and compliance for many organizations. They are used to detect security incidents, performance issues, and to aid in the recovery from incidents. Additionally, they support the investigation and forensic analysis of how an incident occurred.

The UserEvents functionality contributes to a user audit trail the following ways:

User authentication: The API logs events related to user authentication, such as successful and failed login attempts. This can help detect potential security risks, like repeated failed login attempts that might indicate a brute-force attack.
User activity: The API records various user activities like page loads. By tracking these events, administrators can establish a pattern of normal behavior per user, making it easier to identify anomalous actions that could signify a breach.
Timestamps: Every event logged by the API includes a timestamp. This allows administrators to reconstruct the sequence of events leading up to a particular incident, which is vital in forensic investigations.
Data source: The IP addresses from which events originate are also recorded. This can be used to identify suspicious activity from unfamiliar sources.

By extracting and analyzing data from the UserEvents API, organizations can maintain a comprehensive audit trail that helps uphold security, facilitate incident response, and ensure regulatory compliance.

You must be familiar with HTTP methods, specifically POST.
You must be able to use command-line tools like curl.
You must have valid Cloudera Octopai user credentials that is email and password.

User Login

To authenticate a user, send a POST request to the following endpoint:

https://[***YOUR URL NAME***].octopai.com/api/UserAccount/Login

Construct and send this request using curl.


      curl --location 'https://[***YOUR URL NAME***].octopai.com/api/UserAccount/Login' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "Username": "[***YOUR USER EMAIL***]",
      "Password": "[***YOUR PASSWORD***]"
      }'

Replace [***YOUR URL NAME***], [***YOUR USER EMAIL***], and [***YOUR PASSWORD***] with your actual values.

Extract Access Token

After a successful login, the API returns a JSON response containing an accessToken, which is needed for subsequent authenticated requests.

Successful response example


      {
      "accessToken": "[***YOUR ACCESS TOKEN***]",
      "expiration": "2023-07-23T12:36:37.0355877Z",
      "refreshToken": {
      "token": "[***YOUR REFRESH TOKEN***]",
      "expiration": "2023-08-22T10:36:37.035615Z"
      },
      "userName": "[***YOUR USER NAME***]",
      "displayName": "[***YOUR DISPLAY NAME***]",
      "userEmail": null,
      "isAdmin": true,
      "error": null,
      "groupMember": [],
      "authLevel": "ADMIN",
      "displayModules": "..."
      }

Extract the accessToken from this response for the next step.

User Events Request

To retrieve user events, send a POST request to the /api/UserAccount/UserEvents endpoint.

This request requires the accessToken obtained from the previous step and the user must have an Admin role.

Construct and send the request.


      curl --location 'https://[***YOUR URL NAME***].octopai.com/api/UserAccount/UserEvents' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer [***ACCESS TOKEN***]' \
      --data '{
      "PageNumber":"1",
      "RowsInPage":"50",
      "fromDate": "2024-01-10 00:00:01",
      "toDate": "2024-01-10 23:59:59"
      }'

Replace [***YOUR NAME***] and [***ACCESS TOKEN***] with your actual values.

Understanding the Response
The response from the /api/UserAccount/UserEvents endpoint is an array of objects, each representing a user event.
Successful response example
```
      [
      {
      "type": "LOGIN SUCCESS",
      "userName": null,
      "source": "[***IP***]",
      "time": "2023-07-23T10:39:33.84"
      },
      {
      "type": "LOGIN FAIL",
      "userName": null,
      "source": "[***IP***]",
      "time": "2023-07-18T13:11:17.6"
      },
      {
      "type": "PAGE LOAD",
      "userName": null,
      "source": "[***IP***]",
      "time": "2023-07-18T13:10:58.2"
      }
      ]
    
```
Each object contains the following properties:
- ‘type’: The type of the event, for example, "LOGIN SUCCESS", "LOGIN FAIL".
- ‘userName’: The username associated with the event. This might be null or "UNKNOWN USER".
- ‘source’: The IP address from which the event originated.
- ‘time’: The timestamp of when the event occurred.

Store your accessToken securely and refresh it as needed to prevent it from being compromised. Always use HTTPS to make your requests to ensure data security during transit.

Contact Cloudera Support for more details and instructions.