How to Setup Okta SSO

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

Setting up 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
    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.
  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 step.

Creating a SAML Application in Okta

  1. Ensure you are logged into your admin page in Okta
  2. Navigate to “Applications” using the side navigation
  3. Click “Create App Integration”. A modal should open up
  4. Select “SAML 2.0” as the integration type
    Create a new Okta app integration
  5. You should be redirected to the integration setup page. Give your application a name. For example, “MASV”.
    Create SAML integration Okta
  6. Click “Next”

  7. You should now be prompted to enter the following information:

    1. Single sign-on URL
    2. Audience URI (SP Entity ID)

    You must now copy the following values from your MASV SSO settings page into the correct Okta fields.

    1. Copy the “ACS URL” value from your MASV SSO settings page and paste it into the “Single sign-on URL” field in Okta.
    2. Copy the “SP Entity ID” value from your MASV SSO settings page and paste it into the “Audience URL (SP Entity ID)” field in Okta.
  8. Select “Unspecified” as the value of “Name ID format”

  9. Select “Okta username” as the value of “Application username”

  10. Select “Create and update” as the value of “Update application username on”

  11. Your SAML Integration creation page in Okta should now look something like this:

    Create SAML integration step 2 Okta

Scroll down to find the “Attribute Statements” section. You need to map your Okta user attributes to specific fields so that MASV can correctly provision your users.

You will need to add two new empty fields, and then fill them out according to this table:

Name Name format Value
saml_subject Unspecified

Must be

okta

Be sure to enter this value manually!

email Unspecified
user.email

(select from suggestions)

name Unspecified
user.firstName

(select from suggestions)

Your attribute statements table should now look something like this:

Attribute statements

  1. Leave the “Group Attribute Statements” section empty
  2. Click “Next”
  3. On the next screen, select “I’m an Okta customer adding an internal app”Create SAML integration Okta step 3
  4. Click "Finish"

Importing Okta’s Metadata Into MASV

After completing the previous step, you should now be looking at your application’s information page. It looks something like this:

Okta sign on settings

You must now find the XML version of Okta’s metadata and import that into MASV. You can do so with the following steps:

  1. Scroll to the bottom of your applications page. On the right sidebar, you should see a button labelled “View SAML setup instructions”. Click this button.
    Okta SAML setup
  2. You should be redirected to a page titled “How to Configure SAML 2.0 for <application name> Application”. Scroll down until you see the “Optional” heading. The text field under this section contains the raw XML version of Okta’s metadata. Copy this to your clipboard.
    Okta IDP metadata
  3. Go back to your MASV team’s SSO configuration page and look for the “Raw Metadata” field on the right side of the screen. Paste the XML metadata you copied from Okta into this field.
    Okta Raw Metadata
  4. Click “Save” in the bottom right. Your SAML Configuration should now be marked as “active”.
  5. You should now see an “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

You must now assign your newly created Okta applications to your users. Okta has a guide for this here. Users your application is not assigned to will be unable to log into MASV with SSO.

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 Okta 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 normal. If you are redirected to a screen prompting you to accept an email invitation, please do so and then sign back in with SSO.