Federated Authentication

This feature was introduced in Hydrolix version 6.1.

Federated authentication enables the Hydrolix Config API to accept Bearer tokens signed by external JSON Web Token (JWT) issuers: an Okta tenant, an Auth0 application, or any identity provider that publishes a JSON Web Key Set (JWKS) endpoint accessible from the cluster's network.

This is useful when external services or automation tools need programmatic access to the Config API without routing those tokens through the cluster's Keycloak.

Keycloak-issued tokens and service account tokens continue to work alongside federated authentication with no changes required.

When to use federated authentication

Use federated authentication when external services or automation tools need to call the Config API using tokens your organization's identity provider already issues. Federated authentication is for API access only and doesn't support browser login flows.

For browser-based single sign-on, where users log in to the Hydrolix UI through your identity provider, use Single Sign-On (SSO) instead.

How it works

When the Config API receives a request with an Authorization: Bearer <token> header, it:

1. Reads the iss (issuer) claim from the token to identify the issuer.
2. Looks up the matching issuer in its list of trusted issuers.
3. Fetches the issuer's public signing key from the configured JWKS endpoint.
4. Verifies the token signature and validates the exp (expiry). If present, validates aud (audience) and signing algorithm.
5. Looks up the Hydrolix user whose external identity matches the token's iss and sub (subject) claims.

If any step fails, the API returns 401 Unauthorized.

Token validity is enforced on each request.

Configure federated authentication

Setting up federated authentication requires two steps:

1. Configure trusted token issuers
2. Provision an external user

Configure trusted token issuers

Add the turbine_api_trusted_token_issuers tunable to the spec section of your hydrolixcluster.yaml. Each entry in the list defines one trusted issuer, identified by a unique iss value. The first entry in this example includes the optional algorithms and audience fields; the second shows the minimum required configuration.

apiVersion: hydrolix.io/v1
kind: HydrolixCluster
metadata:
  name: hdx
  namespace: hydrolix
spec:
  turbine_api_trusted_token_issuers:
    - iss: https://idp.example.com
      jwks_uri: https://idp.example.com/.well-known/jwks.json
      algorithms:
        - RS256
      audience: https://hydrolix.example.com
    - iss: https://other-idp.example.com
      jwks_uri: https://other-idp.example.com/.well-known/jwks.json

Trusted token issuer fields

Field	Type	Required	Description
iss	string	Yes	The issuer identifier. Must match the iss claim in incoming tokens exactly.
jwks_uri	URL	Yes	The JWKS endpoint where the issuer's public keys are published.
algorithms	list of strings	No	Signing algorithms to accept. If omitted, any algorithm supported by the issuer's keys is accepted.
audience	string	No	When set, the value that must appear in the aud claim of incoming tokens. If omitted, see Token rejected despite valid issuer configuration.

Provision an external user

Before a federated token can be used, you must create a Hydrolix external user account linked to the external identity.

Assign and manage roles on the external user account the same way as any other account. See Account Permissions (RBAC) for details.

To create an external user, call POST /config/v1/users/ with the issuer and external ID:

• issuer must match the iss field in the turbine_api_trusted_token_issuers configuration exactly.
• external_id must match the sub claim in the tokens that user will present.

Create External User

curl --request POST \
     --url https://{hostname}.hydrolix.live/config/v1/users/ \
     --header "Authorization: Bearer $ADMIN_TOKEN" \
     --header "Content-Type: application/json" \
     --data '{
       "issuer": "https://idp.example.com",
       "external_id": "the-sub-claim-from-the-jwt"
     }'

Use a federated token

With configuration complete, the cluster accepts requests authenticated with tokens from your identity provider. Obtain a token and pass it as a Bearer token in the Authorization header.

Config API Request with Federated Token

curl --request GET \
     --url https://hostname.hydrolix.live/config/v1/orgs/ \
     --header "Authorization: Bearer $EXTERNAL_TOKEN"

Troubleshoot

These are the most common causes of authentication failures when setting up federated authentication.

All authentication failures return 401 Unauthorized with the same Invalid authentication credentials provided message. To identify the specific cause, check the turbine-api pod logs, which include the underlying error.

JWKS endpoint unreachable

If the configured jwks_uri isn't accessible from within the cluster's network, the Config API can't retrieve the signing keys needed to verify tokens. All requests from that issuer fail with 401 until the endpoint becomes reachable.

Verify that the JWKS endpoint is accessible from the turbine-api pod and that no network policy or firewall rule blocks outbound HTTP from it.

Token rejected despite valid issuer configuration

If the issuer is configured and the token signature is valid but requests still return 401, check whether audience is set in the issuer configuration.

When audience is omitted, the Config API rejects any token that includes an aud claim, even a valid one. Most identity providers include aud in their tokens by default. Set audience in the issuer's turbine_api_trusted_token_issuers entry to the aud claim value your identity provider includes in its tokens.

User not found

If the token is valid but no Hydrolix external user account matches the iss and sub claims, the request is rejected. Check the turbine-api logs for a User not found entry to confirm this is the cause. Check that an external user exists with both issuer matching the token's iss claim and external_id matching the sub claim exactly. If not, follow the steps in Provision an external user.