Okta Single Sign-On for Shelf: Setup Guide



Document Version History 

Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the document.

7 Feb 2022

Expired

1.1

Shelf

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

28 Jul 2022

Expired

1.2

Shelf

Multiple changes, additions, and corrections to the document to reflect the current state of the Shelf and Okta integration.

14 Dec 2023

Active


Document Purpose

This document describes the required steps to enable and configure Single Sign-On to Shelf via Okta. This feature will help you and your users authenticate yourselves and access your Shelf resources via Okta, without the need to use several sets of credentials.

In case you require assistance, please don’t hesitate to contact us at support@shelf.io or via the Shelf Platform chat.




Setting up the Single Sign-On for Shelf in Okta

The Okta app integrations in your org use Single Sign-On (SSO) to provide a seamless authentication experience for end users. After end users sign in to Okta, they can launch any of their assigned Shelf app integrations to access the Shelf services without reentering their credentials.

The below sections and subsections describe how you can configure the Single Sign-On feature for Shelf via Okta. 


Creating Shelf App in Okta

To start configuring SSO for Shelf, you first need to create the Shelf App in Okta. To do so, follow the below steps.
  1. Log in to your Okta account using your valid credentials.
  2. Once on the Okta Homepage, find and select the Applications menu in the navigation panel.
    Figure 1. Accessing the Applications menu in Okta
  3. In the Applications menu, select the Applications option and then click the Create App Integration button as shown in Figure 1 above.
  4. In the popup window that appears, select the SAML 2.0 option for your new Shelf app integration and click Next.

    Figure 2. Defining the sign-in method for your Shelf app integration

  5. In the next window, indicate the name for your new app integration and upload an image to be displayed to your users as the app icon in Okta. You can also upload the image but choose not to show it to the users.

    Figure 3. Creating the app name and icon

  6. Once you have entered the name and added an icon for your Shelf app integration, click Next to get to the further configuration screen.

    Figure 4. Configuring SAML settings in Okta

  7. In this screen - Configure SAML, you need to enter Single Sign-on URL and Audience URI. To get these values, you have to go to your Shelf KMS account, navigate to Admin Panel, and open the Single Sign-On menu. In the SSO Provider field, select the Custom SAML option and you will see the Shelf SSO Settings block containing the needed values.

    Figure 5. Accessing the Single Sign-On menu in Shelf

  8. Copy the Single Sign-on URL and Audience URI values from Shelf and paste them into the respective fields in Okta. Following that, select the needed options for the Name ID format and Application username fields. The suitable options are Unspecified or EmailAddress for Name ID format and Okta username or Email for Application username.

    Figure 6. Filling in SAML-related fields in Okta

  9. Next, click the Show Advanced Settings button and make sure these advanced settings fields are populated as shown in Figure 7 below.

    Figure 7. Configuring advanced SAML settings in Okta

  10. Once completed in this block of settings, scroll down to the Attribute Statements (Optional) block and make sure that its content is populated as shown in Figure 8 below.

    Figure 8. Adding attribute statements values in Okta

  11. After completing the above steps, click Next to proceed to the last stage of the SAML configurations in Okta.
    Figure 9. Completing the final step of SAML configuration in Okta
  12. At this stage, indicate that you add an internal app and that this internal app has been created by you. Click Finish to complete the SAML configuration in Okta.
    Once done, you will be redirected to your Shelf App page in Okta. 

    Figure 10. Viewing the Shelf App page in Okta


    If what you see is similar to that shown in Figure 10 above, it means that you have successfully created Shelf App in Okta and completed general SAML configurations there. Now, you need to instruct the Shelf KMS SSO feature on how to work with Okta and enable the Single Sign-On feature on the Shelf side. 

Providing Okta SSO details to Shelf SSO feature

To be able to enjoy all the benefits of SSO for your Shelf instance via Okta, you need to complete the below steps.
  1. Once on the Shelf App page in Okta, click the View SAML setup instructions button (see Figure 10 above).
  2. On the page that appears, view and copy the needed OKTA SSO details. Save them locally.

    Figure 11. Viewing SSO details in SAML setup instructions

  3. Go to your Shelf instance, open Admin Panel, navigate to Single Sign-On menu, expand the SSO Identity Provider Settings block, and populate the fields there with the details you have copied from Okta. Use the following schema for this:
    Identity Provider Single Sign-On URL (Okta)  >  IdP SSO Sign-on URL (Shelf)
    Identity Provider Issuer (Okta)  >  SSO Issuer (IdP Entity ID) (Shelf)
    X.509 Certificate (Okta)  >  X.509 Certificate (Shelf)
    Once done, click Save.

    Figure 12. Populating SSO identity provider settings in Shelf


      

Enabling SSO in Shelf

After you have entered all the needed SSO details copied from Okta and made sure everything is okay with them, you can now enable the Single Sign-On feature in Shelf. To do so, select the Enable SSO checkbox in Admin Panel > Single Sign-On. 

Figure 13. Enabling SSO for your Shelf instance
If everything was correct with the settings, the success message will be shown to you, and you can expect to see the following screen.

Figure 14. Viewing the SSO page in Shelf after enabling SSO via Okta




        

Logging in to Shelf via Okta SSO 

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


Figure 15. Viewing the Shelf login screen with the SSO login option
Now, click Sign In with SSO and log in using your Okta credentials to access your Shelf account.

Figure 16. Logging in to Shelf using Okta SSO




Setting up OKTA SCIM for Shelf

Once you have enabled, configured Single Sign-On both on the Okta and Shelf sides and made sure it works and allows you to log in to your Shelf account using your Okta credentials, you can enable and configure SCIM. 

Note: 
SCIM (System for Cross-domain Identity Management) is an open standard-based protocol that allows for a secure automation of the exchange of user identity data between your company's cloud applications (like Shelf KMS) and any service providers (like Okta). It manages user identity data so that all the operations related to user adding, editing, deleting etc. are executed in a consistent and safe manner.


          

Enabling SCIM in Shelf

For enabling the SCIM protocol in Shelf, once logged in to your Shelf account, go to Admin Panel > Single Sign-On > SCIM tab and select the Enable SCIM checkbox there. Click Save to save changes.

Figure 17. Enabling SCIM in Shelf


Enabling and configuring SCIM in Okta

Once you have enabled SCIM in Shelf, you need to do the same on the Okta side. To do so, perform the following steps.
  1. Log in to your Okta account and navigate to the Applications menu. 
  2. Open your Shelf App page and select the General tab. Click Edit there.

    Figure 18. Accessing the editing mode for your Shelf app in Okta

  3. Once the editing mode is active, select the Enable SCIM Provisioning checkbox. Click Save to save changes.
    Figure 19. Enabling SCIM provisioning in Okta

  4. Now open the Provisioning tab that has just been added. Find and click the Edit button in the open tab.

    Figure 20. Editing SCIM provisioning in Okta

  5. When in the editing mode, fill in the highlighted fields with the relevant values. Most of these values you need to take from the SCIM tab of the Single Sign-On menu in Shelf.

    Figure 21. Filling in SCIM connection details in Okta

    SCIM Base URL (Shelf)  >  SCIM connector base URL (Okta)
    SCIM Bearer Token (Shelf)  >  Authorization Bearer (Okta) 

    Make sure to set the Unique identifier field for users value to userName. Also, set the Authentication Mode value to HTTP Header.
    Figure 22. Copying SCIM connection details in Shelf
  6. Once all the details are entered, click the Test Connector Configuration button (Figure 21) to test the SCIM connection. If no errors occur, click Save. 
  7. Go back to the Provisioning tab in your Shelf App page on Okta. Select the To App option in the left sidebar menu and then set the values in the Provisioning to App window as shown in Figure 23 below.

    Figure 23. Configuring SCIM provisioning to app settings in Okta


Adding Okta users to Shelf App

After enabling SCIM in Okta and configuring its settings and provisioning to Shelf App, you need to add Okta users to your Shelf App. 
To do it, follow these steps:
  1. On your Shelf App page in Okta, open the Assignments tab.

    Figure 24. Adding users to Shelf App in Okta

  2. Click Assign and select the Assign to People option in the dropdown menu. This option is valid if you want to add individual users. If you want to add groups of users, select Assign to Groups. 
  3. In the popup window that appears, select the users you want to add to your Shelf App and click Assign next to them. After that click Done.

    Figure 25. Adding individual Okta users to Shelf App

  4. If the user(s) is(are) added without errors, you will see them in the Assignments tab of your Shelf App page, without exclamation marks.

    Figure 26. Viewing Okta users added to Shelf app

  5. You will also be able to see the added users in Shelf at: Admin Panel > Manage Users.
    Figure 27. Verifying that Okta users are added to Shelf AppNow, you can try to log in to Shelf under one of those Okta users you have just added.