Generierte Admin SDKs verwenden

Mit den Firebase Data Connect Admin SDKs können Sie Ihre Abfragen und Mutationen aus vertrauenswürdigen Umgebungen wie Cloud Functions, benutzerdefinierten Backends oder Ihrem eigenen Arbeitsplatz aufrufen. Ähnlich wie beim Generieren von SDKs für Ihre Client-Apps können Sie parallel ein benutzerdefiniertes Admin SDK generieren, während Sie die Schemas, Abfragen und Mutationen entwerfen, die Sie in Ihrem Data Connect-Dienst bereitstellen. Anschließend binden Sie Methoden aus diesem SDK in Ihre Backend-Logik oder Administrationsskripts ein.

Wie bereits erwähnt, werden Data Connect-Abfragen und ‑Mutationen nicht von Clients zum Zeitpunkt der Anfrage gesendet. Stattdessen werden Data Connect-Vorgänge bei der Bereitstellung auf dem Server wie Cloud Functions gespeichert. Das bedeutet, dass Sie bei jeder Bereitstellung von Änderungen an Ihren Abfragen und Mutationen auch Admin-SDKs neu generieren und alle Dienste, die darauf basieren, neu bereitstellen müssen.

Hinweis

Admin SDKs generieren

Nachdem Sie Ihre Data Connect-Schemas, ‑Abfragen und ‑Mutationen erstellt haben, können Sie ein entsprechendes Admin-SDK generieren:

  1. Öffnen oder erstellen Sie eine connector.yaml-Datei und fügen Sie eine adminNodeSdk-Definition hinzu:

    connectorId: default
generate:
  adminNodeSdk:
    outputDir: ../../dataconnect-generated/admin-generated
    package: "@dataconnect/admin-generated"
    packageJsonDir: ../..

    Die Datei connector.yaml befindet sich in der Regel im selben Verzeichnis wie die GraphQL-Dateien (.gql), die Ihre Abfrage- und Mutationsdefinitionen enthalten. Wenn Sie bereits Client-SDKs generiert haben, wurde diese Datei bereits erstellt.

  2. Generieren Sie das SDK.

    Wenn Sie die VS Code-Erweiterung „Data Connect“ installiert haben, werden generierte SDKs immer auf dem neuesten Stand gehalten.

    Verwenden Sie andernfalls die Firebase CLI:

    firebase dataconnect:sdk:generate

    Oder so: SDKs automatisch neu generieren, wenn Sie Ihre gql-Dateien aktualisieren:

    firebase dataconnect:sdk:generate --watch

Vorgänge über ein Admin SDK ausführen

Das generierte Admin SDK enthält Schnittstellen und Funktionen, die Ihren gql-Definitionen entsprechen. Damit können Sie Vorgänge in Ihrer Datenbank ausführen. Angenommen, Sie haben ein SDK für eine Datenbank mit Songs zusammen mit einer Anfrage getSongs generiert:

import { initializeApp } from "firebase-admin/app";
import { getSongs } from "@dataconnect/admin-generated";

const adminApp = initializeApp();

const songs = await getSongs(
  { limit: 4 },
  { impersonate: { unauthenticated: true } }
);

So geben Sie eine Connector-Konfiguration an:

import { initializeApp } from "firebase-admin/app";
import { getDataConnect } from "firebase-admin/data-connect";
import {
  connectorConfig,
  getSongs,
} from "@dataconnect/admin-generated";

const adminApp = initializeApp();
const adminDc = getDataConnect(connectorConfig);

const songs = await getSongs(
  adminDc,
  { limit: 4 },
  { impersonate: { unauthenticated: true } }
);

Identität eines nicht authentifizierten Nutzers annehmen

Admin SDKs sind für die Ausführung in vertrauenswürdigen Umgebungen vorgesehen und haben daher uneingeschränkten Zugriff auf Ihre Datenbanken.

Wenn Sie öffentliche Vorgänge mit dem Admin SDK ausführen, sollten Sie vermeiden, den Vorgang mit vollständigen Administratorberechtigungen auszuführen (Prinzip der geringsten Berechtigung). Stattdessen sollten Sie den Vorgang entweder als imitierten Nutzer (siehe nächster Abschnitt) oder als imitierten nicht authentifizierten Nutzer ausführen. Nicht authentifizierte Nutzer können nur Vorgänge ausführen, die mit PUBLIC gekennzeichnet sind.

Im Beispiel oben wird die Abfrage getSongs als nicht authentifizierter Nutzer ausgeführt.

Identitätsdiebstahl

Sie können auch Vorgänge im Namen bestimmter Nutzer ausführen, indem Sie einen Teil oder das gesamte Firebase Authentication-Token in der Option impersonate übergeben. Mindestens müssen Sie die Nutzer-ID des Nutzers im Anspruch „sub“ angeben. Dieser Wert entspricht dem auth.uid-Serverwert, auf den Sie in Data Connect GraphQL-Vorgängen verweisen können.

Wenn Sie einen Nutzer imitieren, ist der Vorgang nur erfolgreich, wenn die von Ihnen angegebenen Nutzerdaten die in Ihrer GraphQL-Definition angegebenen Authentifizierungsprüfungen bestehen.

Wenn Sie das generierte SDK über einen öffentlich zugänglichen Endpunkt aufrufen, ist es wichtig, dass für den Endpunkt eine Authentifizierung erforderlich ist und dass Sie die Integrität des Authentifizierungstokens validieren, bevor Sie es verwenden, um die Identität eines Nutzers anzunehmen.

Wenn Sie aufrufbare Cloud Functions verwenden, wird das Authentifizierungstoken automatisch überprüft. Sie können es wie im folgenden Beispiel verwenden:

import { HttpsError, onCall } from "firebase-functions/https";

export const callableExample = onCall(async (req) => {
    const authClaims = req.auth?.token;
    if (!authClaims) {
        throw new HttpsError("unauthenticated", "Unauthorized");
    }

    const favoriteSongs = await getMyFavoriteSongs(
        undefined,
        { impersonate: { authClaims } }
    );

    // ...
});

Andernfalls verwenden Sie die Methode verifyIdToken des Admin SDK, um das Authentifizierungstoken zu validieren und zu decodieren. Angenommen, Ihr Endpunkt ist als einfache HTTP-Funktion implementiert und Sie haben das Firebase Authentication-Token wie üblich mit dem authorization-Header an Ihren Endpunkt übergeben:

import { getAuth } from "firebase-admin/auth";
import { onRequest } from "firebase-functions/https";

const auth = getAuth();

export const httpExample = onRequest(async (req, res) => {
    const token = req.header("authorization")?.replace(/^bearer\s+/i, "");
    if (!token) {
        res.sendStatus(401);
        return;
    }
    let authClaims;
    try {
        authClaims = await auth.verifyIdToken(token);
    } catch {
        res.sendStatus(401);
        return;
    }

    const favoriteSongs = await getMyFavoriteSongs(
        undefined,
        { impersonate: { authClaims } }
    );

    // ...
});

Nur wenn Sie echte administrative Aufgaben wie die Datenmigration in einer sicheren, nicht öffentlich zugänglichen Umgebung ausführen, sollten Sie eine Nutzer-ID angeben, die nicht aus einer überprüfbaren Quelle stammt:

// Never do this if end users can initiate execution of the code!
const favoriteSongs = await getMyFavoriteSongs(
  undefined,
  { impersonate: { authClaims } }
);

Mit uneingeschränktem Zugriff ausführen

Wenn Sie einen Vorgang ausführen, für den Berechtigungen auf Administratorebene erforderlich sind, lassen Sie den Parameter „impersonate“ im Aufruf weg:

await upsertSong(adminDc, {
  title: songTitle_one,
  instrumentsUsed: [Instrument.VOCAL],
});

Ein so aufgerufener Vorgang hat vollständigen Zugriff auf die Datenbank. Wenn Sie Abfragen oder Mutationen haben, die nur für Verwaltungszwecke verwendet werden sollen, sollten Sie sie mit der Direktive @auth(level: NO_ACCESS) definieren. So wird sichergestellt, dass nur Anrufer mit Administratorberechtigungen diese Vorgänge ausführen können.