To correctly setup SAML SSO, the Identity Provider (IdP) and the Service Provider (SP) need to know about each other. In this particular case, the process will be SP initiated. In other words, the SP (WebViewer) will request authentication by redirecting the user to the IdP (Azure AD).

Once the user is done with the authentication process, they will be redirected back to the SP site.

Summary

Here is a quick list of all the steps needed to set up SAML SSO with Azure AD for a new customer:

Pre-setup (Signifikant):
- Build SP metadata for the WebViewer
- Send metadata file to customer
Azure setup (Customer):
- Create new enterprise application and enable SAML SSO
- Upload SP metadata
- Add a group claim to get user group in SAML response
- Download IdP metadata file
- Send file to us to finish WebViewer setup
- Provide us with the list of all user groups in Azure that should be used in WebViewer
WebViewer setup (Signifikant):
- Create a new Web.config transform file for the customer and use IdP metadata to set up endpoints and certificate
- Create a new customization of profile.config to configure role mappings based on user groups from Azure
- Test and deploy

If multiple environments need to be set up, then the entire list must be run through for each. Different environments will have different metadata for both SP and IdP.

Build SP metadata

This step is optional but recommended. It will make the setup in Azure faster and less error-prone.

You can use the following tool to generate your SP metadata: https://www.samltool.com/sp_metadata.php

Whatever the tool you use, you need to set up three things:

EntityId: Uniquely identifies the SP (you can use the hostname, for example)
Attribute Consume Service Endpoint: This is where the user will be redirected upon successful login
Single Logout Service Endpoint: Where the user is redirected after logout

In the following screenshot, you can find an example setup:

The parts highlight in red are the only things you need to change depending on the customer/environment.

That is all we need for this part. Signifikant does not use its own certificate, so we can just go ahead and generate the metadata at the bottom:

Even if the customer is using multiple site for the WebViewer, you only need to set up SAML for one site (the main site). This means all SAML requests will be redirected to this one site, regardless of where they were made from. But this is not a problem, since the WebViewer is able to correctly redirect the user back to its original website.

Example:

SAML is set up on site A
User goes to site B and attempts to sign in
The sign-in process operates in Azure and if successful, the user is redirected to site A
Site A redirects the user back to site B
The user can continue normally

This feat is possible because a RelayState is sent to Azure when the user signs in/out.

Identity Provider setup (Azure AD)

Go to Azure AD
Register a new enterprise application
Configure Single Sign On
Import an XML metadata file OR manually fill in the Identifier and the Reply URL fields with the information of the SP:
Edit the Attributes & Claims
Click on Add a group claim at the top
Click Save
Go back to the previous page and Download the Federation Metadata XML for the next step

Service Provider setup (WebViewer)

In order to configurable SSO in the SP, there are two files that must be changed.

The first one is the Web.config file:

<appSettings>
    <add key="Saml2:AzureEnabled" value="true" />
    <add key="Saml2:EntityId" value="http://example.com/" />
    <add key="Saml2:EndPoint" value="https://login.microsoftonline.com/{tenantId}/saml2" />
    <add key="Saml2:ReturnRedirect" value="http://example.com/en/AtlasCopcoPT/Account/SamlRedirect" />
    <add key="Saml2:Certificate" value="PASTE_CERTIFICATE_HERE" />
</appSettings>

There are five important keys to set:

Saml2:AzureEnabled: should be set to true
Saml2:EntityId: should be set to your SP identifier
Saml2:EndPoint: SSO endpoint in Azure to redirect the user to for the authentication step
Saml2:ReturnRedirect: SP app endpoint to redirect the user to once authentication is done
Saml2:Certificate: The X.509 certificate in Azure (available in the Federation Metadata XML)

The second one is profile.config:

<AuthenticationEnabled>true</AuthenticationEnabled>
<AuthenticationRequired>false</AuthenticationRequired>
<AuthenticationProvider>
  <SamlAzureAuthenticationProvider apply-groups-enabled="true" apply-groups="AD,Profile">
    <AttributeMappings>
      <!-- Default claims -->
      <Attribute name="nameid" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" />
      <Attribute name="email" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" />
      <Attribute name="name" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />
      <Attribute name="firstname" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" />
      <Attribute name="lastname" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" />
      <Attribute name="groups" value="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups" />
    </AttributeMappings>
    <GroupMappings>
      <!-- Example groups -->
      <Group name="Admin" object-id="5beade97-a971-4a17-a615-ab4a52b182a9" />
      <Group name="User" object-id="e0d1a3cf-991e-44b3-978f-53ca3138c877" />
      <Group name="MyGroup" object-id="e5853dad-88ca-44f1-bdda-d0b66dd275ab" />
    </GroupMappings>
  </SamlAzureAuthenticationProvider>
</AuthenticationProvider>

The SamlAzureAuthenticationProvider includes two groups of settings:

Attribute mappings: Map claims in the SAML response to the corresponding user properties
Group mappings: Map group IDs in the SAML response to local groups in the application

Attribute mappings

To correctly define an attribute mapping, you need to create an Attribute element and provide two values. The first value is the name and can have one of the following values: nameId, email, name, firstName, lastName. The second value is, well… value and it is the claim specification itself.

Group mappings

To define a group mapping, you first need to know the Object IDs of your groups within Azure AD. Such information can be found in Azure when showing details of groups. Once you have the Object ID of a group, you can set it as the object-id value in your group mapping. The other value you need to set is the name, and it needs to match a valid group present in your permissions.config file.

Possible issues

Redirect requests to not reach the WebViewer

If the user is able to perform their actions in Azure but do not get properly redirected to the WebViewer, it could be because of one measly trailing slash at the end of your URL. It sounds stupid, but it is the truth. I found this the hard way. The presence/absence of this slash in the configuration could be the reason that redirect does not work.

If you run into this kind of problem, try to tweak the Web.config file and see if that fixes it.

Useful links:

Networking issues

If SAML SSO works locally but not on the customer environments, then it could be because of networking issues. Especially, if there is Web Application Firewall (WAF) set to Prevention mode, or if some characters are banned from URLs, then it is likely that SAML requests will get blocked.

SAML could be partially or completely blocked, so it is important to test the entire login/logout process to make sure that networking is not causing any issue. If WAF turns out to be blocking SAML, then the customer will have to tweak their settings to allow SAML requests to be made. That is the only fix found so far.

Issues have been encountered in the past with the logout process because of the following encoded characters in the URL: //.