Overview

SAML Single Sign On (SSO) allows your Users or Callers to quickly and easily log into the Vivantio main application or Self Service Portal (SSP) respectively using your organisation's preferred Identity Provider (IdP). This avoids having to set up or use a username/password in Vivantio.

Considerations

Vivantio SAML SSO works with a variety of mainstream IdPs such as Azure Active Directory (AAD), Okta, Google and Active Directory Federation Services (AD FS), however, we have been unable to test our implementation with every IdP. We are though very happy to work with you if you are using a less common IdP and are experiencing issues. Please note that we only support service-provider initiated sign-in, i.e. sign-in initiated by Vivantio.

SAML SSO requires configuration in both Vivantio and the IdP, with some information being provided by Vivantio for use by the IdP and vice versa. Unfortunately, some of the SAML technical features are referred to by different names by different IdPs and this is a common cause of confusion when configuring a new SAML implementation. In this guide we use AAD as an example IdP so please note that the terminology in the screenshots that follow may differ if you are not using AAD.

A common 'matching attribute' is required in order for a user in an IdP to be recognised as a user in the Vivantio main application or a caller in the SSP. Typically, the user's email address is chosen for this purpose. Where this is the case, in Vivantio user records (Admin > Setup > User Management > Users) and/or caller records (CRM > Contacts) need the Email field to match that specified in the IdP.

Prerequisites

This article assumes that you have already set SAML up with your IdP and that the information required by Vivantio is available to be copied from the IdP settings pages.

Only a Vivantio Local Administrator will be able to configure SAML SSO in Vivantio. If this person does not also have appropriate access to the IdP then they will need to work in conjunction with someone who does.

To configure SAML SSO in Vivantio you must first enable the feature within the admin global settings:

Once enabled, you will then see the SAML option within the Admin > Integration & API, and this is where the settings will need to be configured:

Configuration in Vivantio

Identity Provider (IdP) URL

This is the SAML login URL of the IdP which Vivantio will use to redirect Users or Callers in order for them to login via your IdP.

In our AAD example, this is found in Section 4 as 'Login URL'

Certificate

This is for the IdP's SAML Certificate in Base64 format. Typically, the certificate should be downloaded and opened in a text editor and the entire contents copied in. It is fine to include the --Begin Certificate-- and --End Certificate-- text.

In our AAD example, this is found in Section 3 as 'Certificate (Base64)':

Use POST

POST is the preferred option and is more secure, and is almost always the required option. However, if the SAML IdP uses HTTP GET please leave this box unchecked.

Issuer Name

This is the name by which your IdP will identify Vivantio as a service provider (SP) application. We recommend keeping this simple and using Vivantio as the name. You will need to provide this exact name in your IdP configuration.

In our AAD example, this is added in Section 1 as the 'Identifier (Entity ID)':

Name ID Format

As previously mentioned, this is the common 'matching attribute' that links a user in the IdP with a user or caller in Vivantio, and EmailAddress is the preferred option. In your IdP you will need to ensure that an emailaddress claim has been configured to supply the user's email address.

In our AAD example, this is found in Section 2 as an 'emailaddress/user.mail claim':

Authentication Context

This option is defaulted to PasswordProtectedTransport - this is the recommended option.

However, depending on the configuration of your IdP, you may need to change this, for example, AD FS Servers may require you to use Windows.

IdP Configuration

Issue Name equivalent

As detailed above, the Issuer Name field in Vivantio will need to match the equivalent field in your IdP.

In our AAD example, this is added in Section 1 as the 'Identifier (Entity ID)':

Reply URL or equivalent

This is the URL at the Vivantio end and can be found by downloading the SAML metadata from the Vivantio SAML configuration screen:

Use the Location element which should be a URL in the following format:

https://<domainname>/AuthProviders/Saml/Complete/

In our AAD example, this is added in Section 1 as 'Reply URL (Assertion Consumer Service URL)':

Logging in the Main Application as a User

When the IdP and Vivantio configurations have been saved Users logging in to the main Vivantio application will now get the option to login via SAML:

Logging in the Self Service Portal as a Caller

To enable SAML SSO for Callers to your SSP the configuration remains the same as above, however, a further 'Reply URL' field is required for the IdP configuration in the following format:

https://<domainname>.selfservice.vivantio.com/AuthProviders/Saml/Complete/

Additionally, within Vivantio, you will also need to navigate to the Admin Area > Self Service > Features and check Enable Single Sign On via SAML and then click Save:

When logging into the SSP Callers will then get the option to login via SAML:

Created: 30 August 2023