Some third-party tools, especially AI-based tools or crawlers, prefer to use 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 Security and access > Security settings and then configure an individual reader account to use basic auth. Your third-party tool can then use those reader account credentials and a special basic login page (/basic-login
) to more easily crawl your knowledge base. Refer to the more detailed instructions below.
Knowledge base setup
First, enable basic authentication for your knowledge base overall:
- Go to Security and access > Security settings.
- In the Authentication settings section, check the Allow basic authentication box to Enable designated readers to log in via basic access authentication:
Check the box to Enable designated readers to log in via basic access authentication
- Save your changes.
Basic auth is now turned on for your knowledge base and the /basic-login
page is now available.
Reader setup
Once you have basic auth enabled for the knowledge base as a whole, designate a reader account to use that authentication:
- Go to Security and access > Readers (or Account > Readers).
- Choose whether you want 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.
- Once you're in the Edit Reader screen viewing the details of the reader account you'd like to use, check the Basic Authentication box to Allow this reader to log in via basic access authentication:
Check the box to Allow this reader to log in via basic access authentication.
- Be sure the reader has access to the appropriate knowledge base(s) and/or reader group(s).
- Save your changes.
Your basic auth reader account exists. To test it, go to your knowledge base homepage and add /basic-login
to the URL. For example, here on our Support KB, our homepage URL is https://support.knowledgeowl.com/help
so we'd use https://support.knowledgeowl.com/help/basic-login
. Enter the basic auth reader's email address and password. Once you've confirmed you can login, follow the instructions in the next section to use basic auth.
Use basic auth
To use your basic auth reader account, set up your third-party tool using these settings:
- Account: Add the basic auth reader account's email address and password as the username and password for your tool.
- Login URL: Instead of using our built-in reader login page or any SSO or remote authentication login pages, copy your knowledge base's homepage URL and add
/basic-login
to the URL. For example, here on our Support KB, our homepage URL ishttps://support.knowledgeowl.com/help
so we'd usehttps://support.knowledgeowl.com/help/basic-login
.
We recommend using this basic-login URL instead of other login URLs because many HTTP libraries that use basic auth expect an initial 401 response and a specific set of header responses that our other login options don't support. The basic-login page applies special logic to return the 401 response and use the "Authorization: Basic..." request header on all subsequent responses, which should ensure your third-party tool can properly crawl your knowledge base.
Basic auth reader required
The /basic-login
page only works if you have basic auth turned on in your knowledge base and you use a basic auth reader's credentials. Other reader accounts or SSO accounts can't use this login page.