Chrome uzantılarında Firebase ile kimlik doğrulama

Bu belgede, kullanıcıların Manifest V3 kullanan bir Chrome uzantısında oturum açması için Firebase Authentication nasıl kullanılacağı açıklanmaktadır.

Firebase Authentication, kullanıcıların Chrome uzantısından oturum açması için birden fazla kimlik doğrulama yöntemi sunar. Bu yöntemlerden bazıları diğerlerine kıyasla daha fazla geliştirme çabası gerektirir.

Aşağıdaki yöntemleri bir Manifest V3 Chrome uzantısında kullanmak için firebase/auth/web-extension dosyasından içe aktarmanız yeterlidir:

  • E-posta ve şifre (createUserWithEmailAndPassword ve signInWithEmailAndPassword) ile oturum açma
  • E-posta bağlantısıyla oturum açma (sendSignInLinkToEmail, isSignInWithEmailLink ve signInWithEmailLink)
  • Anonim olarak oturum açma (signInAnonymously)
  • Özel bir kimlik doğrulama sistemiyle oturum açma (signInWithCustomToken)
  • Sağlayıcı oturum açma işlemini bağımsız olarak gerçekleştirin ve ardından signInWithCredential kullanın.

Aşağıdaki oturum açma yöntemleri de desteklenir ancak bazı ek çalışmalar gerektirir:

  • Pop-up pencereyle oturum açma (signInWithPopup, linkWithPopup ve reauthenticateWithPopup)
  • Oturum açma sayfasına yönlendirerek oturum açma (signInWithRedirect, linkWithRedirect ve reauthenticateWithRedirect)
  • reCAPTCHA ile telefon numarası kullanarak oturum açma
  • reCAPTCHA ile SMS çok öğeli kimlik doğrulaması
  • reCAPTCHA Enterprise koruması

Bu yöntemleri Manifest V3 Chrome uzantısında kullanmak için ekran dışı dokümanları kullanmanız gerekir.

firebase/auth/web-extension giriş noktasını kullanma

firebase/auth/web-extension'dan içe aktarma işlemi, Chrome uzantısından kullanıcıların oturumunu açmayı web uygulamasına benzer hale getirir.

firebase/auth/web-extension yalnızca v10.8.0 ve sonraki Web SDK sürümlerinde desteklenir.

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

Ekran dışı dokümanları kullanma

signInWithPopup, linkWithPopup ve reauthenticateWithPopup gibi bazı kimlik doğrulama yöntemleri, uzantı paketi dışından kod yüklenmesini gerektirdiğinden Chrome uzantılarıyla doğrudan uyumlu değildir. Manifest V3'ten itibaren buna izin verilmez ve uzantı platformu tarafından engellenir. Bu sorunu çözmek için ekran dışı belge kullanarak bu kodu bir iframe'e yükleyebilirsiniz. Ekran dışı dokümanda normal kimlik doğrulama akışını uygulayın ve ekran dışı dokümandaki sonucu uzantıya geri yönlendirin.

Bu kılavuzda örnek olarak signInWithPopup kullanılmaktadır ancak aynı kavram diğer kimlik doğrulama yöntemleri için de geçerlidir.

Başlamadan önce

Bu teknik, web'de kullanılabilen ve bir iFrame'e yükleyeceğiniz bir web sayfası oluşturmanızı gerektirir. Firebase Hosting dahil olmak üzere herhangi bir ana makine bu işlem için kullanılabilir. Aşağıdaki içeriğe sahip bir web sitesi oluşturun:

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

Birleşik oturum açma

Google, Apple, SAML veya OIDC ile oturum açma gibi birleşik oturum açma kullanıyorsanız Chrome uzantısı kimliğinizi yetkili alanlar listesine eklemeniz gerekir:

  1. Firebase konsolunda Güvenlik > Kimlik doğrulama'ya gidin.

  2. Ayarlar sekmesindeki Yetkili alanlar bölümünde Alan ekle'yi tıklayın ve aşağıdaki gibi bir URI ekleyin: 

    chrome-extension://CHROME_EXTENSION_ID

Chrome uzantınızın manifest dosyasına aşağıdaki URL'leri content_security_policy izin verilenler listesine eklediğinizden emin olun:

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

Kimlik doğrulamayı uygulama

HTML belgenizde, signInWithPopup.js kimlik doğrulama işlemini gerçekleştiren JavaScript kodudur. Uzantıda doğrudan desteklenen bir yöntemi uygulamanın iki farklı yolu vardır:

  • Uzantı kodunuzda (ör. arka plan komut dosyaları, hizmet çalışanları veya pop-up komut dosyaları) firebase/auth/web-extension kullanın. Bu iframe standart bir web sayfası bağlamında çalıştığı için firebase/auth yalnızca ekran dışı iframe'inizde kullanın.
  • Kimlik doğrulama isteğini ve yanıtını proxy'lemek için kimlik doğrulama mantığını postMessage dinleyicisine sarmalayın.
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 uzantınızı oluşturma

Web siteniz yayına alındıktan sonra Chrome uzantınızda kullanabilirsiniz.

  1. manifest.json dosyanıza offscreen iznini ekleyin:
    2.     {
      "name": "signInWithPopup Demo",
      "manifest_version" 3,
      "background": {
        "service_worker": "background.js"
      },
      "permissions": [
        "offscreen"
      ]
    }
  2. Ekran dışı dokümanı oluşturun. Bu, uzantı paketinizde bulunan ve ekran dışı doküman JavaScript'inizin mantığını yükleyen minimum bir HTML dosyasıdır:
    3.     <!DOCTYPE html>
    <script src="./offscreen.js"></script>
  3. Uzantı paketinize offscreen.js dosyasını ekleyin. 1. adımda oluşturulan herkese açık web sitesi ile uzantınız arasında proxy görevi görür.
    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. Arka plan.js hizmet çalışanı dosyanızdan ekran dışı dokümanı ayarlayın.
    5.     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;
    }

    Artık hizmet çalışanı içinde firebaseAuth() işlevini çağırdığınızda ekran dışı doküman oluşturulur ve site bir iframe'e yüklenir. Bu iFrame arka planda işlenir ve Firebase standart kimlik doğrulama akışını kullanır. Doğrulama nesnesi çözümlendikten veya reddedildikten sonra, ekran dışı doküman kullanılarak iFrame'inizden hizmet çalışanıza proxy üzerinden iletilir.