If you're thinking of using the embeddable web widget, you'll need to consider:
- Whether you need authentication for the widget
- 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 Type | Is authentication required? | Unauthenticated Widget | Group membership included with authentication? | Authenticated Widget |
|---|---|---|---|---|
| Public KB (no login required for any content) | No | All content shows in the widget | N/A | Not necessary (but all content will show) |
| Public KB with some restricted content requiring login | No, if you want it to display public content only Yes, if you want it to display restricted content | Only the public content shows | Necessary to display restricted content appropriately | All public content + all restricted content for the relevant groups shows |
| Private KB (requires login to access KB) but no reader group restrictions on specific content | Yes | Widget will open but shows an endless spinner with no content | Not necessary | All content will show |
| Private KB (requires login to access KB) with some or all content restricted to specific reader groups | Yes | Widget will open but shows an endless spinner with no content | Necessary to display restricted content appropriately | All 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 homepage, 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.
