Skip to main content

Guide to Setup SSO for Sana Agents Enterprise Accounts

V
Written by Viktor L
Updated this week

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

  • Owners access to your Sana Agents workspace.

  • Before enabling SSO in your workspace, you should set up Domain Control Verification (DCV). This ensures that users logging in through SSO have validated email addresses, which is necessary to have all features properly function.
    For assistance with DCV setup, please refer to our help center article on Domain Control Validation.

  • Permissions to administer applications in your identity provider.

Setup

Below we will provide you with generic instructions how to setup SSO in Sana Agents, where applicable we will also provide steps for some specific identity providers. Just expand the instructions for your specific identity provider.

Step 1 - Add a Single Sign-On configuration in Sana Agents

  1. Log in as an owner to your Sana Agents workspace.

  2. Navigate to Settings → Workspace settings... → General and scroll down to Sign in methods.

  3. Click the Add method button and then select Single Sign On - SAML in the dropdown.

  4. Expand the newly created sign in method to expose the configuration.

  5. If you want, enter a name for your identity provider. If no name is provided "SSO" is used.

  6. Click the Save button in the expanded sign-in configuration. Keep it disabled for now.

Microsoft Azure / Entra

  1. Click the download button next to the field labeled Service provider metadata url / entity id and save the metadata file.

Okta

  1. Copy the url from the field labeled Service provider metadata url / entity id.

Step 2 - Create an application in your Identity Provider (IDP)

Create a new application specifically for Sana Agents within your IDP. Follow the instructions for your provider below.

Microsoft Azure / Entra

  1. In the search box, type "enterprise" and then click on the Enterprise applications result.


    ​

  2. Click the New application button in the top left.

  3. Click Create your own application.

  4. In the sidebar, type the name of the application and click the Create button at the bottom of the window. Make sure the third "Non-gallery" option is selected.

  5. When the app has been created, click the Set up single sign on card.

  6. Select SAML

  7. Click the Upload metadata file button.

  8. Browse to select the metadata file you just downloaded and the click the Add button.

  9. In the sidebar that comes up, the urls have been pre-filled. Click the Save button and then close the sidebar.

  10. A popup will appear asking if you want to test the configuration. Discard the popup.

  11. In the third card named SAML Certificates, copy the App Federation Metadata Url to the clipboard.

Okta

  1. Log in to the Okta admin dashboard. Navigate to the Applications page and click the Create App Integration button.

  2. In the popup, select SAML 2.0 and click the Next button.

  3. Enter a name for the application and click Next.

  4. Paste the metadata url you copied from Sana Agents into the fields marked Single sign-on URL and Audience URI (SP Entity ID).

  5. For Application username pick the one you think will change the least over time. If the username changes the user will receive a new account.

  6. Make sure you have at least the following attributes configured. For more information on what attributes are available to configure see the Assertions section of this article.

  7. Scroll down and click the Next button in the box marked B.

  8. On the next page, click the Finish button.

  9. When the application has finished being created, navigate to the Sign On tab.

  10. Copy the metadata url.

Step 3 - Provide metadata to Sana Agents

  1. Go back to the SSO configuration in Sana Agents.

  2. Paste the metadata url you just copied in the previous step into the field labeled Identity provider metadata url (preferred).

  3. Click the Save button in the expanded sign-in configuration. Keep it disabled for now.

Step 4 - Test sign in

Test the single sign on from your IDP to make sure everything works correctly before enabling it for all users.

Microsoft Azure / Entra

  1. After saving the metadata configuration. A popup will appear asking you to test the configuration. Click the Yes button.

  2. Another sidebar will appear. Click the Test sign in button.

  3. After selecting a user you should end up on the Sana Agents SAML test page (see below) if you left the SSO Configuration disabled. If you enabled it, you should now be logged in to the Sana Agents workspace. If you did not finish the DCV setup for your domain you will be asked to link your accounts.

Okta

  1. Assign yourself to the application.

  2. Go to your end user dashboard from the top right of the page.

  3. Click on the application you created for Sana Agents.

  4. After clicking the application you should end up on the Sana Agents SAML test page (see below) if you left the SSO Configuration disabled. If you enabled it, you should now be logged in to the Sana Agents workspace. If you did not finish the DCV setup for your domain you will be asked to link your accounts.
    ​

When testing sign in with a disabled configuration you should end up on the SAML test page. This page shows you if the assertions passed all checks, what attributes you have configured, and which ones are missing.
​

If you already enabled the SSO configuration in Sana Agents you will instead be signed in. If you were already signed in but did not finish the DCV setup you will instead see a page where you can link your already signed in account with the SSO account.

Step 5 - Add users

Assign users and groups to the application in your identity provider.

SCIM

If you want you can continue to setup SCIM which will automatically synchronize your users, making it possible to share content with them before they login.

Step 6 - Enable the SSO configuration in Sana Agents

  1. Go back and tick the Enabled checkbox inside the expanded sign in configuration.

  2. Click the Save button inside the expanded sign in configuration.

  3. Reload the page, you should be asked to link your account with your SSO sign-in. Click the Sign in with <the name of your IDP> button. And follow the sign-in process of your identity provider.

  4. Sign out from Sana Agents. You should end up on your workspace url with the sign in options where your new SSO configuration should be one of the options.

Step 7 - All done

The setup has been completed. You can start directing users to sign in with SSO. Users can sign in in two ways:

  • Your identity provider may list the available applications to a user, allowing the to sign in directly from there.

  • Through Sana Agents by visiting the workspace url and clicking the Sign in with <your IDP name> button.
    ​
    Your workspace url is https://sana.ai/<workspace id>.

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, because of marriage, or mergers, we prefer if you use some sort of persistent ID. UPN (or User Principal Name) is better than email. In Azure, there is the user.pairwise which is the optimal assertion type/value for Name ID it is however not available to choose in the SCIM configuration, so use it only when SCIM is not to be used.
    ​

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

    1. email

    2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

  • 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:
    ​

    1. firstName and lastName

    2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname and http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

    3. http://schemas.microsoft.com/identity/claims/displayname

    4. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

    5. displayName
      ​​

  • 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?