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:

Basic Setup

Generally speaking, when adding an SP to your IdP, there are 3 pieces of information that you will need about the SP which can all be found on the Settings → Security page within your knowledge base:

  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

A fourth piece of information that may be needed that is not present on the Security page is the "Name ID Format". For your KnowledgeOwl integration, this should be set to "Unspecified". Or if you need the long version, it is "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified".

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

The IdP should also provide a public certificate that will need to be downloaded, and then uploaded into KnowledgeOwl by clicking on the "Upload IdP Certificate" link.

Once you have entered the 3 IdP fields and have uploaded the IdP certificate, make sure that the "Enable SAML SSO" checkbox is checked, and save the Security form.

Attribute Mapping

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.

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 and choose names that makes sense for them such as "email", "firstName" etc.

On the Security page in your knowledge base, click on the "Map SAML Attributes" link and paste the names of the outgoing IdP attributes that correspond to the KnowledgeOwl reader attributes and hit 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.

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 redirect to the "No Access" page with your knowledge base, try turning on the "Enable Debug Mode" option on the security settings page and opening the SP Login URL again.

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 on the security settings page.

Otherwise, make sure that the IdP attribute names listed on the debug page match the values listed when you click on the "Map SAML Attributes" page and that the SSO ID and Username / Email fields have values entered.

Still having trouble? Contact our support team and we will try to help figure out what the issue is.