SAML

SAML authentication can be used to authenticate users against your organisation's Active Directory Federation Services (ADFS) identity provider, using the user credentials that are managed within the organisation's Active Directory.

Please note: Enabling SAML authentication will disable Vivi standard authentication.

This section outlines the process for configuring your Vivi environment to accept SAML authentication.

Once you have enabled SAML, Vivi creates the metadata URL which this can be used to automatically configure your relying party trust in ADFS. It will look something like this: https://api.vivi.io/api/v1/users/saml_metadata/xxxx-xxxx-xxxx Where xxxx is your organisation's unique ID.

Load metadata XML into ADFS

The metadata XML that is created by Vivi needs to be loaded into ADFS.

To do this:

• Open ADFS.

• In the left menu, go to "Relying Party Trusts".

• In the "Actions" on the right, select "Add Relying Party Trusts".

• Skip past the welcome page of the wizard.

• Select "Import data about the relying party published online or on a local network, and copy the URL into the relevant text box.

• Go through to the end of the wizard and save the changes.

ADFS Add Relying Party Trust Wizard

Set Up Identity Provider Claims

Identity provider claims need to be set up to support the Vivi solution.

You will need to log in to your ADFS instance and configure an LDAP claim that provides username, display name, and email.

Open

The Vivi solution needs information about group membership in order to assign permissions.

Set up six "Send Group Membership as a Claim" claims as in the screenshot, one for each of the Vivi roles listed below. A suggestion for the "outgoing claim values" for each role is provided. If required, multiple claims can be used to determine the access for a single role.

Finally, clicking the "View Rule Language..." button in the bottom left of each edit claim window shows the particular IDs used for each claim. You'll need to include these in the information below so that the Vivi servers can extract the claims.

Enable SAML authentication

To enable SAML authentication:

• Select the "Organisation" link in Vivi Central.

• Select the "Authentication" link in the menu at the top of the screen.

• Click "Edit".

• Enter the settings outlined below and click "Save Changes".

SAML Settings

SAML Group Settings

The following SAML group settings are also required. These aren't the actual group names or DNs, they're special values returned by the relevant SAML claim.

Multiple groups can be separated with | (pipe). When multiple groups are specified, then a user may be a member of any to receive the relevant role.

SAML should now be ready to test. Open the Vivi App (or restart if already open) and attempt to sign in with the username and password of an account in one of the appropriate groups.

SAML with WIA (Windows Integrated Authentication)

Organisations which use Windows Integrated Authentication (WIA) will require some extra steps to get Vivi working for all users. If your organisation is Windows only, there should be no further configuration required – however if you need to support other devices, such as Mac, iOS and Android you will need to modify your SAML instance.

Steps Required:

1.Edit the global settings in your SAML Management Console

Open

2. In the Global Authentication Policy pop-up tick Forms Authentication in the Intranet pane.

 

3. In Vivi Central, select the "Organisation" link.

4. Select the "Authentication" link in the menu at the top of the screen.

5. Click "Edit".

6. Scroll down until you find the "SAML Force Method" setting, and set it to "Forms".

7. Click "Save Changes".

SAML Force Method setting

When you have completed these steps, the system will use Forms Authentication as a fallback if WIA is not available – for example when connecting an iPad.

SAML Manual Configuration

In most cases, it should be possible to use the metadata XML provided by Vivi Central to auto-configure SAML authentication. If there are any problems with importing the metadata XML into Active Directory Federation Services, try these manual configuration steps.

These steps refer to information that is provided in the metadata XML that is generated when SAML authentication is enabled in Vivi Central. To get a copy of the file:

• Select the "Organisation" link in Vivi Central.

• Select the "Authentication" link in the menu at the top of the screen. This will display the current SAML authentication settings, including the SAML Metadata URL.

• Click on the URL to see the contents. The contents will look like the image below.

On the ADFS Windows server, run the ADFS "Add Relying Party Trust" wizard and work through the following steps:

Welcome Click "Start".

Select Data Source Select "Enter data about the relying party manually" and click "Next".

Specify Display Name Enter "Vivi" or whatever you'd like for the "Display name", then click "Next".

Choose Profile Leave "ADFS profile" selected and click "Next".

Configure Certificate Leave as default and click "Next".

Configure URL Leave as default (we'll fill these in later) and click "Next".

Configure Identifiers Add the metadata XML URL as the identifier, should be https://api.vivi.io/api/v1/saml_metadata/<organisation_id> (also labelled as 1 in the diagram above), make sure to click "Add" then "Next".

Configure Multi-factor Authentication Now? Configure as desired, but leave as default if in doubt, then click "Next".

Choose Issuance Authorization Rules Configure as desired, but leave as default if in doubt, then click "Next".

Ready to Add Trust Just click "Next".

Finish Untick the box to avoid editing claims straight away, then click "Close".

Now go back in by right clicking the new Relying Party Trust and selecting "Properties".

Go to Signature and "Add.." the signing certificate from the metadata XML. This is labelled as 2 in the diagram above, the easiest way is to copy and paste the data into a file with extension cer.

Go to Endpoints and "Add SAML.." two endpoints:

1. Endpoint type: SAML Assertion Consumer, Binding: POST, Default: yes, Trusted URL: should be https://api.vivi.io/api/v1/users/saml labelled as 3 in the diagram above.

2. Endpoint type: SAML Lagout, Binding: POST, Trusted URL: should be https://api.vivi.io/api/v1/saml_logout/<organisation_id> labelled as 4 in the diagram above, Response URL: same as Trusted URL.

You can then click "OK" to save the settings.

Now you can follow the regular steps of configuring the claims and Vivi.

Troubleshooting

• A SAML claim can only return 150 SAML groups total.  Anything beyond that will return a link to an MS Graph object which will not resolve properly with our systems.  To avoid this, users can be configured with only the groups assigned to the application being returned (see https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims#add-group-claims-to-tokens-for-saml-applications-using-sso-configuration)