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)

Enabling SCIM on Shelf

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

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)

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 

Provisioning fails for some users

Here are the steps to retry provisioning for failed users:

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.