Configure SSO using 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 from the security settings page into G Suite.
    1. Copy and paste the SP Login URL into the ACS URL field.
    2. Copy and paste the SP Entity ID into the Entity ID field.
    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.

Map Reader Fields in KnowledgeOwl

  1. Under Settings > Security in KnowledgeOwl, click on the Map SAML Attributes link.
  2. Map the SSO ID, Username / Email, and any optional attributes to the corresponding attributes from G Suite using the names chosen in step 5 above.
  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
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 

In order to test SAML SSO in KnowledgeOwl, you must first configure your SSO integration. View our list of available setup instructions.


TypeSet upTesting
Restrict entire kb to SSOUnder 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 loginsUnder 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.