Widget authentication--when and how to use it

If you're thinking of using the embeddable web widget, you'll need to consider:

  1. Whether you need authentication for the widget
  2. Which type of authentication method to use

Since the answers to these question involve a few variables, here are some resources to help you determine whether you need to authenticate the widget and which type of authentication might be right for you.

Do I need to authenticate my widget?

If your knowledge base is completely public--requiring no login to view any content--you do not need to authenticate your widget.

If your knowledge base requires a login to view some or all of the content, you generally do need to authenticate the widget.

If your knowledge base restricts content to specific reader groups and you want some or all of the groups' content to display, you'll need to pass along group membership in the authentication.

Here are the most common knowledge base configurations and whether you'll need to authenticate your widget for each:

Knowledge Base TypeIs authentication required?Unauthenticated WidgetGroup membership included with authentication?Authenticated Widget
Public KB (no login required for any content)NoAll content shows in the widgetN/ANot necessary (but all content will show)
Public KB with some restricted content requiring loginNo, if you want it to display public content only
Yes, if you want it to display restricted content
Only the public content showsNecessary to display restricted content appropriatelyAll public content  + all restricted content for the relevant groups shows
Private KB (requires login to access KB) but no reader group restrictions on specific contentYesWidget will open but shows an endless spinner with no contentNot necessaryAll content will show
Private KB (requires login to access KB) with some or all content restricted to specific reader groupsYesWidget will open but shows an endless spinner with no contentNecessary to display restricted content appropriatelyAll unrestricted content + all restricted content for the relevant groups shows

Which type of authentication do I need?

We offer two types of authentication for Widget 2.0:

Either authentication mechanism may be used.

However, JWT payloads are not encrypted, so if you consider any of the information you're passing along in the authentication to be sensitive data (such as reader email addresses, reader groups, etc.), you should use Oauth2.

Will an authenticated widget work in all browsers?

Generally, yes, but some browsers disable cookies by default. (We're looking at you, Safari, though some IT policies will also restrict cookie usage.)

In browsers with cookies enabled, you'll see the full widget functionality when the widget is authenticated.

In browsers with cookies disabled, you'll see nearly full widget functionality when the widget is authenticated. The one exception to this is the "Open in full site" link in the footer. This action is cookie-dependent so the link won't be displayed at all when someone accesses your authenticated widget through a browser with cookies disabled.

Use Cases

Mixture of public and private

One of Linus's knowledge bases has mostly public documentation, in the form of product support documentation, with a few restricted articles containing internal support documentation.

If Linus is embedding the widget into his end-product, so it's being opened mainly by customers--who only normally see the public documentation--he can use an unauthenticated widget here. The widget will only pull the public documentation.

If, however, Linus wants to embed the widget into his help ticketing system so that his customer support staff can access it from there, he'd want to use an authenticated widget that opens the widget as the Internal Support reader group, so the support staff would see both the public content and the restricted internal support content.

Login required, but all content visible

One of Linus's knowledge bases is designed for his enterprise clients, to provide additional information to them. This requires login, since he wants only specific clients to have access and he doesn't want the documentation available to the general public. But he doesn't restrict or segregate the content in any way.

Linus is embedding the widget in his enterprise application's home page, which is only accessed by enterprise customers. He wants the entire knowledge base to be accessible in the widget.

Linus can set up the widget with either JWT or Oauth2 authentication to show all enterprise customers the same content. The authentication script won't need to pass in group membership because there is none.

Specific reader restrictions

One of Linus's other knowledge bases is completely private, containing internal policies and procedures. Besides requiring a login, the content is also heavily segregated by reader groups, so that HR only sees HR documentation; compliance only sees compliance and regulatory docs; and so on.

Linus is embedding the widget into his company's intranet portal, and he still wants the reader group restrictions to be enforced. His knowledge base uses Single Sign-On integration, so the login his coworkers use on the portal is also their login for the knowledge base. For this widget, he can use either JWT or Oauth2 authentication and pass the reader groups along with the authentication, so the widget knows which portions of content it should display to each reader.

If he has security concerns around passing email address, reader group names, or other sensitive data to the client as part of authentication, he should use Oauth2.