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

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

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

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

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

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

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

لاستخدام هذه الطرق في إضافة Chrome V3 التي تستخدم 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 إلى قائمة النطاقات:

  1. افتح مشروعك في وحدة تحكّم Firebase.
  2. في قسم المصادقة، افتح صفحة الإعدادات.
  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، في المستند خارج الشاشة)، فإن السياق الذي يتم تشغيلها فيه هو محتوى الويب القياسي.
  • عليك إحاطة منطق المصادقة في مستمع 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.

  1. أضِف الإذن offscreen إلى ملف الدالة "manifest.json".
    2.     {
      "name": "signInWithPopup Demo",
      "manifest_version" 3,
      "background": {
        "service_worker": "background.js"
      },
      "permissions": [
        "offscreen"
      ]
    }
  2. إنشاء المستند خارج الشاشة نفسه هذا ملف HTML بسيط داخل حزمة الإضافات لديك تحميل منطق JavaScript للمستند خارج الشاشة:
    3.     <!DOCTYPE html>
    <script src="./offscreen.js"></script>
  3. يمكنك تضمين "offscreen.js" في حزمة الإضافات. وهو يعمل كخادم وكيل بين موقع إلكتروني عام تم إعداده في الخطوة 1 وفي إضافتك.
    4.     // 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;
    }
  4. يمكنك إعداد المستند خارج الشاشة من مشغّل خدمة الخلفية.js.
    5.     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 إلى مشغّل الخدمات، باستخدام الشاشة جلسة المراجعة.