Authentication and Authorization

Overview

Only SSO and user accounts can authenticate to a Hydrolix cluster. Once authenticated, these users may also acquire authorization tokens.

Service accounts can only use authorization tokens generated and managed by authenticated users. Service accounts are for any programmatic or automated interactions with Hydrolix applications.

Administrators control and assign access to accounts using roles defined in a flexible Account Permissions (RBAC) system.

Permissions are associated with accounts. The unified auth system enforces permissions at time of use and allows administrators to modify roles. After a permission change, clients can use existing tokens to access updated permissions.

Manage users with the web UI or Config API.

This page describes authentication mechanisms to a Hydrolix cluster, and authorization tokens, also known as auth tokens or bearer tokens.

Access enforcement

Hydrolix ensures that one of these conditions is true for each request, or it denies access:

• The request includes a valid authorization token in HTTP header Authorization: Bearer $AUTH_TOKEN
• The web browser client includes a valid authorization token in a cookie
• The endpoint supports HTTP basic auth and the request includes valid user credentials
• The endpoint is an exempt endpoint, necessary for pages like login and password reset

System description

The Config API is the center of the unified auth system.

It depends on Keycloak for hashing and storage of user passwords and signing of user account tokens.

Signing and validation of service account tokens is handled by the Config API using a keypair stored in SERVICE_ACCOUNT_PUBLIC_KEY and SERVICE_ACCOUNT_PRIVATE_KEY Kubernetes general secret.

Other APIs and applications in the cluster call Config API for authentication, authorization, and access control decisions. All services and endpoints accept auth tokens. Some API calls and services accept credentials as well. See the use case chart below for a detailed listing.

Use cases

Authentication mechanisms

There are several authentication mechanisms for interacting with a Hydrolix cluster, depending on the account type. Only SSO and user accounts can authenticate to the unified auth system in a Hydrolix cluster.

• User accounts are locally managed and authenticated by the Config API, credentials stored in Keycloak
• Single-sign on (SSO) authentication is handled by an identity provider. Administrators configure the Keycloak system to delegate authentication responsibility to the identity provider. Keycloak then manages an identity and authorization token for the SSO account.

After successful authentication in the UI, a supplied cookie with authorization information allows web browsers using the Hydrolix UI and other in-cluster services like Prometheus, Grafana, and Superset. The cookie contains an authorization token.

After successful authentication in the API, the client can store the supplied authorization token and use it for its validity lifetime.

For select services, basic authentication is available, managed in the reverse proxy layer. This provides an alternative for diagnostic and administrative purposes. Incompatible with the Config API and the rich Account Permissions system.

Authentication with user credentials

For programmatic access, some HTTP endpoints accept user credentials conveyed using basic access authentication. Auth tokens are recommended instead.

Clients present credentials in the HTTP header Authorization: Basic ${BASE64_ENCODED_CREDENTIALS}.

All non-HTTP services accept user credentials and authorization tokens with a sentinel username: __api_token__.

For browser interactions see Cookies.

Authorization tokens

For programmatic access, authorization tokens are the primary and recommended mechanism. For browser interactions see Cookies.

An authorization token is always associated to exactly one user, SSO, or service account. Tokens are implemented as signed JSON Web Tokens (JWTs) issued to specific accounts. See also Account types.

Clients present an auth token in the HTTP header Authorization: Bearer ${AUTH_TOKEN}.

For non-HTTP services, supply __api_token__ in the username and the auth token in the password field.

Authorization tokens are commonly called auth tokens and are an implementation of RFC 6750, The OAuth 2.0 Authorization Framework: Bearer Token Usage.

Acquiring auth tokens

Only authenticated users may retrieve, create, delete, or revoke authorization tokens.

Local user accounts can use the Login to Hydrolix endpoint to acquire an auth token.

SSO accounts can't receive an authorization token through the usual login flow. Instead, SSO users can create service accounts and corresponding auth tokens. For a workaround, see how to extract auth tokens by inspecting cookies.

The unified auth system issues tokens to authenticated users and validates any authorization tokens presented to APIs, network services, and the Hydrolix UI.

Each token has a validity lifetime and is associated with a single account, of type user, SSO, or service.

User auth tokens

An authorization token for a user account is valid for 24 hours. This token authorizes access without the extra risk of sending rarely-changing usernames and passwords over the network for every request.

Service account auth tokens

Auth tokens issued to service accounts are revocable and have a default lifetime of one year. Tokens can be generated using the API or UI by users with permissions to manage service accounts. See Service Accounts.

Cookies

Users authenticating to the Hydrolix UI with account credentials or with SSO receive an httpOnly cookie containing an authorization token visible to the browser, not the Javascript Hydrolix UI. The browser includes the cookie on subsequent requests, ensuring that the cluster's Config API application receives the auth token.

Cookies contain the following parameters:

It's possible to extract the authorization token from a cookie.

⚠️

Consider service accounts

While it's possible to extract authorization tokens from cookies, these tokens are associated with user and SSO accounts and have a short lifetime. Authorization tokens with a 24-hour lifetime are inconvenient for programmatic usage. Consider service accounts instead.

Beginning with release v5.4, Hydrolix supports flexible service account management tools.

Example command-line cookie retrieval

This example shows how to programmatically retrieve cookies.

curl -v -X POST -H "Content-Type: application/json" \
     --cookie-jar cookie.jar \
  https://{myhost}.hydrolix.live/config/v1/login/ \
  -d "{
    \"username\":\"$HDX_USERNAME\",
    \"password\":\"$HDX_PASSWORD\"
  }"

#HttpOnly_{myhost}.hydrolix.live     FALSE   /       TRUE    1753568882      HYDROLIX_ID_TOKEN       eyJhbGc_ELIDED_LHs4wObQ
#HttpOnly_{myhost}.hydrolix.live     FALSE   /       TRUE    1753568882      HYDROLIX_TOKEN  eyJhbGc_ELIDED_JmhJ28Iw

Example browser cookie screenshot

Inspect the cookie jar using developer tools in the browser to find the cookies.

Browsers support development and inspection tools. Use these tools to locate the cookie.

1. Open web developer tools.
2. Navigate to display of locally stored cookies.
   a. Firefox: Navigate to Storage > Cookies.
   b. Chrome: Navigate to Application > Cookies.
3. Inspect or retrieve the contents of HYDROLIX_TOKEN.

Basic authentication

Administrators can configure some endpoints to support HTTP Basic Access Authentication using a Kubernetes Secret to store the credentials.

⚠️

Not a part of unified auth system

The other authentication and authorization features described here participate in the unified auth system. The basic auth feature exists separately and is incompatible with the Config API and the rich Account Permissions system.

This authentication mechanism is managed outside of the Keycloak unified auth system in the cluster's reverse proxy software. It provides an alternate for administrative, diagnostic, and monitoring purposes. See Enable Basic Authentication.

Exempt endpoints

Some endpoints are necessarily exempt from authentication and authorization requirements, not limited to those which provide authentication services. Here are some examples:

• /login - Hydrolix UI main login page
• /password-reset - password reset request endpoint
• /verifypassword/{uuid}/{token} - password reset verification endpoint
• /.well-known/acme-challenge - HTTP challenge response for proof of control of a domain name, see Hydrolix ACME Client

Reporting

The unified auth system generates Authentication Audit Logging events, retrievable using the Get auth logs endpoint.

Also, view reports of usage, including valid and invalid requests per token, in your Hydrolix cluster's Prometheus reporting.