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.

Getting Started

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

Create a application in your identity provider for Sana Agents
Setup SAML SSO for this application, use the test page as the ACS endpoint.
Change the Name ID to preferably use a pairwise id of sorts. Email and UPN are often not enough static over time to be used as the account id.
Test signing in to the test page.
Make sure the assertion is passing the validation and the data you want to be available to the accounts is present on the page.
In Sana Agents, go to workspace settings and add a new SAML sign-in method.
Copy or download the metadata URL and provide it to your identity provider in the application you set up in step 1. If they do not provide a way to receive the metadata file, open it and extract the needed information and enter it in their UI.
You should now be set up and ready to go.

ACS Test Page

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.

URL: https://sana.ai/x-api/auth/saml/test

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:
- email
- 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:
- firstName and lastName
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname and http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
- http://schemas.microsoft.com/identity/claims/displayname
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
- 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.