SAML-based Single Sign-On Setup for Shelf with Microsoft Entra ID: How-to Guide

Introduction

This document’s goal is to walk you through the whole process of configuring the Single Sign-On (SSO) method for Shelf Application using Microsoft Entra ID (formerly Azure Active Directory (Azure AD)). The Single Sign-On authorization method is expected to help you avoid any manual entry of your username and password to sign in to Microsoft Entra ID. This feature provides your users easy access to your cloud-based applications without needing any additional on-premises components. 

In our case, the properly configured SSO via Microsoft Entra ID is expected to ensure a seamless access to the Shelf App and its full use in accordance with your business needs.

After reading this guide, you will be able to: 

If you have any questions regarding this document or if you need any assistance or support in its relation or the Shelf App and its settings, please contact Shelf’s Technical Support at support@shelf.io or within the Shelf App. 

Creating the Shelf App in Microsoft Entra ID

To create the Shelf App in Microsoft Entra ID, follow the below steps.

1. Open the Microsoft Azure Portal and log in to your account. When on the Azure Portal’s main page, search for the Enterprise applications service by starting to enter its name in the search field on top of the page. The search-as-you-type feature is supported here.

Figure 1. Searching for enterprise applications on Azure

2. Once the needed service is found, select it to navigate to the needed page - Enterprise applications | All applications - of the Azure Portal. 

3. When on this page, find and click the + New application button to start creating your new application on the Azure portal.

Figure 2. Viewing the Enterprise applications page

4. On the page that appears, click the + Create your own application button.

5. In the pane that appears in the right part of the window, enter the name of the application as “Shelf (SAML)” and select the Integrate any other application you don't find in the gallery (Non-gallery) checkbox. Once done, click the Create button.

Figure 3. Creating new application

6. Once the application has been created, you are redirected to the application page where you can overview and/or configure various application’s parameters. In the left-side panel on this page, find and select the Single sign-on option to proceed.

Figure 4. Viewing the Application page

7. On the page that appears, select the SAML option card as your SSO method.

Figure 5. Selecting the SSO method

8. Click the Edit button in the Basic SAML Configuration card. 

   Figure 6. Accessing the basic SAML configurations

9. Copy the required values from the respective Shelf SSO settings fields as shown in Figure 16. These values must be Single sign on URL and Audience URL (Identifier). Paste them into the respective fields of the Basic SAML Configuration pane of the Azure Portal as shown in the figures below.

Figure 7. Filling in the Basic SAML Configuration fields

10. Once the new Basic SAML Configuration values have been successfully saved and you see the confirmation message, close the Basic SAML Configuration pane and go to the Attributes & Claims card and click the Edit button there.

    Figure 8. Viewing SAML configuration saving confirmation

    

    Figure 9. Starting editing Attributes and Claims

    
    

11. On the Attributes and Claims page that appears, add additional claims such as “emailaddress”, “givenname”, “name” and “surname” with actual attributes based on your AD user’s profile.

    Figure 10. Editing Attributes and Claims

12. Once done, navigate back to the SAML-based Sign-on page of Azure Portal using breadcrumbs. On this page, locate the SAML Signing Certificate card and download the Base64 certificate by clicking the respective Download button as shown in the figure below. Save the downloaded certificate on your computer following the OS prompt

    Figure 11. Downloading base64 certificate

    
    

13. Once done with the certificate downloading and saving, navigate to the Set up Shelf (SAML) card. Copy the values sitting in the Login URL, Microsoft Entra Identifier, and Logout URL fields and save them to any text file for further use. You will later need them, as well as the downloaded Base64 certificate, at the next configuration step, that is when enabling the Single Sign-On feature in Shelf.  

    Figure 12. Finding and copying Microsoft Entra ID and Login/Logout URLs in Azure

    
    

14. Go to the Users and groups submenu in the left-side panel. On the Users and groups page that appears, click the +Add user/group button and assign users or groups, which need to have access to Shelf via Microsoft Entra ID SS

Figure 13. Adding user/group

Once all Basic SAML Configuration settings have been successfully configured, you can now proceed to configuring the relevant settings on the Shelf side.

Enabling Single Sign-On in Shelf

1. Log in to your Shelf account and navigate to the Admin Panel. Once it opens, find and select the Single Sign-On option. It navigates you to the SSO page where you need to check if the Enable SSOcheckbox is selected. If it is not, select it as shown in the figure below.
   

   Figure 14. Checking the SSO in Shelf

2. Make sure to select the proper SSO provider option, Custom SAML, in the SSO Providerdropdown list box. Mind the information provided in the warning in the following figure.
   

   Figure 15. SSO provider note

3. Make sure that all SSO settings fields are populated.
   

   Figure 16. Viewing Shelf SSO settings

4. Navigate to the SSO IDENTITY PROVIDER SETTINGS block in Shelf and fill in all fields shown in the figure below with the relevant data from the Set up Shelf (SAML)card in Azure.
   

   Figure 17. Populating the SSO provider parameters in Shelf

   • When populating the fields, follow their mappings explained in Table 1 below.

     • Table 1. Mapping of SAML-based SSO parameters in Azure with SSO Identity Provider parameters in Shelf

       SSO parameter in Azure	SSO parameter in Shelf
       Login URL	IdP SSO Sign-on URL
       Microsoft Entra Identifier	SSO Issuer (IdP Entity ID)
       Logout URL	N/A
       Certificate (Figure 11)	X.509 Certificate

5. Once all the needed fields are populated and the certificate is inserted, click the SAVEbutton and then confirm your choice by clicking the respective button in the confirmation pop-up window.
   

   Figure 18. Saving the SSO configuration in Shelf

6. Once you have successfully completed the above steps, it means that the Single Sign-On feature becomes enabled in Shelf. Its result is that all your users are forced to log in to the Shelf App using the SSO method. Note that as soon as you have confirmed your choice, all users are logged out from the Shelf App, with the admin that has configured and enabled this SSO method staying logged-in only.
7. After the SSO setup is over, your users can log in to Shelf using Microsoft Entra ID from the standard login page at https://login.shelf.io. See the section below for details.

Logging in to Shelf via Microsoft Entra ID SSO

To be able to log in to your Shelf account via Microsoft Entra ID, you need first to log out of Shelf. After that, you will see the following screen: 

Figure 19.Viewing the Shelf login screen with the SSO login option

Now, click SIGN IN WITH SSO and log in using your Microsoft credentials to access your Shelf account.

Figure 20. Proceeding to Microsoft login page to log into Shelf via Azure AD

Once the SSO feature has been enabled in Shelf and you are able to log in to your Shelf account via Microsoft Entra ID, you can see that the new tab—SCIM—appears next to the SSO tab on the Single Sign-On page in Shelf. In this tab, you can now configure your SCIM provisioning. For learning how to do that, go to the Enabling SCIM section below.

Figure 21. Viewing the SCIM tab data on Shelf’s Single Sign-On page

Enabling SCIM

1. When on the Single Sign-On page in Shelf’s Admin Panel, select the SCIM tab. Then in the window that appears, select the Enable SCIM checkbox and click the SAVEbutton. In order to make the changes become enabled, reload the page
   

   Figure 22. Enabling SCIM in Shelf

2. Once the settings are successfully saved, go to your Shelf App on Azure Portal and, in the left-side panel on the Shelf (SAML) | Overview page, select the Provisioning option. On the Provisioning page that appears, click the GET STARTEDbutton.
   

   Figure 23. Accessing Shelf App’s Provisioning page on Azure Portal

3. On the page that appears, in the Provisioning Mode dropdown list box, select the Automatic option. Fill in the required Tenant URL* and Secret Tokenfields in accordance with the figure and table below.
   

   Figure 24. Configuring the provisioning parameters

   • Table 2. Provisioning configuration fields

     Field name	Description
     Tenant URL*	Paste the data from the SCIM Base URL field of the SCIM tab in Shelf.
     Secret Token	Paste the token copied from the SCIM Bearer Token field of the SCIM tab in Shelf.

     Once the fields are populated, click the Test Connection button. If no error messages are displayed, it means that the connection has been successfully established. Click the Save button as shown in the figure above. 

4. Once the settings have been saved on Azure Portal, the respective message is displayed.
   

   Figure 25. Success message

5. Now, go back to your Shelf App’s Provisioning page on Azure Portal, find and select the Edit attribute mappingsbutton to start changing the actual configuration for mappings.
   

   Figure 26. Initiating mappings editing

6. On the page that appears, switch the Provisioning Status toggle on and then click the Savebutton.
   

   Figure 27. Activating the provisioning status

7. Once the provisioning status has been activated, you need to change the mappings accordingly. To do so, click the Mappingsfield on the same page and make sure to configure the required parameters in accordance with the below figures.
   

   Figure 28. Configuring attribute mappings

8. The mappings for the Provision Microsoft Entra ID Groupsitem shall be configured as follows:
   

   Figure 29. Configuring mappings for Provision Microsoft Entra ID Groups

9. The mappings for the Provision Microsoft Entra ID Usersitem shall be configured as follows:

Figure 30. Configuring mappings for Provision Microsoft Entra ID Users

Configure User Plan Types for Shelf (Optional)

1. Go to the Provisioning page on the Azure Portal. For this purpose, go to the Enterprise applications section, select your SAML-enabled Shelf App instance, and then in the left-side panel on the Shelf (SAML) | Overview page, select the Provisioningoption.
   

   Figure 31. Accessing the Provisioning section of your Shelf App instance

2. Once on the Provisioning page, find and select the Edit attribute mappingsoption.
   

   Figure 32. Accessing the attribute mappings

3. Next, on the page that appears, find and select the Mappings option to open the dropdown list and select the Provision Microsoft Entra ID Usersoption there. 
   

   Figure 33. Accessing the Microsoft Entra ID users mappings

4. On the Attribute Mappings page that opens, scroll down and select the Show advanced optionscheckbox.
   

   Figure 34. Access advanced mapping options

5. Scroll down the opened section and click the  Edit attribute list for customappssooption. 
   

   Figure 35. Accessing the attribute list editing mode

6. In the window that appears, scroll down and add the shelfPlanTypeId value in the first empty field of the Name column. Make sure that it has String in the respective Type column field. Once done, click the Savebutton.
   

   Figure 36. Adding a new attribute to the list

7. Once the new attribute is successfully saved, you are redirected to the Attribute Mappings page where you need to click the Add New Mappinglink button. 
   

   Figure 37. Adding a new mapping

8. In the Edit Attributepanel that appears in the right part of the window, fill in the fields as shown in the figure below.
   

   Figure 38. Filling in the new mapping attribute fields