Shelf Single Sign-On Configuration Guide for Custom SAML with SCIM


Document Version History 

Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the document.

28 Jan 2022

Expired

1.1

Shelf

Changes and updates to the document to bring it to compliance to Shelf’s documentation standards. 

13 Jul 2022

Active






















Document Purpose 

This document describes the required steps to enable SSO to Shelf via Custom SAML + SCIM.

There are four configuration steps to enable the Custom SAML SCIM integration:
  1. Create the Shelf App in any SSO provider (we will show it on OneLogin)
  2. Configure SSO in Shelf App
  3. Enable Shelf SCIM settings and configure the created Shelf App on OneLogin
  4. SCIM provisioning configuration on OneLogin

These steps are described in detail below. In case you require assistance, please don’t hesitate to contact us at support@shelf.io or via the Live Chat on our Website or inside of the Shelf App.




Creating the Shelf App on OneLogin

Configure the Shelf App

  1. Open your OneLogin Home page.

  2. In the right upper corner, click the Administration link button.
  3. In the menu toolbar on top of the page, select the Applications option.
    This reveals the list of your apps.
  4. Click  the ADD APP button.
  5. Select the connector named SCIM Provisioner with SAML (SCIM v2 Core) from the list of available options.
  6. Add a name for the app (e.g. “Shelf App”) and upload the icons provided by Shelf. Once done, click SAVE.

Once you have configured the Shelf App and saved its configurations, you can proceed to the next step, which is copying the Single Sign-On data to Shelf. 


Copy SSO information and paste it to Shelf

  1. Open the SSO tab in the sidebar panel. Take note of the values for:

    • Issuer URL

    • SAML 2.0 Endpoint (HTTP)

    • SLO Endpoint (HTTP)

2. Click the View Details button under the X.509 Certificate section.


3. Click the Download button and save the certificate.

4. Save the details mentioned below, as they are to be pasted in Shelf via the Admin Panel using the SSO section:
  • X.509 certificate
  • Issuer URL
  • SAML 2.0 Endpoint (HTTP)
  • SLO Endpoint (HTTP)

Once the needed data is saved, proceed to the next step described in the below section.



Enabling SCIM on Shelf

In order to enable SCIM on Shelf, perform the following procedure:

  1. Open the SSO Settings through the Shelf Admin Panel.
  2. Enable SSO by selecting the respective checkbox, and choose the Custom SAML option from the SSO Provider dropdown list.
  3. Fill in the section with SSO settings, using the data taken from OneLogin (as an example).

  4. Click SAVE and reload the page.
  5. Now you can enable SCIM by selecting the respective checkbox.
    After this, you are able to finish the configuration of the OneLogin Shelf App
  6. With SSO enabled, your users will be forced to log in via SSO. Apart from the Admin that sets up Single Sign-On feature on Shelf, all the users will be logged out as soon as the SSO feature is enabled (once SAVE is clicked). So make sure you complete Step 1 of this guide before enabling this feature.


Configuring SCIM Provisioning on OneLogin

General Configuration

In order to set the SCIM Provisioning on OneLogin, follow the steps below: 

  1. Open the Administration menu on OneLogin. Select the Applications option and choose the Shelf App you have created in the first part of this guide. 
  2. Select the Configuration option in the sidebar panel.
  3. Populate the OneLogin application settings with the values from the Shelf SSO Configuration screen.
  4. Once done, click the Enable button, and make sure the API status is green (Enabled).

  5. Now fill in the Application details section with data:

    • SAML Audience URL:  urn:auth0:shelfio:SHELF_ACCOUNT_ID

    • SAML Consumer URL


      US Region

      EU Region

      https://shelfio.auth0.com/login/callback?connection=SHELF_ACCOUNT_ID

      https://shelfio.eu.auth0.com/login/callback?connection=SHELF_ACCOUNT_ID


      Replace SHELF_ACCOUNT_ID with the actual account ID taken from the Shelf SSO configuration screen.
  6. Click the SAVE button.


Configure User Provisioning

The next step is to configure the provisioning settings inside the OneLogin application. Click the Provisioning button, and make sure all checkboxes and selectors are in the same state as described below. After setting up the correct configuration, click the SAVE button.


Workflow Parameter

Value

Enable Provisioning

true

Admin approval: Create user

false

Admin approval: Delete user

false

Admin approval: Update user

false

Action for deleted users

Suspend

Action for suspended users

Suspend




Propagate “shelfPlanTypeId” property (optional)


Shelf has a concept of user plans. In addition to roles which control permissions, there are user plan types that control how the user is billed. For example, a typical organization has separate billing models (plan types) for contact center agents & non-agent users.

Setting up SCIM will help you manage user plan type assignments in Shelf. This will automate syncing changes to user plan types from your SSO provider into Shelf.

This step is optional. Contact Shelf Support first, to agree on the contracted user plan types. Shelf Support will provide you IDs of the plan types to assign to users.

We’ll walk through setting up a custom field in OneLogin and making it propagated through SCIM into Shelf.

Note: 
With our Shelf Support will be chosen the default plan type for the account and in case via SCIM “shelfPlanTypeId” property is not provided for the user - the default plan type will be set.

  1. First step is to add a custom field shelfPlanTypeId. Select the Custom User Fields option in the Users tab menu.
  2. Press “New User Field” and add a new custom field - “shelfPlanTypeId”. Afterward hit the “Save” button.
  3. Navigate to the “Mappings” in the “Users” tab.
  4. Press “New Mapping” and set shelfPlanTypeId property based on some criteria. Afterward hit the “Save” button.
  5. Press “Reapply All Mappings”

Configure User Profile Parameters

  1. Now we need to add Parameters mapping in OneLogin. Click the “Parameters” button in the Shelf OneLogin application

  2. Click on the “Groups” and set the checkbox with the label “Include in User Provisioning” as active. After that just hit the “Save” button.
    Note: If you attempt this before configuring the “Provisioning” tab, there will be no such checkbox.
  3. Click the “+” button, and add a new parameter named avatarURL 
    Also, click on the checkbox with the “Include in User Provisioning” label. After clicking the save button, the second window will pop up.
  4. Choose the “Value” - “Profile Picture” field and click “Save”.
  5. Click the “+” button again, and add a new parameter named email.
    Don’t forget to enable the Include in SAML Assertion and Include in User Provisioning options by selecting the respective checkboxes. Note that, unlike other parameters, only the email parameter is to be included both in the SAML Assertion and User Provisioning.
  6. In the Value field, select the Email option from the dropdown list, and again make sure all checkboxes are selected.
    Click the Save button
  7. Click the “+” button, and add a new parameter named firstname and select the Include in User Provisioning checkbox. Once done, click the Save button.
  8. In the Value field select the First Name option from the dropdown list, and hit Save.
  9. Click the “+” button, and add a new parameter named as lastname. select the Include in User Provisioning checkbox. Once done, click the Save button.
  10. In the Value field, select the Last Name option from the dropdown list.
    Click the Save button to complete the configuration procedure.
  11. (optional; relevant if you complete this step only) Click the “+” button, and add a new parameter named shelfPlanTypeId. Then select the Include in User Provisioning checkbox. Once done, click the Save button.
  12. In the Value field, select shelfPlanTypeId (Custom) from the dropdown list.


Configure User Group Mapping

Optionally, you can configure the user group membership through SCIM.

  1. Create a user group at the Shelf Admin Panel. Click on the “User Groups” tab, and proceed with “ADD USER GROUP”
  2. Set the User Group title and optionally add a description. Click the SAVE button.
  3. Find and open the newly created User Group.
  4. Open the Library Permissions tab and then click the ADD LIBRARIES button to add shared libraries that will be accessible for all members of the User Group. 
    Note: 
    After the User Group is synchronized with OneLogin, you are not be able to manage User Group Members in Shelf.
  5. Open your OneLogin Home page.
  6. In the right upper corner, select the Administration option. 
  7. Open the Applications tab and then click on the Shelf application that was created in the previous steps.
  8. Select the Provisioning tab and hit the Refresh link button at the bottom of the configuration page.
  9. Now, open the Rules page and add a new rule to define which users should be provisioned into the User Group in Shelf.
  10. Add the rule name, set conditions for the rule that is expected to trigger actions. After you click the Select Groups dropdown field, you can see all User Groups from Shelf. Select those entries, to which you want to add users. In this example, it is the OneLogin Managers option.
  11. Click the Add button after you have selected the correct User Group. Now, it is expected to be displayed on the Added Items list.
  12. Click the Save button.
  13. Users associated with the newly added rule will be synced by SCIM into Shelf, but the time when they are to be synced into the User Groups depends on OneLogin. To manually trigger the sync, click the More Actions button (...) and select the Reapply entitlement mappings option from the popup menu list. Sync may still take up to 60 minutes initially, depending on the number of users.



End of the Journey 

Once you have walked all the above steps, the setup is complete! All your users that have been added to the OneLogin Shelf App will now be managed by SCIM and authenticated via OneLogin. 


All new users will be created in Shelf with a View-Only account role. This can be changed later in Shelf via the Manage User option of the Shelf Admin Panel.


To log into Shelf, navigate to the following URLs depending on your region.




FAQ and Troubleshooting Guide

*.onelogin.com refused to connect 


In case you encounter the error shown on the screenshot, make sure to update your Framing Protection Rules. See the screenshot below for more information.


Allow framing from the following origins: https://shelfio.auth0.com 



Inactive OneLogin users are being synced to Shelf 

We will sync inactive OneLogin users to Shelf. They will be inactive on Shelf as well. If you don’t want such (new) inactive users to be synced to Shelf, remove them from the groups on OneLogin.


Users deleted on OneLogin aren’t deleted on Shelf 

We don’t delete users in Shelf, which have been deleted on OneLogin. Instead, these users get deactivated. Users can not be permanently deleted from Shelf, they can only be deactivated.

Inactive users aren’t considered for in terms of the usage quota.


Deleted users are not be removed from User Group membership but remain inactive there

User group remains managed by SCIM if there are inactive members which have been removed in One Login before.

What needs to be done: Remove those users from this User group manually (SCIM should be OFF)


Unlicensed and then removed users in OneLogin remain active in Shelf

Deletion of unlicensed users does not trigger deactivation in Shelf. If a user was unlicensed, One Login does not trigger any requests to Shelf. So the recommendation is to deactivate the user and then delete it if desired.
Deletion of common users deactivates users in Shelf.

What to do if there are already unlicensed users: Remove these users from the Shelf app manually (SCIM should be OFF), so they will not be treated as active users afterward.


Provisioning fails for some users 

Here are the steps to retry provisioning for failed users:



Failed to provision user with the Resource already exists error

This means that a user with the same email address exists in another Shelf account. The email address must be unique across the entire Shelf platform. Please enter the unique user email address.


User Group membership is not applied to some users. Some users are not synced with Shelf 

This usually happens when you have had users in Shelf created before enabling the SCIM feature. Make sure to reset logins and reapply entitlement mappings.

From the Users page:

From any page:


User Group membership is not applied to some users: User failed updating in the App. userName should not be shorter than 4 characters 

Make sure users have the username property set to the same value as their email address.