דף זה תורגם על ידי Cloud Translation API.

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

במאמר הזה מוסבר איך להשתמש ב-Firebase Authentication כדי לאפשר למשתמשים להיכנס לתוסף ל-Chrome שמשתמש ב-Manifest 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

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

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

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

‫firebase/auth/web-extension נתמך רק בגרסאות Web SDK‏ v10.8.0 ומעלה.

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, כי הן דורשות טעינה של קוד מחוץ לחבילת התוסף. החל מ-Manifest 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 לרשימת הדומיינים המורשים:

פותחים את הפרויקט במסוף Firebase.
בקטע אימות, פותחים את הדף הגדרות.
מוסיפים לרשימת הדומיינים המורשים 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/web-extension בקוד התוסף, כמו סקריפטים של רקע, סקריפטים של Service Worker או סקריפטים של חלונות קופצים. אפשר להשתמש ב-firebase/auth רק בתוך ה-iframe מחוץ למסך, כי ה-iframe הזה פועל בהקשר של דף אינטרנט רגיל.
כדי להעביר את בקשת האימות ואת התגובה שלה דרך ה-proxy, צריך לעטוף את לוגיקת האימות במאזין postMessage.

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.

מוסיפים את ההרשאה offscreen לקובץ manifest.json:

    {
      "name": "signInWithPopup Demo",
      "manifest_version" 3,
      "background": {
        "service_worker": "background.js"
      },
      "permissions": [
        "offscreen"
      ]
    }

יוצרים את המסמך מחוץ למסך. זהו קובץ HTML מינימלי בחבילת התוסף, שטוען את הלוגיקה של ה-JavaScript של המסמך מחוץ למסך:

    <!DOCTYPE html>
    <script src="./offscreen.js"></script>

כוללים את offscreen.js בחבילת התוסף. הוא משמש כשרת proxy בין האתר הציבורי שהוגדר בשלב 1 לבין התוסף.

    // 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;
    }

מגדירים את המסמך מחוץ למסך מתוך ה-service worker של background.js.

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

    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() בתוך קובץ השירות, נוצר מסמך מחוץ למסך והאתר נטען ב-iframe. ה-iframe יעובד ברקע, וב-Firebase יתבצע תהליך האימות הרגיל. אחרי שהבעיה נפתרה או שהבקשה נדחתה, אובייקט האימות מועבר באמצעות proxy מה-iframe אל ה-service worker, באמצעות המסמך מחוץ למסך.

אימות באמצעות Firebase בתוסף ל-Chrome קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.