Skip to content

Audit Logging

Your Hydrolix cluster provides you with an API to access authentication activity.

Overview⚓︎

Hydrolix uses Keycloak for authentication. Retrieve authentication events from the HTTP API at https://{myhost}.hydrolix.live/config/v1/auth_logs using the GET action. The endpoint returns a JSON-formatted list of all Keycloak events.

Filters⚓︎

Filters can be specified in the request body. These filters include:

  • user_id string: Includes all Keycloak events that are created by the given user. To return all Keycloak events regardless of user, exclude the field.

  • event_types array(string): Specifies all the event types to be included in the response. The most useful event types are:

  • LOGIN: A user has successfully logged in and has begun a Keycloak session. The sessionId is included in the Keycloak event object.

  • LOGIN_ERROR: Someone has tried logging in as the user and failed. The reason for this failure is included in the error field in the event object (invalid_user_credentials, timed_out, and others).

  • USER_DISABLED_BY_TEMPORARY_LOCKOUT: A user has been locked out temporarily, with the reason included in the event object.

  • USER_DISABLED_BY_PERMANENT_LOCKOUT: A user has been locked out permanently, with the reason included in the event object.

  • from_date string: Excludes all events that occur before the provided time. Should be in the format YYYY-MM-DD.

  • to_date string: Excludes all events that occur after the provided time. Should be in the format YYYY-MM-DD.

  • limit int: Limits the number of events returned in the response. The default limit is 100 events.

RBAC permissions⚓︎

This endpoint is accessible to admins or those with specific permission to do so with view_auth_logs assigned.

Example API call⚓︎

After setting $HDX_TOKEN and $HDX_HOSTNAME, this command will retrieve all the login errors from May 19, 2024 and onward:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
curl -s --header "authorization: Bearer $HDX_TOKEN" \
  --header "Content-Type: application/json" \
  --request GET \
  --url https://${HDX_HOSTNAME}/config/v1/auth_logs/ \
  --data '{"event_types": ["LOGIN_ERROR"],
           "from_date": "2024-05-19"}' | jq
[
  {
    "time": 1716238444160,
    "type": "LOGIN_ERROR",
    "realmId": "hydrolix-users",
    "clientId": "config-api",
    "userId": "03345f81-7bb2-4a03-8f1f-b248fc2c9efb",
    "ipAddress": "10.8.0.21",
    "error": "invalid_user_credentials",
    "details": {
      "auth_method": "openid-connect",
      "grant_type": "password",
      "client_auth_method": "client-secret",
      "username": "test@hydrolix.io"
    }
  }
]