KnowledgeOwl

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. This feature is available on select plans.

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.

You'll do the KnowledgeOwl steps in the SAML setup: go to Security and access > Access & SSO and, in the Login methods card, select Set up or Manage next to SAML.

OpenID Connect is also an option
You can also connect Google Workspace using OpenID Connect (OIDC) instead of SAML. Google doesn't send groups over OpenID Connect, so use SAML if you need to assign reader groups from Google. Refer to Configure OpenID Connect SSO.

Step 1: Create a Google SAML app for SSO

When in doubt, check Google's docs for this section
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: Set up your own custom SAML application

  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 step 2 of the SAML setup, Connect your identity provider: 

  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 entity ID.
  3. Download the Certificate from Google.
  4. Upload it to KnowledgeOwl by dragging it into the drop zone under IdP certificate, or selecting browse to choose it. The certificate is saved as soon as you upload it.
    SAML step 2, Connect your identity provider, expanded to show the IdP entity ID, IdP login URL, and IdP logout URL fields and the IdP certificate drop zoneSAML step 2, Connect your identity provider
  5. In KnowledgeOwl, expand step 5, Turn on SAML.
  6. Select Available.
  7. Select Save changes in KnowledgeOwl 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 step 1 of the SAML setup, Give these details to your identity provider:

  1. Copy the KnowledgeOwl SP login (ACS) 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, the SAML row on Security and access > Access & SSO displays a warning 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 the KnowledgeOwl SAML setup, expand step 3, Map reader attributes.
  7. 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, and last_name for Last name. To map Reader icon, Reader groups, or custom fields, select Add field, then enter icon, reader_roles, or custom_1, custom_2, etc., for the respective fields.
    • Don't use the Google Workspace fill-in under Identity provider for this setup. It fills in different names (like email and firstName) than the ones above.
  8. Select Save changes.

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 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 three additional options:

  • To make it so that SAML SSO is the main access method for your knowledge base, select Required for all readers in SAML step 5, Turn on SAML, and select Save changes. Anyone who isn't logged in is sent straight to SAML. This overrides the Who can read this knowledge base? selection in Security and access > Access & SSO. Other login methods set to Available still work through their login links. Refer to SSO options for different knowledge base setups for more information.
  • If you'd like to use the SAML SSO as your primary reader authentication mechanism without requiring it, go to Security and access > Access & SSO. In the Login methods card, set Send readers who aren't logged in to to SAML login and select Save changes. (This option isn't shown when Who can read this knowledge base? is set to Logged-in readers only.) Refer to SSO options for different knowledge base setups for more information.
  • If you'd like to use SAML SSO for your authors, refer to Set up SAML SSO for authors.

Troubleshooting Google issues

Issue Possible Resolution
Error app_not_configured_for_user when trying to log in This can mean you have the wrong Entity ID in your SAML app for SSO. It should exactly match the SP entity ID in SAML step 1, Give these details to your identity provider.
Redirected to the KnowledgeOwl login screen after authentication This 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:
https://gsuite.knowledgeowl.com/help/saml-login.
View and customize your subdomain under KB settings > Domain.
Redirected to the Google login screen after authentication This 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 SAML app error messages documentation for help with additional errors.