Set up SSO via G Suite (formerly Google Apps)

Create SAML app for SSO

  1. Create your own custom SAML app in G Suite.
    In G SuiteAdmin Console, go to Apps > SAML Apps and click on Add a service/App to your domain. If you already have existing SAML Apps, click on the yellow circle with the plus symbol to Enable SSO for a SAML Application. Choose Setup my own custom app.
  2. Plug your Google IdP Information into KnowledgeOwl.
    In KnowledgeOwl, go to Settings > Security, click on Enable SAML SSO, and:
    1. Copy and paste the Google Apps SSO URL into the KnowledgeOwl Login URL.
    2. Copy and paste the Google Apps Entity ID into the KnowledgeOwl iDP entityID.
    3. Download the Certificate and upload it to the KnowledgeOwl x509 Certificate.
    4. Click the green Save button in KnowledgeOwl and click NEXT in G Suite.
  3. Set the basic information for your custom app in G Suite.
    Provide an Application Name for the Custom App, such as KnowledgeOwl SSO. You can optionally add a description and upload a logo for the app. Click NEXT.
  4. Insert your Service Provider Details into G Suite.
    1. Copy and paste the following into ACS URL, replacing {kb-domain} with your knowledge base subdomain :
      https://{kb-domain}/help/saml-login
      Example: https://yourcompany.knowledgeowl.com/help/saml-login
    2. Copy and paste the following into Entity ID:
      https://app.knowledgeowl.com/sp
    3. Select EMAIL in the Name ID Format and click NEXT.
  5. Map your G Suite attributes to KnowledgeOwl.
    Click Add New Mapping to set up each required and optional attribute:
    1. Enter "ssoid" as the application attribute and choose Basic Information and Primary Email.
    2. Enter "username" as the application attribute and choose Basic Information and Primary Email.
    3. Repeat for desired optional attributes (see below).
    4. Click FINISH and OK.
  6. Click on SAML Apps and turn your Custom APP ON for everyone.

Create SAML app for Reader Mapping

  1. Create your another custom SAML app in G Suite.
    Click on SAML Apps and add a new SAML App. Choose Setup my own custom app and click NEXT.
  2. Set the basic information for your custom app in G Suite.
    Provide an Application Name for the Custom App, such as KnowledgeOwl Reader Mapping. You can optionally add a description and upload a logo for the app. Click NEXT.
  3. Insert your Service Provider Details into G Suite.
    1. Copy and paste the following into ACS URL, replacing {kb-id} with your knowledge base ID: https://app.knowledgeowl.com/kb/map-saml/id/{kb-id}
    2. Copy and paste the following into Entity ID:
      https://app.knowledgeowl.com/sp-map
    3. Select EMAIL in the Name ID Format and click NEXT.
  4. Map your G Suite attributes to KnowledgeOwl.
    Click Add New Mapping to set up each required and optional attribute:
    1. Enter "ssoid" as the application attribute and choose Basic Information and Primary Email.
    2. Enter "username" as the application attribute and choose Basic Information and Primary Email.
    3. Repeat for desired optional attributes (see below)
    4. Click FINISH and OK.
  5. Click on SAML Apps and turn your Custom APP ON for everyone.

Map Reader Fields in KnowledgeOwl

  1. Under Settings > Security in KnowledgeOwl, click on Map Reader Fields and log in through your Google Apps account if not already authenticated.
  2. Map the SSO ID, Username / Email, and any optional attributes to the corresponding attributes from G Suite.
  3. Click Save.

Optional reader attributes

In addition to mapping the SSO ID and the Login / Username to the primary email, you can optionally pass over the following reader attributes:

  • First Name
    Enter "first_name" as the application attribute and choose Basic Information and First Name.
  • Last Name
    Enter "last_name" as the application attribute and choose Basic Information and Last Name.
  • Picture / Icon
    Enter "icon" as the application attribute and choose the category and attribute containing the picture or icon. The attribute should contain the URL to the user icon.
  • Groups
    Enter "reader_roles" as the application attribute and choose the category and attribute containing the group or groups. 
    • Group names must exactly match the reader group names in KnowledgeOwl to map.
    • To assign a user to multiple reader groups, put a comma-separate list of groups in the attribute with no spaces after the comma.
  • Custom Fields 1-5
    Enter "custom_1" the application attribute and choose the category and attribute containing the attribute you want to map. Repeat for each desired custom field. 

Troubleshooting

IssuePossible Resolution
Map Reader Fields doesn't work
Make sure your Service Provider Details are correct in your G Suite SAML App for reader mapping. 
  • ACS URL: https://app.knowledgeowl.com/kb/map-saml/id/59a0bf61ec161c9f4b813898
    Replace the highlighted section with your knowledge base ID, which can be found at the end of the URL when you are in Settings > Security.
  • Entity ID: https://app.knowledgeowl.com/sp-map
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 literally be "https://app.knowledgeowl.com/sp-map" – no need to replace anything.
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. 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 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


Set up and test SSO 

Type
Set up
Testing
Restrict entire kb to SSO
Under Settings > Security choose:
  1. Access Security: None
  2. Default Login Page: SAML Login URL
  3. Enable SAML:  Restrict Access to SSO
Inside the application:
  1. Click View KB.
  2. Click either Logout button. You should be redirected to the IdP for authentication.
  3. After authenticating, go to Your Account > Readers to ensure the reader was properly created with all the mapped attributes.

Notes:

  • You can also test by going to your knowledge base URL in a browser where you are not logged in as a user.
  • If you authenticate through your IdP with the same email as your KO user, you will be authenticated as the user and not a reader. You can tell you are logged in as a user if you see the dark editor bar at the bottom of the knowledge base to Add Content, Edit in App, and Change Reader Groups.
Restrict only some content to SSO (part public and part private)
Under Settings > Security choose:
  1. Access Security: None
  2. Default Login Page: SAML Login URL
    Note: Do not choose Restrict Access to SSO in the SAML section.

Under Settings > Basic choose:

  1. Add a reader login / logout link

Under Settings > Style

  1. Go to Custom HTML > Top Navigation.
  2. Make sure you have the login template code if you want a login button. It will look like this: [template("login")]
Inside the application:
  1. Click View KB.
  2. Click the Logout button in the top right. This should log you out as a user and return you the home page of the public site with the option to Login.
  3. Click Login to authenticate with your IdP.
  4.  Go to Your Account > Readers to ensure the reader was properly created with all the mapped attributes.

Notes:

  • You can also test by going to your knowledge base URL in a browser where you are not logged in as a user and clicking on Login.
  • If you click on the user Logout in the bottom right, it will bring you to the reader login page. Click Continue as Guest to return to the public home page. You cannot log in here with your IdP credentials. Your KO user credentials will work.
  • If you authenticate through your IdP with the same email as your KO user, you will be authenticated as the user and not a reader. You can tell you are logged in as a user if you see the dark editor bar at the bottom of the knowledge base to Add Content, Edit in App, and Change Reader Groups.
Restrict entire kb but allow both SSO and reader logins
Under Settings > Security choose:
  1. Access Security: Restrict by reader logins
  2. Default Login Page: Choose SAML Login URL or Reader Login Page
  3. Enable SAML:  Restrict Access to SSO

Note: The default login page is where readers will go if they try to access the site without being logged in or click on the logout button in the kb.

Inside the application:
  1. Click View KB.
  2. Click the Logout button in the top right (the kb logout button). You should be redirected to your IdP for authentication.
  3. After authenticating, go to Your Account > Readers to ensure the reader was properly created with all the mapped attributes.
  4. Click View Kb.
  5. Click the Logout button in the bottom right (the user logout button). This will bring you to the reader login page (/readerlogin). 
  6. Test logging in as a reader. You can set up readers under Your Account > Readers.