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