Configure SSO with Google Workspace

If you have an internal knowledge base and use Google Workspace as a shared login, integrate KnowledgeOwl with Google Workspace SSO so your employees can log into the knowledge base using their Google credentials.

In order to set up your knowledge base to use SSO with Google Workspace (formerly G Suite and/or Google Apps), you'll need to:

• In Google Workspace, create a SAML app for SSO and add some KnowledgeOwl info.
• Update info in KnowledgeOwl to capture that SAML app info.

Step 1: Create a Google SAML app for SSO

1. In Google Workspace Admin Console, go to Apps > Web and mobile apps.
2. Select Add app.
3. Select Add custom SAML app.
   
4. In the App name field, add a name that will help you identify this SAML app as belonging to your knowledge base, like KnowledgeOwl SSO. Here, we use Sample KB:
   
5. Then select Continue.

Step 2: Add Google IdP details to KnowledgeOwl and enable SAML SSO

After you complete Step 1 above, Google directs you to the Google Identity Provider detail page. Google offers two options for getting the IdP info KnowledgeOwl will need; we'll use Option 2: Copy the SSO URL, entity ID, and certificate.

For each of these steps, you'll be adding data from Google into KnowledgeOwl, in the Security and access > Single sign-on page on the SAML Settings tab, the Identity provider metadata section: 

1. Copy the Google Apps SSO URL and paste it into the KnowledgeOwl IdP login URL.
2. Copy the Google Apps Entity ID and paste it into the KnowledgeOwl idP entityID.
3. Download the Certificate from Google.
4. Upload it to KnowledgeOwl by selecting the Upload certificate link under IdP certificate:
   
5. In KnowledgeOwl, scroll up to the SAML settings section.
6. Select Enable SAML SSO reader logins.
7. Save your KnowledgeOwl changes and select Continue in Google.

Step 3: Add your KnowledgeOwl service provider details into Google

This is for the step(s) related to Service Provider Details in the Google instructions. 

This references fields in KnowledgeOwl in Security and access > Single sign-on in the SAML Settings tab > Service provider metadata section:

1. Copy the KnowledgeOwl SP login URL and paste it into the Google ACS URL field.
2. Copy the KnowledgeOwl SP entity ID and paste it into the Google Entity ID field.
3. Select EMAIL in the Name ID Format, ensure Name ID is set to Basic Information > Primary email, and select Continue in Google.

Step 4: Attribute mapping and enable Google app

In order for KnowledgeOwl to get information about your readers to properly log them in, you need to map attributes from Google to KnowledgeOwl. There are two required fields and several optional:

1. In Google, on the Attribute mapping page, select Add another mapping to map additional attributes.
2. Choose Basic Information > Primary Email as the Google Directory attribute and enter ssoid as the App attribute.

   Don't forget your SSO ID!
   If you don't set up SSO ID, you'll receive a warning in your Single sign-on pages that it's missing. Refer to Missing SSO ID mapping warning for more info.

3. Choose Basic Information > Primary Email as the Google Directory attribute and enter username as the App attribute.
   
4. Repeat for any of the optional attributes you'd like to use:
   1. First Name
      Choose Basic Information > First Name as the Google Directory attribute and enter first_name as the App attribute.
      
   2. Last Name
      Choose Basic Information > Last Name as the Google Directory attribute and enter last_name as the App attribute.
      
   3. Picture / Icon
      For the Google Directory attribute, choose the category and attribute containing the URL to the user icon (this is usually Custom > Icon but depends on your configuration). Enter icon as the App attribute.
      
   4. Groups
      For the Google Directory attribute, choose the category and attribute containing the group or groups (this is usually Custom > Groups but depends on your configuration). Enter reader_roles as the App attribute.
      
      • In order for this mapping to work, KnowledgeOwl must have Reader Groups with names that exactly match the group names as they appear in Google.
      • To assign a reader to multiple reader groups, put a comma-separate list of groups in the attribute with no spaces after the comma.
   5. Custom Fields 1-5
      If you're using Custom Fields for your readers, use the Google Directory attribute that makes sense, and enter custom_1, custom_2, custom_3, custom_4, or custom_5 for each of the custom fields in the App attributes, respectively.
      
5. Select Finish.
6. In KnowledgeOwl, go to Security and access > Single sign-on.
7. Open the SAML attribute map tab.
8. Enter the same values here that you entered in your Google app. Enter ssoid for SSO ID, username for Username / email, first_name for First name, last_name for Last name, reader_roles for Reader groups, and custom_1, custom_2, etc., for the respective custom fields.

Step 5: Enable Google app

With all your mappings set up, it's time to enable your Google app. In Google:

1. In Apps > Web apps, select your SAML app.
2. Select User access.
3. Most likely, you'll want to turn the app ON for everyone; review Google's documentation on enabling it for specific organizational units.
4. In an Incognito window or tab, test logging in using the SP Login URL in KnowledgeOwl and your Google credentials
   1.  If you've set everything up successfully, login will work. If login doesn't work properly, refer to the Troubleshooting section below.

Step 6: Optional KnowledgeOwl settings

With your SAML SSO login working, you can now review two additional options:

• To make it so that SAML SSO is the only access method for your knowledge base, go to Security and access > Single sign-on > SAML settings tab, select Require all readers to log in via SAML SSO, and Save. This overrides the Content authentication selection in Security and access > Security settings.
• If you'd like to use the SAML SSO as your only or primary reader authentication mechanism, go to Security and access > Security settings. In the Unauthenticated access behavior subsection, select Redirect them to your SAML login URL and Save.

Refer to SSO options for different knowledge base setups for more information.

Troubleshooting Google issues

Review Google's documentation for help with additional errors: https://support.google.com/a/answer/6301076?hl=en&ref_topic=7559288