Integrating with Chrome extensions using OAuth

Hey everyone :wave: my name’s Adam and I’ve been a Customer Support Engineer here at Intercom for over 2 years now. Throughout my time being a support engineer I’ve seen the developer platform evolve from a place where we would manually review each request to generate a Rest API Key to the growing community we have today.

One topic I’ve been wanting to bring up now for some time is integrating Intercom with a browser extension.

Note
This topic isn’t about installing the Intercom Messenger in a browser extension but rather it’s a guide for 3rd party developers on how to retrieve end user Access Tokens through OAuth and store them completely on the client side.

This isn’t an official Intercom integration guide but rather just a side project I’ve been working on.

In The Past
To give some context, integrating with Intercom in the past was a lot different than our current workflows. Each Intercom workspace only had a single Rest API Key that had full permissions. This led to a not so great “copy and paste your API Key” style for 3rd party integrations. In order for a 3rd party to integrate with your Intercom workspace they would ask you to give them your only API Key with unrestricted access to all of your Intercom data :grimacing:

During this period of time there were some pretty neat browser extensions developed like this one which would scan your current page for email addresses and import them into your workspace:

When we got serious about enabling 3rd party developers we revamped our integration process to use the industry standard OAuth protocol and made the “copy and paste your API Key” style against our terms of service:
image

The unfortunate side effect of this necessary revamp is that previous integrations like the one above stopped working unless they also switched over. For the most part the Intercom development community has successfully made the switch to using OAuth. However, I haven’t noticed any working browser extension that currently integrates with us.

Integrating Chrome Extensions Using OAuth
Since I couldn’t find any browser extensions that integrated with Intercom through OAuth I wanted to pave the way. My hope is that if there’s another developer who wants to integrate Intercom into their browser extension then this will hopefully make their life easier :pray: I also wanted this extension to work completely on the client to limit the barriers of needing an external server.

Introducing the Intercom Lead Creator extension on the Chrome app store:

This is mostly a proof of concept project that allows you to manually create new lead accounts in Intercom. This extension uses Intercom’s OAuth on the client side to get an Access Token for your Intercom workspace. The extension then stores the Access Token in Chrome’s local storage and provides you with an interface to create leads through Intercom’s Rest API using the token.

The code for this extension and how it works can be found in this GitHub repo:

To make the integration process as easy as possible I also created a boilerplate extension that includes instructions on how to integrate the commented code into your extension that can all be found this GitHub repo:

Security
The biggest risk factor for this project was security. If I couldn’t find a way to retrieve and store an Access Token securely all being done on the client side then this project would fail. I looked through official Chrome example extensions and ran some of these concepts by our security team but since I’m not an extension developer I wanted to dedicate a section of this topic to go over my findings.

The first step in the OAuth process is to prompt the end user with an OAuth window. Chrome has a method for doing this:
https://developer.chrome.com/apps/identity#method-launchWebAuthFlow

The OAuth flow we’ll be following is the one outlined in Intercom’s developer docs:

During this OAuth flow you’ll need to send a Post request to:
https://api.intercom.io/auth/eagle/token?code=+code+&client_id=+CLIENT_ID+&client_secret=+CLIENT_SECRET

If we want this extension to work completely on the client side that means you’ll need to have your client_id and client_secret hard coded into your extension. This sounds scary but to the best of my knowledge there’s not much someone can maliciously do with these two values. The reason is that you set the redirect urls in your App’s developer hub as shown here:

This means that even if a malicious party uses your client_id and client_secret to attempt to impersonate your app, if an end user does approve authorization then the authorization code will be sent to only your approved redirect url and not the malicious party.

Here’s the GitHub repo of an official Chrome example extension that shows this hard coded client_id and client_secret method being used:

Continuing the OAuth flow, you’ll eventually receive an Access Token for the end user’s Intercom workspace. Since we’re handling everything on the client side we’ll want to store it for later use. Chrome does have a storage method we can use:
https://developer.chrome.com/apps/storage

It’s worth noting that the Access Token stored wouldn’t be encrypted:
image

However, to the best of my knowledge the only sources that can access the extension’s local storage are the extensions itself and whoever is on the device. So if the device was compromised then the Access Token could be compromised too. This shouldn’t be too different than storing a token in Postman for example. Here’s also an official Chrome example extension that stores an Access Token in local storage:

So those are the major risks I identified if you wanted to handle everything on the client side. I can’t say I’m an expert on browser extensions by any means but if there’s anything I missed then feel free to let me know :slightly_smiling_face:

Non Chrome Browsers
For this project I did everything in Chrome but from what I’ve looked at the basic concept should be similar to that on Firefox and other browsers.

4 Likes