How to Setup Azure AD SSO

MASV team owners can require SSO for individual teams. This guide will walk you through how to configure SSO using Azure AD.

Setup SSO in MASV

  1. Ensure you are logged into MASV and that you’ve selected the team you wish to configure SSO for.
  2. Click the team selector at the top of the left sidebar, and then click “Settings” to navigate to your team’s settings page.
    Team settings
  3. Once on the team settings page, navigate to the “SSO” tab 
    If you don’t see the SSO tab, you might not be an administrator on this team. Please contact your team owner to request the necessary access. If you are an administrator but still do not see the SSO tab, SSO may not be enabled for your team.
    SSO tab
  4. Ensure you have ownership of at least one domain verified. For a guide on domain verification, read How to Verify Your Domain for Single Sign On (SSO)
  5. In the “SSO Configuration” section, you should see three fields:

    1. ACS URL
    2. SP Entity ID
    3. SP Metadata URL

    Keep this screen open as you proceed to the next section.

Creating and configuring an Azure Application

  1. Ensure you are signed into Azure.
  2. Click “Azure Active Directory” in the sidebar, then to “Enterprise Applications”, also from the sidebar.
  3. Click “New application” in the top navigation.
  4. Click “Create your own application” in the top navigation. A pane should open to the right of the window.
  5. Give your application a name (for example “MASV”) and select “Integrate any other application you don’t find in the gallery (Non-gallery)”.
    Create a new application in Azure Active Directory
  6. Click “Create” on the bottom left of the pane. After a moment you should be redirected to your new enterprise application’s overview page.
  7. Click “Single sign-on” in the left sidebar.
  8. Select “SAML” as the single sign-on method and continue to the next section.

Import MASV’s Metadata

After completing the last section, you should now be presented with the SAML configuration page. You should also have your MASV team’s SSO configuration page open.

  1. Start by clicking the “Edit” button in the “Basic SAML Configuration” section. A pane should open on the right side of the window.
    Basic SAML configuration Azure AD
  2. Under “Identifier (Entity ID)” click “Add identifier”. A new row should be created.
    Add identifier Azure AD
  3. Copy your “SP Entity ID” value from your MASV team’s SSO configuration page and paste it into the text box in the new row.
    Add identifier Azure AD complete
  4. Under “Reply URL (Assertion Consumer Service URL)” click “Add reply URL”. A new row should be created.
  5. Copy your “ACS URL” value from your MASV team’s SSO configuration page and paste it into the text box in the new row.
    Azure AD reply URL
  6. Click “Save” on the top navigation and proceed to the next section.

Mapping Attributes in Azure

Now that MASV’s SP metadata has been imported into your Azure app, we need to map your Azure user attributes to fields MASV can understand.

  1. Click the “Edit” button to the right of the “Attributes & Claims” section on the SAML configuration page. You will be redirected.
    Azure AD SAML attributes and claims
  2. You should now see a page which looks something like this:
    Azure AD SAML attributes and claims complete
  3. Start by clicking the three dots next to each claim under “Additional claims” and delete them all.
    Additional claims
  4. Create three new claims according to the following table using the following steps:
    Name Value Required
    email user.userprincipalname Yes
    name user.displayname Yes
    saml_subject "azure-ad” Yes
    role member, admin, guest, cloud_connect_config No (default is member)
    1. Click “Add new claim”. You will be redirected.

    2. Reference the above table and enter the name value in the “Name” field.

    3. Leave “Namespace” empty

    4. Reference the above table and enter the value in the “Source attribute field”.

      When you start typing the value, auto-completion will start suggesting values, we recommend using the suggestions to ensure everything is selected correctly.

    5. Click “Save”

  5. After adding the new claims, your claims table should look like this:
    Required claim
  6. Claim mapping is now complete, continue to the next section.

Importing Your Azure Application’s Metadata in MASV

Navigate back to your Azure application’s Single sign-on settings page. To get there from the main Azure page, do the following:

  1. Click “Azure Active Directory” in the sidebar.
  2. Click “Enterprise Applications” in the sidebar.
  3. Select the application you created and configured in previous sections.
  4. Click “Single sign-on” in the sidebar.

Once there, continue with the following steps:

  1. Scroll down to the “SAML Certificates” section and copy the “App Federation Metadata Url” value.
    Azure AD SAML certificate example
  2. Go to your MASV team’s SSO configuration page and paste the URL you copied into the “Metadata URL” input under “SAML Configuration”.
  3. Click “Save” in the bottom right.
  4. Your SAML Configuration should now be showing as active, and the raw XML metadata downloaded from your Azure application should be displayed in the “Raw Metadata” field.
    SAML configuration-1
  5. You should now see a “SSO Name” field at the top of the right side of the page. This is where you choose the name your users will use to log into your team with SSO. For example, if you entered masv, your users would enter masv as the SSO Name on the SSO login page.
  6. Once you have chosen and entered an SSO name, click the switch for “Enable SSO.” 
    You will see an option to enable or disable “Require login with SSO.” If you disable this, you can allow users to sign into MASV with SSO or email authentication.  
  7. Click “Save” once again. SSO configuration is now complete.

Assign users to your application

In order for users to sign into MASV with your SSO configuration, you need to assign users to your application within Azure. Refer to Microsoft’s documentation for steps.

Try it out

Navigate to MASV’s SSO sign-in page and enter the SSO name you chose for your team. When you click “Sign in”, you should be redirected to a Microsoft login page to authenticate. Once you’ve finished authenticating, you should be redirected to MASV.

If you are redirected to the MASV dashboard, great! You can continue using MASV as usual. If you are redirected to a screen prompting you to accept an email invitation, please do so and then sign back in with SSO.