diff --git a/docs/administration/how_to_guides/organization_management/set_up_saml_sso.mdx b/docs/administration/how_to_guides/organization_management/set_up_saml_sso.mdx index 200e8af73..57448ddfd 100644 --- a/docs/administration/how_to_guides/organization_management/set_up_saml_sso.mdx +++ b/docs/administration/how_to_guides/organization_management/set_up_saml_sso.mdx @@ -111,7 +111,9 @@ These are instructions for setting up LangSmith SAML SSO with Entra ID (formerly For additional information, see Microsoft's [documentation](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso). -**Step 1: Create a new Entra ID application integration** + + Step 1: Create a new Entra ID application integration + 1. Log in to the [Azure portal](https://portal.azure.com/#home) with a privileged role (e.g. Global Administrator). On the left navigation pane, select the `Entra ID` service. 1. Navigate to Enterprise Applications and then select All Applications. @@ -199,6 +201,30 @@ For additional information, see Okta's [documentation](https://help.okta.com/en- **Step 1: Create and configure the Okta SAML application** +**Via Okta Integration Network (recommended)** + +1. Sign in to [Okta](https://login.okta.com/). +1. In the upper-right corner, select Admin. The button is not visible from the Admin area. +1. Select `Browse App Integration Catalog`. +1. Find and select the LangSmith application. +1. On the application overview page, select Add Integration. +1. Fill in `ApiUrlBase`: + - US: `api.smith.langchain.com` + - EU: `eu.api.smith.langchain.com` +1. Fill in `AuthHost`: + - US: `auth.langchain.com` + - EU: `eu.auth.langchain.com` +1. Fill in `LangSmithUrl`: Same as `ApiUrlBase` +1. Under Application Visibility, keep the box unchecked. +1. Select Next. +1. Select `SAML 2.0`. +1. Fill in `Sign-On Options`: + - `Application username format`: `Email` + - `Update application username on`: `Create and update` + - `Allow users to securely see their password`: leave **unchecked**. + +**Via Custom App Integration** + 1. Log in to Okta as an administrator, and go to the `Okta Admin console`. 1. Under `Applications > Applications` click `Create App Integration` 1. Select `SAML 2.0` @@ -206,7 +232,7 @@ For additional information, see Okta's [documentation](https://help.okta.com/en- 1. Enter the following information in the `Configure SAML` page: 1. `Single sign-on URL` a.k.a. `ACS URL`: . Keep `Use this for Recipient URL and Destination URL` checked. 1. `Audience URI (SP Entity ID)`: - 1. `Name ID format`: `EmailAddress` + 1. `Name ID format`: **Persistent** 1. `Application username`: `email` 1. Leave the rest of the fields empty or set to their default. 1. Click `Next diff --git a/docs/administration/how_to_guides/organization_management/set_up_scim.mdx b/docs/administration/how_to_guides/organization_management/set_up_scim.mdx index dc2792a43..ce5499115 100644 --- a/docs/administration/how_to_guides/organization_management/set_up_scim.mdx +++ b/docs/administration/how_to_guides/organization_management/set_up_scim.mdx @@ -1,6 +1,6 @@ import { RegionalUrl } from "@site/src/components/RegionalUrls"; -# SCIM User Provisioning (Beta) +# SCIM User Provisioning 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. @@ -9,7 +9,7 @@ SCIM is available for organizations on the [Enterprise plan](https://www.langcha SCIM is available on Helm chart versions 0.10.41 (application version 0.10.108) and later. -While in Beta, SCIM support is API-only (see instructions below). +SCIM support is API-only (see instructions below). ::: ## What is SCIM? @@ -24,15 +24,7 @@ SCIM enables automatic user provisioning and deprovisioning between your identit - **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](../../concepts#organization-roles) can configure SCIM -- For cloud customers: [SAML SSO](./set_up_saml_sso.mdx) must be configured for your organization -- For self-hosted customers: [OAuth with Client Secret](../../../self_hosting/configuration/sso#with-secret) authentication mode must be enabled - -## Capabilities +## Supported Features SCIM enables the following capabilities: @@ -42,7 +34,27 @@ SCIM enables the following capabilities: - **Group-based access**: Sync membership from IdP user groups to LangSmith workspaces - **Role assignment**: Select specific [Organization Roles](../../concepts#organization-roles) and [Workspace Roles](../../concepts#workspace-roles) for groups of users -## Role Precedence +SCIM is supported for these authentication methods: + +- Cloud: [SAML SSO](./set_up_saml_sso.mdx) +- Self-hosted: [OAuth2.0 with Client Secret](../../../self_hosting/configuration/sso#with-secret) + +## Requirements + +### Prerequisites + +- Your organization must be on an Enterprise plan. +- Your Identity Provider (IdP) must support SCIM 2.0. +- Only [Organization Admins](../../concepts#organization-roles) can configure SCIM. +- For cloud customers: [SAML SSO](./set_up_saml_sso.mdx) must be configurable for your organization. +- For self-hosted customers: [OAuth with Client Secret](../../../self_hosting/configuration/sso#with-secret) authentication mode must be enabled. +- For self-hosted customers, network traffic must be allowed from the identity provider to LangSmith: + - Microsoft Entra ID supports allowlisting IP ranges or an agent-based solution to provide connectivity. + ([details](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups#ip-ranges)). + - Okta supports allow-listing IPs or domains ([details](https://help.okta.com/en-us/content/topics/security/ip-address-allow-listing.htm)) + or an agent-based solution ([details](https://help.okta.com/en-us/content/topics/provisioning/opp/opp-main.htm)) to provide connectivity. + +### Role Precedence When a user belongs to multiple groups for the same workspace, the following precedence applies: @@ -55,11 +67,19 @@ When a group is deleted or a user is removed from a group, their access is updat 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 +### 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. + +## Attributes and Mapping + +### Group Naming Convention Group membership maps to LangSmith Workspace membership and workspace roles with a specific naming convention: -### Organization Admin Groups +#### Organization Admin Groups Format: `Organization Admin` or `Organization Admins` @@ -69,7 +89,7 @@ Examples: - `Groups-Organization Admins` - `Organization Admin` -### Workspace-Specific Groups +#### Workspace-Specific Groups Format: `::` @@ -79,17 +99,47 @@ Examples: - `Groups-Organization User:Engineering:Developers` - `Organization User:Marketing:Viewers` -## Email verification +### Mapping -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. +While specific instructions depending on the identity provider may vary, these mappings show what is supported by the LangSmith SCIM integration: + +#### User Attributes + +| **LangSmith App Attribute** | **Identity Provider Attribute** | **Matching Precedence** | +| ------------------------------ | ----------------------------------------------------- | ----------------------- | +| `userName`1 | email address | | +| `active` | `!deactivated` | | +| `emails[type eq "work"].value` | email address2 | | +| `name.formatted` | `displayName` OR `givenName + familyName`3 | | +| `givenName` | `givenName` | | +| `familyName` | `familyName` | | +| `externalId` | `sub`4 | 1 | + +1. `userName` is not required by LangSmith +1. Email address is required +1. Use the computed expression if your `displayName` does not match the format of `Firstname Lastname` +1. To avoid inconsistency, this should match the SAML `NameID` assertion (in cloud) and the `sub` OAuth2.0 claim (in self-hosted). + +#### Group Attributes -## Set up SCIM for your organization +| **LangSmith App Attribute** | **Identity Provider Attribute** | **Matching Precedence** | +| --------------------------- | ------------------------------- | ----------------------- | +| `displayName` | `displayName`1 | 1 | +| `externalId` | `objectId` | | +| `members` | `members` | | + +1. Groups must follow the naming convention described in the [Group Naming Convention](#group-naming-convention) section. + If your company has a group naming policy, you should instead map from the `description` identity provider attribute and + set the description based on the [Group Naming Convention](#group-naming-convention) section. + +## Configuration Steps ### Step 1: Configure SAML SSO (Cloud only) -If you're using LangSmith Cloud, ensure [SAML SSO](./set_up_saml_sso.mdx) is configured for your organization. +There are two scenarios for [SAML SSO](./set_up_saml_sso.mdx) configuration: + +1. If SAML SSO is already configured for your organization, you should skip the steps to initially add the application ([Add application from Okta Integration Network](#add-application-okta-oin) or [Create a new Entra ID application integration](./set_up_saml_sso#create-application-entra-id)), as you already have an application configured and just need to enable provisioning. +1. If you are configuring SAML SSO for the first time alongside SCIM, first follow the instructions to [set up SAML SSO](./set_up_saml_sso.mdx), _then_ follow the instructions here to enable SCIM. #### NameID Format @@ -122,6 +172,10 @@ curl -X PATCH $LANGCHAIN_ENDPOINT/orgs/current/info \ ### Step 3: Generate SCIM Bearer Token +:::note +In self-hosted environments, the full URL below may look like `https://langsmith.internal.corp.dev/api/v1/platform/orgs/current/scim/tokens` (without subdomain, note the `/api/v1` path prefix) or `https://langsmith.internal.corp.dev/subdomain/api/v1/platform/orgs/current/scim/tokens` (with subdomain) - see the [ingress docs](../../../self_hosting/configuration/ingress.mdx) for more details. +::: + 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: @@ -143,9 +197,9 @@ These additional endpoints are present: ### Step 4: Configure your Identity Provider -Follow the IdP-specific instructions below to configure SCIM integration. - -## Identity Provider (IdP) Setup +:::note +If you use Azure Entra ID (formerly Azure AD) or Okta, there are specific instructions below for identity provider setup ([Azure Entra ID](#azure-entra-id), [Okta](#okta)). The requirements and steps above are applicable for all identity providers. +::: ### Azure Entra ID @@ -196,11 +250,13 @@ Set `Target Object Actions` to `Create` and `Update` only (start with `Delete` d | **LangSmith App Attribute** | **Microsoft Entra ID Attribute** | **Matching Precedence** | | --------------------------- | -------------------------------- | ----------------------- | -| `displayName` | `displayname`1 | 1 | +| `displayName` | `displayName`1 | 1 | | `externalId` | `objectId` | | | `members` | `members` | | -1. Groups must follow the naming convention described in the [Azure Group Naming Convention](#group-naming-convention) section +1. Groups must follow the naming convention described in the [Group Naming Convention](#group-naming-convention) section. + If your company has a group naming policy, you should instead map from the `description` Microsoft Entra ID Attribute and + set the description based on the [Group Naming Convention](#group-naming-convention) section. **Step 4: Assign Users and Groups** @@ -216,13 +272,63 @@ Set `Target Object Actions` to `Create` and `Update` only (start with `Delete` d ### 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](mailto:support@langchain.dev). +:::note +You must use the [Okta Lifecycle Management](https://www.okta.com/products/lifecycle-management/) product. This product tier is required to use SCIM on Okta. +::: + + + Step 1: Add application from Okta Integration Network + + +:::note +If you have already configured SSO login via SAML (cloud) or OAuth2.0 with OIDC (self-hosted), you may skip this step. +::: + +See [SAML SSO setup](./set_up_saml_sso#okta) for cloud or [OAuth2.0 setup](../../../self_hosting/configuration/sso#identity-provider-setup-okta) for self-hosted. + +**Step 2: Configure API Integration** + +1. In the Provisioning tab, select Configure API integration. +1. Select Enable API integration. +1. For Base URL (if present): + +- US: `https://api.smith.langchain.com/scim/v2` +- EU: `https://eu.api.smith.langchain.com/scim/v2` +- Self-hosted: `/scim/v2` (note there is no `/api/v1` path prefix) or if subdomain is configured `/subdomain/scim/v2` + +4. For API Token, paste the SCIM token you [generated above](#step-3-generate-scim-bearer-token) +1. Keep `Import Groups` checked. +1. To verify the configuration, select Test API Credentials. +1. Select Save. +1. After saving the API integration details, new settings tabs appear on the left. Select `To App`. +1. Select Edit. +1. Select the Enable checkbox for Create Users, Update Users, and Deactivate Users. +1. Select Save. +1. Assign users and/or groups in the Assignments tab. Assigned users are created and managed in your LangSmith group. + +**Step 3: Configure User Provisioning Settings** + +1. Configure provisioning: under `Provisioning > To App > Provisioning to App`, click `Edit` then + check `Create Users`, `Update User Attributes`, and `Deactivate Users` +1. Under ` Attribute Mappings`, set the user attribute mappings as shown below, and delete the rest: + +![SCIM Okta User Attributes Mapping](./static/scim_okta_user_attributes.png) + +**Step 4: Push Groups** + +:::note +Okta does not support group attributes besides the group name itself, so group name _must_ follow the naming convention described in the [Group Naming Convention](#group-naming-convention) section. +::: + +Follow Okta's instructions [here](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-enable-group-push.htm) to configure groups to push by name or by rule. ### Other Identity Providers Other identity providers have not been tested but may function depending on their SCIM implementation. -## Support and troubleshooting +## Troubleshooting and Tips + +### Support If you have issues setting up SCIM, please reach out to [support@langchain.dev](mailto:support@langchain.dev). @@ -247,4 +353,8 @@ The user will be deprovisioned from your LangSmith organization according to you #### _Can I use custom group names?_ -No, groups must follow the specific naming convention described in the [Group Naming Convention](#group-naming-convention) section to properly map to LangSmith roles and workspaces. +Yes. If your identity provider supports syncing alternate fields to the `displayName` group attribute, you may use an alternate attribute (like `description`) as the `displayName` in LangSmith and retain full customizability of the identity provider group name. Otherwise, groups must follow the specific naming convention described in the [Group Naming Convention](#group-naming-convention) section to properly map to LangSmith roles and workspaces. + +#### _Why is my Okta integration not working?_ + +See Okta's troubleshooting guide here: https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-group-push-troubleshoot.htm. diff --git a/docs/administration/how_to_guides/organization_management/static/scim_okta_user_attributes.png b/docs/administration/how_to_guides/organization_management/static/scim_okta_user_attributes.png new file mode 100644 index 000000000..e4355e23e Binary files /dev/null and b/docs/administration/how_to_guides/organization_management/static/scim_okta_user_attributes.png differ diff --git a/docs/self_hosting/configuration/sso.mdx b/docs/self_hosting/configuration/sso.mdx index d74dbc3ab..db754d5e9 100644 --- a/docs/self_hosting/configuration/sso.mdx +++ b/docs/self_hosting/configuration/sso.mdx @@ -1,3 +1,4 @@ +import { RegionalUrl } from "@site/src/components/RegionalUrls"; import { CodeTabs, DockerBlock, @@ -76,9 +77,7 @@ All of the environment variables in this section are for the `platform-backend` - `OAUTH_SESSION_MAX_SEC` (default 1 day) can be overridden to a maximum of one week (`604800`) - For identity provider setups that don't support refresh tokens, setting `OAUTH_OVERRIDE_TOKEN_EXPIRY="true"` will take `OAUTH_SESSION_MAX_SEC` as the session length, ignoring the identity token expiration -### Identity Provider (IdP) Setup - -**Google Workspace** +### Identity Provider Setup: Google Workspace You can use Google Workspace as a single sign-on (SSO) provider using [OAuth2.0 and OIDC](https://developers.google.com/identity/openid-connect/openid-connect) without PKCE. @@ -106,6 +105,50 @@ You must have administrator-level access to your organization’s Google Cloud P 1. `oauth.enabled`: `true` 1. `authType`: `mixed` +### Identity Provider Setup: Okta + +**Via Okta Integration Network (recommended)** + +1. Sign in to Okta. +1. In the upper-right corner, select Admin. The button is not visible from the Admin area. +1. Select `Browse App Integration Catalog` +1. Find and select the LangSmith application. +1. On the application overview page, select Add Integration. +1. Fill in `ApiUrlBase`: `/api/v1` e.g. `langsmith.internal.corp/api/v1` or, if subdomain is enabled, `/subdomain/api/v1` +1. Fill in `AuthHost`: reuse `ApiUrlBase` from above (this value is unused in self-hosted, so any dummy value will technically work) +1. Fill in `LangSmithUrl`: just `` e.g. `langsmith.internal.corp` (note the protocol is omitted) +1. Under Application Visibility, keep the box unchecked. +1. Select Next +1. Select `OpenID Connect` +1. Fill in `Sign-On Options`: + 1. `Application username format`: `Email` + 1. `Update application username on`: `Create and update` + 1. `Allow users to securely see their password`: leave **unchecked** +1. Click `Finish` + +**Via Custom App Integration** + +1. Log in to Okta as an administrator, and go to the `Okta Admin console`. +1. Under `Applications > Applications` click `Create App Integration` +1. Select `OIDC - OpenID Connect` then `Web Application` +1. Enter an `App integration name` (e.g. `LangSmith`) +1. Enter the following information: + 1. (Optional) Check `Refresh Token` under `Core grants` to extend session lengths via refresh tokens. + 1. `Sign-in redirect URIs`: put the domain of your LangSmith instance followed by `/api/v1/oauth/custom-oidc/callback` e.g. `https://langsmith.yourdomain.com/api/v1/oauth/custom-oidc/callback` + 1. (Optional) `Sign-out redirect URIs`: put the domain of your LangSmith instance e.g. `https://langsmith.yourdomain.com` + 1. `Base URIs`: put the domain of your LangSmith instance e.g. `https://langsmith.yourdomain.com` +1. Click `Finish` + +**Configure LangSmith** + +1. Copy the `Client ID` and `Client Secret` from the `General` or `Sign On` page to use for configuring your installation: + 1. `oauthClientId`: `Client ID` (begins with `0oaud`) + 1. `oauthClientSecret`: `Client secret` + 1. `hostname`: the domain of your instance e.g. `https://langsmith.yourdomain.com` (no trailing slash) + 1. `oauthIssuerUrl`: `https://.okta.com` (can be found by clicking `OpenID Provider Metadata`) + 1. `oauth.enabled`: `true` + 1. `authType`: `mixed` + ## Without Client Secret (PKCE) (Deprecated) {#without-secret} We recommend running with a `Client Secret` if possible (previously we didn't support this). However, if your IdP does not support this, you can use the `Authorization Code with PKCE` flow.