Presentation

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

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

There are two types of Google accounts.

• The “personal” account: This type of account is not dependent on an organization, it can be linked with any email address, but most often we have addresses of the type prénom.nom@gmail.com.

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. This is the primary email address that must be registered.
Only authentication is possible. All other functions described in this document cannot be used with a personal account.

• The “Google Workspace” account: This account is linked to an organization (professional, …) that is managed in Google Workspace.

All users with a Google Workspace account who are already registered in Visult can use Google SSO to sign in to Visult.

When an organization administrator in Google Workspace has also set up their organization in Visult, the features described in this document are accessible.

Technology used

There are several technologies for SSO, including OpenID Connect (OIDC) and SAML
https://support.google.com/a/topic/7556794?hl=en&ref_topic=7556686

Visult chose OIDC which is more flexible and simpler to implement for Google Workspace administrators and is newer than SAML.

Here is a technical description of OpenID Connect: https://openid.net/connect/

And its integration with Google Workspace:

https://developers.google.com/identity/protocols/oauth2/openid-connect

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 Google Workspace) and the information (name and email address) of the person who will be in charge of administering Visult and who must have administrative rights for the organization in Google Workspace (at a minimum, install apps, manage users and groups).

In the example used in this documentation, the organization is “Naturarmony” and the administrator is “admin@naturarmony.org”

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

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

First connection to Visult in Google SSO

Use the administrator’s account (example: alain@naturarmony.org). Depending on the security policy of your organization you will have to enter the password and possibly one or more additional validations (MFA), such as entering in code sent by SMS or email, use an application on Smartphone, …

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

Additional rights

When you grant additional rights, Visult may synchronize information from the Google Workspace directory.

For users: read your Function (Title), your Manager and the Department (team) of which you are a member.

For groups: manage access rights, give you the “manager” position or the “administrator” role. When there are teams in Visult that match Google Groups, you will be automatically added as a member in Visult teams.

Configure permissions and consents for the operation of Visult

Visult cannot use optional rights only when Google users have these rights for the organization’s directory in Google Workspace. By default, this is the case for Google Workspace administrators and for other users is not. If the Visult administrator is not a Google administrator, this user must have been assigned directory drive privileges for users and groups.

On your organization’s admin page in Visult, if the message below is displayed, it’s because the user’s rights are not sufficient in Google Workplace.

If this message is not displayed, you have sufficient rights in Google Workspace, skip to the next chapter.

The easiest way is to sign in to Visult with a Google Workplace admin account and grant the “View groups in your domain” and “View user information in your domain” permissions. This is not required, but in this case, not all the features of the Google Workplace integration, described in the rest of this documentation, will be accessible.

You must log out of Google, otherwise Visult will continue to use the current session and the new administrative rights will not be taken into account. In this example, fred@naturarmony.org will be a Visult administrator and they don’t have sufficient rights in Google Workplace.

Sign in to the Google Workspace Admin console with a Google Admin account.

https://admin.google.com/u/1/ac/roles

Go to role management, create a new “Visult” role and then assign it to the Visult administrator. If you plan to have multiple Visult administrators, it is advisable (but not necessary) to assign the Visult role to all affected accounts.

Visult will use the permissions of the last logged-in administrator, for a maximum of 6 months. With each new connection with an account with sufficient privileges, the duration will be extended by 6 months. You can remove this access by removing the Visult role in Google Workspace whenever you want, in which case the administrator links between Visult and Google will be inactive.

Google SSO configuration for your organization

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

Visult-related operations in Google Workspace

Visult connects to Google Workspace for reading and only for parties authorized by the consents granted.

None of the changes made in Visult impact Google Workspace.

Operations in Visult related to Google Workspace

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 Google Workspace, their unique Google ID is stored in Visult.

If the email address is later changed, in Visult or in Google Workspace, the link persists thanks to the unique Identifier Google ID. 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 Google Workspace 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 (maps, OGSM, …) to other users, but we will want to prevent the connection.

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 “Prohibit local password login (SSO required)” 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	Google	Comment
	googleId	User ID	Set up during the first connection in SSO
	Email	Primary email address	During the first SSO connection if a Visult user exists with this email address, the mapping is done and gooleId 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	Managers’s email	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 service” 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 connects 2) If we allow the creation of teams, we automatically create a team with the name of the service (this is not done for groups to avoid automatically using Google groups that have nothing to do with Visult). See more details on team management.
	Role (administrator)	ADMIN	Your organization’s admins in Google Workspace are also Visult admins. It is possible to select a Google 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 connection. Visult administrators who are not or are no longer in this group remain administrators
	Position (manager)	Manager	At each connection a user can obtain the “manager” position. One can only become a “collaborator” again by changing the position from Visult. Several Google settings are taken into account. –      When you are the “Manager” of a Google user you are considered a manager (including when you are responsible for users who are not yet registered in Visult) –      When you are a member of a Google group selected in “Give the position of manager to the members of”

Team management

Visult teams correspond to the “Department” attribute of users and Google Workspace “Groups”.

In Google Workspace 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 Services and groups is carried out at each SSO connection and its behavior is defined in Visult / administration / organization. The “Manage Visult teams from SSO groups and service” 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 affection of the members when connecting in SSO.

You can also disable this feature from Google Workspace by removing the “View groups in your domain” permission for the Visult app.

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 Google attribute “Department”.
As this attribute is a simple text we consider that the case is not important (Direction = DIRECTION = direction). The SSO identifier is considered to be the lowercase name (direction).
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 Direction = direction).

We then consider Google Workspace groups of which the user who signs in in SSO is a member. Since groups have a unique identifier, we first look for the Visult team that has the same identifier (googleId). 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 “googleId”

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 Google attribute “department”, 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 Google it is better to make only minor changes (case, add / remove spaces, …).

Groups that have different names from Google departments and Visult teams are not created. Indeed, unlike the “service” attribute, Google 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 connection shortcut

If you are logged in on your machine with only one Google account, it will be used by default.

If you have multiple Google 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?google=[email] replace [email] with your email address, for example:
https://app.visult.io/sso?google=alain@naturarmony.org