Skip to main content

SCIM User Provisioning (Beta)

System for Cross-domain Identity Management (SCIM) is an open standard that allows for the automation of user provisioning. Using SCIM, you can automatically provision and deprovision users in your LangSmith organization and workspaces, keeping user access synchronized with your organization's identity provider.

note

SCIM is available for organizations on the Enterprise plan. Please contact sales to learn more.

SCIM is available on Helm chart versions 0.10.39 (application version 0.10.100) and later.

While in Beta, SCIM support is API-only (see instructions below).

What is SCIM?

SCIM enables automatic user provisioning and deprovisioning between your identity provider (IdP) and LangSmith. This eliminates the need for manual user management and ensures that user access is always up-to-date with your organization's identity system.

Benefits of SCIM

  • Automated user management: Users are automatically added, updated, and removed from LangSmith based on their status in your IdP
  • Reduced administrative overhead: No need to manually manage user access across multiple systems
  • Improved security: Users who leave your organization are automatically deprovisioned from LangSmith
  • Consistent access control: User attributes and group memberships are synchronized between systems
  • Scalable: Efficiently manage large teams with many workspaces and custom roles

Prerequisites

  • Your organization must be on an Enterprise plan
  • Your Identity Provider (IdP) must support SCIM 2.0
  • Only Organization Admins can configure SCIM
  • For cloud customers: SAML SSO must be configured for your organization
  • For self-hosted customers: OAuth with Client Secret authentication mode must be enabled

Capabilities

SCIM enables the following capabilities:

  • User provisioning: Automatically add users to your LangSmith organization
  • User deprovisioning: Automatically remove users from your organization
  • Attribute synchronization: Keep user attributes (like full name) synchronized between your IdP and LangSmith
  • Group-based access: Sync membership from IdP user groups to LangSmith workspaces
  • Role assignment: Select specific Organization Roles and Workspace Roles for groups of users

Role Precedence

When a user belongs to multiple groups for the same workspace, the following precedence applies:

  1. Organization Admin groups take highest precedence - users in these groups will be Admin in all workspaces
  2. Most recently-created workspace-specific group takes precedence over other workspace groups
note

When a group is deleted or a user is removed from a group, their access is updated according to their remaining group membership, following the precedence rules above.

SCIM group membership will override manually-assigned roles or roles assigned via Just-in-Time (JIT) provisioning. We recommend disabling JIT provisioning to avoid conflicts.

Group Naming Convention

Group membership maps to LangSmith Workspace membership and workspace roles with a specific naming convention:

Organization Admin Groups

Format: <optional_prefix>Organization Admin or <optional_prefix>Organization Admins

Examples:

  • LS:Organization Admins
  • Groups-Organization Admins
  • Organization Admin

Workspace-Specific Groups

Format: <optional_prefix><org_role_name>:<workspace_name>:<workspace_role_name>

Examples:

  • LS:Organization User:Production:Annotators
  • Groups-Organization User:Engineering:Developers
  • Organization User:Marketing:Viewers

Email verification

In cloud only, creating a new user with SCIM triggers an email to the user. They must verify their email address by clicking the link in this email. The link expires in 24 hours, and can be resent if needed by removing and re-adding the user via SCIM.

Set up SCIM for your organization

Step 1: Configure SAML SSO (Cloud only)

If you're using LangSmith Cloud, ensure SAML SSO is configured for your organization.

NameID Format

LangSmith uses the SAML NameID to identify users. The NameID is a required field in the SAML response and is case-insensitive.

The NameID must:

  1. Be unique to each user.
  2. Be a persistent value that never changes, such as a randomly generated unique user ID.
  3. Match exactly on each sign-in attempt. It should not rely on user input.

The NameID should not be an email address or username because Email addresses and usernames are more likely to change over time and can be case-sensitive.

The NameID format must be Persistent, unless you are using a field, like email, that requires a different format.

Step 2: Disable JIT Provisioning (Cloud only)

Before enabling SCIM, disable Just-in-Time (JIT) provisioning to prevent conflicts between automatic and manual user provisioning. Use the PATCH /orgs/current/info endpoint:

curl -X PATCH $LANGCHAIN_ENDPOINT/orgs/current/info \
-H "X-Api-Key: $LANGCHAIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jit_provisioning_enabled": false}'

Step 3: Generate SCIM Bearer Token

Generate a SCIM Bearer Token for your organization. This token will be used by your IdP to authenticate SCIM API requests. Ensure env vars are set appropriately, for example:

curl -X POST $LANGCHAIN_ENDPOINT/v1/platform/orgs/current/scim/tokens \
-H "X-Api-Key: $LANGCHAIN_API_KEY" \
-H "X-Organization-Id: $LANGCHAIN_ORGANIZATION_ID" \
-H "Content-Type: application/json" \
-d '{"description": "Your description here"}'

Note that the SCIM Bearer Token value is not available outside of the response to this request. These additional endpoints are present:

  • GET /v1/platform/orgs/current/scim/tokens
  • GET /v1/platform/orgs/current/scim/tokens/{scim_token_id}
  • PATCH /v1/platform/orgs/current/scim/tokens/{scim_token_id} (only the description field is supported)
  • DELETE /v1/platform/orgs/current/scim/tokens/{scim_token_id}

Step 4: Configure your Identity Provider

Follow the IdP-specific instructions below to configure SCIM integration.

Identity Provider (IdP) Setup

Azure Entra ID

For additional information, see Microsoft's documentation.

Step 1: Configure SCIM in your Enterprise Application

  1. Log in to the Azure portal with a privileged role (e.g. Global Administrator)
  2. Navigate to your existing LangSmith Enterprise Application
  3. In the left-side navigation, select Manage > Provisioning
  4. Click Get started

Step 2: Configure Admin Credentials

  1. Under Admin Credentials:
    • Tenant URL:
      • US: https://api.smith.langchain.com/scim/v2
      • EU: https://eu.api.smith.langchain.com/scim/v2
      • Self-hosted: <langsmith_url>/scim/v2
    • Secret Token: Enter the SCIM Bearer Token generated in Step 3 above
  2. Click Test Connection to verify the configuration
  3. Click Save

Step 3: Configure Attribute Mappings

Configure the following attribute mappings under Mappings:

User Attributes

Set Target Object Actions to Create and Update (start with Delete disabled for safety):

LangSmith App AttributeMicrosoft Entra ID AttributeMatching Precedence
userNameuserPrincipalName
activeNot([IsSoftDeleted])
emails[type eq "work"].valuemail1
name.formatteddisplayName OR Join(" ", [givenName], [surname])2
externalIdobjectId31
  1. User's email address must be present in Entra ID
  2. Use the Join expression if your displayName does not match the format of Firstname Lastname
  3. To avoid inconsistency, this should match the SAML NameID assertion and the sub OAuth2.0 claim. For SAML SSO in cloud, the Unique User Identifier (Name ID) required claim should be user.objectID and the Name identifier format should be persistent.

Group Attributes

Set Target Object Actions to Create and Update only (start with Delete disabled for safety):

LangSmith App AttributeMicrosoft Entra ID AttributeMatching Precedence
displayNamedisplayname11
externalIdobjectId
membersmembers
  1. Groups must follow the naming convention described in the Azure Group Naming Convention section

Step 4: Assign Users and Groups

  1. Under Applications > Applications, select your LangSmith Enterprise Application
  2. Under the Assignments tab, click Assign then either Assign to People or Assign to Groups
  3. Make the desired selection(s), then Assign and Done

Step 5: Enable Provisioning

  1. Set Provisioning Status to On under Provisioning
  2. Monitor the initial sync to ensure users and groups are provisioned correctly
  3. Once verified, enable Delete actions for both User and Group mappings

Okta

Support for Okta is not yet released. If you are interested in using Okta with SCIM, please let us know at support@langchain.dev.

Other Identity Providers

Other identity providers have not been tested but may function depending on their SCIM implementation.

Support and troubleshooting

If you have issues setting up SCIM, please reach out to support@langchain.dev.

FAQ

Can I use SCIM without SAML SSO?

  • Cloud: No, SAML SSO is required for SCIM in cloud deployments
  • Self-hosted: Yes, SCIM works with OAuth with Client Secret authentication mode

What happens if I have both JIT provisioning and SCIM enabled?

JIT provisioning and SCIM can conflict with each other. We recommend disabling JIT provisioning before enabling SCIM to ensure consistent user provisioning behavior.

How do I change a user's role or workspace access?

Update the user's group membership in your IdP. The changes will be synchronized to LangSmith according to the role precedence rules.

What happens when a user is removed from all groups?

The user will be deprovisioned from your LangSmith organization according to your IdP's deprovisioning settings.

Can I use custom group names?

No, groups must follow the specific naming convention described in the Group Naming Convention section to properly map to LangSmith roles and workspaces.


Was this page helpful?


You can leave detailed feedback on GitHub.