Okta SAML

Overview

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

Once configured, users sign in to KubeSense with their Okta credentials, inheriting your organization's Okta policies — MFA, conditional access, and lifecycle management.

Prerequisites

• An Okta organization with super administrator access
• 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: Create the SAML app in Okta

1. In the Okta Admin Console, go to Applications → Applications
2. Click Create App Integration
3. Select SAML 2.0 and click Next
4. On General Settings, enter App name: KubeSense, then click Next

Step 2: Configure SAML settings

On the Configure SAML page, enter the following exactly:

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

Attribute statements (required)

Unlike Google Workspace, an Okta SAML app sends no attributes by default. KubeSense identifies users by email, so these must be added or every login is rejected.

Under Attribute Statements, add:

Group attribute statements (optional)

Only needed if you want Okta groups to determine KubeSense roles — see Map Okta groups to roles.

Under Group Attribute Statements, add:

Click Next, choose I'm an Okta customer adding an internal app, then Finish.

Leave request signing off

On the app's General tab, leave Signed Requests disabled. KubeSense signs its AuthnRequests with RSA-SHA1, which Okta rejects when request-signature validation is enabled. Okta does not require request signing, and assertion signing (which Okta always does) is what KubeSense verifies.

Step 3: Get the IdP metadata

1. Open the app's Sign On tab
2. Under SAML Signing Certificates → Actions → View IdP metadata, or copy the Metadata URL
3. Save the XML — you will paste it into the KubeSense config in Step 5

The metadata URL looks like:

https://<your-org>.okta.com/app/<app-id>/sso/saml/metadata

Step 4: Assign the app to users

A newly created Okta app is assigned to nobody. Until you assign it, users get an Okta error before ever reaching KubeSense.

1. Open the app's Assignments tab
2. Assign → Assign to People (or Assign to Groups)
3. Select the users or groups who should have access, then Save

Step 5: Configure KubeSense via Helm values

api:
  saml:
    enabled: true
    rootUrl: "https://<KUBESENSE_DOMAIN>"
    entityId: "https://<KUBESENSE_DOMAIN>/saml"
    # Paste the IdP metadata XML from Step 3.
    idpMetadataXml: |
      <?xml version="1.0" encoding="UTF-8"?>
      <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/...">
        ...full XML body...
      </md:EntityDescriptor>
  # Selects the Okta IdP flavour. Supplied via a Secret because the chart does
  # not yet expose `api.saml.provider` as a first-class value.
  extraEnvVarsSecret: kubesense-okta-saml

webapp:
  extraEnv:
    # Renders the "Sign In with Okta SAML" button.
    ENABLE_SAML: "true"
    SAML_PROVIDER: "okta"

Create the Secret that carries the provider setting:

kubectl create secret generic kubesense-okta-saml \
  --namespace <KUBESENSE_NAMESPACE> \
  --from-literal=SAML_PROVIDER=okta

Then apply:

helm upgrade kubesense ./charts/kubesense-server \
  -f values.yaml \
  --set-file api.saml.idpMetadataXml=./OktaIDPMetadata.xml

What the chart handles for you

• kubesense-saml-secret — created on first install with a random 32-byte master key, preserved across upgrades via lookup
• API ConfigMap — rendered with SAML_ENABLED, SAML_ENTITY_ID, SAML_ROOT_URL, SAML_IDP_METADATA_XML
• API Deployment — envFrom-wired to kubesense-saml-secret so SAML_KEY_ENCRYPTION_KEY is injected
• SP signing key — the API generates a self-signed cert + RSA-2048 key on first SAML init, encrypts it with AES-256-GCM, and persists it in the saml_sp_keys table. Restarts reuse the same key.

Configuration reference

api.saml

API environment variables

Webapp environment variables

Step 6: Verify SSO

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

New users are provisioned automatically on first login with the User role.

Map Okta groups to roles

By default every SAML user is created with the User role, and administrators are promoted manually in KubeSense. To let Okta groups drive roles instead, configure a mapping.

saml:
  enabled: true
  provider: okta
  groups_attribute: "groups"
  group_role_map:
    kubesense-admins: Admin
    kubesense-users: User
  sync_role_on_login: false

Behaviour:

• Group names match case-insensitively
• A user in several mapped groups receives the highest-privilege match
• Groups with no mapping are ignored; the user falls back to User
• An unknown role type in the map fails at startup rather than silently downgrading users
• sync_role_on_login: true re-applies the mapping on every login, so revoking an Okta group demotes the user at next sign-in. Left false, a role edited in the KubeSense UI is preserved.

Valid role types are Admin, User and Internal.

Single Logout

KubeSense does not implement SAML Single Logout. Signing out of KubeSense ends the KubeSense session only; the Okta session remains active. Leave the app's Single Logout setting disabled.

Rotate the IdP certificate

Okta rotates SAML signing certificates when you generate a new one or when an app is re-created:

1. Open the app's Sign On tab and view the IdP metadata
2. Replace api.saml.idpMetadataXml in your Helm values
3. Run helm upgrade — the chart re-renders the API ConfigMap and the Deployment rolls automatically

Troubleshooting