Authenticate with Firebase in a Chrome extension

This document shows you how to useFirebase Authentication to sign users into a Chromeextension that usesManifest V3.

Firebase Authentication provides multiple authentication methods to sign in users froma Chrome extension, some requiring more development effort than others.

To use the following methods in a Manifest V3 Chrome extension, you need onlyimport them fromfirebase/auth/web-extension:

  • Sign in with email and password (createUserWithEmailAndPassword andsignInWithEmailAndPassword)
  • Sign in with email link (sendSignInLinkToEmail,isSignInWithEmailLink, andsignInWithEmailLink)
  • Sign in anonymously (signInAnonymously)
  • Sign in with a custom authentication system (signInWithCustomToken)
  • Handle provider sign-in independently then usesignInWithCredential

The following sign in methods are also supported but require some additional work:

  • Sign in with a pop-up window (signInWithPopup,linkWithPopup, andreauthenticateWithPopup)
  • Sign in by redirecting to the sign-in page (signInWithRedirect,linkWithRedirect, andreauthenticateWithRedirect)
  • Sign in with Phone Number with reCAPTCHA
  • SMS multi-factor authentication with reCAPTCHA
  • reCAPTCHA Enterprise protection

To use these methods in a Manifest V3 Chrome extension, you must useOffscreen Documents.

Use the firebase/auth/web-extension entry point

Importing fromfirebase/auth/web-extension makes signing in users from aChrome extension similar to a web app.

firebase/auth/web-extension is only supported on the Web SDK versions v10.8.0and above.

import{getAuth,signInWithEmailAndPassword}from'firebase/auth/web-extension';constauth=getAuth();signInWithEmailAndPassword(auth,email,password).then((userCredential)=>{// Signed inconstuser=userCredential.user;// ...}).catch((error)=>{consterrorCode=error.code;consterrorMessage=error.message;});

Use Offscreen Documents

Some authentication methods, such assignInWithPopup,linkWithPopup, andreauthenticateWithPopup, aren't directly compatible with Chrome extensions,because they require code to be loaded from outside of the extension package.Starting in Manifest V3, this isn't allowed and will be blocked by theextension platform. To get around this, you can load that code withinan iframe using anoffscreen document.In the offscreen document, implement the normal authentication flow and proxy theresult from the offscreen document back to the extension.

This guide usessignInWithPopup as an example, but the same conceptapplies to other authentication methods.

Before you begin

This technique requires you to set up a web page that is available on the web,that you will load in an iframe. Any host works for this, includingFirebase Hosting.Create a website with the following content:

<!DOCTYPE html><html>  <head>    <title>signInWithPopup</title>    <script src="signInWithPopup.js"></script>  </head>  <body><h1>signInWithPopup</h1></body></html>

Federated sign in

If you are using federated sign in, such as sign in with Google, Apple, SAML, orOIDC, you must add your Chrome extension ID to the list of authorizeddomains:

  1. Open your project in theFirebase console.
  2. In theAuthentication section, open theSettings page.
  3. Add a URI like the following to the list of Authorized Domains:
    chrome-extension://CHROME_EXTENSION_ID

In your Chrome extension's manifest file make sure that you add the followingURLs to thecontent_security_policy allowlist:

  • https://apis.google.com
  • https://www.gstatic.com
  • https://www.googleapis.com
  • https://securetoken.googleapis.com

Implement authentication

In your HTML document, signInWithPopup.js is the JavaScript code that handlesauthentication. There are two different ways to implement a method that isdirectly supported in the extension:

  • Usefirebase/auth/web-extension in your extension code such as background scripts, service workers, or popup scripts.Usefirebase/auth only inside your offscreen iframe, because that iframe runs in a standard web page context.
  • Wrap the authentication logic in apostMessage listener, in order to proxy the authentication request and response.
import{signInWithPopup,GoogleAuthProvider,getAuth}from'firebase/auth';import{initializeApp}from'firebase/app';importfirebaseConfigfrom'./firebaseConfig.js'constapp=initializeApp(firebaseConfig);constauth=getAuth();// This code runs inside of an iframe in the extension's offscreen document.// This gives you a reference to the parent frame, i.e. the offscreen document.// You will need this to assign the targetOrigin for postMessage.constPARENT_FRAME=document.location.ancestorOrigins[0];// This demo uses the Google auth provider, but any supported provider works.// Make sure that you enable any provider you want to use in the Firebase Console.// https://console.firebase.google.com/project/_/authentication/providersconstPROVIDER=newGoogleAuthProvider();functionsendResponse(result){globalThis.parent.self.postMessage(JSON.stringify(result),PARENT_FRAME);}globalThis.addEventListener('message',function({data}){if(data.initAuth){// Opens the Google sign-in page in a popup, inside of an iframe in the// extension's offscreen document.// To centralize logic, all respones are forwarded to the parent frame,// which goes on to forward them to the extension's service worker.signInWithPopup(auth,PROVIDER).then(sendResponse).catch(sendResponse)}});

Build your Chrome Extension

After your website is live, you can use it in your Chrome Extension.

  1. Add theoffscreen permission to your manifest.json file:
    2. {"name":"signInWithPopup Demo","manifest_version"3,"background":{"service_worker":"background.js"},"permissions":["offscreen"]}
  2. Create the offscreen document itself. This is a minimal HTML file inside of your extension package that loads the logic of your offscreen document #"no" dir="ltr" is-upgraded syntax="HTML"> <!DOCTYPE html> <script src="./offscreen.js"></script>
  3. Includeoffscreen.js in your extension package. It acts as the proxy between the public website set up in step 1 and your extension.
    4. // This URL must point to the public siteconst_URL='https://example.com/signInWithPopupExample';constiframe=document.createElement('iframe');iframe.src=_URL;document.documentElement.appendChild(iframe);chrome.runtime.onMessage.addListener(handleChromeMessages);functionhandleChromeMessages(message,sender,sendResponse){// Extensions may have an number of other reasons to send messages, so you// should filter out any that are not meant for the offscreen document.if(message.target!=='offscreen'){returnfalse;}functionhandleIframeMessage({data}){try{if(data.startsWith('!_{')){// Other parts of the Firebase library send messages using postMessage.// You don't care about them in this context, so return early.return;}data=JSON.parse(data);self.removeEventListener('message',handleIframeMessage);sendResponse(data);}catch(e){console.log(`json parse failed -${e.message}`);}}globalThis.addEventListener('message',handleIframeMessage,false);// Initialize the authentication flow in the iframed document. You must set the// second argument (targetOrigin) of the message in order for it to be successfully// delivered.iframe.contentWindow.postMessage({"initAuth":true},newURL(_URL).origin);returntrue;}
  4. Set up the offscreen document from your background.js service worker.
    5. import{getAuth}from'firebase/auth/web-extension';constOFFSCREEN_DOCUMENT_PATH='/offscreen.html';// A global promise to avoid concurrency issuesletcreatingOffscreenDocument;// Chrome only allows for a single offscreenDocument. This is a helper function// that returns a boolean indicating if a document is already active.asyncfunctionhasDocument(){// Check all windows controlled by the service worker to see if one// of them is the offscreen document with the given pathconstmatchedClients=awaitclients.matchAll();returnmatchedClients.some((c)=>c.url===chrome.runtime.getURL(OFFSCREEN_DOCUMENT_PATH));}asyncfunctionsetupOffscreenDocument(path){// If we do not have a document, we are already setup and can skipif(!(awaithasDocument())){// create offscreen documentif(creating){awaitcreating;}else{creating=chrome.offscreen.createDocument({url:path,reasons:[chrome.offscreen.Reason.DOM_SCRAPING],justification:'authentication'});awaitcreating;creating=null;}}}asyncfunctioncloseOffscreenDocument(){if(!(awaithasDocument())){return;}awaitchrome.offscreen.closeDocument();}functiongetAuth(){returnnewPromise(async(resolve,reject)=>{constauth=awaitchrome.runtime.sendMessage({type:'firebase-auth',target:'offscreen'});auth?.name!=='FirebaseError'?resolve(auth):reject(auth);})}asyncfunctionfirebaseAuth(){awaitsetupOffscreenDocument(OFFSCREEN_DOCUMENT_PATH);constauth=awaitgetAuth().then((auth)=>{console.log('User Authenticated',auth);returnauth;}).catch(err=>{if(err.code==='auth/operation-not-allowed'){console.error('You must enable an OAuth provider in the Firebase'+' console in order to use signInWithPopup. This sample'+' uses Google by default.');}else{console.error(err);returnerr;}}).finally(closeOffscreenDocument)returnauth;}

    Now, when you callfirebaseAuth() within your service worker, it will createthe offscreen document and load the site in an iframe. That iframe will processin the background, and Firebase will go through the standard authenticationflow. Once it has either been resolved or rejected, the authentication objectwill be proxied from your iframe to your service worker, using the offscreendocument.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-05 UTC.