Firebase 将于 5 月 10 日重返 Google I/O 大会！立即报名

Autorizza l'invio delle richieste

Le richieste inviate a FCM dall'app server o dall'ambiente attendibile devono essere autorizzate. Tieni presente queste importanti differenze tra l'autorizzazione dell'API legacy HTTP e HTTP v1:

  • L'API FCM HTTP v1 autorizza le richieste con un token di accesso OAuth 2.0 di breve durata. Per coniare questo token, puoi utilizzare le credenziali predefinite dell'applicazione Google (negli ambienti server di Google) e/o ottenere manualmente le credenziali richieste da un file di chiave privata JSON generato per un account di servizio. Se utilizzi l'SDK Firebase Admin per inviare messaggi, la libreria gestisce il token per te.
  • I protocolli legacy possono utilizzare solo chiavi API di lunga durata ottenute dalla console Firebase.

Autorizza le richieste di invio HTTP v1

A seconda dei dettagli del tuo ambiente server, utilizza una combinazione di queste strategie per autorizzare le richieste del server ai servizi Firebase:

  • Credenziali predefinite dell'applicazione Google (ADC)
  • Un file JSON dell'account di servizio
  • Un token di accesso OAuth 2.0 di breve durata derivato da un account di servizio

Se la tua applicazione è in esecuzione su Compute Engine, Google Kubernetes Engine, App Engine o Cloud Functions (incluse le funzioni Cloud per Firebase), utilizza le credenziali predefinite dell'applicazione (ADC). ADC utilizza l'account di servizio predefinito esistente per ottenere le credenziali per autorizzare le richieste e ADC abilita test locali flessibili tramite la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS . Per la massima automazione del flusso di autorizzazione, utilizza ADC insieme alle librerie del server Admin SDK.

Se la tua applicazione è in esecuzione su un ambiente server diverso da Google , dovrai scaricare un file JSON dell'account di servizio dal tuo progetto Firebase. Finché hai accesso a un file system contenente il file della chiave privata, puoi utilizzare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS per autorizzare le richieste con queste credenziali ottenute manualmente. Se non disponi di tale accesso al file, devi fare riferimento al file dell'account di servizio nel tuo codice, operazione che dovrebbe essere eseguita con estrema cautela a causa del rischio di esporre le tue credenziali.

Fornire le credenziali utilizzando ADC

Google Application Default Credentials (ADC) controlla le tue credenziali nel seguente ordine:

  1. ADC verifica se la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS è impostata. Se la variabile è impostata, ADC utilizza il file dell'account di servizio a cui punta la variabile.

  2. Se la variabile di ambiente non è impostata, ADC utilizza l'account di servizio predefinito fornito da Compute Engine, Google Kubernetes Engine, App Engine e Cloud Functions per le applicazioni eseguite su tali servizi.

  3. Se ADC non può usare nessuna delle credenziali precedenti, il sistema genera un errore.

Il seguente esempio di codice Admin SDK illustra questa strategia. L'esempio non specifica in modo esplicito le credenziali dell'applicazione. Tuttavia, ADC è in grado di trovare implicitamente le credenziali finché la variabile di ambiente è impostata o finché l'applicazione è in esecuzione su Compute Engine, Google Kubernetes Engine, App Engine o Cloud Functions.

Node.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

Giava

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Pitone

default_app = firebase_admin.initialize_app()

Andare

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

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

Fornire le credenziali manualmente

I progetti Firebase supportano gli account di servizio Google , che puoi utilizzare per chiamare le API del server Firebase dal tuo server dell'app o dall'ambiente attendibile. Se stai sviluppando codice in locale o distribuendo la tua applicazione in locale, puoi usare le credenziali ottenute tramite questo account di servizio per autorizzare le richieste del server.

Per autenticare un account di servizio e autorizzarlo ad accedere ai servizi Firebase, devi generare un file di chiave privata in formato JSON.

Per generare un file di chiave privata per il tuo account di servizio:

  1. Nella console Firebase, apri Impostazioni > Account di servizio .

  2. Fare clic su Genera nuova chiave privata , quindi confermare facendo clic su Genera chiave .

  3. Archivia in modo sicuro il file JSON contenente la chiave.

Quando autorizzi tramite un account di servizio, hai due possibilità per fornire le credenziali alla tua applicazione. Puoi impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS oppure passare esplicitamente il percorso alla chiave dell'account di servizio nel codice. La prima opzione è più sicura ed è fortemente consigliata.

Per impostare la variabile di ambiente:

Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON che contiene la chiave dell'account di servizio. Questa variabile si applica solo alla tua sessione di shell corrente, quindi se apri una nuova sessione, imposta nuovamente la variabile.

Linux o macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

finestre

Con PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Dopo aver completato i passaggi precedenti, ADC (Application Default Credentials) è in grado di determinare implicitamente le tue credenziali, consentendoti di utilizzare le credenziali dell'account di servizio durante il test o l'esecuzione in ambienti non Google.

Usa le credenziali per coniare i token di accesso

A meno che tu non stia utilizzando Admin SDK , che gestisce automaticamente l'autorizzazione, dovrai coniare il token di accesso e aggiungerlo per inviare le richieste.

Usa le tue credenziali Firebase insieme a Google Auth Library per la tua lingua preferita per recuperare un token di accesso OAuth 2.0 di breve durata:

nodo.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    const key = require('../placeholders/service-account.json');
    const jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}
index.js

In questo esempio, la libreria client dell'API di Google autentica la richiesta con un token Web JSON o JWT. Per ulteriori informazioni, consulta Token Web JSON .

Pitone

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = service_account.Credentials.from_service_account_file(
    'service-account.json', scopes=SCOPES)
  request = google.auth.transport.requests.Request()
  credentials.refresh(request)
  return credentials.token
messaging.py

Giava

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}
Messaging.java

Dopo la scadenza del token di accesso, il metodo di aggiornamento del token viene chiamato automaticamente per recuperare un token di accesso aggiornato.

Per autorizzare l'accesso a FCM, richiedere l'ambito https://www.googleapis.com/auth/firebase.messaging .

Per aggiungere il token di accesso a un'intestazione di richiesta HTTP:

Aggiungere il token come valore dell'intestazione Authorization nel formato Authorization: Bearer <access_token> :

nodo.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}
index.js

Pitone

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}
messaging.py

Giava

URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;
Messaging.java

Autorizza le richieste di invio del protocollo legacy

Con il protocollo legacy HTTP, ogni richiesta deve contenere la chiave del server dalla scheda Cloud Messaging del riquadro Impostazioni della console Firebase. Per XMPP, devi utilizzare la stessa chiave del server per stabilire una connessione.

Migra le chiavi del server legacy

A partire da marzo 2020, FCM ha smesso di creare chiavi del server legacy. Le chiavi del server legacy esistenti continueranno a funzionare, ma ti consigliamo di utilizzare invece la versione più recente della chiave denominata Chiave del server nella console di Firebase .

Se desideri eliminare una chiave del server precedente esistente, puoi farlo in Google Cloud Console .

Autorizza le richieste HTTP

Una richiesta di messaggio è composta da due parti: l'intestazione HTTP e il corpo HTTP. L'intestazione HTTP deve contenere le seguenti intestazioni:

  • Authorization : key=YOUR_SERVER_KEY
    Assicurati che questa sia la chiave del server , il cui valore è disponibile nella scheda Cloud Messaging del riquadro Impostazioni della console Firebase. Le chiavi per Android, piattaforma Apple e browser vengono rifiutate da FCM.
  • Content-Type : application/json per JSON; application/x-www-form-urlencoded;charset=UTF-8 per testo semplice.
    Se Content-Type viene omesso, si presume che il formato sia testo normale.

Per esempio:

Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
  "data" : {
    ...
  },
}

Vedere Creazione di richieste di invio per i dettagli completi sulla creazione di richieste di invio. Il Legacy HTTP Protocol Reference fornisce un elenco di tutti i parametri che il tuo messaggio può contenere.

Verifica della validità di una chiave del server

Se ricevi errori di autenticazione durante l'invio di messaggi, controlla la validità della tua chiave del server. Ad esempio, su Linux, eseguire il seguente comando:

api_key=YOUR_SERVER_KEY

curl --header "Authorization: key=$api_key" \
     --header Content-Type:"application/json" \
     https://fcm.googleapis.com/fcm/send \
     -d "{\"registration_ids\":[\"ABC\"]}"

Se ricevi un codice di stato HTTP 401, la chiave del server non è valida.

Autorizza una connessione XMPP

Con XMPP, puoi mantenere una connessione persistente, asincrona e bidirezionale ai server FCM. La connessione può essere utilizzata per inviare e ricevere messaggi tra il tuo server e i dispositivi connessi a FCM degli utenti.

Puoi utilizzare la maggior parte delle librerie XMPP per gestire una connessione di lunga durata a FCM. L'endpoint XMPP viene eseguito su fcm-xmpp.googleapis.com:5235 . Quando si verifica la funzionalità con utenti non di produzione, è invece necessario connettersi al server di pre-produzione all'indirizzo fcm-xmpp.googleapis.com:5236 (notare la porta diversa).

I test regolari in pre-produzione (un ambiente più piccolo in cui vengono eseguite le ultime build di FCM) sono utili per isolare gli utenti reali dal codice di test. I dispositivi di test e il codice di test che si connettono a fcm-xmpp.googleapis.com:5236 devono utilizzare un ID mittente FCM diverso per evitare qualsiasi rischio di invio di messaggi di test a utenti di produzione o di invio di messaggi a monte dal traffico di produzione su connessioni di test.

La connessione ha due requisiti importanti:

  • È necessario avviare una connessione Transport Layer Security (TLS). Tieni presente che attualmente FCM non supporta l' estensione STARTTLS .
  • FCM richiede un meccanismo di autenticazione SASL PLAIN utilizzando <your_FCM_Sender_Id>@fcm.googleapis.com ( ID mittente FCM ) e la chiave del server come password. Questi valori sono disponibili nella scheda Cloud Messaging del riquadro Impostazioni della console Firebase.

Se in qualsiasi momento la connessione fallisce, dovresti riconnetterti immediatamente. Non è necessario fare marcia indietro dopo una disconnessione che si verifica dopo l'autenticazione. Per ogni mittente ID , FCM consente 2500 connessioni in parallelo.

I seguenti frammenti illustrano come eseguire l'autenticazione e l'autorizzazione per una connessione XMPP a FCM.

Server XMPP

Il server XMPP richiede una connessione a FCM

<stream:stream to="fcm.googleapis.com"
        version="1.0" xmlns="jabber:client"
        xmlns:stream="http://etherx.jabber.org/streams">

FCM

FCM apre la connessione e richiede un meccanismo di autenticazione, incluso il metodo PLAIN .

<stream:features>
  <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl">
    <mechanism>X-OAUTH2</mechanism>
    <mechanism>X-GOOGLE-TOKEN</mechanism>
    <mechanism>PLAIN</mechanism>
  </mechanisms>
</stream:features>

Server XMPP

Il server XMPP deve rispondere utilizzando il metodo di autenticazione PLAIN , fornendo la chiave del server dalla scheda Cloud Messaging del riquadro Impostazioni della console Firebase.

<auth mechanism="PLAIN"
xmlns="urn:ietf:params:xml:ns:xmpp-sasl">MTI2MjAwMzQ3OTMzQHByb2plY3RzLmdjbS5hb
mFTeUIzcmNaTmtmbnFLZEZiOW1oekNCaVlwT1JEQTJKV1d0dw==</auth>

FCM

<success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>

Server XMPP

<stream:stream to="fcm.googleapis.com"
        version="1.0" xmlns="jabber:client"
        xmlns:stream="http://etherx.jabber.org/streams">

FCM

<stream:features>
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"/>
  <session xmlns="urn:ietf:params:xml:ns:xmpp-session"/>
</stream:features>

Server XMPP

<iq type="set">
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"></bind>
</iq>

FCM

<iq type="result">
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind">
    <jid>SENDER_ID@fcm.googleapis.com/RESOURCE</jid>
  </bind>
</iq>

Nota: FCM non utilizza la risorsa associata durante l'instradamento dei messaggi.

Vedere Creazione di richieste di invio per i dettagli completi sulla creazione di richieste di invio. Il Legacy XMPP Protocol Reference fornisce un elenco di tutti i parametri che il tuo messaggio può contenere.