Presentation

Single Sign-On (SSO) allows users who have a Microsoft account to sign in to Visult without using a Visult password.

Visult password sign-in can be disabled by the administrator, in which case it is mandatory to have a Microsoft account.

There are two types of Microsoft accounts:

The “personal” account: This type of account can be used to log in to Visult only when the user is already registered in Visult with the same email address.
When the personal account has secondary email addresses, they are not used by Visult. The primary email address in AD must be registered in Visult.
Only authentication is possible. All other functions, described in this document, cannot be used with a personal account.
The “work or school” account: This account is linked to an organization (work or school) that is most often described and managed in “Azure Active Directory” (AAD). This may or may not be related to an organization that has subscribed to “Microsoft 365”.
Organizations using “Microsoft Active Directory” (On-Premise) cannot directly use SSO with Visult. However, it is possible to create an “Azure Active Directory” or “Microsoft 365” directory and synchronize it with “Microsoft Active Directory”.
https://docs.microsoft.com/en-us/microsoft-365/enterprise/set-up-directory-synchronization?view=o365-worldwide

All users with a Microsoft account who are already registered in Visult can use Microsoft SSO to sign in to Visult (except when Visult is declared in the AAD organization and an administrator has a policy in place to prohibit the use of Visult).

When an ADD and Visult administrator has configured their organization in Visult and installed the Visult application in Active Directory, the features described in this document are accessible.

Technology used

There are several technologies for SSO, including OpenID Connect (OIDC) and SAML
https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/sso-options

Visult chose OIDC, which is more flexible and simpler to implement for Active Directory administrators and is the technology recommended by Microsoft.

Here is a technical description of OpenID Connect:
https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc

Configuration

Creating the organization in Visult

This operation is performed by a Visult super administrator. You must provide them with the name of your organization (which is not necessarily the one used in AAD) and the information (name and email address) of the person who will be in charge of administering Visult and who must have administrative rights in Azure Active Directory (at a minimum, install applications, manage users and groups).

In the example used in this documentation, the organization is “Darnwell” and the administrator is “admin@darnwell.eu”

It is better to check that it is possible to connect to Visult with the [Login] button and then use the menu of profile, administration, organization.

At this point there is no Microsoft SSO information for the organization.

Connecting the organization

The easiest way is to reconnect to Visult with the button [Login with Microsoft]

If this does not work directly it is likely that your organization has disabled the automatic installation of applications. If it worked you can go to the “Installing Visult in Azure Active Directory” section

Installing Visult in Azure Active Directory

Sign in to Microsoft Azure with the administrator account (example: admin@darnwell.eu)
https://portal.azure.com/#blade/Microsoft_AAD_IAM/AppGalleryBladeV2

Search and select Visult, then click [Sign up for Visult]

This will call Visult and ask you for authentication.

First connection to Visult in Microsoft SSO

Use the administrator’s account (example: admin@darnwell.eu). Depending on your organization’s security policy you will need to enter the password and possibly one or more additional validations (MFA), such as entering code sent by SMS or email, using Microsoft Authenticator, …

You are asked for the first time to give the basic permissions to operate the OIDC SSO

If you choose to give consent on behalf of your organization, users will no longer be asked. Otherwise, each user must give his consent to the first connection to Visult.

It is recommended to give consent for the organization.

Once logged in to Visult, go to the “Administration / My organization” section.

You will find the following information, which indicates that the configuration is not complete.

Click [Sign in]

Configuring permissions and consents for the operation of Visult

https://portal.azure.com/#blade/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/AllApps/menuId/

Select [Visult] then [Permissions]

The 3 automatically assigned permissions are the ones that are needed for the SSO.

If you do not assign additional permissions:

Users will be able to log in
Accounts will be created automatically
Some information from the profile, manager and teams will not be taken into account.

To give all the necessary permissions for further integration of Visult, click: [Grant admin consent for …]

Click [Accept]

Details of permissions:

Maintain access to data you have given it access to

Allows Visult to store data that is not part of the base profile. In particular: the title of the position, the relationship with his direct manager, the name of the main team.

Sign in and read user profile

Provides complete information from the user who is logging in. In particular: the title of the position, the relationship with his direct manager, the name of the main team.

Read all users’ full profiles

Allows you to obtain the information of the manager of the user who is connecting. Necessary when Visult is configured to automatically register the manager (can be disabled in Visult).

Read all groups

Automatically enroll users in Visult teams that have the same name as Active Directory groups.

Allows you to use Active Directory groups to: restrict access to Visult, assign the “Manager” position, or the “Administrator” role in Visult.

Read directory data

It is possible to obtain certain data from restricted information for OIDC, this consent allows to use that of active directory. Especially for the name and id of the groups.

Once consents have been granted, the screen should look like this (the page must be refreshed)

Once consents have been granted, log out and log back in to Visult.

The Administration/My Organization page should now look like this:

Visult-related operations in Active Directory

Visult connects to Active Directory on read and only for parties authorized by the permissions granted.

None of the changes made in Visult impact Active Directory.

Operations in Visult related to Active Directory

Visult has chosen not to provide provisioning by SCIM (Cross-domain Identity Management). This way, users in your organization are not automatically registered or removed from Visult.

User registration

The link between an existing Visult user and an SSO user is made by his email address. The first time a link was made, if the user is registered in Active Directory, their unique AD ID is stored in Visult.

If the email address is subsequently changed, in Visult or in AD, the link persists thanks to the unique identifier AD. When this link is made, it is visible in the user’s record.

Controlling user SSO access

In Visult / Administration / Organization it is possible to specify 3 Active Directory groups.
When a group is specified in “Grant access to Visult to members of”, then when connecting in SSO the user must be a member of one of the 3 groups to access Visult. This also applies to users who have already registered.

For example, when a user leaves the company we will want to keep his Visult account to assign objects (cards, OGSM, …) to other users, but we will want to prevent the connection. Note that it is also possible to achieve this with Active Directory policies by limiting the use of the Visult application (but this is more complicated). Note that if the user has the right to log in with an account/password they will be able to continue to do so. You can either remove the ability to log in with a password or disable it in Visult.

The “Prevent local connection by password (SSO is mandatory)” check box exists either at the organization level or at the user level.

When a user is created during SSO login, their password is not specified and the user must log in in SSO. If he wants to connect locally you must uncheck this box and specify a password.

Taking into account and updating attributes

Color	Visult	Active Directory	Comment
	microsoftId	Object ID	Set up during the first connection in SSO
	Email	User Principal Name	During the first SSO connection if a Visult user exists with this email address, the mapping is done and microsoftId is saved. Thereafter the link is always made even if the email addresses are modified
	Title	Job title	Set up during automatic creation following an SSO connection. Will not be changed automatically afterwards
	Report to	Manager	Set up during SSO connection if this attribute does not exist in Visult. When it already exists in Visult it is not modified
	Member of	Department	In the settings of the Visult organization you can specify how to take this information into account with the “Manage Visult teams from SSO groups and department” choice list. When this option is in place: 1) We are looking for a team that matches (id, identical name without taking into account the case). When it exists, we assign the user who log in. 2) If we allow the creation of teams, we automatically create a team with the name of the department (this is not done for groups to avoid automatically using AD groups that have nothing to do with Visult). See more details on team management.
	Role (Administrator)		It is possible to select an Active Directory group in the Visult organization “Give admin role to members of”, members of this group will have the Administrator role in Visult. This is achieved with each SSO log in. Visult administrators who are not or are no longer in this group remain administrators
	Position (Manager)	Manager	At each log in a user can obtain the “manager” position. One can only become an “employee” again by changing the position from Visult. Several AD parameters are taken into account. When you are the “Manager” of an AD user you are considered a manager (including when you are a manager of users who are not yet registered in Visult)When you are a member of an AD group selected in “Give manager position to the members of”

Team management

Visult teams correspond to the “Department” attribute of Active Directory users and to AD “Groups”.

In AD a user can be assigned to a single ” Department ” which is a simple text attribute (no unique identifier). Regardless of this it can be a member of one or more groups (groups have a name, a unique identifier and other attributes not used in Visult).

The consideration of Departments and groups is carried out at each SSO log in and its behavior is defined in Visult / administration / organization. The “Manage Visult teams from SSO groups and department” list can take the following values:

Do not manage teams

In this case we will not take any action regarding the creation of teams or the affectation of the members when connecting in SSO.

You can also disable this function from AD by removing the “Read all groups” permission for the Visult application. This requires a PowerShell script action described by Microsoft (Review permissions / This application has more permissions than I want).

If we use this option when SSO operations on the teams have already been carried out, it does not change what has been done.

Assign users in Visult existing teams

For the user who connects in SSO we start by checking if he has the AD attribute “department”.
As this attribute is a simple text we consider that the case is not important (Comex = COMEX = comex). The SSO identifier is considered to be the lowercase name (comex).
We search in Visult if there is a group with the identical “SSO Name” attribute, if it does not exist, we look for a team with the same name in lowercase (here Comex = comex).

We then consider the AD groups of which the user who log in in SSO is a member.

Since groups have a unique identifier, we first look for the Visult team that has the same identifier (microsoftId).

If it does not exist, we search among the teams that do not have an identifier if there is one with an identical “SSO name” and then an identical name. If we find a team we assign it the unique identifier in “microsoftId”

We assign the user as a member in the Visult teams that exist.

Create Visult teams and assign users

The same search is performed as for the previous option. If you can’t find a team that matches the AD “department” attribute, you create the team and remember its name in “SSO Name”. Once “SSO Name” is filled in you can change the name in Visult, it will not have consequences for the next assignments that will be done correctly. To see more easily the correspondences between Visult and AD it is better to make only minor changes (case, add / remove spaces, …).

Groups that have different names from AD departments and Visult teams are not created only.

Indeed, unlike the “department” attribute, AD groups are used for many applications that do not have a link to the company’s team organization.

There would therefore be a creation of too many groups without interest in Visult.

Create a sign-in shortcut

If you’re signed in on your machine with only one Microsoft account, it will be used by default.

If you have multiple Microsoft accounts connected, you’ll be offered to select one of the accounts or use a different one.

It is possible to create a shortcut to force a new connection:

https://app.visult.io/soo?microsoft=[email] by replacing [email] with your email address, for example: https://app.visult.io/sso?microsoft=alain@darnwell.eu

You can use current account or choose between connected accounts with: https://app.visult.io/soo?microsoft=select_account