Skip to content

Account Types

Overview⚓︎

The Config API and Keycloak implement unified auth in a Hydrolix cluster.

The Config API tracks accounts and provides two endpoints providing authentication services: Login to Hydrolix and Login to Hydrolix using SSO. By default, all APIs and network services are protected by unified auth.

Administrators can enable Basic access authentication for some services.

Hydrolix supports these account types:

  • User accounts - users, locally administered and authenticated
    • SSO user accounts - users, authenticated by an external identity provider, a type of user account
  • Service accounts - administrative accounts, added by local or SSO users
  • basic_auth accounts - administrative accounts, locally authenticated, backed by Kubernetes Secrets, not the unified auth system

User accounts⚓︎

User accounts are the traditional username (email address) and password pair and exist locally in a single Hydrolix cluster. To protect sensitive information, account credentials are stored in the Keycloak system. The Config API identifies users only by their UUID, requesting all authentication and authorization services from Keycloak.

For programmatic access, user accounts can retrieve Authorization tokens.

Users with sufficient permissions can use the API or UI to create a new user account and invite the user by email to the cluster. The new account isn't active until the user accepts the invitation and completes the registration process. See [User management How-to][user management howto].

Administrators can modify Account permissions or roles associated with user accounts. See RBAC How-to: Assign Role to User for examples.

SSO user accounts⚓︎

Single Sign-On (SSO) accounts support users authenticated by an external identity provider.

SSO accounts behave identically to user accounts when interacting with the Hydrolix UI and services delivered to a web browser.

Administrators must configure their chosen identity providers in the Keycloak system. See Single-Sign On (SSO) for instructions on configuring SSO.

SSO limitations⚓︎

Service accounts⚓︎

Service accounts are typically used for programmatic access to services. These accounts exist locally in a Hydrolix cluster, managed using the Config API.

  • SSO and user accounts with sufficient permissions can create service accounts and service account tokens.
  • Service accounts themselves have no credentials and can't authenticate. Instead these accounts use manageable, long-lived authorization tokens to gain access to services.
  • Users with permissions to manage service accounts may create, revoke, and delete variable lifetime authorization tokens. See Service Accounts How-to.
  • Service accounts with sufficient permissions can create additional service accounts or issue tokens.
  • Service account tokens are faster to validate than credential-based authentication.

API endpoints for users and service accounts⚓︎

The Config API provides separate endpoints for managing users and service accounts.

Breaking change in v5.11

Starting in v5.11, the /users endpoint no longer returns service accounts in its response. Use the dedicated /service_accounts endpoint to manage service accounts. For a temporary migration period, pass search_service_accounts=true on the /users endpoint to retrieve service accounts. This parameter will be removed in v5.12.x.

The /users endpoint⚓︎

The [List users][ref config_v1_users_list] endpoint returns user accounts only. This endpoint supports the following query parameters for filtering results:

Parameter Type Description
email string Filter by email address
username string Filter by username
first_name string Filter by first name
last_name string Filter by last name
search string Search across username, first name, and last name fields
exact boolean Return only exact matches instead of partial matches
page integer Page number. Defaults to 1
page_size integer Number of results per page. Defaults to 100

The /service_accounts endpoint⚓︎

The dedicated [List service accounts][ref config_v1_service_accounts_list] endpoint returns service accounts only. For details on creating, managing, and deleting service accounts using this endpoint, see Manage Service Accounts.

basic_auth accounts⚓︎

Each cluster runs a reverse proxy which handles internal load balancing among pods and nodes, and other application routing services.

Kubernetes administrators may install configurations into this reverse proxy for some services to support Basic access authentication, known as basic auth.

Basic auth credentials are independent and unknown to unified auth. See also Enable Basic Auth.