Database-Backed Authentication Configuration

This guide explains how to configure the DB authentication mode for a self-hosted Qualytics deployment. In this mode, sign-in is governed by providers that administrators create and manage in the platform under Settings > Access > Providers, instead of by deployment configuration. Other pages in this guide refer to it as the new authentication mode.

Overview

With the DB mode:

• Sign-in providers are managed in the platform. Users with the Admin role configure OIDC and SAML identity providers and email and password sign-in from Settings > Access, without changing the deployment. See Sign-In Providers.
• Multiple providers run side by side. As many OIDC and SAML providers as you need, plus at most one Email & Password provider. The sign-in page shows a button for each enabled provider.
• Changes are staged and verified. Providers can be created, tested, and edited at any time, and the platform adds email invitations, link approvals, and a sign-in log.
• Compatible with environments without public internet access. The built-in Email & Password provider needs no outbound access. OIDC and SAML providers require the identity provider endpoints to be reachable, as in the OIDC mode.

Helm Values

In this mode, provider credentials are entered in the platform and stored encrypted, and the connection values under secrets.oidc and secrets.auth0 are ignored. Three deployment-wide settings under secrets.oidc still apply in every mode: oidc_group_team_sync_enabled (group-based Team membership), oidc_signer_pem_url (custom CA certificate for identity provider endpoints), and oidc_allow_insecure_transport (development only).

Example values.yaml

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

secrets:
  deployment:
    identifier: "<provided by Qualytics>"
  auth:
    jwt_signing_secret: "your-secure-random-string-min-32-chars"
  postgres:
    secrets_passphrase: "your-secure-passphrase"

Merge these authentication settings into the complete protected configuration supplied for your installation. Retain the other required values already present in that file.

New Installations

A new install can start directly in the DB mode: set global.authType: "DB" before the first deploy and follow the Self-Hosted Deployment Guide.

On first access, the sign-in page offers a one-time enrollment of the first administrator. Brand new deployments start with the built-in Email & Password provider (listed as Database Identity Provider) enabled, so the enrolled administrator can sign in right away and set up additional providers.

Switching an Existing Deployment

Switching a deployment from the OIDC or AUTH0 mode to the DB mode is a planned cutover:

1. Stage your providers. Configure and test providers under Settings > Access > Providers while the current mode stays active; they do not affect sign-in until the switch. Deployments coming from the deployment-configured OIDC mode receive a pre-filled provider named OIDC (migrated from env vars) the first time the platform starts with no OIDC providers configured. Review it, because it keeps sign-in behavior consistent with the previous configuration. See How It Works.
2. Enable at least one provider. The platform does not start in the DB mode while every provider is disabled.
3. Schedule a maintenance window. The switch invalidates active sessions, so tell users they will need to sign in again.

4. Set global.authType: "DB" in your values.yaml and apply the change:

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

5. Verify sign-in (see below). Keep your previous secrets.oidc or secrets.auth0 connection values until the new mode is proven: they are ignored in the DB mode, but switching back to the previous mode needs them. When you no longer want that fallback, the connection values can be removed; keep the three deployment-wide settings noted under Helm Values if your deployment uses them.

Verify Authentication

1. Navigate to your Qualytics instance in a browser (e.g., https://qualytics.example.com)
2. The sign-in page should list a button for each enabled provider (and the email and password form when the Email & Password provider is enabled)
3. Sign in through one of the providers
4. Confirm that Settings > Access shows the Providers, Link approvals, and Log tabs for administrators (Invitations appears once an enabled Email & Password provider exists)

Troubleshooting