SAML-based Single Sign-On Setup for Shelf with Google Workspace: How-to Guide


Document Version History

Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the document.

26 July 2024

Active






















Glossary 

Term

Meaning

Google Workspace

A collection of cloud computing, productivity and collaboration tools, software and products developed and marketed by Google. It consists of Gmail, Contacts, Calendar, Meet and Chat for communication; Drive for storage; and the Google Docs Editors suite for content creation.

Shelf KMS

Shelf Knowledge Management System, a platform to store and manage content

SAML

It stands for Security Assertion Markup Language whose primary role in online security is that it enables you to access multiple web applications using one set of login credentials.

SSO

This acronym stands for the Single Sign-On which is an authentication method that enables users to securely authenticate with multiple applications and websites by using just one set of credentials.






Introduction

This document’s goal is to walk you through the whole process of configuring the Single Sign-On (SSO) method for Shelf using Google Workspace. The Single Sign-On authorization method is expected to help you avoid any manual entry of your Shelf username and password and instead use your Google Workspace credentials to access your Shelf KMS account and its resources.

In our case, the properly configured SSO via Google Workspace is expected to ensure a seamless access to the Shelf App and its full use in accordance with your business needs.

After reading this guide, you will be able to: 
  1. Create and enable the Shelf App in Google Workspace
  2. Enable and Configure the Single Sign-On Feature in Shelf
  3. Understand who can and who cannot log in to Shelf via Google SSO. 
If you have any questions regarding this document or if you need any assistance or support in its relation or the Shelf App and its settings, please contact Shelf’s Technical Support at support@shelf.io or within the Shelf App.


Prerequisites 

For configuring all the needed Single Sign-On settings, the following preconditions must be met:
  • For SSO setup on the Google side
    • Your organization’s Google Workspace must be available and accessible
    • Your user role for Google Workspace must be Super Admin
  • For SSO setup on the Shelf side
    • Your user role for Shelf KMS must be Admin
    • Single Sign-On feature must be enabled for your organization and your account.



Configuring Single Sign-On in Google Workspace

If the above preconditions are met, you can proceed to configuring the Single Sign-On settings on the Google side, that is in your Google Workspace’s Admin Panel. To access it, open https://admin.google.com in your web browser.

Figure 1. Opening Google Workspace’s Admin Panel


Creating the Shelf SAML App in Google Workspace

Creating and configuring the dedicated SAML app is the easiest and the most convenient way to enable access to your Shelf resources via Google Workspace Single Sign-On.  

To create such an SAML app for Shelf in Google Workspace, follow the below steps.
  1. Once logged in to your Super Admin account on the Google Admin Panel, find and open the Apps option in the navigation menu.

    Figure 2. Accessing Apps and creating custom SAML app in Google

  2. Under the Apps header, select the Web and mobile apps options to open in the main window. 
  3. Open the Add app menu by clicking the respective button and then select the Add custom SAML app option from the dropdown list. The App details modal window opens.

    Figure 3. Populating the Shelf custom SAML app details in Google

    In this modal window, you can add your custom SAML app’s name, description, and icon, if you want. Once done, click CONTINUE to proceed to the next step.
  4. The next stage is to view and copy the Google Identity Provider (IdP) details which are populated automatically once you access this window. These are SSO URL, Entity ID, and Certificate. Copy them and save to a file on your local device for further use - you will need them when configuring the SSO settings on the Shelf side.  Once done, click CONTINUE.

    Figure 4. Viewing and copying Google IdP details

  5. For the next step—configuring service provider details—you need to log into your Admin account on Shelf, access Admin Panel, and get to the Single Sign-On menu.
    Figure 5. Accessing Admin Panel and SSO settings in Shelf
    5.1 Once you have logged in to your Shelf account and followed the path Admin Panel (1,2) > Single Sign-On (3), select the Custom SAML (4) option from the SSO Provider dropdown list. The SHELF SSO SETTINGS section will appear and autopopulate.
    5.2. Find and copy the Single sign-on URL and Audience URL (SP Entity ID) values. Save them to a file.
  6. Once copied the values, go back to your configurations in admin.google.com.  Paste the Single sign-on URL value you have copied in Shelf into the ACS URL field. Then paste the Audience URL (SP Entity ID) value into the Entity ID field, respectively. You may leave the Start URL field blank as it is the optional one.
  7. Scroll down the Service provider details window to the Name ID section. Click the Name ID format field and select the EMAIL option from the list that appears. Then click the Name ID field and select the Basic Information > Primary email option there. Tap CONTINUE to save the data you have entered.
    Figure 6. Configuring Service provider details in Google
  8. Now, you need to provide mappings between Shelf user attributes and available user profile fields. Click FINISH to save all the changes.

    Figure 7. Configuring attribute mappings in Google

          

Activating Shelf App

By default, the Shelf Custom SAML App you created is turned off and is not visible to the users signed in to your Google domain account.

To activate the app, find the Shelf SAML app you just created and click on the User access tab to enable the app for users. In the Service status section that appears, select the ON for everyone checkbox to enable Shelf SAML App. Once done, click SAVE.

Figure 8. Enabling Shelf SAML App in Google 

You can also turn the app on only for some organizations. Here’s an article on how to add an organizational unit in your Google Workspace account.

After enabling the app, you are done with the settings on the Google side and can proceed to the configurations in Shelf.



Configuring Single Sign-On in Shelf

To start configuring all the needed SSO settings in Shelf, log in to your Shelf account under Admin user role, go to Admin Panel and then open the Single Sign-On section in the navigation menu. Then follow the below steps.

Figure 9. Accessing and configuring SSO settings in Shelf
  1. Make sure that Custom SAML option has been selected in the SSO Provider dropdown menu. You should have done it when performing Step 5 of the Shelf App creation procedure.
  2. Scroll down to the SSO IDENTITY PROVIDER SETTINGS section and populate the required fields there. You should have copied and saved the needed values when performing Step 4 of the Shelf App creation procedure. Note that the correlation between the Google’s values and Shelf’s values is as follows:


    Google value

    Shelf value

    SSO URL

    IdP SSO Sign-on URL

    Entity ID

    SSO Issuer (IdP Entity ID)

    Certificate

    X.509 Certificate


    Figure 10. Entering Google SSO values in Shelf 

  3. After entering all the values, click SAVE (6) as shown in Figure 9 above. 
  4. Finally, select the Enable SSO checkbox and click SAVE again.
Now, after finishing all the above procedures, you have configured all the SSO settings both in Google Workspace and in Shelf. To start using the Google SSO as a login method for accessing Shelf KMS, log out of your Shelf account. 




Logging in to Shelf with Google Workspace SSO

To log in to your Shelf account using Google Workspace SSO, open Shelf KMS in your web browser, and on the Login screen that appears, click anywhere on the SIGN IN WITH SSO button.


Figure 11. Logging in to Shelf via SSO

On the page that appears, select your Google Workspace account. 


Figure 12. Selecting Google Workspace account under which Shelf SSO login will occur

On the next page, enter the password for your Google Workspace account and click Next.

Figure 13. Entering Google Workspace password

If you have configured everything properly and correctly, you will be logged in to your Shelf account and see your Shelf KMS Home Dashboard. That means that your Google SSO successfully works.

Figure 14. Viewing Shelf KMS Home Dashboard after SSO login via Google Workspace

IMPORTANT!
To be able to sign in to Shelf Knowledge Management System via Google Workspace SSO, DO NOT USE Google Super Admin user credentials at signing in via SSO as you will be redirected not to Shelf KMS Home Dashboard but to Google Admin Panel homepage. More details on this case can be found here: https://support.google.com/a/answer/6341409?hl=en.