Before starting the integration process, you must have requested, and been approved for, an Onshape Enterprise account or trial, and have an Onshape Enterprise domain name.

An example of an Enterprise domain name might be: MyCompanyName.onshape.com.

You can use only one (single sign-on) SSO provider at a time.

This configuration process might fail without parameter values customized for your organization. Use your Microsoft Azure AD single sign-on dashboard to add Onshape as an application and record the values that are specific for your organization. You need those values for the following procedure.

Onshape signs all outgoing SAML certification requests. You are not required to upload any certificates (for example, a SAML signing certificate), except in the case of ADFS integration because ADFS validates incoming SAML requests.

Add Onshape to your Azure AD single sign-on account

To enable single sign-on for your company, you must first add the Onshape application to your Azure AD single sign-on account:

  1. Sign in to the Microsoft Azure portal. Click the menu icon at the top left corner to open the left side navigation pane.

    Signing into the Microsoft Azure portal

  2. Select Azure Active Directory in the navigation pane.

    Selecting the Azure Active directory from the navigation menu on the left

  3. Select Enterprise applications in the new navigation pane that opens on the left.

    Selecting Enterprise applications from the navigation menu on the left

  4. At the top of the All applications page, click New application.

    Example selecting New application from the Enterprise applications page

  5. On the Browse Azure AD Gallery page, search for Onshape in the Search application field. Then click the Onshape button.

    Example searching for Onshape in the Browse Azure AD Gallery page

  6. The Onshape application pane opens on the right. Click the Create button at the bottom of the pane.

    Selecting and opening the Onshape application

    Microsoft Azure creates the new application for you. Be aware this can take a few seconds to set up.

  7. Once the app is created, click the 2. Set up single sign on box.

    Selecting the Set up single sign on option

  8. Since Onshape supports only SAML authentication, click the SAML box.

    Clicking the SAML option on the Single sign-on page

    If the Save single sign-on setting opens, click Yes.

    Clicking Yes to Save the signle sign-on setting

    The SAML-based sign-on page opens.

SAML configuration

  1. In the User Attributes & Claims subsection, click Edit at the top right corner of the box.

    Clicking to edit the User Attributes & Claims on the SAML-based Sign-on page

  2. In the User Attributes & Claims page that opens, double-click the companyName claim.

    Selecting the CompanyName claim on the User Attributes & Claims page

  3. Enter your domain name prefix into the Source attribute field. For example, if your Onshape enterprise name is Fishbowl.onshape.com, enter Fishbowl into the field. Once entered, you need to additionally click on the entry below the field (as shown by the cursor in the image below).

    Example of managing a claim

  4. Click Save.

    Example saving the claim from the Manage claim page

  5. Click X at the top right corner to close the page.

    Closing the User Attributes & Claims page

  6. If you are asked if you want to Test the single sign-on, select No, I'll test later.

    Clicking No I'll test later button on the SAML-based Sign-on page

  7. The SAML-based Sign-on page is displayed again. Your page should look similar to the image below.

    Example showing the completed claims

  8. Scroll down the page to subsection 3 SAML Signing Certificate. At the bottom of this subsection, click the "Federation Metadata XML" download link. This XML file is used later in the Single sign-on configuration process.

    Downloading the Federation Metadata XML file

  9. A message appears in the top right upon successful download of this file. Click X to dismiss the message.

    Closing the completed download notice

Set up users and groups

  1. In the left navigation pane, select Users and groups.

    Selecting Users and groups from the navigation on the left of the SAML-based Sign-on page

  2. The Users and groups page appears. Click Add user/group.

    Clicking the add user/group button from the Users and groups page

  3. The Add Assignment page opens. On the left, click Users - None Selected.

    The Users pane opens on the right. Search and then select the Users you would like to invite. Each user is moved into the Selected Items pane subsection below. Once all selected members are listed in this pane, click the Select button.

    Assigning users to the user group/team

  4. Click Assign.

    Clicking the Assign button on the Add Assignment page

  5. The Users and groups page appears with the new users.

    The new users added to the Users and groups page

    At this point, you can leave the Azure portal and open your Microsoft active directory application dashboard.

    Example of the Microsoft active directory application dashboard

Upload the XML configuration file in Onshape

  1. Sign in to your Onshape enterprise account, using your specialized domain name, as an administrator. Select Enterprise settings from your account.

    Selecting my account: Enterprise settings

  2. Select Authentication from the left navigation menu.

    Selecting Authentication from the left side navigation panel

  3. In the Single sign-on (SSO) subsection, click the Configure SSO provider button.

    Clicking the Configure SSO provider button on the Authentication page

  4. The Create SSO provider dialog opens. In the Name field, enter a three-letter name, such as MSA. In the Provider type drop-down, select Microsoft Azure. Then click the Upload configuration file button.

    Create SSO provider dialog

  5. Locate and select the XML file you downloaded previously, and click Open.

    Opening the XML metadata file

  6. Click OK.

    Clicking OK to finalize the creation of the SSO provider

  7. The file is uploaded. A notification appears when the upload is completed.

    Receiving a notification that the XML file was successfully uploaded

    8. You can disable the typical Onshape password sign-in for your users and show only the SSO provider sign-in prompt for the Onshape URL. However, do not perform this step at this time. Make sure you can sign in to Onshape yourself (as administrator) before disabling this additional sign-in option. You can return here later, once you verify you can sign in through your SSO provider.

    Choosing to enforce signing in to Onshape via SSO also results in users not being able to sign in to non-enterprise domains directly, such as cad.onshape.com.

  8. Sign out of both your Onshape and Microsoft accounts. Be sure to do a hard refresh of both accounts. When you reach the Onshape sign-in page once again, the page has a new Sign in link at the bottom, for your Single sign-on provider.

    Signing into Onshape using the Sign in with Microsoft (SSO) button

In order to sign in to Onshape, administrators must provision their users (in their single sign-on account) to use the Onshape application.

Troubleshooting

If you see the following error:

Possible error message when signing in

Close all tabs, fully sign out, and sign back into Microsoft.

Sign into Onshape again.

Be aware that the "test connection" button in the AD admin panel does not work.