This tutorial will help walk you through setting up a an integration between AD FS and KnowledgeOwl using SAML 2.0. This feature is available on select plans.
Screenshot warning
The screenshots below may not match your version of AD FS, but the steps to complete the integration should be the same.
Step 1: Add your IdP info to KnowledgeOwl
- On your Windows server, find and open AD FS 2.0 Management (commonly found in Start > Administrative Tools).

- Once you have opened AD FS Management, go to Action > Edit Federation Service Properties.

- Copy the Federation Service identifier URL.

- In KnowledgeOwl, go to Security and access > Access & SSO.
- In the Login methods card, select Set up or Manage next to SAML.
- Expand step 2, Connect your identity provider.
- Paste the Federation Service identifier you copied as the IdP entity ID.
- Enter your IdP login URL and IdP logout URL.
- If your AD FS build doesn't explicitly list these URLs, you can usually remove
/adfs/services/trustfrom your IdP entity ID URL and replace it with/adfs/ls/. For example, if my IdP entity ID URL washttps://mysite.com/adfs/services/trust, my IdP login URL and IdP logout URL arehttps://mysite.com/adfs/ls.
- If your AD FS build doesn't explicitly list these URLs, you can usually remove
- Select Save changes.
Step 2: Upload the IdP certificate to KnowledgeOwl
Next, export your AD FS cert into an x509 DER format to upload into KnowledgeOwl. To do so:
- In AD FS 2.0, go to Service > Certificates.
- In the main pane, right-click on the certificate in the Token-signing section.
- Select View Certificate... in the right-click menu.

- Open the Details tab.
- Select Copy to File...

- This opens a Certificate Export Wizard. In the wizard, choose Next until you get to the format page. On the format page, make sure that DER encoded binary X.509 is selected and choose next.
- Choose a filename and a location that you will remember for the cert and then finish the wizard.
- In the KnowledgeOwl SAML setup, expand step 2, Connect your identity provider.
- Under IdP certificate, drag the file you just created into the drop zone, or select browse to choose it. KnowledgeOwl accepts .crt, .pem, .cer, and .der files.
- The certificate is saved as soon as you upload it, so there's no need to select Save changes. The IdP certificate section then displays the certificate's common name and the dates it's valid.
Step 3: Enable SAML SSO
Once you have entered the three IdP fields and have uploaded the IdP certificate into KnowledgeOwl, enable SAML SSO:
- In the KnowledgeOwl SAML setup, expand step 5, Turn on SAML.
- Select Available.
Select Available in Turn on SAML - Be sure to select Save changes.
Step 4: Add the KnowledgeOwl SP info to your IdP
Now that KnowledgeOwl has your information, you will need to grab some data from KnowledgeOwl to add into AD FS.
- In the KnowledgeOwl SAML setup, expand step 1, Give these details to your identity provider.
- Select Download metadata. KnowledgeOwl saves the metadata as
knowledgeowl-sp-metadata.xml. XML format is required for AD FS.
Select Download metadata in step 1 - In AD FS, select Add Relying Party Trust.... The Add Relying Party Trust Wizard opens.
- Select Start within that wizard.

- On the next screen, select Import data about the relying party from a file.
- Browse to the
knowledgeowl-sp-metadata.xmlfile you downloaded and choose Next. - Choose a name that makes sense, such as "KnowledgeOwl SSO", add whatever notes you would like, and select Next.
- For most setups, you can click next until you finish this wizard, which should open up the Edit Claim Rules dialog.
I don't see Edit Claim Rules
If the Edit Claim Rules dialog does not open automatically, you can navigate to it by going to Trust Relationships > Relying Party Trusts, select the trust identifier you just named, and click on Edit Claim Rules....
- In the Edit Claim Rules dialog, select Add Rule....
- Choose the default Send LDAP Attributes as Claims and select Next.
- Here you can choose what information you want to send to KnowledgeOwl. At the very least you need to send the E-Mail Addresses.

- Select Add Rule... again.
- This time under Claim rule template: choose Transform an Incoming Claim and select Next.
- Set the Claim rule name to KO Name ID or something similar.
- Set the Incoming claim type to E-Mail Address.
- Set the Outgoing claim type to Name ID.
- Set the Outgoing name ID format to Email.
- Be sure the option to Pass through all claim values is selected. Your configuration should look a bit like this:

- Select Finish.
Step 5: Enable debug mode
AD FS may send the attribute claims over in a way that you are not expecting.
In order to view how AD FS is sending the claims, in KnowledgeOwl:
- In the KnowledgeOwl SAML setup, expand step 4, Test login, and check the box next to Debug mode.
- Select Save changes.
- In a private browser window or in an incognito tab, copy and paste the SP login (ACS) URL into the address bar. If the above steps were done correctly, you should be asked to log into your AD server where you will be redirected back to your knowledge base. Debug mode doesn't stop the login; the attributes AD FS sent are kept for five minutes.
- Back in step 4, select Load last login attempt. You'll then see the IdP attributes that AD FS is sending over.
- Once you're done with Step 6, be sure to uncheck Debug mode and select Save changes.
Step 6: Map SAML attributes to fields in KnowledgeOwl
With the attributes from your test login loaded, you can now map SAML attributes to fields in KnowledgeOwl. To do so:
- In the KnowledgeOwl SAML setup, expand step 3, Map reader attributes.
- Optional: Under Identity provider, select AD FS, then select Fill in AD FS settings. This fills in the standard AD FS claim names for SSO ID, Username / email, First name, Last name, and Reader groups. AD FS only sends the claims your claim rules include, so check them against what AD FS sent.
- In the attributes from your test login, locate the attribute that contains your email address, and copy its name exactly as it appears.
- Paste that attribute name into the fields for SSO ID and Username / email in step 3. You can also select the arrow at the right end of the field and pick it from the attributes your IdP sent.
- To map additional fields, repeat this process. Refer to SAML attribute map for more information.
- If you cannot directly map an IdP attribute to a KnowledgeOwl reader attribute, use Custom attribute map rules.
- Once you're done mapping fields, uncheck Debug mode in step 4.
- Select Save changes.
- In a private browser window, open the SP login (ACS) URL to log in through AD FS again. If everything was successful, you'll log into your knowledge base. If so, congratulations! You now have a working SAML SSO integration with AD FS.
The SSO ID is a required mapping. If you don't set it up, the SAML row in the Login methods card of Security and access > Access & SSO displays a warning: "No SSO ID mapped, so readers won't be created".
Step 7: Optional settings
With your AD FS SAML SSO login working, 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.










