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
{
  "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
    }
  ],
  "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.

Check user permissions⚓︎

To check whether a user has a particular RBAC permission within a particular scope, use the POST /config/v1/users/check_perm/ endpoint. Provide a bearer token, the name of the permission to check, and an optional scope for the permission to be verified against.

Field Mechanism Type Required Description
Authorization Header string Yes Bearer token identifying the requesting user. Format: Bearer {token}.
permission Request body field string Yes The codename of the permission to check. For example: add_table, select_sql. Returns 400 if the codename doesn't exist. See Permissions Reference for a full list of RBAC permissions.
scope_type Request body field string No The type of scoped object to check against. For example: org, project, table. Must be provided together with either scope_id or scope_name.
scope_id Request body field UUID No The UUID of the scoped object. Mutually exclusive with scope_name.
scope_name Request body field string No The dot-separated full name of the scoped object. For example: my-org.my-project. Mutually exclusive with scope_id.

Scope parameter rules:

  1. To do a global permission check, omit all three scope fields.
  2. To do a scoped check, provide scope_type plus exactly one of scope_id or scope_name.
  3. Providing scope_type without a scope identifier or vice versa returns 400.
  4. Providing both scope_id and scope_name returns 400.

Example requests⚓︎

Global check, Bearer token 
1
2
3
4
curl -X POST "https://$HOST/config/v1/users/check_perm/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permission": "add_table"}'
Scoped by ID, Bearer token 
1
2
3
4
5
6
7
8
curl -X POST "https://$HOST/config/v1/users/check_perm/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permission": "add_table",
    "scope_type": "project",
    "scope_id": "123e4567-e89b-12d3-a456-426614174000"
  }'
Scoped by name, Bearer token 
1
2
3
4
5
6
7
8
curl -X POST "https://$HOST/config/v1/users/check_perm/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permission": "add_table",
    "scope_type": "project",
    "scope_name": "my-org.my-project"
  }'

Responses⚓︎

1
2
200 OK
{ "permission": true }

1
2
200 OK
{ "permission": false }

1
400 Bad Request