Shelf SAML Single Sign-On with SCIM: Okta Setup Guide




Document details

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

Expired

1.3

Shelf

Major update to the document to bring it to compliance with Okta's documentation style guide and requirements.

29 Oct 2024

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.


Glossary

Term

Definition

Shelf KMS

Shelf Knowledge Management System, an AI-enabled content creation, storage, and management platform that helps businesses keep their information up-to-date, streamline workflows, enhance decision-making, and expedite content creation. Shelf KMS provides a seamless search journey with naturally intuitive interactions to make finding content easy. This ease of search achieves enterprise-level findability backed by AI.

SSO

Single Sign-On, a technology which combines several different application login screens into one. With SSO, a user only has to enter their login credentials (username, password, etc.) one time on a single page to access all of their SaaS applications.

SAML

Security Assertion Markup Language, an open standard used for authentication. Based upon the Extensible Markup Language (XML) format, web applications use SAML to transfer authentication data between two parties - the identity provider (IdP) and the service provider (SP).

The technology industry created SAML to simplify the authentication process where users needed to access multiple, independent web applications across domains.

SCIM

System for Cross-domain Identity Management, 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.

JIT

Just in Time (JIT) Provisioning is used to create users the first time they log in to an application via a third-party identity provider. JIT provisioning eliminates the need to provision users or create user accounts manually. This saves effort and time. JIT Provisioning is independent of the SSO protocol used by the application but it’s vital to note that for this approach to work, the web application must support JIT Provisioning.






Prerequisites

Prior to proceeding with all the needed actions to create the Shelf app in Okta and configure the relevant Single Sign-On settings to integrate Shelf and Okta, make sure that the following preconditions are met:
  • You must have the Admin user role in Okta
  • You must have the Admin user role in Shelf
  • Enterprise Single Sign-On feature must be enabled for your Shelf account.


Supported features 

Once installed and configured, Shelf integration in Okta is expected to support the following features:

  • Service provider(SP)-initiated SSO

  • Identity provider(IdP)-initiated SSO

  • JIT provisioning (for non SCIM scheme).


When SCIM is enabled for Shelf Okta SSO integration, the following features are expected to be supported:

  • Adding users

  • Updating user attributes

  • Managing users

  • Deactivating users

  • Adding user groups

  • Importing users

  • Importing user groups

  •  Pushing users

  • Pushing user groups





Configuring SP-initiated SSO for Shelf

The Okta integrations in your organization use SSO to provide a seamless authentication experience for end users. Once the SSO integration is set, end users can use their Okta credentials to sign in to their Shelf app accounts and access Shelf services without entering their Shelf credentials.
The below sections and subsections describe how you can configure the SSO feature for Shelf via Okta. 


Creating Shelf app in Okta

Shelf app is a portal to Shelf Knowledge Management platform that helps modern businesses thrive through well-thought capabilities of content creation, storage, management, and intelligence, including analysis and enrichment. The solution connects businesses' departments with AI-enabled knowledge base and allows them to receive accurate answers to their customers' questions in a timely and efficient manner. The Okta Shelf integration allows users to sign in to Shelf platform, using Okta as a Single Sign-On provider.
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 the figure 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 (1) and Audience URI (2) 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 the figure 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 the figure 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.




Configuring SSO in Shelf with Okta SSO details

After creating and configuring your Shelf SAML-app integration in Okta, you need to configure SSO settings in Shelf, for enjoying all the benefits of logging in to your Shelf instance via Okta SSO. To do so, perform the following 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 to a file for the next stage of configurations. 
    Figure 11. Viewing SSO details in SAML setup instructions
  3. Go to your Shelf instance, open Admin Panel, navigate to the Single Sign-On menu, expand the SSO IDENTITY PROVIDER SETTINGS block, and populate the fields there with the details you have copied from Okta to the local file. 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 there are no typos or erroneous symbols, 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


Adding users to Shelf app in Okta

Prior to logging in to your Shelf instance via Okta-initiated SSO, you need to add users, who are expected to be permitted to use this SSO method of accessing Shelf, to the created Shelf app. 

To do so, perform the following steps:

For the purpose of this document, let’s describe adding ourselves as a user to the Shelf app created in Okta.
  1. Go back to your Okta Admin page, navigate to the Applications menu, select the Applications option under it, and then find your Shelf SSO app you have recently created and configured. Open it.
    Figure 14. Opening Shelf app in Okta
  2. On the Shelf app page that appears, navigate to the Assignments tab and then open the Assign dropdown menu. Select the Assign to People option.

    Figure 15. Accessing user assignment menu

    If you need to add a group of persons—e.g. your organization’s business unit, department, or team—as users who are permitted to use the Shelf SSO app in Okta, select the Assign to Groups option.
  3. In the popup window that opens, find the needed user (in our case—yourself) and click the Assign button next to it.
    Figure 16. Selecting user for adding to Shelf app

  4. In the next window, make sure you have selected the right user. If yes, click Save and Go Back.

    Figure 17. Confirming user


  5. Click Done. You are redirected to the Shelf app page > Assignments tab, where you can make sure the needed person—you—is listed as the user assigned for the Shelf app.

    Figure 18. Viewing the list of users assigned for Shelf app




Logging in to Shelf via Shelf-initiated SSO for Okta

💡Note:

Before telling users they can start logging in to their Shelf accounts via Okta SSO, you first need to assign them--users--to Shelf app you have created in Okta. If a user that hasn't been assigned to Shelf app tries to log in to their Shelf account via Okta, they will see an error message "User is not assigned to application".

When your account is configured for Shelf-initiated SSO for Okta, you need to know credentials (email address/password) for your Okta domain. Once you have them, perform the following steps:
  1. Navigate to the Shelf web application, considering the geography and domain: 
    https://yourcompanyaccount.shelf.io/  
    https://yourcompanyaccount.shelf-eu.com/  
    https://yourcompanyaccount.shelf-ca.com etc. 
    Figure 19. Viewing the Shelf login screen with the SSO login option
    After you hit Enter on your keyboard, you can expect to see the following screen.
  2. Click Sign In with SSO and log in using your Okta credentials (username and password) to access your Shelf account.
    Figure 20. Logging in to Shelf using Okta SSO
    If your credentials are correct, you are logged in to your Shelf account and get to the Shelf KMS homepage as shown in the figure below.
    Figure 21. Viewing Shelf homepage after successful login



Configuring IdP-initiated SSO for Shelf

This chapter will guide you in configuring the IdP-initiated Single Sign-On method for Shelf with Okta as the initiating IdP. Once you complete all the configurations described here, you will be able to visit an Okta provided link, authenticate, and then be logged into your Shelf instance.



Creating Shelf app in Okta

Perform Steps 1-10 laid down in the Creating Shelf app in Okta section of the Configuring SP-initiated SSO for Shelf chapter.


Configuring SSO in Shelf with Okta details

Perform Steps 1-3 laid down in the Configuring SSO in Shelf with Okta details section of the Configuring SP-initiated SSO for Shelf chapter.


Enabling SSO in Shelf 

Activate the SSO feature in your Shelf instance as described in the Enabling SSO in Shelf section of the Configuring SP-initiated SSO for Shelf chapter.


Adding users to Shelf app

For adding users to the list of those who are permitted to use the Okta-initiated SSO method to sign in toctheir Shelf accounts, perform steps described in the Adding users to Shelf app in Okta section of the Configuring SP-initiated SSO for Shelf chapter.





Logging in to Shelf via Okta-initiated SSO

💡Note:

Before telling users they can start logging in to their Shelf accounts via Okta SSO, you first need to assign them—users—to Shelf app you have created in Okta. If a user that hasn't been assigned to Shelf app tries to log in to their Shelf account via Okta, they will see an error message "User is not assigned to application".


Testing Shelf login from Okta

  1. Once on the Shelf app page in Okta, navigate to the General tab and scroll to the App Embed Link section. Copy and save the Embed Link value. This is the link a user needs to visit to begin the IdP initiated SSO, so you could place it in your application’s navigation, launchpad, or elsewhere.

    Figure 22. Finding and copying Shelf app link in Okta

  2. Open an incognito (private) browser window or tab and in the address field, enter the Embed Link value you have copied and saved in Step 1 above. Press Enter on your keyboard to open the URL. Log in with your Okta IdP credentials.
    Figure 23. Signing in to Shelf from Okta
    If all the IdP-initiated SSO settings have been configured properly, you are redirected to the homepage of your Shelf instance.
    Figure 24. Viewing Shelf homepage after successful login


Signing in to Shelf from Okta End-User Dashboard

If the test login described above was successful, it means that non-Admin end users added to the Shelf app in Okta will be able to sign in to their Shelf accounts directly from Shelf app on the Okta End-User Dashboard.

Figure 25. Finding and using Okta Shelf app to log in to Shelf KMS




Setting up SCIM for Shelf

Once you have enabled and configured Single Sign-On (the SP-initiated or IdP-initiated method, depending on your organization’s needs) both on the Okta and Shelf sides, and made sure it works and allows you to log in to your Shelf account, you can enable and configure SCIM. 

💡Note: 

SCIM's goal is to securely automate the exchange of user identity data between your company’s cloud apps and any Service Providers (SP)—in our case, Okta.

As your company grows, the number of user accounts and provisioned applications may increase. Requests to add and remove users, reset passwords, change permissions, and add new types of accounts all take up valuable time.

With the SCIM protocol, user data is stored in a consistent way and can be shared between Okta and Shelf platforms. Since data is transferred automatically, complex exchanges are simplified and the risk of error is reduced..


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 26. Enabling SCIM in Shelf

Once done, your SCIM configurations in Shelf are basically completed.


Enabling and configuring SCIM in Okta

After 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 on the Okta Admin homepage, navigate to Applications > Applications in the menu. 
  2. Find and open the Shelf app.
  3. Once on the Shelf app page, go to the General tab and, in the App Settings block, click Edit.
  4. Following that, select the Enable SCIM provisioning checkbox for the Provisioning option. Click Save.
    Figure 27. Enabling SCIM provisioning for Shelf app in Okta
  5. Now open the Provisioning tab that has just been added. Find and click the Edit button in the open tab. Once 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 28. Copying SCIM connection details in Shelf

    Figure 29. Filling in SCIM connection details in Okta

    Make sure to comply with the following legend of entering Shelf SCIM values into Okta.SCIM Base URL (Shelf) > SCIM connector base URL (Okta)
    SCIM Bearer Token (Shelf) > Authorization Bearer (Okta)

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



Additional information

💡Note: 

We are planning an update to our SSO integration with Okta in the near time. After the release of this update, you will need certain additional parameters. 
In order to make your use of the Shelf-Okta integration as smooth as possible, we are listing those parameters here along with the description where you can find them and save for future needs.

List of parameters

Account ID: the identification of user's account in Shelf KMS.

This parameter can be found in your Shelf at: Admin Panel > Account Overview.

Figure 31. Finding Shelf Account ID parameter

Shelf Auth0 Domain: URL of your Shelf Auth0 domain, use the following value: shelfio.auth0.com 

Shelf Auth0 Tenant: the identification (name) of your Shelf Auth0 domain user group, use the following value: shelfio.