Skip to main content

Guide to migrate a Legacy SSO configuration in Sana Agents

V
Written by Viktor L
Updated this week

For a more stable experience, and to be able to enable SCIM, a Legacy SSO configuration must be migrated to a current one. The following instructions will guide you through the process.

Considerations

If you have too many different email domains or external users in your Identity Provider or for some other reason is unable to perform Domain Control Validation it may be better to remain on a Legacy SSO configuration since all users would need to re-validate their email address.

Migration guide

Overview

  1. First you create a new SSO configuration in Sana Agents and copy over the settings from the previous one.

  2. Second you update your identity provider configuration to use the new SSO configuration you just created.

  3. Test the configuration from your identity provider.

  4. Enable the new and disable the old configuration in Sana Agents.

Step 1 - Add a new 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 both the new and old configurations and copy over the previously set values for Name, Identity provider metadata url (preferred), and Metadata xml content from the old to the newly created SSO configuration.

  5. Click the Save button in the expanded sign-in configuration. Keep it disabled for now, but you should be quick to enable it as soon as you apply the changes in your identity provider.

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 - Update the application in your Identity Provider (IDP)

Update your Sana Agents application within your IDP.

You can either upload the new metadata.xml file or update the ACS and Entity ID manually.

We provide instructions for some identity provider services below.

Microsoft Azure / Entra

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

  2. ​On the Enterprise applications page, search for the application you previously configured for Sana Agents and then click the correct entry in the list.

  3. Click the Set up single sign on card.

  4. Click the Upload metadata file button.

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

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

  7. A popup will appear asking if you want to test the configuration. Keep it open and continue on to step 4. The settings have now been saved and users are now unable to sign in until this process is finished.

Okta

  1. Log in to the Okta admin dashboard. Navigate to the Applications page search for the app you previously configured for Sana Agents and the click the app in the search results.

  2. Navigate to the General tab, and then click the Edit button in the SAML Settings box.

  3. Click the Next next button to skip past the General Settings.

  4. Replace the urls in the fields marked Single sign-on URL and Audience URI (SP Entity ID) by pasting the new metadata url you previously copied from Sana Agents into both fields.

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

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

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.

If things doesn't work as expected you can always revert the configuration changes you did to your identity provider and everything should be as before.

Microsoft Azure / Entra

  1. After saving the metadata configuration. A popup will appear asking you to test the configuration. Click the Yes button. If you had closed the popup, click the Test this application button instead.

  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).

Okta

  1. Make sure you are assigned 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).
    ​

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. Since no settings other than the urls has changed, this should show the assertion passing and all the info as previously configured. Go to the next step.
​

Step 6 - Enable the SSO configuration in Sana Agents

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

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

  3. Go to the old configuration and disable it in the same way.

  4. Reload the page, you may 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.

All done

You have now completed the migration. With Domain Control Validation your users should not notice any changes, unless you changed the name for the new configuration.

Did this answer your question?