feat: SAML SSO docs

versioned_docs/version-2.0/how_to_guides/setup/set_up_saml_sso.mdx

@@ -0,0 +1,208 @@
+import { RegionalUrl } from "@site/src/components/RegionalUrls";
+
+# SAML SSO (beta)
+
+Single Sign-On (SSO) functionality is available for Enterprise customers to access LangSmith through a single authentication source. This allows administrators to centrally manage team access and keeps information more secure.
+
+LangSmith's SSO configuration is built using the SAML (Security Assertion Markup Language) 2.0 standard. SAML 2.0 enables connecting an Identity Provider (IdP) to your organization for an easier, more secure login experience.
+
+:::note
+SAML SSO is available for organizations on the [Enterprise plan](../../pricing.mdx). Please [contact sales](https://www.langchain.com/contact-sales) to learn more.
+:::
+
+## What is SAML SSO?
+
+SSO services permit a user to use one set of credentials (for example, a name or email address and password) to access multiple applications. The service authenticates the end user only once for all the applications the user has been given rights to and eliminates further prompts when the user switches applications during the same session.
+
+## Benefits of SSO
+
+- Streamlines user management across systems for organization owners.
+- Enables organizations to enforce their own security policies (e.g. MFA)
+- Removes the need for end-users to remember and manage multiple passwords. Simplifies end-users experience by allowing them to sign in at one single access point and enjoy a seamless experience across multiple applications.
+
+## Set up SAML SSO for your organization
+
+### Prerequisites
+
+- While in beta, you must reach out to [email protected] to enable for your organization
+- Your organization must be on an Enterprise plan
+- Your Identity Provider (IdP) must support the SAML 2.0 standard
+- Only [Organization Admins](../../concepts/admin#organization-roles) can configure SAML SSO
+
+### Initial configuration
+
+:::note
+See IdP-specific instructions [below](#identity-provider-idp-setup)
+:::note
+
+1. In your IdP: Configure a SAML application with the following details, then copy the metadata URL or XML for step 3 below
+   1. Single sign-on URL a.k.a. ACS URL: <RegionalUrl suffix='/auth/v1/sso/saml/acs'/>
+   1. Audience URI a.k.a. SP Entity ID: <RegionalUrl suffix='/auth/v1/sso/saml/metadata'/>
+   1. Name ID format: email address
+   1. Application username: email address
+   1. Required claims: `sub` and `email`
+1. In LangSmith: Go to `Settings` -> `Members and roles` -> `SSO Configuration`
+   1. Fill in the required information and submit to activate SSO login
+      1. Fill in either the `SAML metadata URL` or `SAML metadata XML`
+      1. Select the `Default workspace role` and `Default workspaces`.
+         New users logging in via SSO will be added to the specified workspaces with the selected role.
+
+### Editing SAML SSO settings
+
+- `Default workspace role` and `Default workspaces` are editable.
+  The updated settings will apply to new users only, not existing users.
+- (Coming soon) `SAML metadata URL` and `SAML metadata XML` are editable. This is usually only necessary when cryptographic keys are rotated/expired or the metadata URL has changed but the same IdP is still used.
+
+## Just-in-time (JIT) provisioning
+
+LangSmith supports Just-in-Time provisioning when using SAML SSO. This allows someone signing in via SAML SSO to join the organization and selected workspaces automatically as a member.
+
+:::note
+JIT provisioning only runs for new users i.e. users who do not already have access to the organization with the same email address via a [different login method](../../reference/authentication_authorization/authentication_methods.mdx#cloud)
+:::
+
+## Login methods and access
+
+Once you have completed your configuration of SAML SSO for your organization, users will be able to login via SAML SSO in addition to [other login methods](../../reference/authentication_authorization/authentication_methods.mdx#cloud) such as username/password and Google Authentication.
+
+- When logged in via SAML SSO, users can only access the corresponding organization with SAML SSO configured.
+- Users with SAML SSO as their only login method do not have [personal organizations](../../concepts/admin/admin.mdx#organizations)
+- When logged in via any other method, users can access the organization with SAML SSO configured along with any other organizations they are a part of
+
+## Enforce SAML SSO only
+
+To ensure users can only access the organization when logged in using SAML SSO and no other method, update the `Login method` to `Only SAML SSO`.
+Once this happens, users in the organization will be logged out and required to log back in using SAML SSO.  
+This setting can be switched back to `Any method` at any point.
+
+:::note
+You must be logged in via SAML SSO in order to update this setting to `Only SAML SSO`.
+This is to ensure the SAML settings are valid and avoid locking users out of your organization.
+:::
+
+## Support and troubleshooting
+
+If you have issues setting up SAML SSO, please reach out to [[email protected]](mailto:[email protected]).
+
+## Identity Provider (IdP) Setup
+
+These are instructions for setting up LangSmith SAML SSO with Entra ID (formerly Azure), Google, and Okta. If you use a different Identity Provider and need assistance with configuration, please contact our support team.
+
+### Entra ID (Azure)
+
+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**
+
+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.
+1. Click `Create your own application`.
+1. In the Create your own application window:
+   1. Enter a name for your application (e.g. `LangSmith`)
+   1. Select `Integrate any other application you don't find in the gallery (Non-gallery)`.
+1. Click `Create`.
+
+**Step 2: Configure the Entra ID application and obtain the SAML Metadata**
+
+1. Open the enterprise application that you created.
+1. In the left-side navigation, select `Manage > Single sign-on`.
+1. On the Single sign-on page, click `SAML`.
+1. Update the `Basic SAML Configuration`
+   1. `Identifier (Entity ID)`: <RegionalUrl suffix='/auth/v1/sso/saml/metadata'/>
+   1. `Reply URL (Assertion Consumer Service URL)`: <RegionalUrl suffix='/auth/v1/sso/saml/acs'/>
+   1. Leave `Relay State`, `Logout Url`, and `Sign on URL` empty
+   1. Click `Save`
+1. Ensure required claims are present with `Namespace`: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims`
+   1. `sub`: `user.objectid`
+   1. `emailaddress`: `user.userprincipalname` or `user.mail` (if using the latter, ensure all users have the `Email` field filled in under `Contact Information`)
+1. On the SAML-based Sign-on page, under `SAML Certificates`, copy the `App Federation Metadata Url`.
+
+**Step 3: Set up LangSmith SSO Configuration**
+
+Follow the instructions under [initial configuration](#initial-configuration) in the `Fill in required information` step, using the metadata URL from the previous step.
+
+**Step 4: Verify the SSO setup**
+
+1. Assign the application to users/groups in Entra ID
+   1. Select `Manage > Users and groups`
+   1. Click `Add user/group`
+   1. In the Add Assignment window:
+      1. Under Users, click `None Selected`.
+      1. Search for the user you want to assign to the enterprise application, and then click `Select`.
+      1. Verify that the user is selected, and click `Assign`.
+1. Have the user sign in via the unique login URL from the `SSO Configuration` page, or go to `Manage > Single sign-on` and select `Test single sign-on with <application name>`
+
+### Google
+
+For additional information, see Google's [documentation](https://support.google.com/a/answer/6087519).
+
+**Step 1: Create and configure the Google Workspace SAML application**
+
+1. Make sure you're signed into an administrator account with the appropriate permissions.
+1. In the Admin console, go to `Menu -> Apps -> Web and mobile apps`.
+1. Click `Add App` and then `Add custom SAML app`.
+1. Enter the app name and, optionally, upload an icon. Click `Continue`.
+1. On the Google Identity Provider details page, download the `IDP metadata` and save it for Step 2 below. Click Continue.
+1. In the `Service Provider Details` window, enter:
+   1. `ACS URL`: <RegionalUrl suffix='/auth/v1/sso/saml/acs'/>
+   1. `Entity ID`: <RegionalUrl suffix='/auth/v1/sso/saml/metadata'/>
+   1. Leave `Start URL` and the `Signed response` box empty.
+   1. Set `Name ID` format to `EMAIL` and leave `Name ID` as the default (`Basic Information > Primary email`).
+   1. Click `Continue`.
+1. Use `Add mapping` to ensure required claims are present:
+   1. `Basic Information > Primary email` -> `email`
+
+**Step 2: Set up LangSmith SSO Configuration**
+
+Follow the instructions under [initial configuration](#initial-configuration) in the `Fill in required information` step, using the `IDP metadata` from the previous step as the metadata XML.
+
+**Step 3: Turn on the SAML app in Google**
+
+1. Select the SAML app under `Menu -> Apps -> Web and mobile apps`
+1. Click `User access`.
+1. Turn on the service:
+   1. To turn the service on for everyone in your organization, click `On for everyone`, and then click `Save`.
+   1. To turn the service on for an organizational unit:
+      1. At the left, select the organizational unit then `On`.
+      1. If the Service status is set to `Inherited` and you want to keep the updated setting, even if the parent setting changes, click `Override`.
+      1. If the Service status is set to `Overridden`, either click `Inherit` to revert to the same setting as its parent, or click `Save` to keep the new setting, even if the parent setting changes.
+   1. To turn on a service for a set of users across or within organizational units, select an access group. For details, go to [Use groups to customize service access](https://support.google.com/a/answer/9050643).
+1. Ensure that the email addresses your users use to sign in to LangSmith match the email addresses they use to sign in to your Google domain.
+
+**Step 4: Verify the SSO setup**
+
+Have a user with access sign in via the unique login URL from the `SSO Configuration` page, or go to the SAML application page in Google and click `TEST SAML LOGIN`.
+
+### Okta
+
+For additional information, see Okta's [documentation](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm).
+
+**Step 1: Create and configure the Okta SAML application**
+
+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`
+1. Enter an `App name` (e.g. `LangSmith`) and optionally an `App logo`, then click `Next`
+1. Enter the following information in the `Conofigure SAML` page:
+   1. `Single sign-on URL` a.k.a. `ACS URL`: <RegionalUrl suffix='/auth/v1/sso/saml/acs'/>. Keep `Use this for Recipient URL and Destination URL` checked.
+   1. `Audience URI (SP Entity ID)`: <RegionalUrl suffix='/auth/v1/sso/saml/metadata'/>
+   1. `Name ID format`: `EmailAddress`
+   1. `Application username`: `email`
+   1. Leave the rest of the fields empty or set to their default.
+   1. Click `Next
+1. Click `Finish`
+1. Copy the `Metadata URL` from the `Sign On` page to use in the next step
+
+**Step 2: Set up LangSmith SSO Configuration**
+
+Follow the instructions under [initial configuration](#initial-configuration) in the `Fill in required information` step, using the metadata URL from the previous step.
+
+**Step 3: Assign users to LangSmith in Okta**
+
+1. Under `Applications > Applications`, select the SAML application created in Step 1
+1. Under the `Assignments` tab, click `Assign` then either `Assign to People` or `Assign to Groups`
+1. Make the desired selection(s), then `Assign` and `Done`
+
+**Step 4: Verify the SSO setup**
+
+Have a user with access sign in via the unique login URL from the `SSO Configuration` page, or have a user select the application from their Okta dashboard.

versioned_docs/version-2.0/reference/authentication_authorization/authentication_methods.mdx

@@ -12,6 +12,10 @@ Users can use an email address and password to sign up and login to LangSmith.
 
 Users can alternatively use their credentials from GitHub, Google, or Discord.
 
+### SAML SSO
+
+Enterprise customers can configure [SAML SSO](../../how_to_guides/setup/set_up_saml_sso.mdx)
+
 ## Self-Hosted
 
 Self-hosted customers have more control over how their users can login to LangSmith.