Service Accounts Overview

This page describes service account concepts and how to use service account tokens.

Hydrolix recommends using service account tokens for automated processes. They validate faster than credential-based authentication, especially under repeated or high-volume use.

Service accounts

exist at the global scope in a cluster
have defined permissions in a specific cluster and aren't associated with any user accounts
use authorization tokens as the sole mechanism for gaining access to a cluster
can exist without currently valid tokens
can't be disabled; they must be deleted
with sufficient permissions can create other service accounts or issue service account tokens

To create and manage service accounts, see Manage Service Accounts.

For the permissions needed to create and manage service accounts, see Required permissions.

Service account token lifecycle⚓︎

Tokens and their lifecycle have the following characteristics:

Each service account can have unlimited valid tokens
Tokens have a configurable lifetime, determined by the expiry query parameter
Tokens default to a one year lifetime, 365 days
Tokens are valid until expiration, revocation, or deletion of the service account
Tokens can be invalidated individually or all tokens associated with a service account can be invalidated at once

Required permissions⚓︎

Users creating and managing service accounts and tokens must have the following permissions:

Permission	Action	Scope
`add_serviceaccount`	Create a service account.	`global`
`delete_serviceaccount`	Delete a service account.	`global`
`view_serviceaccount`	View service account details.	`global`
`issue_serviceaccounttoken`	Issue a new token for a service account.	`global` or `serviceaccount`
`revoke_serviceaccounttoken`	Revoke existing tokens.	`global` or `serviceaccount`
`view_serviceaccounttoken`	View token metadata for a service account.	`global` or `serviceaccount`

Permission rename in v6.0

The tokens_serviceaccount permission from earlier Hydrolix versions is renamed to issue_serviceaccounttoken in Hydrolix version 6.0. Existing roles that held tokens_serviceaccount automatically receive issue_serviceaccounttoken in its place.

Permission scopes⚓︎

Apply cluster-wide permissions using scope_type of global and scope_id of Service Account using the UI or API.

Limit token management permissions using scope_type of serviceaccount and set the scope_id field to the service account ID, using the API only:

Limit Token Management Permissions To A Single Service Account

This role can list, create, and delete service account tokens only for the specified service account.

curl --location "${HDX_HYDROLIX_URL}/config/v1/roles/" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${HDX_TOKEN}" \
--data '{
    "name": "token_manager",
    "policies": [
        {
            "permissions": [
                "view_serviceaccounttoken",
                "issue_serviceaccounttoken",
                "revoke_serviceaccounttoken"
            ],
            "scope_type": "serviceaccount",
            "scope_id": "'"${HDX_SA_UUID}"'"
        }
    ]
}'

Additional permissions are required to define and manage roles. For instructions on creating and assigning roles, see RBAC How-to: Assign Role to User.

Manage service accounts⚓︎

Action	UI	API
View a service account	View in UI	View with API
Create a service account	Create in UI	Create with API
Assign roles	Assign roles in UI	Assign roles with API
Issue a token	Issue token in UI	Issue token with API
View token metadata	Unavailable	List token metadata
Revoke tokens	Unavailable	Revoke tokens with API
Delete a service account	Delete in UI	Delete with API

Use service accounts⚓︎

Service accounts gain access solely using authorization tokens.

The service account username is never used when connecting to the Hydrolix cluster.

For HTTP services, use the HTTP header Authorization: Bearer $AUTH_TOKEN. For information about token format and lifetime, see Authorization tokens.

For non-HTTP services, use the special username __api_token__ and place the authorization token in the password field.

For connection examples using the __api_token__ pattern, see MySQL Client and ClickHouse.

Token Management⚓︎

A service account token authenticates a request to a Hydrolix cluster as a particular service account. Each token has a set expiry. A single service account can have several tokens issued on its behalf, and more than one of those tokens can be valid at the same time.

Because the service account itself never expires, the value to monitor for rotation is the token expiry, not the account. See View token issue and expiration dates to get a token expiration datetime using the API, and see Revoke tokens to disable tokens using the API.

Prior to v6.0, token metadata wasn't stored in Hydrolix after token creation making these tokens "untracked." See Get tracked and untracked tokens for a service account to determine how many untracked (pre-v6.0) and tracked (v6.0 and above) tokens exist for a cluster.

Configure datasources in visualization tools⚓︎

After creating a service account and issuing a token, configure datasources in visualization tools.

Grafana⚓︎

For detailed instructions on configuring Grafana with service accounts, including authentication patterns and circuit breaker settings, see Hydrolix Data Source Plugin for Grafana.

Other visualization tools⚓︎

For Superset, Kibana, and other tools that use the __api_token__ authentication pattern:

Username: __api_token__
Password: The service account token (the full JWT token value)

Consult the datasource configuration documentation for additional connection parameters.