OIDC Authentication Configuration

This guide explains how to configure OpenID Connect (OIDC) authentication for a self-hosted Qualytics deployment. OIDC is the recommended authentication method for self-hosted deployments because it integrates directly with your enterprise Identity Provider (IdP) and supports environments without internet egress.

Overview

When configured for OIDC, Qualytics authenticates users directly against your organization's Identity Provider using the OpenID Connect protocol. This means:

• No external authentication dependency: Authentication is handled entirely within your network.
• Your IdP governs access: User login requirements, MFA, and password policies are enforced by your IdP.
• Air-gapped support: Authentication does not require egress to external services.

sequenceDiagram
    participant User
    participant Qualytics
    participant IdP as Your Identity Provider

    User->>Qualytics: Access Qualytics UI
    Qualytics->>IdP: Redirect to IdP login
    IdP->>User: Prompt for credentials
    User->>IdP: Authenticate
    IdP->>Qualytics: Return authorization code
    Qualytics->>IdP: Exchange code for tokens
    Qualytics->>IdP: Fetch user info
    Qualytics->>User: Set session cookies & redirect to UI

Supported Identity Providers

Any OIDC-compliant Identity Provider is supported, including:

• Microsoft Entra ID (Azure Active Directory)
• Okta / Okta Workforce Identity
• Google Workspace
• Keycloak
• OneLogin
• PingFederate
• ForgeRock
• Active Directory Federation Services (ADFS)

Step 1: Register Qualytics in Your IdP

Before configuring Qualytics, you need to register it as an application in your Identity Provider.

Application Registration Settings

After registration, your IdP will provide:

• A Client ID
• A Client Secret
• A Discovery URL (typically https://<your-idp-domain>/.well-known/openid-configuration)

Step 2: Configure Qualytics

Set global.authType to OIDC in your Helm values.yaml file and provide the OIDC configuration under secrets.oidc.

Every installation must also keep its Qualytics-provided deployment identifier under secrets.deployment.identifier. The identifier is separate from your OIDC credentials, image registry token, and platform license. See the Self-Hosted Deployment Guide for secure handling requirements.

Discovery URL (Recommended)

The simplest way to configure OIDC is to provide a Discovery URL. Qualytics will automatically fetch your IdP's .well-known/openid-configuration document and populate the authorization, token, userinfo, JWKS, and issuer endpoints for you.

For OIDC authentication, a discovery URL reduces the required configuration to four values. Other installation requirements, including the deployment identifier, still apply.

Set global.authType: "OIDC" in your values.yaml. Scopes, claim mappings, and endpoints have defaults that work with most IdPs.

Common Discovery URLs

Manual Endpoint Configuration (Fallback)

If your IdP does not support a standard discovery URL, or if the discovery endpoint is not reachable from your cluster, you can configure endpoints individually instead:

Optional Settings

OIDC Scopes and Behavior

Claims Mapping

All claim keys default to standard OIDC claim names and work out of the box with most IdPs. You only need to override these if your IdP uses non-standard claim names:

Optional IdP Group Mapping to Teams

Self-hosted deployments can add users to existing Qualytics Teams based on an IdP group claim. This feature is disabled by default because Team membership can grant access to data.

Before enabling it, confirm the exact claim name and values emitted by your IdP. Some providers require an additional scope before they include groups in the token or user information response.

secrets:
  oidc:
    oidc_user_groups_key: "<verified group claim>"
    oidc_group_team_sync_enabled: true

Group mapping follows these rules:

• Group names are matched case-insensitively against existing Team names.
• Unmatched groups are ignored. This feature does not create Teams.
• Membership is add-only. Removing a user from an IdP group does not remove them from the matching Team.
• Administrators must remove obsolete Team memberships in Qualytics when access should be revoked.

Review the Team Best Practices before enabling automated membership.

Environment Variable Reference

The Helm values on this page are the supported configuration interface. Do not add authentication environment variables directly to the application workloads, because their internal mapping can change between chart versions. For advanced troubleshooting, provide your approved chart version and a redacted copy of the relevant Helm values to Qualytics Support.

Example values.yaml: Discovery URL (Recommended)

This example uses the default scopes, claim mappings, and endpoints:

global:
  dnsRecord: "qualytics.example.com"
  authType: "OIDC"

secrets:
  deployment:
    identifier: "<provided by Qualytics>"
  oidc:
    oidc_discovery_url: "https://your-org.okta.com/.well-known/openid-configuration"
    oidc_client_id: "your-client-id"
    oidc_client_secret: "your-client-secret"
  auth:
    jwt_signing_secret: "your-secure-random-string-min-32-chars"
  postgres:
    secrets_passphrase: "your-secure-passphrase"
  rabbitmq:
    rabbitmq_password: "your-secure-password"

Example values.yaml: Manual Endpoints (Fallback)

Use this approach only if your IdP's discovery endpoint is not reachable from your cluster:

global:
  dnsRecord: "qualytics.example.com"
  authType: "OIDC"

secrets:
  deployment:
    identifier: "<provided by Qualytics>"
  oidc:
    oidc_client_id: "your-client-id"
    oidc_client_secret: "your-client-secret"
    oidc_scopes: "openid,email,profile"
    oidc_authorization_endpoint: "https://login.example.com/oauth2/authorize"
    oidc_token_endpoint: "https://login.example.com/oauth2/token"
    oidc_userinfo_endpoint: "https://login.example.com/oauth2/userinfo"
  auth:
    jwt_signing_secret: "your-secure-random-string-min-32-chars"
  postgres:
    secrets_passphrase: "your-secure-passphrase"
  rabbitmq:
    rabbitmq_password: "your-secure-password"

Step 3: Deploy or Restart

If this is a new deployment, follow the Self-Hosted Deployment Guide to deploy Qualytics.

If you are updating an existing deployment's authentication configuration, apply the changes:

CHART_VERSION="<version provided by Qualytics>"

helm upgrade qualytics qualytics/qualytics \
  --namespace qualytics \
  --version "$CHART_VERSION" \
  -f values.yaml \
  --wait \
  --timeout=20m

Use the complete protected values.yaml file that contains the installation's existing deployment identifier. Do not pass the identifier with --set, because command arguments can be stored in shell history and process logs.

Step 4: Verify Authentication

1. Navigate to your Qualytics instance in a browser (e.g., https://qualytics.example.com)
2. You should be redirected to your IdP's login page
3. Authenticate with your IdP credentials
4. After successful authentication, you should be redirected back to the Qualytics UI

Security Architecture

Qualytics implements a three-tier security model for OIDC authentication:

Tier 1: HttpOnly Cookies + CSRF Protection

• Session JWTs are stored in HttpOnly cookies (not accessible to JavaScript)
• CSRF protection uses a double-submit cookie pattern
• SameSite=Lax cookie attribute prevents cross-site request forgery

Tier 2: Token Fingerprinting

• A random fingerprint is embedded in the JWT and stored in a separate HttpOnly cookie
• Prevents stolen JWT replay because an attacker needs both the JWT and the fingerprint cookie
• Session lifetime can be set with secrets.oidc.oidc_jwt_ttl_minutes; automatic session refresh is supported

Tier 3: DPoP (Demonstration of Proof-of-Possession)

• The browser generates a non-extractable ECDSA key pair
• The JWT is cryptographically bound to the key pair
• Each API request includes a signed proof, so a stolen JWT is useless without the private key

CLI Authentication

When using OIDC authentication, the Qualytics CLI authenticates via manual token paste:

1. Generate an API token in the Qualytics UI
2. Provide the token to the CLI when prompted

Troubleshooting