Single Sign-On (SSO)

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.

For limitations regarding SSO in Hydrolix, see Limitations.

Prerequisites

If you have not already installed either the kubectl or K9s tools, see Install Tools.

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 mappers

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.

1. Sign in to the Hydrolix cluster.
2. Navigate to {myhost}.hydrolix.live/keycloak/admin.
3. You will be redirected to the Keycloak administration realm login page. This page 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

  1. Run K9s using the kubeconfig for your Hydrolix cluster.
  2. Run the command :secrets to view existing Secrets for the cluster.
  3. Navigate to the general Secret and press x to decode its config.
  4. Copy the value for the KEYCLOAK_ADMIN_PASSWORD.

Create an identity provider

See also Keycloak's Integrating identity providers .

⚠️

Hydrolix does not support IdP-initiated SSO

Users must initiate authentication from the Hydrolix cluster login page.

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

2. Select Identity providers in the sidebar.

3. Select an identity provider.
4. Complete the identity provider form using values from your IdP of choice.
5. Click Add once you've completed the configuration for your IdP.
6. 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.

Create identity provider attribute mappers

User profile attributes determine 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 user's organization and account permissions.

Custom Attributes

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

The following covers a general use case in which the sso-org and sso-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.

1. In the hydrolix-users realm, select the Identity Providers section of the sidebar.
2. Select the IdP you would like to configure mappers for.
3. Navigate to the Mappers tab and select Add mapper.
4. Name the mapper, for example: “SSO Organization ID” or “Read-Only User Role”.
5. Set Sync mode override to Force.
   • This ensures that the user’s attributes are updated with every sign in.
6. Set Mapper type to “Hardcoded Attribute”.
7. Configure 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 with Keycloak’s administration API or using other mapper types, this limitation does not apply.

9. Click 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 Admin console. While SAML is more complex to configure, it allows more flexibility and is recommended.

In the Google Admin console:

1. Navigate to Apps > Web > Mobile apps.
2. Select Add app > Add custom SAML app.
3. Enter the relevant information.
4. Select Continue.
5. Select Download IdP metadata and save this metadata to a location you will remember.
6. Select Continue.

In the Keycloak Admin Console:

1. Navigate to Identity providers in the hydrolix-users realm.
2. Select SAML v2.0.
3. Enter the relevant information.
4. Disable Use entity descriptor under SAML settings.
5. Import config from file: select the IdP metadata file you previously downloaded from Google.
6. Make a note of the values set for Redirect URI and Service provider entity ID.

Return to the Google Admin console:

1. Configure the service provider details.
2. Select Continue.
3. Enter the previously noted Redirect URI in the ACS URL input.
4. Enter the previously noted Service provider entity ID in the Entity ID field.
5. Configure any desired group memberships or attributes.
6. Select Finish.

In the Keycloak Admin Console:

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

Google OAuth

SSO with Google OAuth is easier to configure than Google SAML, but allows less granular permission configuration. OAuth clients can be restricted to a single Google Workspace organization, but configuration of permissions can't be more specific: all users will be able to sign into the Hydrolix cluster.

In the Google Cloud console:

1. Create an OAuth application. See the official documentation for details.
2. 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 Admin Console:

1. Navigate to the Identity providers tab within the hydrolix-users realm.
2. Select Google as the type.
3. Populate Client ID and Client Secret with details for your app from the Google Cloud console.

In the Google Cloud console:

1. Copy the provided Redirect URI from the Keycloak administration interface and add it to your application’s Authorized redirect URIs.
2. (Optional): Enter your Google Workspace domain into the Hosted Domain field.

In the Keycloak Admin Console:

1. Enable the Trust Email option.
2. Select Save.
3. Configure attribute mappings according to the Create Identity Provider Attribute Mappings section.

Verify the configuration:

1. Visit https://${HDX_HOSTNAME}/config/v1/login .
2. Sign in with google should be an option.
3. Confirm successful login to the cluster.

Limitations

Keycloak’s production environment recommendations state that it is best practice to host the Keycloak Admin Console and API endpoints on a separate domain, without public access. This is not possible with the Hydrolix architecture. Keycloak access is behind unified auth. Users must be signed in to the cluster before authenticating to the Keycloak system.