Single Sign-On (SSO)

Overview

TextQL supports Single Sign-On (SSO) via OpenID Connect (OIDC), allowing your users to authenticate using your organization’s identity provider instead of managing separate credentials.

Supported Identity Providers

Okta
Microsoft Entra ID (Azure AD)
Ping Identity

Email Requirements

TextQL signs SSO users in by the email claim in the ID token from your identity provider, so check that claim before you add a provider. It must be on one of your organization’s allowed email domains, set under Settings → Security → General. It must match the address each user already signs in with, because the first SSO login is linked to an existing account by email, and a different address creates a new, separate account without the user’s history. Your identity provider must also mark the email as verified, or TextQL rejects the login. By default, you can only add your own email domain (the one in the address you’re signed in with) to your organization’s allowed email domains. On TextQL Cloud, contact support@textql.com to add another domain. Self-hosted deployments can lift the limit with global.auth.allowCrossDomainEmailAllowlist.

Microsoft Entra ID

Entra ID doesn’t send the email_verified claim by default. In your app registration, go to Token configuration → Add optional claim, choose the ID token type, and add the email and xms_edov claims. TextQL accepts xms_edov as confirmation that the email is verified.

Getting Started

Before configuring SSO, you’ll need to access your TextQL organization with a role that holds the organization write permission (the built-in admin role has it). If you don’t have an organization yet, you’ll need to create one first. Navigate to the TextQL login page and sign in using one of the available methods:

Work email: Enter your email address to receive a login email
Continue with Google: Use your Google account for quick authentication

TextQL login page with email and Google sign-in options

Once logged in, ensure your role holds the organization write permission. Only members with that permission (the built-in admin role has it) can configure SSO settings.

Step 2: Add an Allowed Email Domain

Go to Settings → Security and open the General tab. Under Allowed Email Domains, enter your email domain (e.g., yourcompany.com) and click Submit. You can’t add a provider until your organization has at least one allowed email domain. See Email Requirements.

Step 3: Open the Provider Form

Open the Authentication tab and click Add provider.

Step 4: Configure the Provider

Fill in the fields below with the values from your identity provider, then click Add provider to save.

Redirect URL

This URL is system-generated and read-only. Copy this value and paste it into your identity provider’s configuration as the callback/redirect URI.

Display Name

A friendly name for this SSO connection (e.g., “Company SSO”). This is what users will see during login.

Client ID

The unique identifier for your application, provided by your identity provider when you create the OIDC application.

Client Secret

The secret key used to authenticate your application. This is provided by your identity provider during OIDC app creation.

Issuer URL

The base URL of your identity provider (e.g., https://yourcompany.okta.com or https://login.microsoftonline.com/your-tenant-id).

Type

Select your identity provider from the dropdown:

Okta OIDC
Microsoft OIDC
Ping OIDC
Generic OIDC

For detailed setup instructions for each provider:

Configuring SSO with Okta

Scopes

OAuth scopes that determine what information your application can access. openid and email are required, and openid, email and profile are selected by default. Enter any other scopes your identity provider needs under Additional scopes, separated by spaces. Additional scopes are ignored when Type is Microsoft OIDC; use Generic OIDC for Entra ID if you need them.

Attribute Mapping

JSON mapping of identity provider attributes to TextQL user fields. This allows you to map custom claims from your IdP to user properties. Example:

{
  "email": "email",
  "name": "name",
  "given_name": "first_name",
  "family_name": "last_name"
}

How It Works

Once SSO is configured:

User visits the TextQL login page
User enters their email address
TextQL detects the email domain matches your configured OIDC organization
User is automatically redirected to your identity provider
User authenticates with their corporate credentials
User is redirected back to TextQL and logged in

Organization Scoping for OIDC Users

When a user authenticates via OIDC, TextQL restricts which organizations they can access:

Membership-based discovery: OIDC users only see organizations they are already members of. Domain-based org discovery is disabled for OIDC sessions — users cannot find or join orgs simply by sharing an email domain.
Provider-scoped org list: If your current organization has an OIDC provider configured, the org switcher only shows other organizations that share the same provider. This prevents OIDC-managed users from switching into orgs outside their identity provider’s scope.
Org-switch validation: When switching organizations, TextQL verifies that the target org has the same OIDC provider configured. If it does not, the switch is blocked.

This means that if you manage multiple TextQL organizations under one identity provider, users will be able to move between them seamlessly. Organizations not covered by your IdP will not appear in the switcher for OIDC-authenticated users.

Testing

Saving a provider changes login for every user on your organization’s allowed email domains at once. With a single provider, the login page sends those users straight to your identity provider, and email login to the organization stops working. Meet the email requirements before you save, then test one account right away while keeping an admin session open in another browser, so you can delete the provider if the login fails.

After saving your configuration:

Open a new incognito/private browser window
Navigate to your TextQL login page
Enter an email address from your organization’s domain
Verify you’re redirected to your identity provider
Complete authentication
Verify you’re logged into TextQL

Troubleshooting

Users not being redirected to SSO

Verify the email domain matches what’s configured in your OIDC settings
Check that the OIDC configuration is saved and active

Authentication fails at identity provider

Verify the Redirect URL is correctly configured in your IdP
Check that the Client ID and Client Secret are correct
Ensure users are assigned to the application in your IdP

Users redirected but not logged in

Verify required scopes (openid and email) are configured
Check that the Issuer URL is correct
Review attribute mapping to ensure email field is properly mapped
email_verified claim issues: Some identity providers send the email_verified claim as a string ("true") rather than a boolean, or omit it from the ID token entirely. TextQL handles both cases automatically — it parses string values and falls back to the UserInfo endpoint when the claim is absent. If sign-in still fails, check your IdP’s token configuration to ensure email_verified is included and set to true for your users.

”Your identity provider did not verify your email address”

Configure your identity provider to send email_verified: true in the ID token or from its UserInfo endpoint
For Microsoft Entra ID, add the email and xms_edov optional claims to the ID token (see Microsoft Entra ID)

“You can only add your own email domain”

By default, admins can only add the domain of the address they’re signed in with
Have your identity provider send users’ addresses on that domain (see Email Requirements), or follow the steps there to add another domain

OIDC user cannot see a specific organization

Confirm the user has been added as a member of that organization (domain-based discovery is not used for OIDC sessions)
Confirm the target organization has the same OIDC provider configured as the user’s current org

Security Considerations

Client Secrets are stored encrypted in the database
Only members whose role holds the organization write permission can modify SSO settings
Users must be assigned to the application in your identity provider to authenticate
Sessions follow your organization’s token expiration policies
OIDC users are scoped to organizations covered by their identity provider — they cannot switch into or discover orgs outside their IdP’s scope

Get Started

How It Works

Set Up Your Data

Integrations

Ontology

Get Better Results

Admin & Security

FAQ

Legacy Features

Overview

Supported Identity Providers

Email Requirements

Microsoft Entra ID

Getting Started

Step 2: Add an Allowed Email Domain

Step 3: Open the Provider Form

Step 4: Configure the Provider

Redirect URL

Display Name

Client ID

Client Secret

Issuer URL

Type

Scopes

Attribute Mapping

How It Works

Organization Scoping for OIDC Users

Testing

Troubleshooting

Users not being redirected to SSO

Authentication fails at identity provider

Users redirected but not logged in

”Your identity provider did not verify your email address”

“You can only add your own email domain”

OIDC user cannot see a specific organization

Security Considerations

​Overview

​Supported Identity Providers

​Email Requirements

​Microsoft Entra ID

​Getting Started

​Step 1: Login to TextQL

​Step 2: Add an Allowed Email Domain

​Step 3: Open the Provider Form

​Step 4: Configure the Provider

​Redirect URL

​Display Name

​Client ID

​Client Secret

​Issuer URL

​Type

​Scopes

​Attribute Mapping

​How It Works

​Organization Scoping for OIDC Users

​Testing

​Troubleshooting

​Users not being redirected to SSO

​Authentication fails at identity provider

​Users redirected but not logged in

​”Your identity provider did not verify your email address”

​“You can only add your own email domain”

​OIDC user cannot see a specific organization

​Security Considerations

Overview

Supported Identity Providers

Email Requirements

Microsoft Entra ID

Getting Started

Step 1: Login to TextQL

Step 2: Add an Allowed Email Domain

Step 3: Open the Provider Form

Step 4: Configure the Provider

Redirect URL

Display Name

Client ID

Client Secret

Issuer URL

Type

Scopes

Attribute Mapping

How It Works

Organization Scoping for OIDC Users

Testing

Troubleshooting

Users not being redirected to SSO

Authentication fails at identity provider

Users redirected but not logged in

”Your identity provider did not verify your email address”

“You can only add your own email domain”

OIDC user cannot see a specific organization

Security Considerations