How to Implement OAuth in a Chrome Extension - Wildfire Support Center

How to Implement OAuth in a Chrome Extension

15 min

Overview

These are general guidelines on how to implement OAuth in a Chrome extension.

Things to note before getting started:

The permissions of the token you will be sending from your server must be safe enough to be exposed publicly.
This method only verified to work with Chrome, Firefox, and Safari Desktop extensions. Safari on iOS has special security precautions when redirecting to a non HTTPS protocol, so this method will need some modifications to work on Safari for iOS. Ideally, you would use the native iOS app to handle logins for your extension.
To fully understand this tutorial, some knowledge of how Chrome extensions work is required. Please check the documentation for basic information on getting a Chrome extension set up and how they work.
The v2 manifest version is used in the examples.
Here is the example code used in this tutorial:

The first step in this process is creating an HTML page that your server will redirect to. This HTML page will be hosted within the extension itself, not on a server, which helps maintain a secure environment.

The common pattern that we see is having the HTML page display a loading screen while your .js file parses the URL to grab the token passed back from your server.

Here are the example pages we have created:

oauth.html

oauth.html 1 2 3 4 5 6 7Loading 8 9 10

11 12 13

oauth.js

oauth.js 1// Example URL: https://examplelogin.com?access_token=token&=refresh_token=token 2const url = new URL(window.location.href); 3const accessToken = url.searchParams.get("access_token"); 4const refreshToken = url.searchParams.get("refresh_token"); 5 6chrome.runtime.sendMessage({ 7 type:"OAUTH_TOKEN_RECIEVED", 8 payload:{ 9 accessToken, 10 refreshToken, 11 }, 12});

Update your manifest.json and specify your oauth.html file, so it can be accessed as a resource. You will also need the “tabs” permission for the later steps.

1{
2  "manifest_version": 2,
3  "name": "Example",
4  "description": "Example",
5  "version": "1.0.0",
6  "background": {
7    "scripts": ["background.js"]
8  },
9  "content_scripts": [
10    {
11      "js": ["content.js"],
12      "matches": ["<all_urls>"]
13    }
14  ],
15  "web_accessible_resources": ["oauth.html"],
16  "browser_action": {
17    "default_popup": "popup.html",
18    "default_icon": {
19      "16": "images/toolbar-icon-16.png",
20      "19": "images/toolbar-icon-19.png",
21      "32": "images/toolbar-icon-32.png",
22      "38": "images/toolbar-icon-38.png"
23    }
24  },
25  "permissions": ["tabs"]
26}

Request the Token

Now that we have built out the pages to receive the token, we can work on requesting the token.

Add a login button to our popup.html file:

1<!DOCTYPE html>
2<html>
3<head>
4<meta charset="UTF-8"/>
5<link rel="stylesheet" href="popup.css"/>
6</head>
7<body>
8<button>Login</button>
9<script src="popup.js"></script>
10</body>
11</html>

Here is our popup.js file:

1const button = document.querySelector("button");
2
3button.onclick = () =>
4  chrome.runtime.sendMessage({
5    type: "OAUTH_TOKEN_REQUEST",
6  });

This will create a simple HTML page that displays when you click the icon in your browser:

When we click the login button, it sends a message to that background script to request the OAuth token. Modify the background.js file to handle the request:

1chrome.runtime.onMessage.addListener(({ type, payload }) => {
2  switch (type) {
3    case "OAUTH_TOKEN_REQUEST":
4      const oauth = chrome.runtime.getURL("oauth.html");
5      const exampleLoginPage = "<https://examplelogin.com>";  
6      const url = new URL(exampleLoginPage);
7      url.searchParams.append("ext", oauth);
8      console.log(url.toString());
9      break;
10  }
11});

If you were to check your background console, you should see an output like this:

1<https://examplelogin.com/?ext=chrome-extension%3A%2F%2Fjiaieifpmjjbmaghajbhhppmhfgbikpp%2Foauth.html>

Note example link will be replaced by your login URL.

Option #1: Send access token

After the user has logged in successfully, redirect the user to the URL located in the ext parameter with the token attached.

1const url = req.query.ext + `?access_token=${accessToken}&refresh_token=${refreshToken}`;
2res.redirect(url);

Store the Token

After the redirect is successful, your oauth.js file will be able to send the token back to your background script to store.

1chrome.runtime.onMessage.addListener(({ type, payload }) => {
2  switch (type) {
3    case "OAUTH_TOKEN_REQUEST":
4      const oauth = chrome.runtime.getURL("oauth.html");
5      const exampleLoginPage = "<https://examplelogin.com>";
6      const url = new URL(exampleLoginPage);
7      url.searchParams.append("ext", oauth);
8      chrome.tabs.create({
9        active: true,
10        url: url.toString(),
11      });
12      break;
13    case "OAUTH_TOKEN_RECIEVED":
14      const { accessToken, refreshToken } = payload;
15      console.log("Recieved: ", accessToken, refreshToken);
16      break;
17  }
});

Option #2: Send tracking code

Alternatively, you can send the tracking code you would like used for the user directly, avoiding the OAuth flow. The UUID is the only value required by the extension so things can be simplified by just providing the extension with the UUID that should be used as the tracking code.

1const url = req.query.ext + `?uuid=<TRACKING CODE>`;
2res.redirect(url);

You can test this without logging in by grabbing your URL from the background console by calling:

1chrome.runtime.getURL("oauth.html");

Or by adding example tokens in the URL and pasting the link in your browser:

Congratulations, you have implemented OAuth in a Chrome Extension!

Updated 17 Jun 2026