Modern Slideout Widget Authentication with OAuth2

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 KB 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 KB settings > Widget.
2. In the Admin Settings section, select Generate Client Secret underneath OAuth Authentication.
3. A Client ID and Client Secret display.

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

Get new client secret

You can generate a new OAuth client secret at any time.

To do so:

1.  Go to KB settings > Widget.
2. In the Admin Settings section, underneath OAuth Authentication, select Regenerate OAuth Secret.

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

Here's a sample curl request to get the 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

The above request returns your access token with some additional information, like this:

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

Widget Embed Code with Token

And here's how you might pass it into your widget embed code:

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);
})();