General security options

Create a public knowledge base

To make your knowledge base public and available to anyone with the link:

  1. Go to Settings > Security.
  2. Set the Default Access to Public.
  3. Save your changes.

If your site is public, it can show up in Google and other search engines.

Learn more about search engine optimization in our SEO guide.

Create a public knowledge base with some private content

To make some content private on your public knowledge base, you can create a reader group (or groups), restrict content to the appropriate group, and require readers to log in to get access to the reader group restricted content.

To log in readers to your site to access the restricted content, you can add a reader login/logout button to your website or use one of the other authentication methods like single sign-on or remote authentication to automatically authenticate certain readers.

To add a reader login/logout button to your knowledge base:

  1. Go to Settings > Basic.
  2. In the Website Settings section, check the Top navigation box next to "Add a reader login / logout link".
  3. Save your changes.
  4. Check that the login link appears in your knowledge base by going to Settings > Style.
  5. Below the preview pane, select Custom HTML, then select the dropdown that appears and select Top Navigation.
  6. The login link will be added wherever the [template("login")] appears.

Create a private knowledge base

You can choose to make your knowledge completely private, meaning that no one will be able to access it without some type of login, password, or shared IP.

You can make your knowledge base private by going to Settings > Security and choosing one of our available security options:

  • Restrict by reader logins
    Readers will be required to log in with a username and password. Authors with full account admin access can set up readers, reader groups, and reader settings under Your Account > Readers (or Account > Readers for authors with admin access to readers). Learn more in our Reader Management guide.
  • Restrict by IP or shared password
    Readers will need to be coming from a specified IP address or enter a shared password to access the site. You can also choose to require both an approved IP address and a password to log in.
  • Remote authentication
    Readers will be required to log in through a 3rd party site, such as your own website or application. You can use this option to automatically log in readers from your software. You'll need to configure remote authentication in Settings > SSO.
  • SAML SSO (single sign-on)
    Readers will be required to log in through your specified identity provider, such as ADFS, Okta, or G Suites (Google Apps for Work). Configure this in Settings > SSO. See Single sign-on (SSO) for more information.
  • Salesforce SSO (single sign-on)
    Readers will only be able to log in through your Salesforce account. Configure this in Settings > SSO. See our Salesforce SSO Configuration guide.

Create a private knowledge base with different content for different readers

To restrict content access in a private knowledge base, create reader groups for the different segment of your audience and restrict your content to the appropriate reader groups. When you create readers in KnowledgeOwl or log them in using single sign-on (SSO) or remote authentication, assign the readers to the appropriate groups.

To learn more about readers, read our Reader Management guide.

Restrict by IP address, shared passwords, reader logins, or a combination

The security settings under the Settings tab are mostly centered around the needs of private or internal knowledge bases. By default, your knowledge base will be visible to the public which means anyone can peruse your content. However, under Settings > Security, you have quite a few options.

When would I use the different types of security?

Restrict by reader logins

Readers offer the most power in terms of authentication to your knowledge base. Essentially a reader is an individual login for each person or group whom you want to give access to your knowledge base. With this setting turned on, a person trying to access your knowledge base will be asked for a username and a password which we can then use to identify who they are. Once they log in, they will remain authenticated for 2 hours and can browse normally. If you select this option, you will need to set up readers under Your Account > Readers.

You can also choose remote authentication, Salesforce SSO, or a SAML SSO integration to create readers using existing credentials.

Restrict by IP address

This setting is great for internal office knowledge bases. If you can track down the IP addresses that your office uses, you can paste the comma separated list into the box and ensure that no one trying to access your knowledge base from outside of your office can get in.

You can also use the /24 subnet mask for a range of IP addresses; at this time, we only support the /24 subnet mask.

Restrict by shared password

This one is great if you need to restrict access to your knowledge base but you aren't sure of your office's IP addresses or if your readers are going to be spread out. Creating a single password that you can give to everyone will allow you to control who gets in but will allow for more flexibility.

IP-based Restriction OR Shared Password

You can also use the shared password setting in combination with the IP protection setting for even more flexibility. What this means is that while someone is in your office, on an approved IP address, they won't have to worry about logging in because they are accessing the knowledge base from an approved IP address. If they work from home one day though, they will be asked for the shared password to log in.

IP-based Restriction AND Shared Password

Need more security? You can select to use IP-based restriction as well as a shared password for two-factor authentication.


Restrict Content to Logged In Readers

You can restrict some content so that it is only visible to specific readers. To do so, create a reader group or groups and then restrict the category or individual articles to that group.

Restrictions can be set:

  • At the category level: restrictions set in the Restrict to Groups section will automatically be inherited by all subcategories and articles in the category.
    • Groups inherited from a category are identified in the Inherited Restrictions section of the editor.
    • By default, articles and subcategories are set to "Use Inherited Only" (they will only use the groups they've inherited from the category).
    • You can add additional groups to individual subcategories and articles by using the Add More Restrictions checkboxes within those pages.
  • At the article level: if an article has no inherited restrictions: restrictions set in the Restrict to Groups section apply only to the individual article and don't impact other articles or categories in any way.
    • If an article has inherited restrictions: by default it is set to "Use Inherited Only", but you may Add More Restrictions to require additional group membership to view the article. Add More Restrictions selections don't impact other articles or categories in any way.

Restrict access based on Reader Groups

  1. If you do not have your reader groups set up, you will need to set them up by following these instructions
  2. Create a new category or article (or edit an existing one by clicking on the wrench icon to the right of any content) inside Knowledge Base > Articles.
  3. If the category or article has "None" in the Inherited Restrictions section of the editor:
    • Use the checkboxes under Restrict to Groups in the righthand column to set which groups can see this content. This section looks a little different in the category editor compared to the article editor, but the functionality is the same:
      Sample Restrict to Groups section in the article editor; groups will vary based on your setup
      Sample Restrict to Groups section in the category editor; groups will vary based on your setup
  4. If the category or article has groups listed in the Inherited Restrictions section of the editor:
    • Use the checkboxes to Add More Restrictions to the the content. Readers will have to belong to at least one of these additional groups AND at least one of the inherited groups (possibly more, depending on your knowledge base logic; see How do reader groups work? for more info).
      Sample Add More Restrictions section in the article editor
      Sample Add More Restrictions section in the category editor
  5. Click Save

For more information on how reader group work and what happens when you restrict to multiple reader groups, see How do reader groups work?


Basic authentication

Sometimes, to facilitate integration with a third-party tool, it's useful to have an account that uses basic authentication (basic auth). Basic auth uses an email address and a password, similar to readers set up directly in KnowledgeOwl.

Basic auth can be useful if you have your knowledge base access restricted in one format, but you'd like to give a third-party tool its own reader account to authenticate with. We see this most often used for tools that crawl your knowledge base for various purposes (such as Amazon's Kendra or other chatbot/search integrators).

To enable Basic Authentication in KnowledgeOwl, you need to enable the overall setting in Settings > Security and then configure an individual reader account to use basic auth. See below for more detailed instructions.

Setup

First, enable basic authentication for your knowledge base overall:

  1. Go to Settings > Security.
  2. In the Security Settings section, look for the Basic Authentication subsection.
  3. Check the box next to "Enable designated readers to log in via basic access authentication."
  4. Save your changes.

Once you have basic auth enabled for the knowledge base as a whole, you need to designate a reader account to use that authentication:

  1. Go to Your Account > Readers.
  2. You can choose to create a new reader account to use with basic auth, or edit an existing reader account to use as your basic auth account. Be sure the reader account is set up with a self-administered password.
  3. Once you're in the Edit Reader screen viewing the details of the reader account you'd like to use, look for the Basic Authentication subsection.
  4. Check the box next to "Allow this reader to log in via basic access authentication".
  5. Be sure the reader has access to the appropriate knowledge base(s) and/or reader group(s).
  6. Save your changes.

You can now use the email address and password you set this account up with as the username/password for your third-party tool.

HTTP response headers

In order to improve the security of your knowledge base, you can enable some additional HTTP response headers and/or Content Security Policies that will be returned by our servers that give additional instructions to the reader's browser. The effects of these headers vary and should only be enabled by someone with a clear understanding of what they do.

You can find these settings under Settings > Security in the HTTP Response Headers section. Below we'll provide a brief high level description of what each of these headers is used for.

HTTP Response Header Options

HTTP Strict Transport Security (HSTS)

The HTTP Strict Transport Security header informs the browser that it should never load a site using HTTP and should automatically convert all attempts to access the site using HTTP to HTTPS requests instead. See MDN Web Docs for more info.

X-XSS-Protection: 1

Enables XSS filtering (usually the default in browsers). If a cross-site scripting attack is detected, the browser will sanitize the page (remove the unsafe parts). See MDN Web Docs for more info.

X-Content-Type-Options: nosniff

The X-Content-Type-Options response HTTP header is a marker used by the server to indicate that the MIME types advertised in the Content-Type headers should not be changed and be followed. This is a way to opt out of MIME type sniffing, or, in other words, to say that the MIME types are deliberately configured. See MDN Web Docs for more info.

X-Frame-Options: SAMEORIGIN/DENY

The X-Frame-Options HTTP response header can be used to indicate whether or not a browser should be allowed to render a page in an <iframe>, <embed>, or <object>. Sites can use this to avoid click-jacking attacks, by ensuring that their content is not embedded into other sites. See MDN Web Docs for more info.

Content Security Policy

Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks. These attacks are used for everything from data theft to site defacement to distribution of malware. If you're pulling external resources, the CSP determines which domains are allowed to do certain things, such as run scripts, load resources, and so on. See MDN Web Docs for more info.

You can include domains with and without the scheme (such as https:, wss:, etc.), 'unsafe-eval', and domains with wildcards (*) for any of the CSP directives here.

These options have the most potential to cause unintended consequences for your knowledge base. If you are referencing any remote JavaScript, fonts, images/files, or CSS, you will need to make sure you add the remote domains into this policy or they will be blocked.

Defining the script-src or default-src policy may also prevent the KnowledgeOwl modern widget from rendering (Widget 2.0 will not be affected).

To enable CSP:

We recommend that you:

  1. First, review the individual directives below and add appropriate domains/settings to individual CSP directives (such as default-src, script-src, etc.). See the sections below for more information on each directive.
  2. Once you've reviewed all directives and added appropriate domains and resources, check the box to Enable content security policy header.
  3. You'll be presented with a pop-up confirming you're ready to enable. You must select Enable to proceed.
    Enable content security policy headers confirmation pop-up
  4. CSP won't be fully enabled until you Save.
  5. We recommend navigating around your knowledge base after you've enabled the CSP to ensure that you didn't overlook any necessary domains or resources. Console errors can help you identify things you missed!

default-src

This CSP directive is used as a fallback when any of the others don't have values specified. See MDN Web Docs for more information. We include default-src *.knowledgeowl.com, 'self', 'unsafe-inline', and a few other required resources here even if you don't specify them.

script-src

This CSP directive specifies valid sources for JavaScript. This includes not only URLs loaded directly into <script> elements, but also things like inline script event handlers like onclick. See MDN Web Docs for more information.

If you're using the Fancy Box plugin for images, include cdnjs.cloudflare.com in this list. You may also want to add 'unsafe-eval' to this list. See MDN Web Docs for more information.

Before you enable, consider checking these places for domains you may be running scripts from and be sure you've added them to this directive:

  • Settings > Style > Custom HTML: Body, Article, etc.
  • Settings > Style > Custom Head
  • Library > Snippets: Check individual snippets that may be running scripts themselves

style-src

This CSP directive specifies valid sources for stylesheets. See MDN Web Docs for more information.

If you're using the Fancy Box plugin for images, include cdnjs.cloudflare.com in this list.

Before you enable, consider checking these places for references to external stylesheets and be sure you've added them to this directive:

  • Settings > Style > Custom HTML: Body, Article, etc.
  • Settings > Style > Custom Head
  • Library > Snippets: Check individual snippets that may be running scripts themselves

font-src

This CSP directive specifies valid sources for fonts loaded using @font-face. See MDN Web Docs for more information.

Before you enable, consider checking these places for references to font-face rules containing external resources:

  • Settings > Style > Fonts: If a Custom Font is selected, be sure to add that domain.
  • Settings > Style > Custom CSS: Look for any font-face rules.
  • Settings > Style > Custom Head: Look for any font references outside of KnowledgeOwl.
  • Library > Snippets: Check individual snippets to be sure they don't have font-face rules.

img-src

This CSP directive specifies valid sources for images and favicons. See MDN Web Docs for more information.

Before you enable, consider checking these places for references to images outside of KnowledgeOwl:

  • Settings > Style > Custom Head
  • Settings > Style > Custom CSS
  • Settings > Style > Custom HTML: Body, Home Page, Article, etc.
  • Individual snippets or articles containing external images in the body or in article thumbnails/banners

Requiring login to view files/images

The Security Settings for your knowledge base (Settings > Security) determine the general security requirements for readers to access your knowledge base.

The files you upload to your knowledge base--PDFs, Excel sheets, screenshots, Word documents, etc.--do not automatically use this same security.

By default, even if your knowledge base requires login, the files you've uploaded do not require login. This is by design so that you can give customers the link to specific documents and they can easily download the file by clicking on that link or URL without having to log in to your knowledge base.

However, you can adjust your security settings so that readers have to be logged in to access files and images stored within your knowledge base.  If you make this change, the URLs you'll see will change slightly to a different cloudfront URL.

With authentication required, if you share a hyperlink directly to a file stored in KnowledgeOwl, anyone accessing that link will be prompted to log in to the knowledge base using the default authentication method before they'll be able to view the file.

When this secure file library setting is enabled, you'll no longer see your knowledge base's logo when you're viewing the KnowledgeOwl app dashboard (/app/switch-project). The logos often showed as broken images until you'd opened the knowledge base. We felt hiding the logo entirely was a better experience than showing you a broken logo link. They'll only be hidden from the app switch-project view; they're still shown everywhere else!

If you would like to require that someone must log into your knowledge base before accessing files:

  1. Go to Settings > Security.
  2. In the Reader Options section, check the Image / File Resources box next to "Require authentication to view any image or file from your file library."
    Check the box here to require login to view all files and images
  3. You'll receive a warning asking you if you're sure you want to do this. Click Cancel to keep files unauthenticated; click Proceed anyway to continue with requiring login to view files.
    File authentication confirmation screen
  4. Be sure to Save your changes.

Once these changes are saved, we will programmatically update the URL for most of your files referenced in your knowledge base's theme, within articles, and within article thumbnails/banners and category icons. If you are using URL redirect categories or articles pointing to files stored in KnowledgeOwl, you may need to manually update those URLs.

Some customers who require file authentication have noticed some issues with their upper left logos not loading properly on initial page load. If you make this change and notice issues with your logo, please contact us and let us know you're having issues. We can move your logo file to unrestricted storage so it will load faster.

Spam protection

If any part of your knowledge base is publicly available, you're probably interested in preventing spam from reaching you!

There are three main areas you can get spam from:

KnowledgeOwl provides two ways for you to prevent spam:

ReCAPTCHA

reCAPTCHA is a free service from Google that helps prevent spam activity in your knowledge base.

It's designed to verify that someone signing up for a subscription is a real person and not a bot. A "CAPTCHA" is a simple test--usually a task that is very easy for a human to perform, but hard for bots and other malicious software to figure out. There are two versions of reCAPTCHA:

  • v2: Verify requests with a challenge. Example: checking a box next to "I am not a robot."
  • v3: Verify requests with a score. Example: click on all the images that have cars in them.

KnowledgeOwl currently supports specific versions in specific places:

  • v2: Supported in the full knowledge base; not supported in Contextual Help Widget (2.0). For these reCAPTCHAs, configurations with "I am not a robot" reCAPTCHAs, and you can see one in action if you try to subscribe to a category in this knowledge base.
  • v3: Supported in Contextual Help Widget (2.0); not supported in the full knowledge base.

Only v2 reCAPTCHAs will work properly in your main knowledge base. We've tested our configurations with "I am not a robot" reCAPTCHAs, and you can see one in action if you try to subscribe to a category in this knowledge base!

See Add reCAPTCHA for more information on setting up reCAPTCHA.

Pros

  • Free service provided by Google
  • Once set up, you don't have to think about it
  • Most readers are familiar with reCAPTCHA processes, since they're used so many places
  • Generally very effective at blocking spambot traffic

Cons

  • Requires you to set up one or more site keys and secrets with Google and get them configured
  • People can get caught in a reCAPTCHA loop, depending on the type of reCAPTCHA you've selected--this is why we recommend using the checkbox version rather than the "select all pictures of xx" version
  • reCAPTCHA is a Google-supported tool, and particularly if you have GDPR requirements or concerns, reCAPTCHA might not be a viable option

Honeypot

Honeypots are an alternative way to handle spam protection. Honeypots are used in a variety of ways, but the basic gist is that they create something that is enticing and somewhat irresistible to bad actors.

For things like contact forms, this means that instead of making all readers complete an action or test before they can submit a form, a honeypot might include some hidden form fields that no human will see. Spambots do see them and generally fill them out. Submissions with these fields completed are ignored.

Honeypots might also include time or repeat submission restrictions, where they'll flag repeated submissions from the same reader within xx seconds of each other, or flag submissions that took fewer than xx seconds to fill out.

Our built-in honeypot function works similarly to these options (though for security reasons, we can't tell you the full details!).

Pros

  • Simple setup: check a box, Save, and you're done; no registration or site keys to configure
  • Better end-user experience for your average human reader (no tests/tasks to complete)

Cons

  • If someone seriously wants to attack and spam you, they can figure a honeypot out and bypass it, so they aren't as effective as reCAPTCHA when it comes to dedicated malicious attackers