> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.vessl.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# SAML SSO
> Integrate your SAML 2.0 identity provider to manage organization membership.
Simplify organization membership by integrating your organization's identity provider (IdP) with VESSL Cloud through Security Assertion Markup Language (SAML) Single Sign-On (SSO). Once configured, members sign in to VESSL Cloud with the accounts they already use in your IdP.
## Prerequisites
VESSL Cloud integrates with any identity provider that supports the SAML 2.0 protocol. Commonly used providers include:
* [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)
Before you start, make sure that:
* You are an organization admin. Only admins can configure SAML SSO.
* SAML SSO is enabled for your organization. If the **SAML SSO** menu does not appear under **Settings**, contact [support@vessl.ai](mailto:support@vessl.ai).
- The Assertion Consumer Service (ACS) endpoint supports HTTP-POST bindings only.
- IdP-initiated SSO and Single Logout (SLO) are not supported.
## Find your SP configuration
In the sidebar, select **Settings**, then select **SAML SSO** under **Organization**.
The **SP Configuration** section shows the two service provider (SP) URLs your identity provider needs. Both URLs are unique to your organization, so copy them directly from this page:
* **VESSL Cloud's metadata**: the SAML Entity ID, also called the metadata URL. Opening this URL serves the raw metadata XML, which some identity providers require during configuration.
* **SAML ACS URL**: the endpoint that receives SAML responses from your identity provider.
## Configure your identity provider
Choose the setup instructions that match 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 an application name like `VESSL Cloud`, select **Non-gallery** application, and click **Create**.
After creating the application, you land on the **Overview** page. Click **1. Assign users and groups**, then select **+ Add user**.
Add the users who will use VESSL Cloud, 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), set **Identifier (Entity ID)** to the **VESSL Cloud's metadata** URL and **Reply URL** to the **SAML ACS URL** from [Find your SP configuration](#find-your-sp-configuration), then click **Save**.
Copy the **App Federation Metadata URL** from Section 3. You will paste it into VESSL Cloud in the next section.
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 Cloud`). **Download** the **IAM Identity Center SAML metadata file**; you will paste its contents into VESSL Cloud later.
In **Application metadata**, choose **Manually type your metadata values** and fill in the fields using the URLs from [Find your SP configuration](#find-your-sp-configuration):
| Field | Value |
| ------------------------- | ---------------------------------- |
| Application ACS URL | The **SAML ACS URL** |
| Application SAML audience | The **VESSL Cloud's metadata** URL |
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 |
After finishing the IdP setup, use `username` for **IdP User ID** and `email` for **IdP User email attribute** in VESSL Cloud. See [IdP attribute reference](#idp-attribute-reference).
Sign 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 an app name like `VESSL Cloud`, then click **Next**.
Fill in the required fields using the URLs from [Find your SP configuration](#find-your-sp-configuration):
| Field | Value |
| --------------------------- | ---------------------------------- |
| Single sign-on URL | The **SAML ACS URL** |
| Audience URI (SP Entity ID) | The **VESSL Cloud's metadata** URL |
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 the users who will use VESSL Cloud.
Navigate to the **Sign On** tab. In the **SAML 2.0** section, copy the **Metadata URL**. You will paste it into VESSL Cloud in the next section.
Access your identity provider's admin console and register VESSL Cloud using the URLs from [Find your SP configuration](#find-your-sp-configuration).
After completing the setup, copy the metadata URL or XML provided by your identity provider. You will paste it into VESSL Cloud in the next section.
## Configure VESSL Cloud
After setting up your identity provider, register its metadata in VESSL Cloud.
In the sidebar, select **Settings**, then select **SAML SSO** under **Organization**.
In the **IdP Configuration** section, click **Add SAML SSO**.
In **Metadata XML**, choose **XML** to paste the metadata XML, or choose **URL** to enter the metadata URL you copied from your identity provider.
Fill in **IdP User ID** and **IdP User email attribute** with the attribute names your identity provider uses in its SAML response. The correct values depend on your provider; see [IdP attribute reference](#idp-attribute-reference).
Click **Save**. A confirmation appears when SAML SSO is configured. If saving fails with a `Failed to configure SAML SSO` error that mentions `invalid IdP metadata`, the metadata could not be parsed. Check that you pasted the complete metadata XML or entered the correct metadata URL, then try again.
Saving enforces SAML SSO for the organization: members must sign in through your identity provider to access it, and sessions signed in with other methods lose access. The session you used to save the configuration switches to an SSO session automatically, so you stay signed in.
## Sign in with SAML SSO
Once SAML SSO is configured, members sign in to the organization through your identity provider:
On the VESSL Cloud sign-in page, click **Continue with SAML SSO**.
Enter your organization name in **Organization name** and submit. You are redirected to your identity provider.
Complete the sign-in at your identity provider. You are then redirected back to your organization.
SSO sign-in resolves organization membership as follows:
* A user without a VESSL Cloud account gets an account created and joins your organization automatically on their first SSO sign-in.
* An existing member of your organization signs in as usual.
* A user who already has a VESSL Cloud account but is not a member of your organization cannot sign in with SSO. Invite them to the organization first; see [Invite a member](/admin/teams/invite-member).
SSO works for CLI sign-in too: `vesslctl auth login` signs in through the browser by default, where members can continue with SAML SSO.
## IdP attribute reference
Identity providers use attributes in the SAML response to pass each user's ID and email. VESSL Cloud looks up these values using the attribute names you enter in **IdP User ID** and **IdP User email attribute**, so the names must match your identity provider's configuration exactly.
Refer to the values below for your provider:
| Field | Attribute name |
| ------------------------ | -------------------------------------------------------------------- |
| IdP User ID | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` |
| IdP User email attribute | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` |
| Field | Attribute name |
| ------------------------ | -------------- |
| IdP User ID | `username` |
| IdP User email attribute | `email` |
The values below assume you followed the Okta setup guide on this page. If you use a custom configuration, adapt them accordingly.
| Field | Attribute name |
| ------------------------ | -------------- |
| IdP User ID | `user.login` |
| IdP User email attribute | `user.email` |
Refer to your identity provider's documentation to identify the attribute names for user ID and user email. If needed, consult your IdP administrator to confirm the configuration.
## See also
* [Organization overview](/admin/organization/overview)
* [Invite a member](/admin/teams/invite-member)