Configure SSO with Google Workspace

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. Click on 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 click Continue.

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

After you click Continue above, you'll be directed 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 Settings > SSO  page, on the SAML Settings tab:

From

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 clicking the Upload certificate link in the IdP Certificate section:
   
5. In KnowledgeOwl, check the box to Enable SAML SSO.
6. Click the green Save button in KnowledgeOwl and click 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. Again, this references fields in KnowledgeOwl in Settings > SSO, in the SAML Settings tab:

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 click 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, click Add another mapping to map additional attributes.
2. Choose Basic Information > Primary Email as the Google Directory attribute and ssoid as the App attribute.
   If you don't set up SSO ID, you'll see warnings in both the SAML Settings tab and the SAML Attribute Map tab. See Missing SSO ID mapping warning for more info.
3. Choose Basic Information > Primary Email as the Google Directory attribute and 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 first_name as the App attribute.
      
   2. Last Name
      Choose Basic Information > Last Name as the Google Directory attribute and 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). Use 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). Use 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 are using Custom Fields for your readers, use the Google Directory attribute that makes sense, and use custom_1, custom_2, custom_3, custom_4, or custom_5 for each of the custom fields in the App attributes, respectively.
      
5. Click Finish.
6. In Apps > Web apps, select your SAML app.
7. Click User access.
8. Most likely, you'll want to turn the app ON for everyone; review Google's documentation on enabling it for specific organizational units.
9. In an Incognito window or tab, test logging in using the SP Login URL in KnowledgeOwl and your Google credentials. If you've set everything up successfully, login will work. If login doesn't work properly, see the Troubleshooting section below.

Step 5: 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, check the Restrict Access to SSO box in Settings > SSO and Save. This will override the Default Access selection in Settings > Security.
• If you'd like to use the SAML SSO as your only or primary reader authentication mechanism, set the Default Login Page in Settings > Security to SAML Login URL and Save.

See SSO options for different knowledge base setups for more information.

Troubleshooting Google issues

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