User Authentication

Overview

Hydrolix provides a unified auth system for your cluster. It works for all externally available endpoints. It is enabled by default and covers:

• Ingestion: HTTP Stream API
• Query: HTTP Query API, ClickHouse HTTP, ClickHouse (native), and MySQL
• Web: Hydrolix UI
• Utility and management services and endpoints like the transform validator, version, prometheus, and others

See Authentication and Authorization for more detail.

Users with sufficient permissions may create new users and manage existing users with web UI or user management Config API calls like List users.

Authenticating to the UI

Visit your Hydrolix cluster's IP address in a web browser to be directed to the login page if you aren't already logged in. Your browser will store an auth token in a browser cookie and present it during your session.

Authenticate to the API

For most Config API endpoints, only an auth token is accepted. The Login to Hydrolix endpoint accepts user credentials and supplies the auth token.

With this mechanism, the auth token, sometimes called a Bearer token after its type, is provided to the endpoint rather than a username and password. This token is valid for 24 hours, and can be thought of as a session token. This token authorizes access without the extra risk of sending usernames and passwords over the network for every request.

Retrieve an authorization token

Retrieve an auth or bearer token, using the Login to Hydrolix endpoint.

curl --request POST \
     --url https://{myhost}.hydrolix.live/config/v1/login \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "username": "[email protected]",
     "password": "secret"
}
'

Abridged user login response

This example shows how the response to a user passing valid credentials should look. The response JSON has been abridged for readability.

{
  "auth_token": {
    "access_token": "eyJhbGc___THIS_LONG_STRING_IS_THE_AUTHORIZATION_TOKEN___IJR7YQ",
    "expires_in": 86400,
    "token_type": "Bearer"    # -- Note, type, hence sometimes called "Bearer tokens"
  },
  "uuid": "3c2bac6c-ce32-4f52-afc6-1930d94fe307",
  "email": "[email protected]",
  "orgs": [
    {
      "uuid": "ae5e3698-b13a-4f8f-ab82-ad2fa391a1a8",
      "name": "Hydrolix",
      "type": "singletenant",
      "cloud": "aws",
      "kubernetes": true
    }
  ],
  "is_superuser": false,
  "roles": [
    "super_admin"                       # -- See Account Permissions (RBAC)
  ],
  "audit": false,
  "emailVerified": true,
  "enabled": true,                      # -- Accounts can be enabled / disabled
  "is_service_account": false,
  "name": "[email protected]"
}

JSON can be made more human-readable using a JSON pretty-printing utility such as jq or yq.

# `--raw-output` or `-r` prints only the value, omits the quotation marks
#
jq --raw-output .auth_token.access_token < "$FILE_CONTAINING_SUCCESSFUL_RESPONSE"

Example usage of an auth token

Fetch an auth token and store it in $HDX_TOKEN shell variable.

Present the Bearer <TOKEN> in an HTTP Authorization header. This is an example query using the HTTP Query API requesting recent record count in your cluster's hydro.logs table:

curl --request POST \
  --url https://{myhost}.hydrolix.live/query/ \
  --header "Authorization: Bearer $HDX_TOKEN" \
  --data 'SELECT COUNT() FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR'

If the token is invalid, the API will respond with a message like this:

{
    "error": "Code: 516. DB::Exception: [email protected]: Authentication failed: password is incorrect, or there is no user with such name. (AUTHENTICATION_FAILED)",
    "query": "SELECT COUNT() FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR"
}

🚧

Token Prefix

Don't forget the prefix Bearer.