Configure SAML SSO (generic instructions)

Below are instructions for setting up SAML SSO using a generic identity provider. We have specific instructions for our most popular identity providers:

Step 1: Add the KnowledgeOwl SP info to your IdP

Generally speaking, when adding an SP to your IdP, there are 4 pieces of information that you will need about the SP.

  1. SP Entity ID
  2. SP Login URL — sometimes referred to as a "sign on URL"
  3. SP Logout URL — some systems do not ask for this
    All three of these fields can be found in your knowledge base in Settings > SSO in the SAML Settings tab:
    Screenshot of the SP Entity ID, SP Login URL, and SP Logout URL fields from the Settings > SSO page in KnowledgeOwl.
    Sample SP entity ID and login/logout URLs
  4. Name ID Format — some systems do not ask for this. If yours needs it, you should set it to "Unspecified" or, if you need the long version: "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"

Step 2: Add your IdP info to KnowledgeOwl

Once you have entered those pieces of information into your IdP, the IdP should provide you with the same 3 pieces of information as above, but for the IdP side of the connection:

  1. IdP Entity ID
  2. IdP Login URL — sometimes referred to as a "sign on URL"
  3. IdP Logout URL — if the IdP does not provide this, use the login URL

Add this information into the appropriate fields in KnowledgeOwl, located just under the SP fields in Settings > SSO in the SAML Settings tab:

Be sure to Save your changes if you aren't ready to upload your certificate yet.

Step 3: Upload the IdP certificate to KnowledgeOwl

The IdP should also provide a public certificate. You will need to download the certificate and then upload it into KnowledgeOwl.

To do so, go to Settings > SSO. Be sure you're in the SAML Settings tab. 

Click on the Update link in the IdP Certificate section, located just under the IdP URL fields:

Once you successfully upload your certificate, this section will update to include the information from the certificate. For example:

Screenshot of the IdP Certificate section. The area to the right of the IdP Certificate label has changed from saying Sample IdP certificate details

Step 4: Enable SAML SSO

Once you have entered the 3 IdP fields and have uploaded the IdP certificate into KnowledgeOwl, make sure that the Enable SAML SSO checkbox is checked, and Save the SSO Settings page.

Step 5: Map SAML attributes to fields in KnowledgeOwl

Now that the IdP URLs have been added to your knowledge base settings and vice versa with the SP URLs into your IdP, you will need to configure your IdP to pass over identifying information about the users logging in so that we can create / update them within your KnowledgeOwl account.

These mappings are configured in Settings > SSO in the SAML Attribute Map tab.

The minimum required information needed to successfully log a user in through SAML SSO is a unique ID (SSO ID) and an email address. The user's email address can be used as both the SSO ID and their email address if this is preferred.

In the IdP, there should be a mechanism to add outgoing attributes where you can choose a name and select the appropriate field from the IdP's database.

Add the user's email and any other information you would like to the outgoing attributes. Choose names that make sense for these attributes, such as "email", "firstName" etc.

  1. In KnowledgeOwl, go to Settings > SSO.
  2. Click on the SAML Attribute Map tab. 
  3. Paste the names of the outgoing IdP attributes that correspond to the KnowledgeOwl reader attributes in the Direct Reader Attribute Map section.
    • If you cannot directly map an IdP attribute to a KnowledgeOwl reader attribute, you can use Custom Attribute Map Rules to do some mappings or logic for you. See the help page on those rules for more info.
  4. Once you're done adding attribute mappings, Save.

If everything has been done correctly up to this point, you should be able to open a new incognito or private browser window and log into your knowledge base by pasting the SP Login URL.

Step 6: Optional 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

If you try to open the SP Login URL and the resulting page does not resolve, make sure that the IdP Login URL is correct, that it is using HTTPS, and that you can resolve the page by going to the IdP login URL directly.

If you are able to successfully log into your IdP but you get redirected to the "No Access" page with your knowledge base:

  1. Go to Settings > SSO.
  2. Check the box next to Enable Debug Mode near the top of the SAML Settings tab
  3. Save those settings.
  4. Now open the SP Login URL again.
    1. If you see an error on the resulting debug page after logging in:
      • You may have an issue with the IdP certificate you uploaded, or 
      • Your IdP may require one of the Advanced Options to be enabled in the SAML Settings tab.
    2. If you don't see an error on the debut page after logging in:
      • Make sure that the IdP attribute names listed on the debug page match the values listed when you click on the SAML Attribute Map tab.
      • Make sure that the SSO ID and Username / Email fields have values entered in the SAML Attribute Map tab.
  5. Once you're done troubleshooting, be sure to uncheck the Enable Debug Mode box and save the SAML Settings.
  6. If you're still having trouble after trying all of the above steps, contact our support team and we will try to help figure out what the issue is.