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:
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.
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 theuser.pairwisewhich 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:viewereditorowner
For further information about Sana Agents, please contact [email protected] via email.