Setting up Viewpoint ID SSO for ANZ Customers

IMPORTANT NOTE

This article is intended for our Australia and New Zealand-Based Vista ERP Cloud customers ONLY.   Vista ERP Cloud customers located in North America CANNOT use this method.  Please see the following link if you are located in the U.S. or Canada:

The Three Steps to SSO Joy - Setting up Trimble ID SSO 

Author: Eric Vasbinder

Overview

As mentioned in a previous FAQ article, Single Sign On (SSO) provides a powerful way to simplify user credential management, improve security, and allow end users to realize the full value of Trimble Viewpoint's solutions.  To that end, we created Viewpoint ID to provide a way to have a single set of credentials to authenticate into Viewpoint products, including Vista, Vista Web (HFF/Keystyle), and Team Project Management.   

Going forward, most new customers transforming into the Trimble Construction One (TC1) or Viewpoint One (VP1) cloud offerings in Australia or New Zealand will be set up to use Viewpoint ID SSO. 

Three Steps to Enable Viewpoint ID SSO

There are three major steps to properly enable your environment for Viewpoint ID SSO.  

• Step 1:  Set up Portal Administrator in Trimble Construction One (TC1) (formerly Team Enterprise Admin)

• Step 2 (Optional):  Request Viewpoint ID federation with preferred authentication provider and provide consent

• Step 3:  Push Existing Vista Users into Viewpoint ID

• Step 4:  Configure Individual Viewpoint ID Users

Step 1:  Portal Administrator(s) in the ANZ TC1 Portal

Formerly known as a Viewpoint Team Enterprise Admin, the TC1 Portal administrator is a critical user who must be setup prior to being able to "promote" or migration users into Trimble ID.

Please note that for the next step in the process, if you decide to federate Viewpoint ID with Azure AD, it is HIGHLY important that one of the Team Enterprise Admins added in this step 1 have Azure AD admin permissions so that they can consent on behalf of your organization.  AS SUCH, Any Azure AD admin added in this step MUST have an email inbox that can accept an invitation that will be sent in this step.

Please note that a CRITICAL requirement of any TC Portal admin is that their email address must fit the following three requirements:

• Their email address must be unique

• Their email address in the portal must EXACTLY match the email address for their account in Vista

• No trailing or leading spaces can be present in either the TC1 Portal email address or the email addressed stored in Vista

Please note that Trimble highly recommends setting up a minimum of TWO portal admin accounts, both for redundancy as well as to allow for a smoother initial pushing of users into Viewpoint ID.

To verify that you have appropriate access, please log in to your TC1 portal at https://au.team.viewpoint.com and look to see if you have user management rights.  If you do, then you are a portal admin.

Setting up Portal Admin Accounts

If you do NOT already have a portal admin account in our ANZ Team enterprise for you, you will need to have one created.  To do so, we ill need to complete the following steps:

1.  (CUSTOMER):  Submit a Cloud support case requesting that the names and email address(es) of your admin(s) be added to the https://au.team.viewpoint.com enterprise that corresponds to your organization.

2.  (VIEWPOINT):  Proceed to the AU Team platform admin screen, locate the customer in question, then click to "Send New Admin Invite".

3.  (VIEWPOINT):  Enter the First and Last Name of the admin user, along with their email address to which they will receive the invitation to join the enterprise as an enterprise admin.

Now that the invitation has been sent, you may skip the next section and proceed to activate your admin accounts, OR if you are going to use Azure AD federation, please wait until Step 2 is also complete.

Step 2 (Optional):  Set Up Viewpoint ID Federation in Team Platform

If you have a need to associate your Viewpoint ID domain with Azure AD (Entra ID), you will need to perform the following steps:

1.  (CUSTOMER):  Submit a cloud support case through the Viewpoint support portal to request that Viewpoint ID federation to Azure AD be turned on for your domain(s) in question.

2.  (VIEWPOINT):  Once the cloud support case is submitted, our team will go to your enterprise as listed in the ANZ Team platform and add the requested domain(s).

Step 3:  Finalizing Admin User Setup

The following steps will let you complete the set up of your Team Enterprise Admin user.

1.  (CUSTOMER):  Locate the Email Invitation that was sent to your email address from "DoNotReply@viewpoint.com"

2.  (CUSTOMER):  Click on the "Confirm Email and Configure Account" link.

   1. PLEASE VERIFY FIRST THAT THE DOMAIN NAME IN THE URL WILL TAKE YOU TO https://au.team.viewpoint.com

3.  (CUSTOMER):  You will then see a login screen that will ask you to enter your email address.  Please enter the email address of your admin account.

• NOTE:  If you are setting up federation to Azure AD (Entra ID) in this step, this will be the email address of your Azure AD admin as well.

(OPTIONAL) Finalizing Azure AD (Entra ID) Federation

If you are NOT setting up Azure AD federation in step 2, you will then proceed to set up a standalone Viewpoint ID account with a new password.  However, if you are finishing the set up of Azure AD Federation, please proceed with this next few steps:

1.  (CUSTOMER):  After entering your email address for your Team Enterprise Admin (who is also an Azure AD admin) in the login screen, you will then be presented with EITHER a login screen for Azure AD, if you have yet to log in for the day, or a "Permissions Requested" screen if you have already logged in today to Azure AD.

   1. The Permissions Requested will be from the voidentity-productionau Azure AD Enterprise application. 

   2. Permissions requested should be:

      1. "Sign you in and read your profile"

      2. "Maintain access to data you have given it access to"

2.  (CUSTOMER):  Assuming that this account as which you are logged in is an Azure AD admin, you may click on the checkbox "Consent on behalf of your organization", which will prevent this screen from being showed to all of your end users at login time.  

3.   (CUSTOMER):  Click "Accept".

Step 4:  Push Existing Vista Users into Viewpoint ID

Once you have assigned a TC1 Portal account to be a portal admin and optionally federated your Azure AD SSO, you will need to log in to Vista with that account to push existing Vista users into Viewpoint ID SSO.  That's always the first thing, right?  Logging in so that things can be done - I know, master of the obvious, here.

Well, in the Viewpoint Vista Cloud, logging into Vista for this step will be done using SSO itself.  "How does that work?", you might ask. 

First, you will need to ensure that you are able to log in to Viewpoint ID overall.  The next section of this article will walk you through that process.

a.  Validating Your Viewpoint ID is Working

If you are unsure whether your Viewpoint ID (VP ID) account has been set up, or if you have concerns that it may not be working, please use the following steps to validate if your VP ID account is up and running:

1. Open a web browser.

2. Go to our Team Platform Home page:  https://au.team.viewpoint.com

3. You will then be prompted to log in.

4. If you are able to log in, you will see the Team Project Management home page.

   1. If you see this page, then your VP ID account is set up properly.

5. If you are not able to log in, then please reach out to your Trimble Viewpoint support contact to verify if your VP ID account has been properly set up. 

The below is a screenshot of what that may look like for Team Enterprise Admins

CRITICAL NOTE - SSO MIGRATION PORTAL FOR HUMAN END USERS ONLY - NOT SERVICE ACCOUNTS

The migration portal listed in the followeing steps should only be used for migrating Vista human end user into SSO.  It should never be used to migrate service accounts, such as Keystyle.svc, Ryvit, etc.  Migrating Service accounts into SSO will break their functionality.

b.  Promoting Users to Viewpoint ID

Once you have set up a TC1 portal admin account using the same email address as a Vista admin, you can then begin the process of promoting Vista users into Viewpoint ID SSO.

NOTE:  Prior to beginning this process, please ensure your HQMA table is purged down to a reasonable size of no more than 1M records.  Extremely large HQMA tables can extend the SSO migration process by days and dramatically impact system responsiveness.  Please see this FAQ on Vista performance for more details:  Optimizing Vista Cloud Performance 

This method involves going to a specific website, clicking on the users that you would like to migrate to Viewpoint ID SSO, and then clicking the "migrate users" button.

1. Open your web browser of choice.

2. Open a web browser page to the following URL:  https://CODE-sso.viewpointforcloud.com/vista/1

   1. CRITICAL:  YOU MUST HAVE VISTA FORM AND MENU ADMINISTRATOR ACCESS IN VISTA IN ORDER TO LOAD THIS PAGE.

   2. CRITICAL:  YOU MUST ALSO HAVE ENTERPRISE ADMIN RIGHTS IN THE VIEWPOINT TEAM PLATFORM TO LOAD THIS PAGE AND PROMOTE USERS TO SSO.

      1. IN OTHER WORDS, THE SAME EMAIL ADDRESS SHOULD BE LISTED AS A TEAM ENTERPRISE ADMIN AND AS A FORM AND MENU ADMIN IN VISTA ITSELF

   3. Replace "CODE" with your 3 to 4 character alphanumeric cloud code.  This code is a unique identifier for each customer in our ERP cloud and can be obtained from your cloud support or transformations team.

   4. IMPORTANT:  The URL above is CASE-SENSITIVE.   For example, it will fail if you try to use a capital "V" for "vista"  https://CODE-sso.viewpointforcloud.com/Vista/1

3. On the resulting web page, click the users that you would like to migrate to Viewpoint ID SSO

4. Click on the checkbox for the user(s) you wish to migrate, or push, into Viewpoint ID.

5. Then click Migrate users.

The users will then receive invitations into Viewpoint ID and can create their new Viewpoint ID accounts.

CRITICAL NOTE

DO NOT PERFORM USER MIGRATIONS TO SSO ONE USER AT A TIME.  

If you do so, each SQL job to rename the user's name and audit trail entries will block the other SQL jobs, causing significant system slowness and potential many hours of downtime.  

BEST PRACTICE FOR SELECTING USERS

1. Prior to leaving for the day, select your users to migrate, so that this process performs OVERNIGHT.

2. Choose 15-25 users.  Then Click Migrate Users once all 15-25 are selected. 

3. Continue performing the user migration nightly until all users have been promoted to SSO.

Subsequent Logins - Viewpoint ID SSO

Admin logins to Vista that occur after the Vista admin account has been pushed into Viewpoint ID take place through the normal Viewpoint ID Vista login process.  Please see this article for more details (NOTE:  This article still applies to Viewpoint ID, save for the two screens that reference Trimble ID, which will NOT appear for ANZ customers):  Logging In - Via Trimble ID SSO 

Step 4:  Configure Individual Viewpoint ID Users

The next step of the move to Viewpoint ID SSO authentication is for each end user to set up their own Viewpoint ID.  If you have already set up Viewpoint ID SSO Federation to an external authentication system, this process will be as simple as receiving an email message, following the steps in the email message, clicking "next" a few times and then you will be done.

If you have not set up a federated authentication provider, the end user will need to set up their password for their Viewpoint ID account and ensure that the correct email address that corresponds to the address in Vista is set up in Viewpoint ID.