אימות באמצעות Firebase בתוסף ל-Chrome

במסמך הזה מוסבר איך להשתמש ב-Firebase Authentication כדי להכניס משתמשים לחשבון ב-Chrome תוסף שמשתמש במניפסט V3.

Firebase Authentication מספק כמה שיטות אימות לכניסה של משתמשים מתוסף Chrome, חלקן דורשות יותר מאמצים לפיתוח מאחרות.

כדי להשתמש בשיטות הבאות בתוסף ל-Chrome עם מניפסט V3, צריך רק לייבא אותן מ-firebase/auth/web-extension:

  • נכנסים באמצעות כתובת האימייל והסיסמה (createUserWithEmailAndPassword ו-signInWithEmailAndPassword)
  • כניסה באמצעות קישור לאימייל (sendSignInLinkToEmail,‏ isSignInWithEmailLink ו-signInWithEmailLink)
  • כניסה באופן אנונימי (signInAnonymously)
  • כניסה באמצעות מערכת אימות בהתאמה אישית (signInWithCustomToken)
  • צריך לטפל בכניסה של הספק בנפרד ואז להשתמש ב-signInWithCredential

יש תמיכה גם בשיטות הכניסה הבאות, אך דורשות עבודה נוספת:

  • כניסה באמצעות חלון קופץ (signInWithPopup, linkWithPopup ו-reauthenticateWithPopup)
  • כניסה לחשבון באמצעות הפניה לדף הכניסה (signInWithRedirect,‏ linkWithRedirect ו-reauthenticateWithRedirect)
  • כניסה באמצעות מספר טלפון באמצעות reCAPTCHA
  • אימות רב-שלבי של הודעות SMS באמצעות reCAPTCHA
  • הגנת reCAPTCHA Enterprise

כדי להשתמש בשיטות האלה בתוסף מניפסט מגרסה V3 ל-Chrome, צריך להשתמש הסר מסמכים מהמסך.

שימוש בנקודת הכניסה firebase/auth/web-extension

ייבוא מ-firebase/auth/web-extension הופך את הכניסה למשתמשים תוסף ל-Chrome בדומה לאפליקציית אינטרנט.

יש תמיכה ב-firebase/auth/web-extension רק בגרסאות 10.8.0 של Web SDK ומעלה.

import { getAuth, signInWithEmailAndPassword } from 'firebase/auth/web-extension';

const auth = getAuth();
signInWithEmailAndPassword(auth, email, password)
  .then((userCredential) => {
    // Signed in
    const user = userCredential.user;
    // ...
  })
  .catch((error) => {
    const errorCode = error.code;
    const errorMessage = error.message;
  });

שימוש במסמכים מחוץ למסך

שיטות אימות מסוימות כמו signInWithPopup, linkWithPopup reauthenticateWithPopup, לא תואמים ישירות לתוספים ל-Chrome, כי הם מחייבים טעינה של קוד מחוץ לחבילת התוספים. החל מגרסה V3, אסור לעשות זאת והוא ייחסם על ידי בפלטפורמת התוסף. כדי לעקוף את הבעיה הזו, אפשר לטעון את הקוד הזה בתוך iframe באמצעות מסמך מחוץ למסך. במסמך מחוץ למסך, מטמיעים את תהליך האימות הרגיל ומעבירים את התוצאה מהמסמך מחוץ למסך חזרה לתוסף.

במדריך הזה נעשה שימוש ב-signInWithPopup כדוגמה, אבל אותו קונספט חלה על שיטות אימות אחרות.

לפני שמתחילים

בשיטה הזו צריך להגדיר דף אינטרנט שזמין באינטרנט, שתטען ב-iframe. כל מארח יכול לעשות את זה, כולל אירוח ב-Firebase. יצירת אתר עם התוכן הבא:

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

כניסה מאוחדת

אם אתם משתמשים בכניסה מאוחדת, למשל כניסה באמצעות Google, Apple, SAML או OIDC, עליך להוסיף את המזהה של תוסף Chrome לרשימת המשתמשים המורשים דומיינים:

  1. פותחים את הפרויקט במסוף Firebase.
  2. בקטע Authentication, פותחים את הדף Settings (הגדרות).
  3. מוסיפים URI כמו הבא לרשימת הדומיינים המורשים:
    chrome-extension://CHROME_EXTENSION_ID

בקובץ המניפסט של תוסף Chrome, יש להוסיף את הפרטים הבאים כתובות URL לרשימת ההיתרים של content_security_policy:

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

הטמעת אימות

במסמך ה-HTML, signInWithPopup.js הוא קוד JavaScript שמטפל אימות. יש שתי דרכים שונות להטמיע שיטה נתמכת ישירות בתוסף:

  • כדאי להשתמש ב-firebase/auth ולא ב-firebase/auth/web-extension. נקודת הכניסה web-extension מיועדת לקוד שרץ בתוך התוסף. הקוד הזה פועל בסופו של דבר בתוסף (ב-iframe, במסמך שאינו במסך), אבל ההקשר שבו הוא פועל הוא ה-web הרגיל.
  • כוללים את לוגיקת האימות ב-listener של postMessage, כדי להעביר לשרת proxy של בקשת האימות ושל התגובה.
import { signInWithPopup, GoogleAuthProvider, getAuth } from'firebase/auth';
import { initializeApp } from 'firebase/app';
import firebaseConfig from './firebaseConfig.js'

const app = initializeApp(firebaseConfig);
const auth = 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.
const PARENT_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/providers
const PROVIDER = new GoogleAuthProvider();

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

יצירת תוסף ל-Chrome

אחרי שהאתר יהיה פעיל, תוכלו להשתמש בו בתוסף ל-Chrome.

  1. מוסיפים את ההרשאה offscreen לקובץ המניפסט.json:
  2.     {
          "name": "signInWithPopup Demo",
          "manifest_version" 3,
          "background": {
            "service_worker": "background.js"
          },
          "permissions": [
            "offscreen"
          ]
        }
        
  3. יוצרים את המסמך עצמו שלא מופיע במסך. זהו קובץ HTML מינימלי בתוך חבילת התוספים שלך טוען את הלוגיקה של JavaScript של המסמך מחוץ למסך:
  4.     <!DOCTYPE html>
        <script src="./offscreen.js"></script>
        
  5. צריך לכלול את offscreen.js בחבילת התוספים. הוא משמש כשרת Proxy בין להגדיר את האתר הציבורי בשלב 1 ואת התוסף.
  6.     // This URL must point to the public site
        const _URL = 'https://example.com/signInWithPopupExample';
        const iframe = document.createElement('iframe');
        iframe.src = _URL;
        document.documentElement.appendChild(iframe);
        chrome.runtime.onMessage.addListener(handleChromeMessages);
    
        function handleChromeMessages(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') {
            return false;
          }
    
          function handleIframeMessage({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}, new URL(_URL).origin);
          return true;
        }
        
  7. מגדירים את המסמך מחוץ למסך מ-background.js service worker.
  8.     const OFFSCREEN_DOCUMENT_PATH = '/offscreen.html';
    
        // A global promise to avoid concurrency issues
        let creatingOffscreenDocument;
    
        // Chrome only allows for a single offscreenDocument. This is a helper function
        // that returns a boolean indicating if a document is already active.
        async function hasDocument() {
          // Check all windows controlled by the service worker to see if one
          // of them is the offscreen document with the given path
          const matchedClients = await clients.matchAll();
          return matchedClients.some(
            (c) => c.url === chrome.runtime.getURL(OFFSCREEN_DOCUMENT_PATH)
          );
        }
    
        async function setupOffscreenDocument(path) {
          // If we do not have a document, we are already setup and can skip
          if (!(await hasDocument())) {
            // create offscreen document
            if (creating) {
              await creating;
            } else {
              creating = chrome.offscreen.createDocument({
                url: path,
                reasons: [
                    chrome.offscreen.Reason.DOM_SCRAPING
                ],
                justification: 'authentication'
              });
              await creating;
              creating = null;
            }
          }
        }
    
        async function closeOffscreenDocument() {
          if (!(await hasDocument())) {
            return;
          }
          await chrome.offscreen.closeDocument();
        }
    
        function getAuth() {
          return new Promise(async (resolve, reject) => {
            const auth = await chrome.runtime.sendMessage({
              type: 'firebase-auth',
              target: 'offscreen'
            });
            auth?.name !== 'FirebaseError' ? resolve(auth) : reject(auth);
          })
        }
    
        async function firebaseAuth() {
          await setupOffscreenDocument(OFFSCREEN_DOCUMENT_PATH);
    
          const auth = await getAuth()
            .then((auth) => {
              console.log('User Authenticated', auth);
              return auth;
            })
            .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);
                return err;
              }
            })
            .finally(closeOffscreenDocument)
    
          return auth;
        }
        

    עכשיו, כשאתם קוראים ל-firebaseAuth() בתוך ה-service worker, הוא יוצר את המסמך מחוץ למסך וטעון את האתר ב-iframe. ה-iframe יתבצע ברקע, ו-Firebase יעבור את תהליך האימות הרגיל. לאחר פתרון הבעיה או דחייה, אובייקט האימות יועבר דרך שרת proxy מה-iframe ל-Service Worker, באמצעות המתג מחוץ למסך מהמסמך.