Documentation
ProductPricingDocsBlog

Enable Query Authentication

Suggest Edits

You can query your Hydrolix cluster in two ways:

  • The native ClickHouse interface via TCP
  • The HTTP API

Enable query authentication to require authentication tokens for both methods.

📘

Query Authentication is now on by default

Starting with version 4.6 of Hydrolix, Query Authentication is part of Unified Authentication, which is turned on by default. If you wish to disable Unified Authentication, set unified_auth: false in your hydrolixconfig.yaml file.

Enable Query Authentication

To enable query authentication, add the enable_query_auth: true flag in the cluster configuration file:

spec:
  enable_query_auth: true

Authenticate Over TCP

The native ClickHouse interface configures authentication using a username and password methodology. Users must have a username and password set up within Hydrolix to be able to gain access.

An example for using Authentication for the clickhouse-client is provided below:

clickhouse client --host hostname.company.net --port 9440 -s --user [email protected] --password mypassword

{
    "timestamp": "2023-08-15T16:41:48.929+00:00",
    "component": "tcp_handler",
    "level": "error",
    "message": "Address: 10.24.216.136:40924 failed to authenticate user '[email protected]' due to <TurbineApiAuthenticatorError api login failed with provided username/password '[email protected]'. <HttpPermanentResponseError error=request_failed status_code=401 path=/v1/login {\"detail\":\"Could not login\"} (Hydrolix v3.48.5 - Turbine aceb91e6)> (Hydrolix v3.48.5 - Turbine aceb91e6)>",
    "hydrolix_version": "v3.48.5",
    "turbine_revision": "aceb91e6"
}

For invalid login info, it throws a NETWORK_ERROR and logs an error message in query-head.

❗️

TLS encryption

Always Enable TLS on a cluster that uses query authentication. This ensures that the client does not send unencrypted username and password information to the server.

Authenticate Grafana

Use the following configuration to authenticate with Grafana using the ClickHouse plugin configuration:

1488

Authenticate Superset

To authenticate with Hydrolix in Superset using the ClickHouse plugin, modify the connection string:

clickhouse+native://[email protected]:[email protected]/sample_project?secure=true
1000

Authenticate over HTTP API

The HTTP API authentication mechanism supports two types of authentication:

Bearer Token

In this mechanism, the Bearer token is provided to the end-point, rather than the username and password.

Use the Login API endpoint to retrieve the Bearer token, which generates a token valid for 1 day. Use this token to authorize queries.

Use the login API to retrieve a token:

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

The login API returns the following output:

{
  "uuid": "1111-2222-3333-4444-5555",
  "email": "[email protected]",
  "orgs": [
    {
      "uuid": "aaaa-bbbb-cccc-dddd",
      "name": "Hydrolix",
      "type": "singletenant"
    }
  ],
  "groups": [
    "org.asdf.Hydrolix.admin"
  ],
  "auth_token": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJXbzNLa21MbnhDNzVyaHVJQXR0RHhxak9LTlh4bURvWU5pTkVyeExueHhRIn0.eyJleHAiOjE2NjA0MDE4NjQsImlhdCI6MTY2MDMxNTQ2NCwianRpIjoiYmUzOTllMmItZjhkNC00MjY2LWI3OTYtZDdjN2NhZDhkNGU1IiwiaXNzIjoiaHR0cDovL2tleWNsb2FrOjgwODAvYXV0aC9yZWFsbXMvaHlkcm9saXgtdXNlcnMiLCJhdWQiOlsiY29uZmlnLWFwaSIsImFjY291bnQiXSwic3ViIjoiODM0NTc4M2YtYjE3Yi00ZTdhLTk3MDAtOTA5MzAxNmIyNWFmIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiY29uZmlnLWFwaSIsInNlc3Npb25fc3RhdGUiOiJiZjY0ZTkwMy1iNmZjLTQ0NWEtYWU4Yi0wZDM1NzI1OGZkZGEiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbImh0dHA6Ly9sb2NhbGhvc3Q6MzAwMSJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiZGVmYXVsdC1yb2xlcy1oeWRyb2xpeC11c2VycyIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6ImVtYWlsIGNvbmZpZy1hcGktc2VydmljZSBwcm9maWxlIiwic2lkIjoiYmY2NGU5MDMtYjZmYy00NDVhLWFlOGItMGQzNTcyNThmZGRhIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2VzQGh5ZHJvbGl4LmlvIiwiZW1haWwiOiJzZXJ2aWNlc0BoeWRyb2xpeC5pbyJ9.hR9Cv52CYVlG_FoSoGxvKjWXJXSWxxBMQJKP7EMbVxfpOZmQNmfaBPuBMO7NbGM12a7VPo8V_SQqxneJHPX4sxOiZ1DPePU1QPTrhh41-FkvyD6lQ9FEnAQGZFLFp0VKYiNbMIYnnM1dyfQAARwwcNq7wWQ_kZmzAz9QZMbdvtKzmGnlhsZkirBkz7aWQcnyuJQPcg6CZPa4p9nsP7qcLqMGY_b88v_VnBO13qM4u20NFvo2h8pef_tgtFupvZiUDMDjIFI_UTij6PLNJZFBYwmrxIMNrmJshtGIbMfRMFHKMVe6l7ruzwxCj-asdfasdfasdf",
    "expires_in": 86400,
    "token_type": "Bearer"
  }
}

Include the auth_token.access_token field value in your HTTP requests to authenticate with the token. Use a header named authorization with the value Bearer <TOKEN>:

curl --request POST \
  --url https://hostname.company.net/query/ \
  --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJXbzNLa21MbnhDNzVyaHVJQXR0RHhxak9LTlh4bURvWU5pTkVyeExueHhRIn0.eyJleHAiOjE2NjA0MDE4NjQsImlhdCI6MTY2MDMxNTQ2NCwianRpIjoiYmUzOTllMmItZjhkNC00MjY2LWI3OTYtZDdjN2NhZDhkNGU1IiwiaXNzIjoiaHR0cDovL2tleWNsb2FrOjgwODAvYXV0aC9yZWFsbXMvaHlkcm9saXgtdXNlcnMiLCJhdWQiOlsiY29uZmlnLWFwaSIsImFjY291bnQiXSwic3ViIjoiODM0NTc4M2YtYjE3Yi00ZTdhLTk3MDAtOTA5MzAxNmIyNWFmIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiY29uZmlnLWFwaSIsInNlc3Npb25fc3RhdGUiOiJiZjY0ZTkwMy1iNmZjLTQ0NWEtYWU4Yi0wZDM1NzI1OGZkZGEiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbImh0dHA6Ly9sb2NhbGhvc3Q6MzAwMSJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiZGVmYXVsdC1yb2xlcy1oeWRyb2xpeC11c2VycyIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6ImVtYWlsIGNvbmZpZy1hcGktc2VydmljZSBwcm9maWxlIiwic2lkIjoiYmY2NGU5MDMtYjZmYy00NDVhLWFlOGItMGQzNTcyNThmZGRhIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2VzQGh5ZHJvbGl4LmlvIiwiZW1haWwiOiJzZXJ2aWNlc0BoeWRyb2xpeC5pbyJ9.hR9Cv52CYVlG_FoSoGxvKjWXJXSWxxBMQJKP7EMbVxfpOZmQNmfaBPuBMO7NbGM12a7VPo8V_SQqxneJHPX4sxOiZ1DPePU1QPTrhh41-FkvyD6lQ9FEnAQGZFLFp0VKYiNbMIYnnM1dyfQAARwwcNq7wWQ_kZmzAz9QZMbdvtKzmGnlhsZkirBkz7aWQcnyuJQPcg6CZPa4p9nsP7qcLqMGY_b88v_VnBO13qM4u20NFvo2h8pef_tgtFupvZiUDMDjIFI_UTij6PLNJZFBYwmrxIMNrmJshtGIbMfRMFHKMVe6l7ruzwxCj-asdfasdfasdf' \
  --data 'SELECT column FROM table'

{
    "error": "std::exception. Code: 1001, type: h::db::AclError, e.what() = <AclError invalid user token provided (Hydrolix v3.48.5 - Turbine aceb91e6)>, Stack trace (when copying this message, always include the lines below):\n\n (version 22.12.1.1)",
    "query": "select count() from hydro.logs"
}

🚧

Token Prefix

Don't forget the prefix Bearer .

Username and Password

We also support authentication using username and password. Pass username and password data via the Authorization header. This basic authentication base64-encodes the username and password, separated by a colon.
The following snippet shows one way to authenticate via username and password with the curl command:

curl --user user:password \
  --request POST \
  --url https://hostname.company.net/query/ \
  --data 'SELECT column FROM table'

{
    "error": "std::exception. Code: 1001, type: h::TurbineApiAuthenticatorError, e.what() = <TurbineApiAuthenticatorError api login failed with provided username/password '<username>'. <HttpPermanentResponseError error=request_failed status_code=401 path=/v1/login {\"detail\":\"Could not login\"} (Hydrolix v3.48.5 - Turbine aceb91e6)> (Hydrolix v3.48.5 - Turbine aceb91e6)>, Stack trace (when copying this message, always include the lines below):\n\n (version 22.12.1.1)",
    "query": "select count() from hydro.logs"
}

Updated about 2 months ago