SSO Configuration

Set up Single Sign-On for LangWatch with your identity provider

LangWatch supports SSO with the identity providers below. Choose one and configure it as described.

If your provider is not named here and speaks OpenID Connect, use the generic oidc provider. The named entries exist because each has setup steps worth spelling out, not because the others are unsupported.

SSO requires an Enterprise license. Setting the environment variables is not enough on its own: a deployment with an identity provider configured but no license runs in email mode, the identity-provider button is not shown on the sign-in page, and SSO sign-in routes are refused. Email sign-in and Forgot password stay available so users are not locked out, though Forgot password can only deliver if outbound email is configured. If everyone on an unlicensed deployment signs in through SSO, set LANGWATCH_LICENSE_KEY or configure SMTP before upgrading, see Editions and licensing.

The decision is made once at startup, so a license activated on a running server enables SSO at the next restart. See Editions and licensing for how to obtain and activate one.

Supported Providers

Provider	NEXTAUTH_PROVIDER value	Requires
Email/Password	email (default)	Nothing extra
Auth0	auth0	Client ID, Client Secret, Issuer
AWS Cognito	cognito	Client ID, Client Secret, Issuer
Azure AD	azure-ad	Client ID, Client Secret, Tenant ID
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
OneLogin	onelogin	Client ID, Client Secret, Issuer
Any other OpenID Connect provider	oidc	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, okta, onelogin, or oidc. This is the same value you set as NEXTAUTH_PROVIDER.

A NEXTAUTH_PROVIDER value LangWatch does not recognise, or one whose client credentials are missing, starts the deployment in email mode and logs which provider it could not mount. That keeps a licensed deployment signable-in while you correct the value, rather than pointing the sign-in page at an identity provider that was never wired up.

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 email gateway as the rest of LangWatch. Configure one as described in Email so the reset email can be delivered. Without a gateway the screen says the deployment cannot send email and points the person at whoever operates it, rather than offering a form whose link could never arrive. With one configured, submitting an address that has no account returns the same confirmation as one that does, so the form never reveals who holds an account. 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 and the deployment holds a license, the credential form and the “Forgot password?” link are not shown, and the password reset endpoints are disabled: the identity provider owns credentials from that point on.

Without a license the deployment stays in email mode regardless of what NEXTAUTH_PROVIDER says, and both the credential form and password reset remain available.

Auth0

1. Create an application in the Auth0 Dashboard
2. Set Allowed Callback URLs to https://your-domain.com/api/auth/callback/auth0
3. 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

AWS Cognito

1. In the Cognito console, open your user pool and give it a hosted-UI domain if it does not have one yet (App integration > Domain)
2. Create an app client with a client secret, and set its Allowed callback URL to https://your-domain.com/api/auth/callback/cognito
3. Under the app client’s login pages, enable the Authorization code grant flow and the openid, email and profile scopes
4. 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.eu-central-1.amazonaws.com/eu-central-1_abc123"

Or via environment variables:

Variable	Value
NEXTAUTH_PROVIDER	cognito
COGNITO_CLIENT_ID	Your app client ID
COGNITO_CLIENT_SECRET	Your app client secret
COGNITO_ISSUER	https://cognito-idp.<region>.amazonaws.com/<userPoolId>

The issuer is the user pool’s own issuer, not the hosted-UI domain. LangWatch reads the hosted-UI endpoints from the issuer’s discovery document, so the domain never has to be configured separately. You can confirm a pool’s issuer is reachable with:

curl https://cognito-idp.<region>.amazonaws.com/<userPoolId>/.well-known/openid-configuration

Azure AD

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

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

The provider is azure-ad while its credentials sit under providers.azureAd. The first is the value LangWatch selects on, the second is the chart’s key for the AZURE_AD_* variables.

Variable	Value
NEXTAUTH_PROVIDER	azure-ad
AZURE_AD_CLIENT_ID	Application (client) ID
AZURE_AD_CLIENT_SECRET	Client secret value
AZURE_AD_TENANT_ID	Directory (tenant) ID

GitHub

1. Create an OAuth App in GitHub Developer Settings
2. Set Authorization callback URL to https://your-domain.com/api/auth/callback/github
3. 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

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

Variable	Value
NEXTAUTH_PROVIDER	gitlab
GITLAB_CLIENT_ID	Application ID
GITLAB_CLIENT_SECRET	Application secret

Google

1. Create credentials in Google Cloud Console
2. 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

1. Create an application in Okta Admin Console
2. 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

OneLogin

1. In the OneLogin Admin portal, add an OpenID Connect (OIDC) application
2. Set the Redirect URI to https://your-domain.com/api/auth/callback/onelogin
3. Under SSO, set the application type to Web so it is issued a client secret, and note the Client ID and Client Secret

app:
  nextAuth:
    provider: onelogin
    providers:
      onelogin:
        clientId:
          secretKeyRef: { name: langwatch-sso, key: oneloginClientId }
        clientSecret:
          secretKeyRef: { name: langwatch-sso, key: oneloginClientSecret }
        issuer:
          value: "https://your-subdomain.onelogin.com/oidc/2"

Variable	Value
NEXTAUTH_PROVIDER	onelogin
ONELOGIN_CLIENT_ID	Client ID
ONELOGIN_CLIENT_SECRET	Client secret
ONELOGIN_ISSUER	https://your-subdomain.onelogin.com/oidc/2

If OneLogin sits behind another identity provider, for example a Cognito user pool that federates to it, point LangWatch at whichever one it talks to directly and let that one handle the hop. LangWatch only needs one OIDC issuer.

Any other OpenID Connect provider

Any provider that publishes an OpenID Connect discovery document and supports the authorization code flow with PKCE works without being named above: Keycloak, Authentik, Zitadel, Ping, JumpCloud, a self-hosted IdP, whatever you run.

1. Register an OIDC client with your provider, with the authorization code flow and the openid, email and profile scopes
2. Set its redirect URI to https://your-domain.com/api/auth/callback/oidc

app:
  nextAuth:
    provider: oidc
    providers:
      oidc:
        clientId:
          secretKeyRef: { name: langwatch-sso, key: oidcClientId }
        clientSecret:
          secretKeyRef: { name: langwatch-sso, key: oidcClientSecret }
        issuer:
          value: "https://idp.example.com"

Variable	Value
NEXTAUTH_PROVIDER	oidc
OIDC_CLIENT_ID	Client ID
OIDC_CLIENT_SECRET	Client secret
OIDC_ISSUER	Whatever your provider publishes .well-known/openid-configuration under

Check the issuer is right by fetching its discovery document, which is exactly what LangWatch does at sign-in:

curl https://idp.example.com/.well-known/openid-configuration

JSON back means the issuer is right. LangWatch then reads authorization_endpoint, token_endpoint and userinfo_endpoint from that document, so all three have to be there, and the client you registered has to allow the authorization code flow with PKCE.

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

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

UPDATE "User"
SET "pendingSsoSetup" = true
WHERE "email" LIKE '[e-mail]';

3. 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.