Verificare i token App Check da un backend personalizzato

Puoi utilizzare App Check per proteggere le risorse di backend personalizzate non Google per la tua app, ad esempio il tuo backend self-hosted. Per farlo, devi eseguire entrambe le seguenti operazioni:

  • Modifica il client dell'app in modo che invii un token App Check insieme a ogni richiesta al backend, come descritto nelle pagine per iOS+, Android, web, Flutter, Unity o C++.
  • Modifica il backend in modo che richieda un token App Check valido con ogni richiesta, come descritto in questa pagina.

Verifica dei token

Per verificare i token App Check sul backend, aggiungi una logica agli endpoint API che esegua le seguenti operazioni:

  • Verifica che ogni richiesta includa un App Check token.

  • Verifica il token App Check utilizzando l'SDK Admin.

    Se la verifica ha esito positivo, l'SDK Admin restituisce il App Check token decodificato. Una verifica riuscita indica che il token proviene da un'app appartenente al tuo progetto Firebase.

Rifiuta qualsiasi richiesta che non supera uno dei due controlli. Ad esempio:

Node.js

Se non l'hai già fatto, installa l'SDK Admin Node.js.

Quindi, utilizzando il middleware Express.js come esempio:

import express from "express";
import { initializeApp } from "firebase-admin/app";
import { getAppCheck } from "firebase-admin/app-check";

const expressApp = express();
const firebaseApp = initializeApp();

const appCheckVerification = async (req, res, next) => {
    const appCheckToken = req.header("X-Firebase-AppCheck");

    if (!appCheckToken) {
        res.status(401);
        return next("Unauthorized");
    }

    try {
        const appCheckClaims = await getAppCheck().verifyToken(appCheckToken);

        // If verifyToken() succeeds, continue with the next middleware
        // function in the stack.
        return next();
    } catch (err) {
        res.status(401);
        return next("Unauthorized");
    }
}

expressApp.get("/yourApiEndpoint", [appCheckVerification], (req, res) => {
    // Handle request.
});

Python

Se non l'hai già fatto, installa l'SDK Admin Python, fallo.

Quindi, nei gestori degli endpoint API, chiama app_check.verify_token() e rifiuta la richiesta se non va a buon fine. Nell'esempio seguente, una funzione decorata con @before_request esegue questa attività per tutte le richieste:

import firebase_admin
from firebase_admin import app_check
import flask
import jwt

firebase_app = firebase_admin.initialize_app()
flask_app = flask.Flask(__name__)

@flask_app.before_request
def verify_app_check() -> None:
    app_check_token = flask.request.headers.get("X-Firebase-AppCheck", default="")
    try:
        app_check_claims = app_check.verify_token(app_check_token)
        # If verify_token() succeeds, okay to continue to route handler.
    except (ValueError, jwt.exceptions.DecodeError):
        flask.abort(401)

@flask_app.route("/yourApiEndpoint")
def your_api_endpoint(request: flask.Request):
    # Handle request.
    ...

Vai

Se non l'hai già fatto, installa l'SDK Admin per Go, fallo.

Quindi, nei gestori degli endpoint API, chiama appcheck.Client.VerifyToken() e rifiuta la richiesta se non va a buon fine. Nell'esempio seguente, una funzione wrapper aggiunge questa logica ai gestori degli endpoint:

package main

import (
    "context"
    "log"
    "net/http"

    firebaseAdmin "firebase.google.com/go/v4"
    "firebase.google.com/go/v4/appcheck"
)

var (
    appCheck *appcheck.Client
)

func main() {
    app, err := firebaseAdmin.NewApp(context.Background(), nil)
    if err != nil {
        log.Fatalf("error initializing app: %v\n", err)
    }

    appCheck, err = app.AppCheck(context.Background())
    if err != nil {
        log.Fatalf("error initializing app: %v\n", err)
    }

    http.HandleFunc("/yourApiEndpoint", requireAppCheck(yourApiEndpointHandler))
    log.Fatal(http.ListenAndServe(":8080", nil))
}

func requireAppCheck(handler func(http.ResponseWriter, *http.Request)) func(http.ResponseWriter, *http.Request) {
    wrappedHandler := func(w http.ResponseWriter, r *http.Request) {
        appCheckToken, ok := r.Header[http.CanonicalHeaderKey("X-Firebase-AppCheck")]
        if !ok {
            w.WriteHeader(http.StatusUnauthorized)
            w.Write([]byte("Unauthorized."))
            return
        }

        _, err := appCheck.VerifyToken(appCheckToken[0])
        if err != nil {
            w.WriteHeader(http.StatusUnauthorized)
            w.Write([]byte("Unauthorized."))
            return
        }

        // If VerifyToken() succeeds, continue with the provided handler.
        handler(w, r)
    }
    return wrappedHandler
}

func yourApiEndpointHandler(w http.ResponseWriter, r *http.Request) {
    // Handle request.
}

Altro

Se il backend è scritto in un altro linguaggio, puoi utilizzare una libreria JWT per uso generico, ad esempio una disponibile su jwt.io, per verificare i token App Check.

La logica di verifica dei token deve completare i seguenti passaggi:

  1. Ottieni il set di chiavi web JSON (JWK) pubbliche di Firebase App Check dall'endpoint JWKS di App Check: https://firebaseappcheck.googleapis.com/v1/jwks
  2. Verifica la firma del token App Check per assicurarti che sia legittima.
  3. Assicurati che l'intestazione del token utilizzi l'algoritmo RS256.
  4. Assicurati che l'intestazione del token sia di tipo JWT.
  5. Assicurati che il token sia emesso da Firebase App Check nel tuo progetto.
  6. Assicurati che il token non sia scaduto.
  7. Assicurati che il pubblico del token corrisponda al tuo progetto.
  8. Facoltativo: verifica che l'oggetto del token corrisponda all'ID app della tua app.

Le funzionalità delle librerie JWT possono variare. Assicurati di completare manualmente tutti i passaggi non gestiti dalla libreria che scegli.

L'esempio seguente esegue i passaggi necessari in Ruby utilizzando la gemma jwt come livello di middleware Rack.

require 'json'
require 'jwt'
require 'net/http'
require 'uri'

class AppCheckVerification
def initialize(app, options = {})
    @app = app
    @project_number = options[:project_number]
end

def call(env)
    app_id = verify(env['HTTP_X_FIREBASE_APPCHECK'])
    return [401, { 'Content-Type' => 'text/plain' }, ['Unauthenticated']] unless app_id
    env['firebase.app'] = app_id
    @app.call(env)
end

def verify(token)
    return unless token

    # 1. Obtain the Firebase App Check Public Keys
    # Note: It is not recommended to hard code these keys as they rotate,
    # but you should cache them for up to 6 hours.
    uri = URI('https://firebaseappcheck.googleapis.com/v1/jwks')
    jwks = JSON(Net::HTTP.get(uri))

    # 2. Verify the signature on the App Check token
    payload, header = JWT.decode(token, nil, true, jwks: jwks, algorithms: 'RS256')

    # 3. Ensure the token's header uses the algorithm RS256
    return unless header['alg'] == 'RS256'

    # 4. Ensure the token's header has type JWT
    return unless header['typ'] == 'JWT'

    # 5. Ensure the token is issued by App Check
    return unless payload['iss'] == "https://firebaseappcheck.googleapis.com/#{@project_number}"

    # 6. Ensure the token is not expired
    return unless payload['exp'] > Time.new.to_i

    # 7. Ensure the token's audience matches your project
    return unless payload['aud'].include? "projects/#{@project_number}"

    # 8. The token's subject will be the app ID, you may optionally filter against
    # an allow list
    payload['sub']
rescue
end
end

class Application
def call(env)
    [200, { 'Content-Type' => 'text/plain' }, ["Hello app #{env['firebase.app']}"]]
end
end

use AppCheckVerification, project_number: 1234567890
run Application.new

Protezione di riproduzione (beta)

Per proteggere un endpoint dagli attacchi di riproduzione, puoi utilizzare il token App Check dopo averlo verificato in modo che possa essere utilizzato una sola volta.

L'utilizzo della protezione di riproduzione aggiunge un round trip di rete alla chiamata verifyToken() e, di conseguenza, aggiunge latenza a qualsiasi endpoint che la utilizza. Per questo motivo, ti consigliamo di attivare la protezione di riproduzione solo sugli endpoint particolarmente sensibili.

Per utilizzare la protezione di riproduzione:

  1. Nella console Google Cloud, assegna il ruolo "Verificatore di token Firebase App Check" al service account utilizzato per verificare i token.

    • Se hai inizializzato l'SDK Admin con le credenziali del service account dell'SDK Admin scaricate dalla console Firebase, il ruolo richiesto è già assegnato.
    • Se utilizzi Cloud Functions di prima generazione con la configurazione predefinita dell'SDK Admin, assegna il ruolo al service account predefinito di App Engine. Consulta Modificare le autorizzazioni del service account.
    • Se utilizzi Cloud Functions di seconda generazione con la configurazione predefinita dell'SDK Admin, assegna il ruolo al service account di Compute predefinito.

  2. Quindi, per utilizzare un token, passa { consume: true } al verifyToken() metodo ed esamina l'oggetto risultato. Se la proprietà alreadyConsumed è true, rifiuta la richiesta o intraprendi un'azione correttiva, ad esempio richiedendo al chiamante di superare altri controlli.

    Ad esempio:

    const appCheckClaims = await getAppCheck().verifyToken(appCheckToken, { consume: true });

if (appCheckClaims.alreadyConsumed) {
    res.status(401);
    return next('Unauthorized');
}

// If verifyToken() succeeds and alreadyConsumed is not set, okay to continue.

    In questo modo il token viene verificato e contrassegnato come utilizzato. Le future invocazioni di verifyToken(appCheckToken, { consume: true }) sullo stesso token imposteranno su alreadyConsumed a true. (Tieni presente che verifyToken() non rifiuta un token utilizzato né verifica se è utilizzato se consume non è impostato.)

Quando attivi questa funzionalità per un determinato endpoint, devi anche aggiornare il codice client dell'app per acquisire token utilizzabili a uso limitato da utilizzare con l'endpoint. Consulta la documentazione lato client per le piattaforme Apple, Android e web.