Deployment Configuration

Overview

This guide covers the configuration options for self-hosted TextQL deployments. Settings are applied either through Helm values (at deploy time) or through the Settings UI (at runtime). For IdP-specific SSO setup instructions, see Single Sign-On (SSO).

Authentication

Single Sign-On (OIDC)

Single-tenant OIDC mode enforces one identity provider for all users in the deployment.

global:
  auth:
    singleOIDCTenant: true
    singleOidcIdleLogoutAfter: "45m"  # optional idle timeout
    oidc:
      providerType: "Okta OIDC"       # Okta OIDC | Microsoft OIDC | Ping OIDC
      issuerUrl: "https://your-idp.example.com"
      clientId: "your-client-id"
      clientSecret: "your-client-secret"
      scopes: "openid profile email"   # default: openid profile email
      attributeMapping: '{"role_sync_enabled": true, "preserve_admin_role": true}'
      emailVerification: true          # default: true

oathkeeper:
  enforceAuth: true

Field	Required	Default	Description
`singleOIDCTenant`	Yes	`false`	Enables single-tenant OIDC mode
`oidc.providerType`	Yes	—	Identity provider type
`oidc.issuerUrl`	Yes	—	OpenID Connect issuer URL
`oidc.clientId`	Yes	—	OAuth2 client ID
`oidc.clientSecret`	Yes	—	OAuth2 client secret
`oidc.scopes`	No	`openid profile email`	Space-separated OIDC scopes
`oidc.attributeMapping`	No	`{}`	JSON attribute mapping (see Role Sync)
`oidc.emailVerification`	No	`true`	Require IdP-verified email addresses
`singleOidcIdleLogoutAfter`	No	none	Idle session timeout (e.g., `45m`, `2h`)
`oathkeeper.enforceAuth`	No	`false`	Require authentication on all routes

All four OIDC fields (providerType, issuerUrl, clientId, clientSecret) must be set together. Partial configuration will cause authentication failures.

When single-tenant OIDC is enabled:

Users are redirected directly to the IdP — the login page is bypassed
Email/magic-link login is disabled
The OIDC provider appears as read-only in the Settings UI

When enforceAuth is also enabled:

Every request must carry a valid session or API key
Unauthenticated requests are automatically redirected to the IdP
This is the recommended setting for locked-down deployments

enforceAuth requires singleOIDCTenant to be true. The Helm chart will fail validation if enforceAuth is enabled without single-tenant OIDC.

Multiple OIDC Providers

For deployments that need multiple OIDC providers or per-organization configuration, leave singleOIDCTenant as false and configure providers through Settings → Security → OIDC Identity Providers. See Single Sign-On (SSO) for details. When using multiple providers, each organization must be mapped to one or more providers. Users can switch between organizations that share the same provider.

Email Domain Restrictions

global:
  auth:
    allowedDomains: "company.com,trusted.org"  # comma-separated
    banDisposableEmails: true                   # default: true

Field	Default	Description
`allowedDomains`	none (all domains)	Email domains that can sign up
`banDisposableEmails`	`true`	Block signups from disposable email providers

When allowedDomains is set, only users with matching email domains can create new accounts. Existing users are not affected.

Organization Settings

The following settings are configured per-organization through the TextQL Settings panel.

Discoverability

Controls whether an organization appears when users sign up with a matching email domain.

Value	Behavior
`true`	Organization appears in domain-based discovery during signup
`false` (default)	Organization is hidden — users must be explicitly invited

When to disable:

Single-tenant deployments where all users are provisioned via OIDC
Organizations that should only be accessible by direct invitation
Deployments using SCIM for user provisioning

Organizations with an OIDC provider mapping are automatically hidden from email-based discovery regardless of this setting.

Tool Availability

Control which tools are available to users from Settings → Capabilities.

Tool	Description
Text-to-SQL	Query databases using natural language
Python	Execute Python code in a sandbox
Web Search	Search the web for information
Ontology	Use ontology for structured queries
Ontology Editing	Allow users to modify the ontology
Context Editing	Allow users to edit context documents
File Upload	Upload files for analysis
Tableau	Connect to Tableau
PowerBI	Connect to PowerBI
Google Drive	Access Google Drive files
Microsoft 365	Access Microsoft 365 data
Bash	Execute shell commands in a sandbox
JavaScript	Execute JavaScript code
Playbooks	Run and manage playbooks
Form Editor	Create and edit forms
Model Switching	Allow users to switch LLM models
Auto-Approve	Skip approval for tool execution
Parallel Tools	Run multiple tools concurrently

Organization-level restrictions override defaults. Member-level overrides (if set) take precedence over organization defaults but not restrictions.

LLM Configuration

Configure the default model and available models from Settings → Models.

Setting	Description
Default model	Model used for new chats
Preferred provider	Anthropic or OpenAI
Enabled models	Models available to the organization
Restricted models	Models blocked for the organization

Feature Flags

Toggle features on or off per-organization from Settings → Capabilities.

Feature	Description
Dashboards	Dashboard creation and viewing
Activity Feed	Activity feed for the organization
Notifications	In-app notifications
Secrets	Allow members to store secrets
Fast Mode	Fast execution mode
Context Review	Require context review before execution
Google Connectors	Enable Google connectors
Training Mode	Training mode for new users

Role Sync

When enabled, user roles are automatically synchronized from IdP group claims on every login.

Enabling Role Sync

Add role_sync_enabled to the OIDC attribute mapping:

{"role_sync_enabled": true, "preserve_admin_role": true}

Single-tenant mode: Set via oidc.attributeMapping in Helm values
Multi-provider mode: Set in the Attribute Mapping field in Settings → Security → OIDC Identity Providers

How It Works

On login, TextQL reads group claims from the IdP token
Group names are matched case-insensitively to TextQL role names
Matching roles are assigned; roles not present in the IdP groups are removed
Groups with no matching TextQL role are silently ignored

When preserve_admin_role is true, the admin role is never removed by sync — this prevents accidental lockout if IdP groups change. If the IdP cannot return group memberships (e.g., the user belongs to too many groups), role sync is skipped and a warning is shown.

Troubleshooting

Symptom	Resolution
Roles not syncing	Verify `role_sync_enabled` is set in the attribute mapping
All roles removed on login	Ensure your IdP group names match TextQL role names (case-insensitive)
“Role sync was skipped” warning	Configure a groups filter in your IdP or reduce group memberships
Admin role unexpectedly removed	Add `"preserve_admin_role": true` to the attribute mapping

Common Deployment Patterns

Locked-Down Enterprise (Single IdP)

global:
  auth:
    singleOIDCTenant: true
    oidc:
      providerType: "Okta OIDC"
      issuerUrl: "https://company.okta.com"
      clientId: "..."
      clientSecret: "..."
      attributeMapping: '{"role_sync_enabled": true, "preserve_admin_role": true}'
    allowedDomains: "company.com"

oathkeeper:
  enforceAuth: true

Discoverable: off (users are provisioned via OIDC)
Configure tool restrictions per organization requirements

Multi-Org with Shared IdP

global:
  auth:
    singleOIDCTenant: false

Configure the OIDC provider once via Settings → Security → OIDC Identity Providers
Map the provider to each organization that should use it
Users can switch between organizations that share the provider
Discoverable: off for each org (OIDC handles access)

Email-Only (No SSO)

No OIDC configuration needed
Discoverable: on for organizations users should find via domain matching
Set allowedDomains to your company domain to prevent external signups

Get Started

How It Works

Set Up Your Data

Integrations

Ontology

Get Better Results

Admin & Security

FAQ

Legacy Features

Deployment Configuration

Overview

Authentication

Single Sign-On (OIDC)

Multiple OIDC Providers

Email Domain Restrictions

Organization Settings

Discoverability

Tool Availability

LLM Configuration

Feature Flags

Role Sync

Enabling Role Sync

How It Works

Troubleshooting

Common Deployment Patterns

Locked-Down Enterprise (Single IdP)

Multi-Org with Shared IdP

Email-Only (No SSO)

​Overview

​Authentication

​Single Sign-On (OIDC)

​Multiple OIDC Providers

​Email Domain Restrictions

​Organization Settings

​Discoverability

​Tool Availability

​LLM Configuration

​Feature Flags

​Role Sync

​Enabling Role Sync

​How It Works

​Troubleshooting

​Common Deployment Patterns

​Locked-Down Enterprise (Single IdP)

​Multi-Org with Shared IdP

​Email-Only (No SSO)

Overview

Authentication

Single Sign-On (OIDC)

Multiple OIDC Providers

Email Domain Restrictions

Organization Settings

Discoverability

Tool Availability

LLM Configuration

Feature Flags

Role Sync

Enabling Role Sync

How It Works

Troubleshooting

Common Deployment Patterns

Locked-Down Enterprise (Single IdP)

Multi-Org with Shared IdP

Email-Only (No SSO)