Configure SSO using Active Directory Federation Services (ADFS)

This tutorial will help walk you through setting up a an integration between ADFS and KnowledgeOwl using SAML 2.0.

The screenshots below may not match your version of ADFS, but the steps to complete the integration should be the same.

  1. On your windows server, find and open AD FS 2.0 Management (commonly found in the start menu under Administrative Tools).
  2. Once you have opened ADFS Management, got to "Action" -> "Edit Federation Service Properties".  
  3. Copy the link that is displayed under "Federation Service identifier" and paste it into KnowledgeOwl under "iDP entityID"

  4. For most ADFS builds, the "Login URL" and the "Logout URL" will be the base URL of the "iDP entityID" with "/adfs/ls/" as the endpoint instead of "/adfs/services/trust". If this is not true for your setup, you will need to locate the URL that your ADFS setup uses for authentication.  
  5. Next we will want to export our ADFS cert into a x509 DER format to upload into KnowledgeOwl. You can do this by going to "Service" -> "Certificates" right click on the certificate underneath of "Token-signing" and click on "View Certificate...".  
  6. Go to the "Details" tab and click on "Copy to File..." which will bring up a "Certificate Export Wizard".  
  7. 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.
  8. In KnowledgeOwl, upload the certificate file we created by clicking on the "Choose File" button next to x509 Certificate.  
  9. Once you have selected the correct certificate, scroll to the bottom of the page and click the save button.
  10. Now that KnowledgeOwl has your information, you will see some new links underneath of the SAML SSO Integration section of the page. Click on "KnowledgeOwl SP Metadata" which will bring up a popup with KnowledgeOwl XML metadata within it.
    If you aren't seeing any metadata, ensure that you've checked the box to "Enable SAML SSO" and saved. The metadata is only generated after this option is saved.
  11. Copy the text from the "Service Provider Metadata for Reader Mapping" and open up new "Notepad". Paste the metadata text into notepad and choose "File" -> "Save as...".  Change the "Save as type:" to "All Files" and make sure you name the file with a .xml extention.
  12. In ADFS, click on "Add Relying Party Trust..." which will open up another wizard. Click on "Start".  
  13. On the next screen select "Import data about the relying party from a file" and browse to the XML metadata that we saved in step 11 and choose next.
  14. Choose a name that makes sense, such as "KnowledgeOwl SSO", add whatever notes you would like, and click next.
  15. For most setups, you can click next until you finish this wizard which should open up the "Edit Claim Rules" dialog.
  16. If the "Edit Claim Rules" dialog does not come up, you can navigate to it by going to "Trust Relationships" -> "Relying Party Trusts" select the newly created trust identifier and click on "Edit Claim Rules...". 
  17. In the edit claim rules dialog click on "Add Rule..." and choose the default "Send LDAP Attributes as Claims" and click next. Here you can choose what information that you want to send to KnowledgeOwl. At the very least you need to send the E-Mail Address.  
  18. Click on "Add Rule..." again but this time under "Claim rule template:" choose "Transform an Incoming Claim" and choose next.
  19. Update the claim to match the following picture and click finish.  
  20. ADFS may send the attribute claims over in a way that you are not expecting, so in order to view how ADFS is sending the claims, check the "Enable debug mode" option in KnowledgeOwl and save.
  21. In a private browser window or in an incognito tab, copy and paste the "SP Login 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.
  22. On the resulting screen, you should see the list of IDP attributes that ADFS is sending over. Locate the "attribute value" that contains your email address, and copy the "Attribute Name" exactly as it appears after the colon.
  23. On the security settings page, click on the "Map SAML Attributes" link and paste the attribute name copied above into the fields for "SSO ID" and "Username / Email", then click on the save button.
  24. Uncheck the "Enable debug mode" option and save the security settings form. In the tab or window that contained the debug information, click on the "Re-login to see any changes" link at the top to log in through ADFS again. If everything was successful, you will be logged into your knowledge base and you will now have a working SAML SSO integration with ADFS.