Skip to content

feat: document support for IDP migration for custom-oidc users in self-hosted #4803

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Kenil Vora (kenvora) wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: document support for IDP migration for custom-oidc users in self-hosted #4803

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
86dd383
feat: document support for IDP migration for custom-oidc users in sel…
kenvora Jul 9, 2026
de32a3c
updates
kenvora Jul 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions src/langsmith/self-host-sso.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -308,6 +308,22 @@ If unset, the default value for this configuration uses the `oid` claim when Azu
ISSUER_SUB_CLAIM_OVERRIDES='{"https://login.microsoftonline.com/": "oid", "https://sts.windows.net/": "oid", "https://login.microsoftonline.us/": "oid", "https://login.partner.microsoftonline.cn/": "oid"}'
```

### Migrate custom OIDC users to a new identity provider

When you switch identity providers (for example, Google to Okta) or reconfigure an existing one, the new provider issues a different `sub` value for the same user. Existing custom-OIDC users are matched on the old `sub`, so after the switch they fail to log in — with **"Failed to create or link your account"** — even though their email address is unchanged.

Set the `OIDC_ALLOW_SUB_MIGRATION` environment variable to `true` to let LangSmith re-link an existing user to the new provider identity by matched email on their next login, updating the stored `sub` in place:

```
OIDC_ALLOW_SUB_MIGRATION=true
```

This is **disabled by default** and only takes effect on **self-hosted** installations, where the OIDC provider is administrator-configured. It applies to custom-OIDC users, and the re-link occurs **only when the IdP asserts `email_verified: true`** in the token — a login with an unverified or missing `email_verified` claim is never re-linked, so a spoofable email cannot rebind an existing account. If you deploy with the LangSmith Helm chart, set the `config.oauth.allowSubMigration` value to `true` instead of setting the environment variable directly.

<Note>
SCIM-provisioned users whose stored `externalId` conflicts with the incoming `sub` are still refused. Realign those users through SCIM instead — either re-sync from your identity provider or issue a SCIM `PATCH` that sets `externalId` to the new provider user ID. If the mismatch is a claim-mapping issue rather than a provider change, see [Override sub claim](#override-sub-claim).
</Note>

### SSO Groups Sync

<Note>
Expand Down
Loading