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). It can support environments without public internet egress when the Qualytics application and your users can reach the required IdP endpoints through approved network paths.

Overview

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

• No Qualytics-hosted authentication dependency: Authentication is handled by your IdP.
• Your IdP governs access: User login requirements, MFA, and password policies are enforced by your IdP.
• Private-network support: OIDC can work without public internet access when the IdP endpoints are available inside or reachable from the environment.

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

Network Prerequisites

Before configuring OIDC, confirm the following network paths:

• User browsers can reach the IdP authorization endpoint.
• The Qualytics application can reach the discovery, token, user information, and JWKS endpoints used by your IdP.
• The application trusts the TLS certificates presented by those endpoints.

An environment without public internet access can use OIDC when these endpoints are available through private or internal network routes.

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, omit oidc_discovery_url and 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

Qualytics can add users to existing Teams based on an IdP group claim at sign-in. This is disabled by default because Team membership can grant access to data.

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

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, and several send group identifiers rather than group names. Membership is add-only, so removing a user from an IdP group does not remove them from the matching Team.

For claim setup per Identity Provider, Team naming, verification, and the routine that keeps membership accurate over time, see Just-in-Time Provisioning and Group Sync.

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. Merge these authentication settings into the complete protected configuration supplied for your installation.

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"

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"

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

Run the CLI authentication flow:

qualytics auth login --url https://qualytics.example.com

Replace the example URL with your Qualytics deployment URL. The CLI opens your browser and uses your active Qualytics session to confirm your identity. If no active session is available, sign in to Qualytics in the browser. When the browser-based flow is unavailable, the authorization page provides a manual token fallback.

Troubleshooting