> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vessl.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# SAML SSO
Streamline member management for your organization by integrating your third-party identity provider with VESSL through SAML Single Sign-On (SSO).
## Prerequisites
VESSL supports integration with any identity provider that complies with the SAML 2.0 protocol. Below are some commonly used providers:
* [Microsoft Entra](https://www.microsoft.com/en-us/security/business/microsoft-entra) (formerly Azure Active Directory)
* [AWS IAM Identity Center](https://aws.amazon.com/iam/identity-center/)
* [Okta](https://okta.com)
### Important Notes:
* VESSL's Assertion Consumer Service (ACS) only supports HTTP-POST bindings.
* The following SAML features are not supported by VESSL:
* Identity Provider (IdP)-initiated SSO
* Identity Provider (IdP)-initiated Single Logout (SLO)
## VESSL Endpoints
You can also find this information on the SAML SSO Settings page.
For each organization, VESSL is using the following format for SAML service provider configuration.
Be sure to replace `{your-org-name}` with your organization's name in the following URLs:
* SAML Entity ID (Metadata URL): `https://app.vessl.ai/{your-org-name}/saml/metadata`
* Assertion Consumer Service (ACS) URL: `https://app.vessl.ai/{your-org-name}/saml/acs`
The metadata URL itself serves raw metadata XML, which may be required for certain identity providers during configuration.
## Configuring Identity Provider
Choose the appropriate setup instructions based on your identity provider.
Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).
Navigate to **Enterprise applications** using the search bar.
Click **+ New Application**, then select **+ Create your own application**.
Enter `VESSL AI` as the application name and ensure you select **Non-gallery** application. Click **Create**.
After creating the application, you'll be directed to the **Overview** page.
Click on **1. Assign users and groups**, then select **+ Add user**.
Add users who will use VESSL, then click **Assign**.
Return to the **Overview** page and click **2. Set up single sign-on**. Select **SAML** as the sign-on method.
In **Basic SAML Configuration** (Section 1), add the **Identifier** and **Reply URL** using the information from [VESSL Endpoints](#vessl-endpoints), then click **Save**.
Copy the **App Federation Metadata URL** from Section 3. This will be needed in the next step.
In the AWS console, go to **IAM Identity Center** → **Applications**, then click **Add application**.
Select **I have an application I want to set up**, then choose **SAML 2.0**.
On the configuration page, set a recognizable **Display name** (for example, "VESSL AI"). **Download** the **IAM Identity Center SAML metadata file** (this will be used in VESSL later). In **Application metadata**, choose **Manually type your metadata values** and fill the fields using [VESSL Endpoints](#vessl-endpoints):
**Application ACS URL**: `https://app.vessl.ai/{your-org-name}/saml/acs`\
**Application SAML audience**: `https://app.vessl.ai/{your-org-name}/saml/metadata`
Use the following attribute names in VESSL SAML SSO Settings after finishing the IdP setup:
IDP User ID Attribute: username
IDP User Email Attribute: email
From the application detail page, go to **Actions** → **Edit attribute mappings**.
Enter the mappings as follows:
| User attribute | Maps to this string value | Format |
| -------------- | ------------------------- | --------- |
| Subject | `${user:email}` | transient |
| `email` | `${user:email}` | basic |
| `username` | `${user:email}` | basic |
Log in to your Okta organization with an administrator account.
In the admin console, go to **Applications** > **Applications**, then click **Create App Integration**.
Choose **SAML 2.0** as the sign-on method, then click **Next**.
Enter `VESSL AI` as the app name, then click **Next**.
Use the information from [VESSL Endpoints](#vessl-endpoints) to fill in the required fields.
Under **Attribute Statements**, configure the following attributes:
| Name | Name format | Value |
| ------------ | ------------- | ------------ |
| `user.email` | `Unspecified` | `user.email` |
| `user.login` | `Unspecified` | `user.login` |
Click **Next**, then click **Finish** to create the application.
On the app settings page, go to **Assignments**.
Select **Assign** > **Assign to People** to add users for VESSL.
Navigate to the **Sign On** tab. In the **SAML 2.0** section, copy the **Metadata URL**. This will be used in the next step.
Access your identity provider’s admin console and input the necessary information from the [VESSL Endpoints](#vessl-endpoints) section.
After completing the setup, copy the metadata URL or XML provided by your identity provider. This will be used in the next step.
## Configuring VESSL
After completing the setup of your identity provider, use the interactive demo below to configure VESSL's SAML SSO settings.
Open your organization **Settings** → **SAML SSO**.
Click **Add SAML SSO**.
Use the following values in the form:
| Field | Value |
| ------------------------ | ------------------------------------------------------------------ |
| Metadata XML | Paste contents of the downloaded IAM Identity Center metadata file |
| IdP User ID Attribute | `username` |
| IdP User Email Attribute | `email` |
### IdP Attributes
Identity providers (IdPs) use attributes to supply user ID and email information. VESSL requires these attributes to retrieve the corresponding user data during authentication. Ensure you configure the correct attribute names based on your identity provider.
Refer to the details below to fill in the required fields:
Use the following attribute names for Microsoft Entra:
* **IDP User ID Attribute**:
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
* **IDP User Email Attribute**:
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
Use the following attribute names for AWS IAM Identity Center:
* **IDP User ID Attribute**:
`username`
* **IDP User Email Attribute**:
`email`
The attributes below assume you followed the Okta setup guide in this documentation. If you use a custom configuration, adapt the values accordingly:
* **IDP User ID Attribute**:
`user.login`
* **IDP User Email Attribute**:
`user.email`
For custom identity providers, refer to their documentation to identify the correct attribute names for user ID and user email. If needed, consult your administrator to ensure proper configuration.