Microsoft Entra ID (formally Azure AD)

Owned by William Crane (Unlicensed)
Last updated: Oct 16, 2024 by Blake Irving
4 min read

A Premium P1 Microsoft Entra ID Licence is required to set up this integration.

Enabling Microsoft Entra ID authentication will disable Vivi standard authentication.

This page will guide you on setting up Vivi Central against your organisation's Microsoft Entra ID instance. Once configured, users will sign into the Vivi App using their Microsoft Entra ID credentials.

Set the authentication type to SAML in Vivi Central

To enable Microsoft Entra ID authentication:

  1. Select the "Organisation" link in Vivi Central.

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

  3. Click "Edit".

  4. Select "SAML" as the Authentication Type and click "Save Changes".

This will generate a SAML Metadata URL which needs to be added to the Microsoft Entra ID configuration.

Example SAML Metadata URL

Enable authentication in Microsoft Entra ID

One you have set Authentication to SAML and have your SAML metadata URL follow these steps to configure the authentication. These steps take place in both the Microsoft Entra ID Portal, and in Vivi Central.

  1. Log in to the Microsoft Entra ID Portal at https://portal.azure.com.

  2. In the left navigation panel, click on "Microsoft Entra ID" and navigate to "Enterprise applications".

  3. Click "New application", then click "Create your own application".

  4. Enter "Vivi" for the name then select "Integrate any other application you don't find in the gallery (Non-gallery)" and click "Create".

  5. Go back to the “Enterprise applications” tab, and find and select “Vivi" in the list”

  6. Click "2. Set up single sign-on".

  7. For "Single Sign-On Mode" select "SAML".

  8. For "Identifier" enter the SAML metadata URL that was generated by Vivi Central. The format will be something like: "https://api.vivi.io/api/v1/users/saml_metadata/<your organisation id>"

  9. For "Reply URL" enter https://api.vivi.io/api/v1/users/saml and press Save

  10. Download the "SAML Signing Certificate" as "Certificate (Base64)"

Setting up Vivi Central

  1. Select the "Organisation" link in Vivi Central.

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

  3. Click "Edit".

  4. Open the certificate in a text editor and copy the contents into the "SAML Token-Signing Certificate" field. The certificate should begin and end with the following: 

    -----BEGIN CERTIFICATE-----
    -----END CERTIFICATE-----

  5. Back in Microsoft Entra ID, press "Configure Vivi".

  6. Copy the "SAML Single Sign-On Service URL" value into "SAML SSO URL" configuration item in Vivi Central. It should look something like this : https://login.microsoftonline.com/<your organisation id>/saml2

  7. Ignore the rest of the values, such as "Sign-Out URL" and "SAML SLO URL" (keep these blank on Vivi Central).

  8. Click "Save Changes".

The SAML Signing Certificate is generated and managed on the Entra ID side. To avoid service interruptions, it's crucial to configure certificate expiry notifications within Entra to be sent to a monitored email address. This will ensure timely renewal and prevent downtime when the certificate expires.

For more detailed information, please refer to the following Microsoft FAQ: https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/application-management-certs-faq

Setting up Microsoft Entra ID

  1. In Microsoft Entra ID, go back to "Microsoft Entra ID" and then to "App registrations".

  2. Find and select the "Vivi" application.

  3. Click "Manifest" to view the JSON configuration.

  4. Find "groupMembershipClaims" and change the value from null to "SecurityGroup" (with quotes).

  5. Continuing in Microsoft Entra ID, go back to the Vivi application from the Enterprise Application list and click "Single sign-on".

  6. For "Logout URL" enter “https://api.vivi.io/api/v1/users/saml_logout/<your organisation id>” and click “Save”,

    1. The following guide from Microsoft shows where this Organisation/Tenant ID can be found: https://docs.microsoft.com/en-us/partner-center/find-ids-and-domain-names

  7. Go back to "Enterprise applications" -> "Vivi" -> "Users and Groups".

  8. Only users and groups explicitly added here will be able to sign in to the Vivi App. You will need an "Object ID" to match each of the Vivi roles.

    1. Nested groups cannot be assigned in Microsoft Entra ID according to Microsoft: https://docs.microsoft.com/en-us/azure/active-directory/enterprise-users/directory-service-limits-restrictions

    2. Please ensure that you are only using Security Groups. Distribution Groups and other types of groups are not supported.

  9. Alternatively, you can disable "User assignment required?" in "Vivi" -> "Properties" to allow all users to sign in.

Defining Groups in Vivi Central

  1. In Vivi Central, go to the Organisations > Authentication tab and click “Edit”

  2. For "SAML Name Attribute" enter "http://schemas.microsoft.com/identity/claims/displayname"

  3. For "SAML Email Attribute" enter "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"

  4. For "SAML Group Attribute" enter "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"

  5. For "SAML Presenter Group", "SAML Student Group", "SAML Emergency Authorised Group", "SAML IT Admin Group", SAML E-Learning Admin Group" use the "Object ID" found on the groups you want to use.

    1. The object ID can be found on the Group page by clicking the name of the group:

Microsoft Entra ID authentication 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.