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: SAML Service Provider (SP) Metadata XML Builder | SAMLTool.com

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)

There are two different ways of configuring SAML in the WebViewer:

Using only profile.config (5.3 and later)
Using Web.config and profile.config (before 5.3)

Configuring via `profile.config` (v5.3 and onwards)

With the introduction of the MultiAuthenticationProvider in version 5.3, SAML configuration has been revamped and everything can now be configured directly in profile.config or a snippet file:

<AuthenticationProvider>
  <MultiAuthenticationProvider default-provider="AssertDB">
    <SignifikantAuthenticationProvider provider-identity="AssertDB" provider-name="UserNameAndPassword" view-name="">
      <Trigger selected-provider-identity="AssertDB"/>
    </SignifikantAuthenticationProvider>
    <SamlAzureAuthenticationProvider provider-identity="saml2" provider-name="Domain" apply-groups-enabled="true" apply-groups="AD,Profile">
      <Trigger selected-provider-identity="saml2"/>
      <Setting>
        <EntityId>https://example.com/</EntityId>
        <EndPoint>https://login.microsoftonline.com/{tenantId}/saml2</EndPoint>
        <ReturnRedirect>https://example.com/en/{site}/Account/SamlRedirect</ReturnRedirect>
        <Certificate>PASTE_CERTIFICATE_BASE64_HERE</Certificate>
      </Setting>
      <AttributeMappings>
        <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>
        <Group name="Admin" object-id="1131fba2-a1da-4075-bfbc-be536696a677"/>
        <Group name="Editor" object-id="e32898a3-436f-46fe-bfa4-daf737e030de"/>
      </GroupMappings>
    </SamlAzureAuthenticationProvider>
  </MultiAuthenticationProvider>
</AuthenticationProvider>

Configuring via `Web.config` (before v5.3)

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

No groups applied

If user is able to login but does not get any group, it could be because of misconfiguration with either:

WebViewer (SP = Service Provider)
Azure (IdP = Identity Provider)

The following log line from AssertWeb.log is typically associated with this issue:

One way to troubleshoot if the issue is with the SP or IdP is by examining the SAML response originating from Azure. This can be done using the Developer Console in your browser (Networking tab) but a better solution is to install the SAML-tracer browser extension:

This extension will make it easier to visualize the HTTP requests related to the SAML process.

Make sure to click/open the extension so that it starts recording HTTP traffic. The only part we are interested in is whenever you have successfully logged in to Azure and it redirects you to the WebViewer. Around that time, you should be able to spot a line in SAML-tracer which looks like POST https://.../Account/SamlRedirect. It is easy to spot thanks to the “SAML” orange badge at the end of the line.

If you click on the line, you should get a window at the bottom with different tabs. Click on the “Summary” tab and you should see something similar to this:

On the above screenshot, we can see that the summary contains the groups claim. Check your SAML response:

If the groups claim is missing then it means that Azure is not returning the groups properly
If the groups claim is present then it means the issue is with the WebViewer, likely misconfiguration

Refer to the appropriate setup parts above in this document for checking that the configuration is correct.

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 configured SAML redirect URL 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: //.

Signifikant Knowledge Base

SAML SSO with Azure AD

Analytics

Summary

Build SP metadata

Identity Provider setup (Azure AD)

Service Provider setup (WebViewer)

Configuring via `profile.config` (v5.3 and onwards)

Configuring via `Web.config` (before v5.3)

Attribute mappings

Group mappings

Possible issues

No groups applied

Redirect requests to not reach the WebViewer

Networking issues

Related content

SAML SSO with Azure AD

Summary

Build SP metadata

Identity Provider setup (Azure AD)

Service Provider setup (WebViewer)

Configuring via profile.config (v5.3 and onwards)

Configuring via Web.config (before v5.3)

Attribute mappings

Group mappings

Possible issues

No groups applied

Redirect requests to not reach the WebViewer

Networking issues

Related content

Configuring via `profile.config` (v5.3 and onwards)

Configuring via `Web.config` (before v5.3)