Google SAML

Set up SSO with SAML for KubeSense

This article describes how to set up SAML-based single sign-on (SSO) for the KubeSense observability platform using Google as the identity provider (IdP).

When you set up SSO for a SAML application, your users sign in to KubeSense using their managed Google Account credentials.

Before you begin

To configure SSO for the KubeSense SAML app, sign in to your Google Admin console using a super administrator account.

You'll also need:

• A KubeSense deployment reachable at a public HTTPS URL (e.g. https://kubesense.example.com)
• The ability to run helm upgrade against the deployment

Step 1: Add the custom SAML app

1. In the Admin console, go to Menu → Apps → Web and mobile apps
2. Click Add app → Add custom SAML app
3. On the App details page:
   • Enter App name: KubeSense
   • App icon (optional): download the official KubeSense logo and upload it
4. Click Continue

Step 2: Download the IdP metadata

On the Google Identity Provider details page:

1. Click Download metadata to save the IdP metadata XML file (e.g. GoogleIDPMetadata.xml)
2. Click Continue

You'll paste the contents of this file into the KubeSense config in Step 5.

Step 3: Enter Service provider details

On the Service provider details page, enter the following values exactly:

Replace <KUBESENSE_DOMAIN> with your actual KubeSense domain (e.g. kubesense.example.com).

Click Continue.

Step 4: Add attribute mappings

On the Attribute mapping page, add the following mappings:

Click Finish.

Step 5: Configure KubeSense via Helm values

SAML is fully driven by Helm values — you do not edit ConfigMaps, Secrets, or Deployment manifests directly. Add the following block to your values.yaml (or pass via --set-file):

api:
  saml:
    enabled: true
    rootUrl: "https://<KUBESENSE_DOMAIN>"
    entityId: "https://<KUBESENSE_DOMAIN>/saml"
    # Paste the contents of GoogleIDPMetadata.xml from Step 2 here.
    idpMetadataXml: |
      <?xml version="1.0" encoding="UTF-8"?>
      <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://accounts.google.com/o/saml2?idpid=...">
        ...full XML body...
      </md:EntityDescriptor>

Replace <KUBESENSE_DOMAIN> with your actual domain (no trailing slash).

If you'd rather keep the metadata XML in a separate file, use --set-file:

helm upgrade kubesense ./charts/kubesense-server \
  -f values.yaml \
  --set api.saml.enabled=true \
  --set api.saml.rootUrl=https://kubesense.example.com \
  --set api.saml.entityId=https://kubesense.example.com/saml \
  --set-file api.saml.idpMetadataXml=./GoogleIDPMetadata.xml

That's it. The chart takes care of everything else:

• kubesense-saml-secret Secret created on first install with a random 32-byte master key. Preserved across helm upgrade via lookup (no rotation, no churn).
• API ConfigMap rendered with SAML_ENABLED, SAML_ENTITY_ID, SAML_ROOT_URL, SAML_IDP_METADATA_XML env vars (Viper reads them at startup).
• API Deployment envFrom-wired to kubesense-saml-secret so SAML_KEY_ENCRYPTION_KEY is injected.
• Webapp ConfigMap sets ENABLE_GOOGLE_SAML=true so the "Sign in with Google SAML" button renders.
• API binary auto-generates the SP signing key (self-signed cert + RSA-2048) on first SAML init, encrypts it with AES-256-GCM using the master key, and persists in the saml_sp_keys table. Restarts reuse the same key.

Configuration reference

values.yaml → api.saml

Chart-managed Secrets

The SAML SP signing key itself (a self-signed cert + RSA-2048 key pair) is auto-generated by the API on first SAML init and persisted in the saml_sp_keys table in the primary database. Restarts and rolling upgrades reuse the same key.

Step 6: Turn on the app for users

By default, the new SAML app is off for everyone. Until you turn it on, users see app_not_enabled_for_user from Google.

1. In the Admin console, go to Apps → Web and mobile apps → KubeSense
2. Click User access
3. Set Service status to ON for everyone (or for a specific OU)
4. Click Save

Propagation can take up to a few minutes.

Step 7: Verify SSO

1. Open https://<KUBESENSE_DOMAIN>/login in a private browser window
2. Click Sign in with Google SAML
3. Authenticate with your Google Workspace account
4. You should land on the KubeSense dashboard

Rotate the IdP metadata

Google rotates SAML signing certificates from time to time. When that happens:

1. In the Admin console, open the KubeSense SAML app
2. Click Download metadata to get the new XML
3. Replace api.saml.idpMetadataXml in your Helm values (or re-run --set-file)
4. helm upgrade ... — the chart re-renders the API ConfigMap and the Deployment automatically rolls.

Troubleshooting