How to set up single sign-on (SSO) in MASV

A MASV Team Owner can configure a SAML-enabled identity provider (IdP), such as Okta, Microsoft Entra ID, or PingIdentity, for secure user management and service authentication in MASV. SAML is an acronym for security assertion markup language, an XML-based standard used for exchanging authentication and authorization data.

This page includes the following topics:

• Overview
• What you'll need
• Domain verification tips
• SSO configuration in your identity provider
• SAML configuration in MASV
• How to set up SSO in MASV
• How to sign in to MASV with SSO

Overview

Setting up SSO with MASV includes verifying a domain, configuring your identity provider, and saving the metadata from your identity provider in MASV.

Steps for setting up SSO in MASV:

1. In MASV, add the domain you want to use for SSO. MASV generates a token that you can copy and use to verify the domain.
2. In the application where you manage the DNS (domain name system) for your domain, create a TXT record that includes the token generated by MASV, and save it to the DNS for your domain.
3. In MASV, you can now verify the domain. Remove the TXT record from your DNS manager after verification.
4. In your identity provider, create a new app integration for MASV. This includes importing the required SSO configuration information from MASV, mapping attributes, and assigning users to MASV.
5. Copy the configuration metadata (URL or raw metadata) from your identity provider, paste it into MASV, and save.
6. In MASV, enable the SSO toggle, set a unique SSO Name to provide to your users, and save.

After SSO is enabled for a MASV Team, all members of the Team must sign in with an email address that matches the domain verified in MASV, with the exception of the Team Owner who can sign in with an alternative method (sign in with Google; or email address/password combination).  For example, if the domain verified in the MASV SSO configuration is company.com, then all MASV Team members (aside from MASV Team Owner) must sign in with a user@company.com email address (jane@company.com, jon@company.com,...). Those same users and email addresses must be configured in the identity provider.

What you’ll need

As a MASV Team Owner who wants to set up SSO in MASV, you’ll need the following:

• Confirmation that SSO is available for your MASV Team. Contact support@masv.io for details.
• Permission to manage the DNS for the domain you want to use for SSO. The domain cannot be verified in MASV without the corresponding permissions.
• Admin rights to your identity provider in order to configure it for MASV.
• A list of the users who will be signing in to MASV. If you have existing Teams in MASV, review the list of users to ensure you remove any users who will not be registered with your identity provider–these users will be blocked from signing in to any MASV Team if you don’t remove them from your Team.

Domain verification tips

A key step in setting up SSO in MASV is verifying the domain you want to use by adding a TXT record for the domain in the software that you use to manage DNS. The exact steps depend on the DNS management software you use.

Keep in mind the following:

• Root domains: If the domain you entered in MASV was [example.com], this is called a root domain, and you likely don’t need to enter a host name. Many providers let you leave the host name field empty, while others require you to enter @ to indicate that you want the record to exist on the root domain.
• Subdomains: If the domain you entered in MASV was [sub.example.com], this is called a subdomain, and you need to enter the subdomain as the host name in the DNS record.
• As a security measure, after you verify the domain in MASV, delete the TXT record from your DNS.

SSO configuration in your identity provider

After you complete the domain verification in MASV, you can use the endpoints provided in the SSO Configuration area of the SSO Settings page to configure MASV in your identity provider. The endpoints required can vary according to the individual identity provider, so refer to your identity provider’s instructions for details.

MASV provides the following endpoints:

• ACS URL: An assertion consumer service (ACS) used to send SAML assertions to authenticate users.

• SP Entity ID: A unique URI (uniform resource identifier) used to identify an application (MASV) to a service provider.

• SP Metadata URL: An XML file containing the MASV metadata required to configure the identity provider.

Configuring your identity provider for MASV SSO includes creating an app integration, mapping attributes, and assigning users to MASV.

SAML configuration in MASV

After you configure your identity provider, you can finish configuring MASV using SAML 2.0 metadata generated by your identity provider. You have the choice of providing a metadata URL if your IdP provides it or you can paste the raw configuration metadata into MASV. If your IdP configuration changes, you can clear the current metadata in MASV and replace it with the new configuration metadata.

How to set up SSO in MASV

The following instructions step you through the process of setting up SSO in MASV. You'll need to complete some tasks in your DNS management software and your identity provider in order to complete the process. Consult the corresponding documentation as required.

After SSO is set up in MASV, you can control if it is active or not and choose if it is enforced for sign in.

To set up SSO in MASV

1. As a MASV Team Owner, sign in to the MASV Web App.
2. From the top of the sidebar on the left, ensure that you select the Team you want.
3. On the sidebar, select Features & Settings > SSO (near the bottom of the sidebar). Note: SSO appears only if it is available for your Team. Please contact support@masv.io for details
4. On the SSO Settings page, select the Domains tab or Subdomains tab, and enter the fully qualified domain name (FQDN) that you want to use for SSO in MASV. 
   
   
   
5. Select Add Domain. A verification token is generated and displayed below the domain field. Copy the token.
6. In the application where you manage the DNS for your domain, create a TXT record that includes the verification token generated by MASV, and save it to the DNS for your domain. 
7. In the MASV Web App select Verify.
   1. If the token disappears and a check mark displays next to your domain, the verification is successful. Remove the TXT record from your DNS.
   2. If you see a Verification failed message, please double-check that you created the TXT record correctly and that you waited long enough for the record to propagate. DNS record propagation usually happens within a few hours, but it can sometimes take multiple days for records to propagate worldwide.
8. In the SSO Configuration area, copy the endpoint(s) you require to configure MASV in your identity provider. Refer to your identity provider’s instructions for details.
9. After you configure your identity provider with MASV, copy the metadata URL or raw metadata (SAML that defines the configuration settings for your IdP) from your IdP and paste it into the SAML Configuration area in MASV.
10. In MASV, select Save in the lower right corner of the SSO Settings page.
11.  In the SSO Name box in the upper right side, enter a unique name for your MASV SSO. You will need to provide this name to all your MASV Team members.
12. To turn on your SSO, select Enable SSO toggle above SSO Name.
13. Select the Require login with SSO checkbox.

SSO is now set up for your Team. The next step is to invite users to sign in to MASV using SSO.

To turn off SSO or change the sign in requirement

1. As a MASV Team Owner, sign in to the MASV Web App.
2. From the top of the sidebar on the left, ensure that you select the Team you want.
3. On the sidebar, select Features & Settings > SSO.
4. On the SSO Settings page, do one of the following:
   1. To turn SSO off, select Enable SSO toggle above SSO Name, ensuring the the toggle is in the off position.
   2. To keep SSO on but not require it for sign in, deselect the Require login with SSO checkbox.

How to sign in to MASV using SSO

If you are a user signing in to MASV with SSO for the first time, follow the steps below to join the MASV Team. You’ll need the following:

• An email address that the MASV Team Owner has registered for SSO in MASV.
• The SSO Name provided to you by the MASV Team Owner. 

After signing in with SSO for the first time, subsequent sign-ins require only the first four steps below.

To sign in to MASV with SSO (first time)

1. Do one of the following:
   1. In your browser, open the MASV  sign in page.
   2. In the MASV Desktop App, from the drop-down menu in the upper right corner, select Sign in. You will be directed to sign in via your browser.
2. On the sign in page, select Continue with SSO.
3. In the Sign in to Your Organization window, enter the SSO Name provided to you by the MASV Team Owner/SSO Admin.
4. If redirected to your identity provider, enter your credentials.
5. You will receive an email to join the MASV Team. Open the email and select Join Now.
   
   
6. Return to the MASV sign in page, and select Continue with SSO.
7. Enter the SSO Name.

You now have access to the corresponding MASV Team. The scope of your access is determined by the role set for you by the Team Owner or Admin.