To make it easy and secure for everyone in your organization to access MURAL, you might choose to implement SSO (single sign-on). SSO allows members to authenticate into MURAL with their company’s network credentials.

SSO works by forming a relationship between two parties: a Service Provider (SP) and an Identity Provider (IdP). In our case, MURAL is the SP. So, to configure SSO, you need to set up a connection between MURAL and an IdP so MURAL can accurately verify your collaborators’ identities.

There are a number of IdPs to choose from. Two of the most common IdPs are Microsoft Azure Active Discovery and Okta. Since these are widely used, we offer dedicated integrations to set up SSO if you’re using them.

To use Azure Active Discovery as an Identity Provider, follow our Azure instructions.

To use Okta as an Identity Provider, follow our Okta instructions.

If you’re using an IdP not mentioned above, this article walks you through how to set up a custom SSO configuration.

Configuring SSO is an exchange of information between MURAL and your IdP. We provide all the information you need from MURAL in a metadata file. You can download the file here or from your company dashboard.

To download MURAL’s metadata from the company dashboard:

With MURAL’s metadata in hand, you can now configure your IdP. Each IdP requires different information and the steps to input that information also varies. Still, you’ll find everything you need in the metadata file you just downloaded. Most IdPs require these common values:

Within your IdP, you also need to configure a few specific attributes for SSO to work properly with MURAL. The required attributes are:

If you need help at any point during this step, refer to your IdP’s documentation.

Once you finish configuring your IdP, you should have the option of downloading a version of their metadata in an XML file. This serves the same purpose as the metadata you downloaded from MURAL, except now you’re going to input the IdP’s information into MURAL.

Remember, every IdP is different. So, if you need help downloading the IdP’s metadata, refer to their documentation. And once you have the metadata, move on to the next section.

With your IdP configured, you’re ready to return to MURAL. You’ll use your IdP’s metadata to configure MURAL as the service provider. There are two elements to this configuration:

To upload your IdP’s metadata, you have two options. You can upload the entire metadata file (which is an XML file) or you can open the metadata yourself and input the needed details manually.

To configure MURAL as the service provider by uploading an XML file:

If uploading an XML file is unsuccessful, you can also complete this form manually. If this sounds complicated, don’t worry. You can still find the necessary information in the metadata file you downloaded from your IdP. You’ll just need to open it in your browser or a text editor to view it.

To configure MURAL as the service provider manually:

Now, you’re ready to add claim mapping. Claim mapping is like the final piece of the bridge you’re building between MURAL and your IdP. Let’s say MURAL speaks one language and your IdP speaks another. Claim mapping acts as the translator between them.

With claim mapping, you can take attributes from an IdP and assign them to attributes within MURAL. For example, one IdP might refer to an individual’s email as emailAddress while another might refer to it as simply email. This is called an attribute’s name. And MURAL needs to know that name so it can correctly interpret information from an IdP.

You’ll find the name of each attribute in the same XML metadata file you downloaded from your IdP earlier. These names are in lines of code that look like this:

<saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">

In this example, you can see that the IdP refers to someone’s email address as just email. That’s found here: Name=”email”.

Keep in mind that each XML file looks slightly different. So, be prepared to look through the file until you find what you need. To help your search, here are the attributes you need to configure in MURAL:

While the External ID is optional, it can be a good idea to include it. On the IdP’s end, the external ID could be a UPN or an employee ID number. Whatever the value, it serves as a unique identifier in case a member’s email changes. For example, if someone’s email changes because of a marriage, the external ID can still identify them so they maintain access even if they’re using a different email. If this happens, MURAL automatically updates their member account to reflect their new email address.

Once you’ve found the names of these attributes in your IdP’s XML file, you’re ready to set up claim mapping in your company dashboard.

To configure claim mapping in MURAL:

A successful simulated test of your SSO configuration is required before you can save it. You can do this right from the SSO page on your company dashboard.

To test your SSO configuration:

If your test is not successful, review your metadata entries in both MURAL and your IdP to ensure they are correct. Then, run your test again. If you’re unable to fix the issue, reach out to support@mural.co for assistance.