Your Hydrolix cluster provides you with an API to access authentication activity, starting with Hydrolix version 4.12.

Overview

Hydrolix uses Keycloak under the hood for authentication. Authentication events can be retrieved from the HTTP API at https://<your_cluster_hostname>/config/v1/auth_logs using the GET action. The endpoint will return 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 should only be accessible to admins or those with specific permission to do so with view_auth_logs assigned.

Example

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

% 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": "[email protected]"
    }
  }
]