SSO Configuration

LangWatch supports SSO via NextAuth.js. Choose one provider and configure it as described below.

Supported Providers

Provider	`NEXTAUTH_PROVIDER` value	Requires
Email/Password	`email` (default)	Nothing extra
Auth0	`auth0`	Client ID, Client Secret, Issuer
Azure AD	`azureAd`	Client ID, Client Secret, Tenant ID
AWS Cognito	`cognito`	Client ID, Client Secret, Issuer
GitHub	`github`	Client ID, Client Secret
GitLab	`gitlab`	Client ID, Client Secret
Google	`google`	Client ID, Client Secret
Okta	`okta`	Client ID, Client Secret, Issuer

OAuth Redirect URL

When configuring your identity provider, set the redirect/callback URL to:

https://your-langwatch-domain.com/api/auth/callback/{provider}

Replace {provider} with: auth0, azure-ad, cognito, github, gitlab, google, or okta.

Provider Setup

Email/Password

The default mode (NEXTAUTH_PROVIDER=email) needs no identity provider. Users register with an email and password, and a self-service “Forgot password?” link on the sign-in screen lets them reset a forgotten one. Reset links are sent through the same transactional email provider as the rest of LangWatch. Configure SendGrid or AWS SES as described in Third-party integrations so the reset email can be delivered. If no email provider is configured, the request still returns the same neutral confirmation but no email is sent. The reset link expires one hour after it is issued, and a completed reset signs out the account’s other active sessions. When NEXTAUTH_PROVIDER is set to any SSO provider below, the credential form and the “Forgot password?” link are not shown, and the password reset endpoints are disabled.

Auth0

Create an application in the Auth0 Dashboard
Set Allowed Callback URLs to https://your-domain.com/api/auth/callback/auth0
Configure in Helm:

app:
  nextAuth:
    provider: auth0
    providers:
      auth0:
        clientId:
          secretKeyRef: { name: langwatch-sso, key: auth0ClientId }
        clientSecret:
          secretKeyRef: { name: langwatch-sso, key: auth0ClientSecret }
        issuer:
          value: "https://your-tenant.auth0.com"

Or via environment variables:

Variable	Value
`NEXTAUTH_PROVIDER`	`auth0`
`AUTH0_CLIENT_ID`	Your Auth0 client ID
`AUTH0_CLIENT_SECRET`	Your Auth0 client secret
`AUTH0_ISSUER`	`https://your-tenant.auth0.com`

Azure AD

Register an application in Azure Portal > App registrations
Add a Redirect URI: https://your-domain.com/api/auth/callback/azure-ad
Create a client secret under Certificates & secrets
Configure in Helm:

app:
  nextAuth:
    provider: azureAd
    providers:
      azureAd:
        clientId:
          secretKeyRef: { name: langwatch-sso, key: azureClientId }
        clientSecret:
          secretKeyRef: { name: langwatch-sso, key: azureClientSecret }
        tenantId:
          value: "your-tenant-id"

Variable	Value
`NEXTAUTH_PROVIDER`	`azureAd`
`AZURE_AD_CLIENT_ID`	Application (client) ID
`AZURE_AD_CLIENT_SECRET`	Client secret value
`AZURE_AD_TENANT_ID`	Directory (tenant) ID

AWS Cognito

Create a User Pool in AWS Cognito
Add an app client with a Callback URL: https://your-domain.com/api/auth/callback/cognito
Configure in Helm:

app:
  nextAuth:
    provider: cognito
    providers:
      cognito:
        clientId:
          secretKeyRef: { name: langwatch-sso, key: cognitoClientId }
        clientSecret:
          secretKeyRef: { name: langwatch-sso, key: cognitoClientSecret }
        issuer:
          value: "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX"

Variable	Value
`NEXTAUTH_PROVIDER`	`cognito`
`COGNITO_CLIENT_ID`	User pool app client ID
`COGNITO_CLIENT_SECRET`	User pool app client secret
`COGNITO_ISSUER`	`https://cognito-idp.{region}.amazonaws.com/{userPoolId}`

GitHub

Create an OAuth App in GitHub Developer Settings
Set Authorization callback URL to https://your-domain.com/api/auth/callback/github
Configure:

app:
  nextAuth:
    provider: github
    providers:
      github:
        clientId:
          secretKeyRef: { name: langwatch-sso, key: githubClientId }
        clientSecret:
          secretKeyRef: { name: langwatch-sso, key: githubClientSecret }

Variable	Value
`NEXTAUTH_PROVIDER`	`github`
`GITHUB_CLIENT_ID`	OAuth app client ID
`GITHUB_CLIENT_SECRET`	OAuth app client secret

GitLab

Create an application in GitLab > Applications
Set Redirect URI to https://your-domain.com/api/auth/callback/gitlab
Select scopes: read_user, openid, profile, email

Variable	Value
`NEXTAUTH_PROVIDER`	`gitlab`
`GITLAB_CLIENT_ID`	Application ID
`GITLAB_CLIENT_SECRET`	Application secret

Google

Create credentials in Google Cloud Console
Add an Authorized redirect URI: https://your-domain.com/api/auth/callback/google

Variable	Value
`NEXTAUTH_PROVIDER`	`google`
`GOOGLE_CLIENT_ID`	OAuth client ID
`GOOGLE_CLIENT_SECRET`	OAuth client secret

Okta

Create an application in Okta Admin Console
Set Sign-in redirect URI to https://your-domain.com/api/auth/callback/okta

app:
  nextAuth:
    provider: okta
    providers:
      okta:
        clientId:
          secretKeyRef: { name: langwatch-sso, key: oktaClientId }
        clientSecret:
          secretKeyRef: { name: langwatch-sso, key: oktaClientSecret }
        issuer:
          value: "https://your-org.okta.com"

Variable	Value
`NEXTAUTH_PROVIDER`	`okta`
`OKTA_CLIENT_ID`	Client ID
`OKTA_CLIENT_SECRET`	Client secret
`OKTA_ISSUER`	`https://your-org.okta.com`

Domain-to-Organization Mapping

For on-premises deployments with SSO, map email domains to organizations:

-- Connect to PostgreSQL and run:
UPDATE "Organization"
SET "ssoProvider" = 'okta',
    "ssoEmailDomain" = 'yourcompany.com'
WHERE "id" = 'your-org-id';

This ensures users with @yourcompany.com emails are automatically associated with the correct organization.

Migrating from Email/Password to SSO

Enable SSO by setting the provider configuration above
Flag existing email/password users for SSO migration:

UPDATE "User"
SET "pendingSsoSetup" = true
WHERE "email" LIKE '%@yourcompany.com';

When flagged users next sign in via SSO, their accounts are automatically linked

Users keep their existing data, projects, and permissions after the SSO migration. The migration only changes their authentication method.

Overview

Configuration

Deployment

Infrastructure

Operations

Ops Console

Supported Providers

OAuth Redirect URL

Provider Setup

Email/Password

Auth0

Azure AD

AWS Cognito

GitHub

GitLab

Google

Okta

Domain-to-Organization Mapping

Migrating from Email/Password to SSO

​Supported Providers

​OAuth Redirect URL

​Provider Setup

​Email/Password

​Auth0

​Azure AD

​AWS Cognito

​GitHub

​GitLab

​Google

​Okta

​Domain-to-Organization Mapping

​Migrating from Email/Password to SSO

Supported Providers

OAuth Redirect URL

Provider Setup

Email/Password

Auth0

Azure AD

AWS Cognito

GitHub

GitLab

Google

Okta

Domain-to-Organization Mapping

Migrating from Email/Password to SSO