Overview

This feature is available as of Hydrolix version 4.21.x. See the Configuring SSO section to enable it.

Single Sign-On (SSO) gives users access to one or more Hydrolix clusters through an identity provider (IdP) of your choice. This allows each user within an organization to use a single set of credentials to access multiple applications, including Hydrolix. Using SSO improves organizational security through features like automated access provisioning/revocation and makes it easier for users to sign into multiple applications.

Hydrolix supports SSO through Keycloak, an open source Identity and Access Management (IAM) tool. Keycloak supports configuring various external identity providers using the following protocols:

• SAML v2.0
• OpenID Connect v1.0
• OAuth v2.0

Any identity provider that supports one of the above protocols works with Hydrolix.

📘

API uses Basic Authentication

With SSO enabled, API authentication still uses the Hydrolix basic authentication (username and password). You can read more about API authentication on the User Authentication page.

Configuring SSO

Configuring and enabling the use of SSO within a cluster has three main steps:

1. Access the Keycloak administration interface
2. Create an Identity Provider
3. Create Identity Provider attribute mappings

Access the Keycloak Administration Interface

🚧

Only the default admin account can access the Keycloak administration interface

Hydrolix user accounts are not able to authenticate to the Keycloak administration interface. You must instead use the automatically-generated Keycloak admin account.

Sign in to the Hydrolix cluster before accessing the Keycloak administrative interface. Once logged in, navigate to {hydrolix_url}/keycloak/admin. Upon accessing this page, you will be redirected to the Keycloak administration realm login page which requires using the following credentials for the automatically-generated Keycloak administration account:

Username: admin

Password: The password for the Keycloak administration account is stored in the general Kubernetes Secret, under the KEYCLOAK_ADMIN_PASSWORD key. You can access this Secret and base64 decode it using either of the following two methods:

• Kubectl: kubectl get secrets -o jsonpath='{.data.KEYCLOAK_ADMIN_PASSWORD}' general | base64 -d
• K9s:
  • Run K9s using the kubeconfig for your Hydrolix cluster.
  • Run the command :secrets to view existing Secrets for the cluster.
  • Navigate to the general Secret and press x to decode its config.
  • Copy the value for the KEYCLOAK_ADMIN_PASSWORD.
  • Exit K9s and run echo {insert-keycloak-admin-password-here}

📘

Security and the Keycloak admin panel

Keycloak’s production environment recommendations state that it is best practice to host the Keycloak administration UI and API endpoints on a separate domain, without public access. This is not currently possible with Hydrolix’s architecture. Instead, the Keycloak administration interface is placed behind unified authentication: a user must be signed in to the cluster before the administration login interface is accessible. Access beyond the administration login interface requires use of the additional administrator password.

Create an Identity Provider

🚧

Hydrolix does not currently support IdP-initiated SSO

Users must initiate authentication from the Hydrolix cluster login page.

In the Keycloak administration interface, select the hydrolix-users realm.

Select Identity providers in the sidebar.

Select Add provider. At minimum, the following must be configured:

Select Add once you've completed the configuration for your IdP.

After creating the IdP, ensure that Trust Email is enabled if the option is available.

🚧

"Trust Email" must be enabled

If Trust Email is not enabled, users authenticating using the newly created IdP will be unable to sign into Hydrolix. Hydrolix does not currently support Keycloak’s email verification.

Next, configure your Identity Provider Mappers.

Create Identity Provider Attribute Mappings

User profile attributes instruct turbine-api on how a user should be handled when they sign into Hydrolix. IdP Attribute mappers dictate which attributes should be set on a user’s profile when they sign into Hydrolix using the Identity Provider. Attribute mappers are configured on a per-IdP basis, and determine the Org a user is a part of, as well as optionally the RBAC permissions they should be granted.

Custom Attributes

The following are descriptions of Hydrolix-specific user profile attributes:

The following covers a general use case in which the Org and RBAC roles are hardcoded and set to the same values for all users who will be authenticating with the given IdP. Advanced configuration is possible; for example, extracting RBAC roles from a SAML response.

• In the hydrolix-users realm, select the Identity Providers section of the sidebar.

• Select the IdP you would like to configure mappers for.

• Navigate to the Mappers tab.

• Select Add mapper.

• Give the mapper a descriptive name such as “SSO Organization ID” or “Read-Only User Role”.

• Sync mode override: In many cases setting “Sync mode override” to “Force” will be the preferred functionality, ensuring that the user’s attributes are updated with every sign in.

• Set Mapper type to “Hardcoded Attribute”.

• User Attribute

  • If configuring the hdx-sso-org attribute, select it in the “User Attribute” dropdown. Enter the UUID of the org in the “User Attribute Value” input.
  • If configuring the hdx-sso-rbac-roles attribute, select it in the “User Attribute” dropdown. Enter the name of the role in the “User Attribute Value” input.
  
  

🚧

Keycloak UI constrains hardcoded RBAC Roles

Due to limitations in the Keycloak administration UI, when hardcoding RBAC roles, only one may be specified. If configuring via Keycloak’s administration API or using other mapper types, this limitation does not apply.

• Select Save when finished.

---

Google: SAML vs OAuth

Hydrolix can be configured to use SSO authentication through Google using two different protocols. Both of these authentication methods allow access to a Hydrolix cluster with a Google account, but there are tradeoffs in ease of configuration and the ability to restrict access to particular resources.

Google SAML

Using SAML to configure authentication with Google allows more fine grained control, limiting its usage to only users in groups that you specify in the Google administration Console. It is relatively more complex to configure than Google OAuth, but allows more flexibility. It is the recommended way to configure sign on with Google.

In the Google administration Console:

• Navigate to Apps > Web then Mobile apps. Select Add app > Add custom SAML app.
• Fill out App details with the relevant information.
• Select Continue.
• Select Download IdP metadata and save this metadata to a location you will remember.
• Select Continue.

In the Keycloak administration interface:

• Navigate to Identity providers in the hydrolix-users realm.
• Select Add provider > SAML v2.0.
• Configure the provider information with the relevant information.
• Uncheck Use entity descriptor under SAML settings.
• Import config from file: select the file you previously downloaded from Google.
• Make a note of the values set for Redirect URI and Service provider entity ID.

Back in the Google administration console:

• Configure the service provider details.
• Select Continue.
• Enter the previously noted Redirect URI in the ACS URL input.
• Enter the previously noted Service provider entity ID into the Entity ID input.
• Configure any desired group memberships or attributes.
• Select Finish.

In the Keycloak administration interface:

• Ensure Trust email is enabled on the IdP.
• Configure attribute mappings according to the Create Identity Provider Attribute Mappings section.
• Select Add to save the IdP in Keycloak.

Google OAuth

SSO with Google OAuth is easier to configure than Google SAML, but allows less fine-grained permission configuration. OAuth clients can be restricted to a single Google Workspace organization, but configuration of permissions cannot be more fine grained than that - all users will be able to sign into the Hydrolix cluster.

In the Google Cloud Console:

• Create an OAuth application. See the official documentation for details.
• Recommended: Configure the application to be Internal ensuring only users from your Organization are able to sign in with it. If this is not configured, any user with a Google account will be able to access your cluster.

In the Keycloak administration interface:

• Navigate to the Identity Providers tab within the hydrolix-users realm.
• Add a new Identity Provider, selecting Google as the type.
• Populate Client ID and Client Secret with details for your app from the Google Cloud Console.

In the Google Cloud Console:

• Copy the provided Redirect URI from the Keycloak administration interface and add it to your application’s Authorized redirect URIs in the Cloud Console.
• Optional: Enter your Google Workspace domain into the Hosted Domain input.

In the Keycloak administration interface:

• Enable the “Trust email” option
• Save the IdP in Keycloak.
• Configure attribute mappings according to the Create Identity Provider Attribute Mappings section.
• Verify that Google now displays as an option when authenticating in a browser through {hydrolix_url}/config/v1/login and that you are able to sign into the cluster using it.