Skip to content

Self-Hosted Authentication Setup

  • Self-hosted

Qualytics administrators manage email and password sign-in and single sign-on (SSO) under Settings > Access > Providers. Start by creating the first administrator, then connect your organization's OpenID Connect (OIDC) or SAML 2.0 identity provider. Provider changes are saved in Qualytics and do not require redeploying the application.

For managed deployments, see Managed Deployment SSO Setup. The Sign-In Providers guide covers provider management for both deployment models.

Before You Start

  • Install Qualytics using the configuration template for your approved release. Keep its authentication defaults. See the Self-Hosted Deployment Guide.
  • Make the deployment available at its HTTPS address before creating an account.
  • Configure SMTP for automatic invitation delivery and password reset emails. SMTP is not required to create the initial administrator.

New Installations

A new deployment starts with Email & Password sign-in enabled. Its provider is listed as Database Identity Provider until an administrator renames it.

  1. Open your deployment's HTTPS address.
  2. Enter your Name, Email, Password, and Confirm Password in the initial administrator form. Follow the displayed password requirements.
  3. Click Create Administrator. Your account receives the Admin role and you are signed in.
  4. Open Settings > Access > Providers to configure the available sign-in methods.
  5. Invite additional users, or configure SSO with automatic user provisioning.

Initial administrator enrollment is available only before any personal account has been created. Deactivating accounts does not reopen enrollment. Existing deployments use their enabled sign-in providers, and an administrator invites additional users or configures SSO.

Configure Sign-In Providers

Sign-in method Setup
Email & Password Configure the existing provider, including its password policy, account lockout, and session duration.
OpenID Connect Add an OIDC provider, then register the Redirect URI shown by Qualytics in your identity provider's application.
SAML 2.0 Add a SAML provider and configure your identity provider using the service provider metadata from Qualytics.

Multiple identity providers can be enabled together. Each appears on the sign-in page, alongside the email and password form when password sign-in is enabled. Configure account provisioning, identity linking, and access restrictions for each provider. See How Sign-In Providers Work.

Helm Values

Keep these installation values in your protected configuration. Enter identity provider client secrets and SAML configuration in Settings > Access > Providers.

Helm value Purpose
secrets.deployment.identifier The unique installation identifier supplied by Qualytics. Retain it through upgrades.
secrets.auth.jwt_signing_secret Signs application sessions. Use a secure random value of at least 32 characters. Changing it signs users out.
secrets.postgres.secrets_passphrase Protects sensitive configuration stored by the application. Retain it through upgrades so existing values remain readable.

Merge these values into the complete installation template. They do not replace the other required settings.

Identity Providers on Private Networks

Identity provider requests accept publicly routable addresses by default. If your identity provider resolves to a private address, set controlplane.auth.allowPrivateNetworkFetches: true in your Helm values. The setting covers discovery, token exchange, signing keys, user information, SAML metadata, and provider diagnostics. Cloud metadata addresses remain blocked.

Use HTTPS for identity provider endpoints. If your organization uses a private certificate authority, configure secrets.oidc.oidc_signer_pem_url with the approved certificate URL. Apply deployment setting changes using the upgrade procedure.

Email and password sign-in does not require internet access. SSO requires the relevant identity provider endpoints to be reachable by Qualytics and the user's browser. Automatic invitation delivery and password reset emails require a reachable SMTP service.

Verify Authentication

  1. Run Test on the SSO provider and review the results. Diagnostics check configuration and connectivity, but they do not replace signing in as a user.
  2. Enable the provider and open the deployment in a separate browser session.
  3. Complete a sign-in and confirm the account's role and Team memberships.
  4. Confirm an Admin can sign in through a method you intend to keep enabled before disabling another provider.

To disable password sign-in, first sign in as an Admin through the tested SSO provider. Qualytics prevents disabling the provider used by your current session and prevents disabling the last enabled customer sign-in provider.

Troubleshooting

Symptom What to check
Initial administrator form is absent A personal account has already been created. Ask an existing Admin for an invitation or use an enabled SSO provider.
An SSO button is absent Confirm the provider is enabled under Settings > Access > Providers.
Sign-in reports an invalid redirect URI Copy the provider's Redirect URI from Qualytics and register that exact value in the identity provider.
Provider Test or sign-in cannot reach a private identity provider Review network reachability, certificate trust, and the private-network setting above.
Invitation or password reset email does not arrive Check SMTP configuration and confirm Email & Password sign-in is enabled.
Existing users cannot sign in through a new provider Review its identity linking and access restrictions, then check Link approvals and the Log tab.

For further help, contact Qualytics Support with the affected sign-in method and the results from the sign-in log. Do not include passwords or client secrets.