Modern Slideout Widget Authentication with OAuth2

As of August 2022, we have deprecated the Legacy and Modern widgets. See Deprecation of Modern & Legacy widget for more information.

If your site is restricted behind reader logins or one of the other security options we offer, you can enable the "Secure widget access using OAuth2" option on Settings > Widget to give your readers access to your content inside of the widget.

When this option is enabled, the widget will not work unless a valid OAuth2 token is passed through on initiation. To pass the OAuth token through, make sure your widget embed code includes the applicable line from below:

//Modern Slideout Widget
_ko16_p.push(['_setToken', 'OAUTH2 TOKEN']);

//Legacy Popover Widgets
_helpgizmo_p.push(['_setToken', 'OAUTH2 TOKEN']);

To retrieve an OAuth2 token, you will first need to generate the Client Secret for your knowledge base.

  1. Go to Settings > Widget.
  2. In the Admin Settings section, select the "Generate Client Secret button underneath OAuth Authentication.
  3. This will display a Client ID and Client Secret.

Now that you have your client secret and client ID, you can use them to request an access token from the OAuth token endpoint.  See below for workflow examples.

Should you ever need to regenerate your client secret, you can do so using the Regenerate OAuth Secret button on this page. Note that regenerating a secret will immediately invalidate your existing secret, so your widget authentication will basically be broken until you update it to use the new secret.

Request Token

//Basic curl request for token without reader information
curl -u clientID:clientSecret https://app.knowledgeowl.com/oauth2/token -d "grant_type=client_credentials"

//curl request for token with reader information
curl -u clientID:clientSecret https://app.knowledgeowl.com/oauth2/token 
-d "grant_type=client_credentials&reader[ssoid]=UID&reader[username]=reader@mysite.com&reader[groups]=Group1,Group2"

Example Response

{"access_token":"1234567890987654321234567890987654321234","expires_in":3600,"token_type":"Bearer","scope":null}

Widget Embed Code with Token

var _ko16_p = _ko16_p || [];
_ko16_p.push(['_setProject', '123abc1231231abc123-123abn1231123abnc']);
_ko16_p.push(['_setToken', 'Oauth Token']);
(function() {
	setTimeout(function(){
		var ko = document.createElement('script');
		ko.type = 'text/javascript';
		ko.async = true;
		ko.src = "//yourkbURL/javascript/ko-index?__pc=123abc1231231abc123-123abn1231123abnc"; //kb -- with demo content
		document.head.appendChild(ko);
	},250);
})();