Enabling SAML in a Kubernetes installation

This guide explains how to configure SAML (Security Assertion Markup Language) authentication for Deephaven running in Kubernetes. SAML enables single sign-on (SSO) by allowing Deephaven to delegate authentication to your organization's identity provider (IdP) such as Okta, Azure AD, or others.

Prerequisites

Before configuring SAML integration, ensure you have:

• A running Deephaven Grizzly (or later) deployment in Kubernetes.
• Access to your organization's SAML identity provider with administrator privileges.
• kubectl access to your Kubernetes cluster.
• TLS certificates for your Deephaven deployment.

This guide covers the Deephaven and Kubernetes configuration. You must separately configure your SAML IdP to recognize Deephaven as a service provider. Consult your IdP's documentation for those steps.

Configuration overview

Enabling the SAML integration requires:

1. A Kubernetes secret containing a PKCS12 keystore for the authentication server to use. This can be the same deephaven-tls secret used by Envoy. Note that the SAML ACS (Assertion Consumer Service) is hosted behind Envoy, so the certificate from the PKCS12 keystore is only seen by Envoy itself -- the TLS connection from clients will terminate at Envoy, as with the UI.
2. Updating the Deephaven configuration to use SAML.

Step 1 must be performed manually. Step 2 is handled by setting the appropriate Helm values.

Creating PKCS12 Keystore

The PKCS12 keystore and its base64-encoded passphrase must be loaded from Kubernetes secrets.

First, create a secret containing the keystore passphrase. In this case, the secret will include both the plaintext and base64-encoded passphrase. The authentication server requires the base64-encoded version, but the plaintext version can be used (e.g., by cert-manager) when creating the keystore.

The example below adds a keystore passphrase to a Kubernetes secret.

TEMP_DIR=$(mktemp -d)
KEYSTORE_PW_FILE="$TEMP_DIR/keystore-password"
echo -n "some-password" > "$KEYSTORE_PW_FILE"
cat "$KEYSTORE_PW_FILE" | base64 > "$KEYSTORE_PW_FILE.base64"
# Create a k8s secret with the password from the file.
# The password will be stored under the key "passphrase" in the secret (and can be mounted as a file in a container).
kubectl create secret generic saml-pkcs12-pw-secret --from-file=passphrase="$KEYSTORE_PW_FILE" --from-file=passphrase_base64="$KEYSTORE_PW_FILE.base64"
rm -v "$KEYSTORE_PW_FILE" "$KEYSTORE_PW_FILE.base64"

Next, add a secret containing the PKCS12 keystore. If using cert-manager, this can be done automatically by adding YAML for a certificate from cert-manager. Below is an example that requests a certificate from cert-manager called cert-dhe-k8s-test. The actual certificate files (PEM-encoded tls.key and tls.crt files) will be stored in the deephaven-tls secret. A PKCS12 keystore will also be created, which will take its passphrase from the passphrase field of the saml-pkcs12-pw-secret created above. This certificate has multiple dnsNames so that it can be used by both Envoy (for connections to the DH UI) and the authentication server (for the SAML ACS).

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: cert-dhe-k8s-test
spec:
  secretName: deephaven-tls
  privateKey:
    algorithm: ECDSA
    size: 256
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - 'dhe-k8s-test.devrel.deephaven.io'
  keystores:
    pkcs12:
      create: true
      passwordSecretRef: # Password used to encrypt the keystore
        key: passphrase
        name: saml-pkcs12-pw-secret

The certificate YAML can be added with kubectl apply:

kubectl apply -f deephaven-tls-cert.yaml

Once the certificate has been generated, the deephaven-tls secret will contain tls.crt, tls.key and keystore.p12 files:

> kubectl describe secrets/deephaven-tls
Type:  kubernetes.io/tls

Data
====
keystore.p12:  4520 bytes
tls.crt:       5473 bytes
tls.key:       227 bytes

Alternatively, you can manually create a Kubernetes secret containing an appropriate keystore.p12 file.

SAML Helm values

The following Helm values are used to configure SAML:

To enable SAML in the config, set the following values when installing the Helm release:

saml:
  # Provider name displayed in UI:
  providerName: 'Okta'

  # Name of secret with a 'keystore.p12' file with a key/cert for saml.authServerHostname:
  authServerSecretName: 'deephaven-tls'

  # Name of secret with password for the keystore.p12 file (under the 'passphrase' key of the secret):
  pkcsPassphraseSecretName: 'saml-pkcs12-pw-secret'

  # Parameters from IdP:
  idpEntityId: 'http://www.okta.com/exk85yotnys6vgNdm5d7'
  idpSsoUrl: 'https://dev-62524573.okta.com/app/dev-62524573_rbdhtest_1/exk85yotnys6vgNdm5d7/sso/saml'
  ## IdP certificate (remember to escape newlines):
  idpCert: "-----BEGIN CERTIFICATE-----\\nMIIDqDCC...TCnXJJ\\nzO21KV7oTpH8pqUAUaj6o6BapmQcTnCln6V6pQ==\\n-----END CERTIFICATE-----"