تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

المصادقة باستخدام Firebase في إحدى إضافات Chrome

يوضّح لك هذا المستند كيفية استخدام Firebase Authentication لتسجيل دخول المستخدمين إلى إحدى إضافات Chrome التي تستخدم Manifest V3.

توفّر واجهة برمجة التطبيقات Firebase Authentication طرق مصادقة متعدّدة لتسجيل دخول المستخدمين من خلال إضافة Chrome، ويتطلّب بعضها مجهودًا أكبر في التطوير مقارنةً بغيرها.

لاستخدام الطرق التالية في إضافة Chrome متوافقة مع الإصدار 3 من Manifest، ما عليك سوى استيرادها من firebase/auth/web-extension:

تسجيل الدخول باستخدام عنوان البريد الإلكتروني وكلمة المرور (createUserWithEmailAndPassword وsignInWithEmailAndPassword)
تسجيل الدخول باستخدام رابط البريد الإلكتروني (sendSignInLinkToEmail وisSignInWithEmailLink وsignInWithEmailLink)
تسجيل الدخول مع إخفاء الهوية (signInAnonymously)
تسجيل الدخول باستخدام نظام مصادقة مخصّص (signInWithCustomToken)
التعامل مع تسجيل الدخول إلى الموفّر بشكل مستقل ثم استخدام signInWithCredential

تتوفّر أيضًا طرق تسجيل الدخول التالية، ولكنّها تتطلّب بعض الخطوات الإضافية:

تسجيل الدخول باستخدام نافذة منبثقة (signInWithPopup وlinkWithPopup وreauthenticateWithPopup)
تسجيل الدخول عن طريق إعادة التوجيه إلى صفحة تسجيل الدخول (signInWithRedirect وlinkWithRedirect وreauthenticateWithRedirect)
تسجيل الدخول باستخدام رقم الهاتف من خلال reCAPTCHA
المصادقة المتعدّدة العوامل المستندة إلى الرسائل القصيرة باستخدام reCAPTCHA
الحماية التي توفّرها reCAPTCHA Enterprise

لاستخدام هذه الطرق في إضافة Chrome متوافقة مع Manifest V3، عليك استخدام المستندات خارج الشاشة.

استخدام نقطة الإدخال firebase/auth/web-extension

تتيح عملية الاستيراد من firebase/auth/web-extension تسجيل دخول المستخدمين من إضافة Chrome بطريقة مشابهة لتسجيل الدخول إلى تطبيق ويب.

لا تتوافق firebase/auth/web-extension إلا مع الإصدار 10.8.0 والإصدارات الأحدث من حزمة تطوير البرامج (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 لأنّها تتطلّب تحميل الرمز من خارج حزمة الإضافة. بدءًا من الإصدار 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 في رمز الإضافة، مثل النصوص البرمجية التي تعمل في الخلفية أو برامج الخدمة أو النصوص البرمجية المنبثقة. استخدِم firebase/auth داخل إطار iframe خارج الشاشة فقط، لأنّ هذا الإطار يعمل في سياق صفحة ويب عادية.
يمكنك تضمين منطق المصادقة في أداة معالجة 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 في حزمة الإضافة. تعمل هذه الصفحة كوكيل بين الموقع الإلكتروني العام الذي تم إعداده في الخطوة 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;
    }

إعداد المستند خارج الشاشة من عامل الخدمة 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 مسار المصادقة العادي. بعد حلّ المشكلة أو رفضها، سيتم نقل عنصر المصادقة من إطار iframe إلى عامل الخدمة باستخدام المستند خارج الشاشة.

المصادقة باستخدام Firebase في إحدى إضافات Chrome تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.