Skip to main content

Guide to Setup SSO for Sana Agents Enterprise Accounts

A
Written by Alexander
Updated over a month ago

Overview

Sana Agents employs SAML for Single Sign-On (SSO) functionality, a feature integral to the platform. Sana Agents simplifies this setup by leveraging SAML Metadata files, ensuring a seamless integration experience. While we recommend providing a URL for configuration, please note that while most Identity Providers support this, some may not. Initially, the default assertion fields are sufficient for initiating SSO, but we advise customizing the Name ID before the first sign-in. To assist you in this process, our ACS test page allows you to review outcomes and adjust fields until you achieve your desired configuration.

Prerequisites

Before enabling SSO in your workspace, you should set up Domain Control Verification. This ensures that users logging in through SSO have validated email addresses, which is necessary for all features to function properly.

For assistance with the setup, please refer to our help center article on Domain Control Validation.
​

Getting Started

The best ways of setting up SSO with Sana Agents are described in the following checklist:

  1. Create an Application in your Identity Provider: Set up a new application specifically for Sana Agents within your identity provider (IdP).ACS Test Page

  2. Configure SAML SSO for the Application: Use the test page as the ACS endpoint. Ensure that the SAML SSO configuration is correctly set up in your IdP.

  3. Modify the Name ID: Preferably use a pairwise identifier for the Name ID. Avoid using email or UPN as they may change over time and are not static enough to serve as a reliable account ID.

  4. Test the SSO Configuration: Attempt to sign in using the test page to ensure the configuration is working. Verify that the SAML assertion passes validation and that the necessary data is available on the test page.

  5. Configure SAML Sign-In in Sana Agents: Navigate to the workspace settings in Sana Agents and add a new SAML sign-in method.

  6. Provide Metadata to Your Identity Provider: Copy or download the metadata URL from Sana Agents. Provide this metadata to your IdP in the application you set up in step 1. If your IdP does not support metadata files directly, manually extract the necessary information from the file and enter it into their user interface.

  7. Finalize and Test: Ensure all configurations are complete and test the SSO setup thoroughly to confirm everything is functioning as expected.

To demonstrate the impact of configuring various assertions, we've developed a test page. Utilize this page as the Assertion Consumer Service (ACS) URL and initiate an identity provider-based login to observe the outcomes firsthand.

Assertions

Sana Agents recognizes several assertions, with the email and a special Name ID field being mandatory. Additionally, specifying the display name and image URL is recommended for enhanced functionality.

  • Name ID
    The most important assertion is the ID you will represent the user with in our database. Often, email is used, but since the email address often changes, we prefer if you use some sort of persistent ID. In Azure, there is the user.pairwise which is the optimal assertion type/value for Name ID.
    ​

  • Email
    The provision of an email address is required. We will retrieve it from the specified assertions, adhering to the following sequence:
    ​
    Field names:
    ​

  • Display Names
    The inclusion of a display name is discretionary, with retrieval from various assertion fields. Depending on the field, it may be sourced either directly or from pairs of fields. The fields will be attempted in the specified sequence below until a valid display name is obtained or all fields have been exhausted:
    ​
    Field names:
    ​

  • Image URL
    This serves as a link to the user's profile picture. Please note that currently, the profile picture is only set upon user creation and will not be updated if changed thereafter.
    ​
    Field name: imageUrl
    ​

  • Role
    This denotes the user's role within the product. If provided, it will override the user's default role upon login. Should you opt not to include the role field, access roles will need to be managed within the product. You can adjust this behavior as needed by either including or excluding this field from the assertion.
    ​
    Field name: role
    ​
    Available roles:​

    • viewer

    • editor

    • owner

For further information about Sana Agents, please contact [email protected] via email.

Did this answer your question?