...
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 Where xxxx is your organisation's unique ID.
...
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
...
You will need to log in to your ADFS instance and configure an LDAP claim that provides username, display name, and email.
...
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.
Vivi Role | Suggested claim value |
IT Admin | itadmins |
E-Learning Admin | elearning |
Emergency Authorised | emergency |
Presenter | presenters |
Signage Admin | signageadmin |
Student | students |
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.
...
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
Setting | Description |
Authentication Type | SAML |
Require Inheritance Code | This can be used to restrict users to signing in to particular organisations. If this is disabled, then users can log into any managed organisation that exists within the same ADFS service. |
SAML Default Email Domain | A default email domain to use in case a user has no email address, e.g. "myschool.com.au", then emails will be "username@myschool.com.au". |
SAML SSO URL | Full URL to your ADFS identity provider single sign-on endpoint, e.g. "https://dc.example.com/adfs/ls/". |
SAML SLO URL | Full URL to your ADFS identity provider single logout endpoint. This can be left blank if this is the same as the single sign-on endpoint. |
SAML Token-Signing Certificate | Exported Token-Signing Certificate from your ADFS identify provider, in PEM format. |
SAML Name Attribute | Name used by your ADFS identity provider for the claim mapping a user's display name, for example: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name. |
SAML Email Attribute | Name used by your ADFS identity for the claim mapping a user's email address, for example: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress". |
SAML Group Attribute | SAML Group Attribute: Name used by your ADFS identity provider for the claim mapping a user's group membership, for example: "http://schemas.xmlsoap.org/claims/Group". |
SAML Inheritance Code Attribute | Name used by your ADFS identify provider for the claim mapping a user's inheritance code. Only needed if Require Inheritance Code is enabled. |
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.
Setting | Description |
SAML Presenter Group | Group of users who will be given the presenter role. Leave blank to include everyone (not recommended). |
SAML Student Group | Group of other users allowed to access Vivi. Leave blank to include everyone (not recommended). |
SAML Emergency Authorised Group | Group of users allowed to trigger emergencies. Leave blank to assign manually in Vivi Central. |
SAML IT Admin Group | Group of users provided with admin access to Vivi Central. Leave blank to assign manually in Vivi Central. If the group is set, existing IT Admins will lose their admin access since the Vivi Central role will no longer be relevant. |
SAML E-Learning Admin Group | Group of users allowed access to metrics. Leave blank to assign manually in Vivi Central. |
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.
...
1.Edit the global settings in your SAML Management Console
...
2. In the Global Authentication Policy pop-up tick Forms Authentication in the Intranet pane.
  
3. In Vivi Central, select the "Organisation" link.
...
6. Scroll down until you find the "SAML Force Method" setting, and set it to "Forms".
7. Click "Save Changes".
SAML Force Method setting
...
In most cases, it should be possible to use the the metadata XML provided by Vivi Central to 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:
...
Configure Identifiers Add the metadata XML URL as the identifier, should be 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".
...
Go to Endpoints and "Add SAML.." two endpoints:
Endpoint type: SAML Assertion Consumer, Binding: POST, Default: yes, Trusted URL: should
...
...
labelled as 3 in the diagram above.
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)