Skip to content

User Authentication

Overview⚓︎

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

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 authorization token in a browser cookie and present it during your session.

Authenticate to the API⚓︎

For most Config API endpoints, only an authorization token is accepted.

The Login to Hydrolix endpoint accepts user credentials and supplies the authorization token. Clients can then present this authorization token, sometimes called a bearer token, rather than a username and password.

The authorization token is valid for access to everything permitted to the connected user account for 24 hours from issue, before the server requires reauthentication.

Retrieve an authorization token⚓︎

Retrieve an authorization token using the Login to Hydrolix endpoint.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
curl --request POST \
     --url https://hostname.hydrolix.live/config/v1/login \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "username": "username@example.com",
     "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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "auth_token": {
    "access_token": "eyJhbGc___THIS_LONG_STRING_IS_THE_AUTHORIZATION_TOKEN___IJR7YQ",
    "expires_in": 86400,
    "token_type": "Bearer" // (1)
  },
  "uuid": "3c2bac6c-ce32-4f52-afc6-1930d94fe307",
  "email": "username@example.com",
  "orgs": [
    {
      "uuid": "ae5e3698-b13a-4f8f-ab82-ad2fa391a1a8",
      "name": "Hydrolix",
      "type": "singletenant",
      "cloud": "aws",
      "kubernetes": true
    }
  ],
  "is_superuser": false,
  "roles": [
    "super_admin" // (2)
  ],
  "audit": false,
  "emailVerified": true,
  "enabled": true, // (3)
  "is_service_account": false,
  "name": "username@example.com"
}
  1. This type of token is usable in an HTTP Authorization header of type Bearer.
  2. This is a listing of role names. Each contains sets of permissions. See also Account Permissions (RBAC).
  3. Usually, enabled. An account can be permanently disabled. See Disable User.

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

1
2
3
# `--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 authorization token⚓︎

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

Get the bearer token, which is good for the next 24 hours, to authenticate future API calls. This command assumes you've set the $HDX_HOSTNAME, $HDX_USER, and $HDX_PASSWORD environment variables:

1
2
3
4
5
6
7
8
export HDX_TOKEN=$(
  curl -v -X POST -H "Content-Type: application/json" \
  https://$HDX_HOSTNAME/config/v1/login/ \
  -d "{
    \"username\":\"$HDX_USER\",
    \"password\":\"$HDX_PASSWORD\"  
  }" | jq -r ".auth_token.access_token"
)

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:

1
2
3
4
curl --request POST \
  --url https://hostname.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:

1
2
3
4
{
    "error": "Code: 516. DB::Exception: username@example.com: 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.