Configure SSO using G Suite (formerly Google Apps)

In order to set up your knowledge base to use SSO with Google Workspace (formerly G Suite), 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

These instructions are adapted from the Google Workspace instructions to create your own custom SAML app in Google Workspace. We don't actively maintain the Google steps of these instructions; when in doubt, review Google's own documentation: https://support.google.com/a/answer/6087519?hl=en

  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 link underneath IdP Certificate:
  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.
  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 user 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 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

IssuePossible Resolution
Error app_not_configured_for_user when trying to log inThis can mean you have the wrong Entity ID in your SAML app for SSO. It should literally be "https://app.knowledgeowl.com/sp-map" – no need to replace anything.
Redirected to the KnowledgeOwl login screen after authenticationThis can mean you have the wrong ACS URL in your G Suite SAML app for SSO.  It should look like the URL below, with the highlighted section replace with your KnowledgeOwl subdomain. You can view and customize your subdomain under Settings > Basic, or quickly check your subdomain by clicking View KB:
https://gsuite.knowledgeowl.com/help/saml-login
Redirected to the Google login screen after authenticationThis can mean you have an incomplete ACS URL. It might be missing "/help/saml-login". It should look like the link below, with the highlighted portion replaced with your KO subdomain.
https://gsuite.knowledgeowl.com/help/saml-login

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