Skip to main content

​
Setting up a connection

A connection is an organization’s link to its identity provider, over OpenID Connect or SAML. To set one up, open Settings > Authentication > Identity provider as an organization administrator and give:
  • the provider’s issuer, client id and client secret, or its SAML metadata
  • the email domain the connection signs in
  • a test sign-in through the provider
  • an administrator who can still sign in if the provider is unavailable
See the SSO setup guide for the full journey and screenshots, and First run for the steps on a fresh install. On a licensed installation, a domain added in the setup page is verified right away, with no DNS record or file to publish. A domain belongs to one organization per installation. When the installation has more than one organization, only a platform operator listed in ADMIN_EMAILS adds a domain without proof. Other organization administrators complete the DNS or file check.

​
Before you start

  • Activate an Enterprise license. Single sign-on turns on without a restart once the license is active.
  • Set BASE_HOST and NEXTAUTH_URL to the public HTTPS address people use to open LangWatch. The redirect URI the identity provider calls uses that address.
  • Keep CREDENTIALS_SECRET stable across app and worker processes. It encrypts the stored client secrets, and a new value cannot decrypt the existing ones.

​
Redirect URI

Every connection has its own redirect URI, shown on the setup page:
A SAML connection posts to its assertion consumer service instead, also shown on the setup page:
The connection id stays the same for the life of the connection, so the address registered in the identity provider does not change. To fix a wrong issuer, client id or client secret, or to replace SAML metadata, edit the connection with the pencil button next to its issuer on the setup page. Editing keeps the connection id, so the redirect URI, the domains and who the connection admits stay the same. A blank client secret keeps the current one. The new settings are checked the same way as at registration. If they are refused, the connection keeps its current settings. The protocol of a connection cannot be changed.

​
Issuer

Enter the issuer exactly as it appears in the iss claim of the provider’s ID tokens. When you register the connection, LangWatch fetches <issuer>/.well-known/openid-configuration and saves the issuer value from that response, so a trailing slash you typed or left out is corrected. If the response gives a different issuer, you get an error and the connection is not saved. Check an issuer by fetching its discovery document: Replace YOUR_TENANT_ID with your tenant id, or set ISSUER to your provider’s issuer:
Register the client with the authorization code flow and the openid, email and profile scopes. GitHub sign-in is OAuth without OpenID Connect, so it cannot be a connection.

​
Microsoft Entra ID

  • Register LangWatch as an app in Entra ID and add the redirect URI under the Web platform.
  • Use the issuer of the tenant that holds the app registration, https://login.microsoftonline.com/<tenant id>/v2.0. You cannot register the common, organizations or consumers endpoints: an ID token from them has the user’s own tenant in iss.
  • LangWatch reads the address from the email claim, so each user needs a mail address in Entra ID. In Token configuration, add the optional email and xms_edov claims to the ID token.
If you see “Your identity provider names a different issuer” on the test sign-in, compare the two issuers it lists. A guest user’s token can carry their home tenant. Set the issuer on the connection to the app’s tenant issuer.

​
Existing email and password accounts

On a self-hosted installation, a sign-in through a connection links to an existing email and password account with the same address once the connection has verified the address’s domain. This includes accounts whose address was never confirmed, which is every account on an installation without outbound email. The identity provider does not have to send email_verified. Microsoft Entra ID never sends it, and SAML has no such attribute. A sign-in where the provider reports the address as unverified, with email_verified: false or with Entra ID’s xms_edov: false, is refused with “An account with this address already exists”. On LangWatch Cloud, a sign-in links to an existing account only when the address is confirmed and the provider sends email_verified: true.

​
Upgrading an existing installation

Identity and access migrations run automatically after each upgrade, one organization at a time. Each organization switches over as soon as it migrates cleanly. When an organization’s historical data needs attention, it stays on its existing sign-in path and the deployment starts anyway. See the upgrade guide for what still blocks startup and how to check and retry a held organization. Installations that configure a sign-in provider in the deployment settings keep working after an upgrade, with the same redirect URI. To move to a connection set up in Settings, follow Move to your own identity provider.
Last modified on October 12, 2026