Verificare i token App Check da un backend personalizzato

Puoi proteggere le risorse non Firebase della tua app, ad esempio i backend self-hosted, con App Check. A questo scopo, dovrai eseguire entrambe le seguenti operazioni:

  • Modifica il client dell'app in modo da inviare un token App Check insieme a ogni richiesta al tuo backend, come descritto nelle pagine per iOS+, Android e web.
  • Modifica il backend in modo da richiedere un token App Check valido con ogni richiesta, come descritto in questa pagina.

Verifica del token

Per verificare i token App Check nel tuo backend, aggiungi una logica agli endpoint dell'API che:

  • Verifica che ogni richiesta includa un token App Check.

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

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

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

Node.js

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

Poi, 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 ancora fatto, installa l'SDK Admin per Python.

Poi, nei gestori degli endpoint API, chiama app_check.verify_token() e rifiuta la richiesta in caso di errore. Nel seguente esempio, una funzione decorata con @before_request esegue questa operazione 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 ancora fatto, installa l'SDK Amministrazione per Go.

Poi, negli handler degli endpoint API, chiama appcheck.Client.VerifyToken() e rifiuta la richiesta in caso di errore. Nell'esempio seguente, una funzione wrapper aggiunge questa logica agli handler 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 tuo backend è scritto in un'altra lingua, puoi utilizzare una libreria JWT generica, ad esempio quella disponibile all'indirizzo jwt.io, per verificare i token di App Check.

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

  1. Ottieni l'insieme 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 legittimo.
  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 stato 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 scelta.

L'esempio seguente esegue i passaggi necessari in Ruby utilizzando il gem 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 da replay (beta)

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

L'utilizzo della protezione antiriproduzione aggiunge un viaggio di andata e ritorno della rete alla chiamata verifyToken() e, di conseguenza, aggiunge latenza a qualsiasi endpoint che la utilizza. Per questo motivo, ti consigliamo di attivare la protezione da replay solo su endpoint particolarmente sensibili.

Per utilizzare la protezione antiriproduzione:

  1. Nella console Cloud, concedi il ruolo "Verificatore token Firebase App Check" all'account di servizio utilizzato per verificare i token.

    • Se hai inizializzato l'SDK Admin con le credenziali dell'account di servizio SDK Admin che hai scaricato dalla console di Firebase, il ruolo richiesto è già stato concesso.
    • Se utilizzi Cloud Functions di 1ª generazione con la configurazione predefinita dell'SDK di amministrazione, concedi il ruolo all'account di servizio predefinito di App Engine. Consulta Modificare le autorizzazioni dell'account di servizio.
    • Se utilizzi Cloud Functions di 2ª generazione con la configurazione predefinita dell'SDK amministratore, concedi il ruolo all'account di servizio Compute predefinito.

  2. Poi, per utilizzare un token, passa { consume: true } al metodo verifyToken() e esamina l'oggetto del risultato. Se la proprietà alreadyConsumed è true, rifiuta la richiesta o esegui un qualche tipo di azione correttiva, ad esempio richiedi all'utente che ha effettuato la chiamata 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.

    Il token viene verificato e contrassegnato come utilizzato. Le invocazioni future di verifyToken(appCheckToken, { consume: true }) nello stesso token imposteranno alreadyConsumed su true. Tieni presente che verifyToken() non rifiuta un token consumato né controlla se è stato consumato se verifyToken() non è impostato.consume

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