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
- Create the Shelf App in any SSO provider (we will show it on OneLogin)
- Configure SSO in Shelf App
- Enable Shelf SCIM settings and configure the created Shelf App on OneLogin
- SCIM provisioning configuration on OneLogin
Creating the Shelf App on OneLogin
Configure the Shelf App
Open your OneLogin Home page.
- In the right upper corner, click the Administration link button.
- In the menu toolbar on top of the page, select the Applications option.
This reveals the list of your apps.
- Click the ADD APP button.
- Select the connector named SCIM Provisioner with SAML (SCIM v2 Core) from the list of available options.
- 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
- Open the SSO tab in the sidebar panel. Take note of the values for:
- Issuer URL
- SAML 2.0 Endpoint (HTTP)
- SLO Endpoint (HTTP)
- Click the View Details button under the X.509 Certificate section.
- Click the Download button and save the certificate.
- 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
- Open the SSO Settings through the Shelf Admin Panel.
- Enable SSO by selecting the respective checkbox, and choose the Custom SAML option from the SSO Provider dropdown list.
- Fill in the section with SSO settings, using the data taken from OneLogin (as an example).
- Click SAVE and reload the page.
- Now you can enable SCIM by selecting the respective checkbox.
After this, you are able to finish the configuration of the OneLogin Shelf App - 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
- 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.
- Select the Configuration option in the sidebar panel.
Populate the OneLogin application settings with the values from the Shelf SSO Configuration screen.
- Once done, click the Enable button, and make sure the API status is green (Enabled).
- 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.
- 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)
- First step is to add a custom field shelfPlanTypeId. Select the Custom User Fields option in the Users tab menu.
- Press “New User Field” and add a new custom field - “shelfPlanTypeId”. Afterward hit the “Save” button.
- Navigate to the “Mappings” in the “Users” tab.
Press “New Mapping” and set shelfPlanTypeId property based on some criteria. Afterward hit the “Save” button.
Press “Reapply All Mappings”
Configure User Profile Parameters
Now we need to add Parameters mapping in OneLogin. Click the “Parameters” button in the Shelf OneLogin application
- 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.
- 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. Choose the “Value” - “Profile Picture” field and click “Save”.
- 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. - In the Value field, select the Email option from the dropdown list, and again make sure all checkboxes are selected.
Click the Save button - Click the “+” button, and add a new parameter named firstname and select the Include in User Provisioning checkbox. Once done, click the Save button.
- In the Value field select the First Name option from the dropdown list, and hit Save.
- Click the “+” button, and add a new parameter named as lastname. select the Include in User Provisioning checkbox. Once done, click the Save button.
- In the Value field, select the Last Name option from the dropdown list.
Click the Save button to complete the configuration procedure. - (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.
- 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.
Create a user group at the Shelf Admin Panel. Click on the “User Groups” tab, and proceed with “ADD USER GROUP”
- Set the User Group title and optionally add a description. Click the SAVE button.
- Find and open the newly created User Group.
- 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. - Open your OneLogin Home page.
- In the right upper corner, select the Administration option.
- Open the Applications tab and then click on the Shelf application that was created in the previous steps.
- Select the Provisioning tab and hit the Refresh link button at the bottom of the configuration page.
- Now, open the Rules page and add a new rule to define which users should be provisioned into the User Group in Shelf.
- 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.
- Click the Add button after you have selected the correct User Group. Now, it is expected to be displayed on the Added Items list.
- Click the Save button.
- 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.
US Region | EU Region |
FAQ and Troubleshooting Guide
*.onelogin.com refused to connect
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
Unlicensed and then removed users in OneLogin remain active in Shelf
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
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.