Autoryzuj wysyłanie żądań

Żądania wysyłane do FCM z serwera aplikacji lub zaufanego środowiska muszą być autoryzowane. Zwróć uwagę na te ważne różnice między przestarzałą, starszą autoryzacją API HTTP a autoryzacją API HTTP v1:

  • Interfejs API FCM HTTP v1 autoryzuje żądania za pomocą krótkotrwałego tokena dostępu OAuth 2.0. Aby wybić ten token, możesz użyć domyślnych danych uwierzytelniających aplikacji Google (w środowiskach serwerowych Google) i/lub ręcznie uzyskać wymagane dane uwierzytelniające z pliku klucza prywatnego JSON wygenerowanego dla konta usługi. Jeśli do wysyłania wiadomości używasz pakietu Firebase Admin SDK, biblioteka obsługuje token za Ciebie.
  • Przestarzałe starsze protokoły mogą używać tylko długotrwałych kluczy API uzyskanych z konsoli Firebase.

Autoryzuj żądania wysyłania HTTP v1

W zależności od szczegółów środowiska serwera użyj kombinacji tych strategii, aby autoryzować żądania serwera kierowane do usług Firebase:

  • Domyślne dane uwierzytelniające aplikacji Google (ADC)
  • Plik JSON konta usługi
  • Krótkoterminowy token dostępu OAuth 2.0 pochodzący z konta usługi

Jeśli Twoja aplikacja działa w Compute Engine, Google Kubernetes Engine, App Engine lub Cloud Functions (w tym Cloud Functions dla Firebase), użyj domyślnych danych uwierzytelniających aplikacji (ADC). ADC używa istniejącego domyślnego konta usługi w celu uzyskania poświadczeń w celu autoryzacji żądań, a ADC umożliwia elastyczne testowanie lokalne za pośrednictwem zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS . Aby uzyskać pełną automatyzację przepływu autoryzacji, użyj ADC wraz z bibliotekami serwerowymi Admin SDK.

Jeśli Twoja aplikacja działa w środowisku serwerowym innym niż Google , musisz pobrać plik JSON konta usługi z projektu Firebase. Jeśli masz dostęp do systemu plików zawierającego plik klucza prywatnego, możesz używać zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS do autoryzacji żądań przy użyciu ręcznie uzyskanych poświadczeń. Jeśli nie masz takiego dostępu do pliku, musisz odwołać się do pliku konta usługi w swoim kodzie — co należy zrobić ze szczególną ostrożnością ze względu na ryzyko ujawnienia Twoich danych uwierzytelniających.

Podaj poświadczenia za pomocą ADC

Domyślne dane uwierzytelniające aplikacji Google (ADC) sprawdzają Twoje dane uwierzytelniające w następującej kolejności:

  1. ADC sprawdza, czy ustawiono zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS . Jeśli zmienna jest ustawiona, ADC używa pliku konta usługi, na który wskazuje zmienna.

  2. Jeśli zmienna środowiskowa nie jest ustawiona, ADC używa domyślnego konta usługi udostępnianego przez Compute Engine, Google Kubernetes Engine, App Engine i Cloud Functions dla aplikacji działających w tych usługach.

  3. Jeśli ADC nie może użyć żadnego z powyższych poświadczeń, system zgłasza błąd.

Poniższy przykład kodu pakietu Admin SDK ilustruje tę strategię. Przykład nie określa jawnie poświadczeń aplikacji. Jednak funkcja ADC może niejawnie znaleźć dane uwierzytelniające, jeśli ustawiono zmienną środowiskową lub jeśli aplikacja działa w Compute Engine, Google Kubernetes Engine, App Engine lub Cloud Functions.

Node.js

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

Jawa

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

FirebaseApp.initializeApp(options);

Pyton

default_app = firebase_admin.initialize_app()

Iść

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

C#

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

Podaj poświadczenia ręcznie

Projekty Firebase obsługują konta usług Google, których możesz używać do wywoływania interfejsów API serwera Firebase z serwera aplikacji lub zaufanego środowiska. Jeśli tworzysz kod lokalnie lub wdrażasz aplikację lokalnie, możesz użyć poświadczeń uzyskanych za pośrednictwem tego konta usługi, aby autoryzować żądania serwera.

Aby uwierzytelnić konto usługi i autoryzować je do dostępu do usług Firebase, musisz wygenerować plik klucza prywatnego w formacie JSON.

Aby wygenerować plik klucza prywatnego dla swojego konta usługi:

  1. W konsoli Firebase otwórz Ustawienia > Konta usług .

  2. Kliknij opcję Wygeneruj nowy klucz prywatny , a następnie potwierdź, klikając opcję Wygeneruj klucz .

  3. Bezpiecznie przechowuj plik JSON zawierający klucz.

Podczas autoryzacji za pośrednictwem konta usługi masz dwie możliwości podania poświadczeń do aplikacji. Możesz ustawić zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS lub jawnie przekazać ścieżkę do klucza konta usługi w kodzie. Pierwsza opcja jest bezpieczniejsza i zdecydowanie zalecana.

Aby ustawić zmienną środowiskową:

Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na ścieżkę pliku JSON zawierającego klucz konta usługi. Ta zmienna dotyczy tylko bieżącej sesji powłoki, więc jeśli otworzysz nową sesję, ustaw zmienną ponownie.

Linux lub macOS

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

Okna

Z PowerShellem:

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

Po wykonaniu powyższych kroków domyślne dane uwierzytelniające aplikacji (ADC) mogą niejawnie określić Twoje dane uwierzytelniające, umożliwiając korzystanie z danych uwierzytelniających konta usługi podczas testowania lub uruchamiania w środowiskach innych niż Google.

Użyj poświadczeń, aby wybić tokeny dostępu

Jeśli nie korzystasz z pakietu Admin SDK , który automatycznie obsługuje autoryzację, musisz utworzyć token dostępu i dodać go, aby wysyłać żądania.

Użyj danych uwierzytelniających Firebase razem z biblioteką Google Auth dla preferowanego języka, aby pobrać krótkotrwały token dostępu OAuth 2.0:

węzeł.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);
    });
  });
}

W tym przykładzie biblioteka klienta API Google uwierzytelnia żądanie za pomocą tokena sieciowego JSON, czyli JWT. Aby uzyskać więcej informacji, zobacz tokeny internetowe JSON .

Pyton

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

Jawa

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

Po wygaśnięciu tokenu dostępu metoda odświeżania tokenu jest wywoływana automatycznie w celu pobrania zaktualizowanego tokenu dostępu.

Aby autoryzować dostęp do FCM, poproś o zakres https://www.googleapis.com/auth/firebase.messaging .

Aby dodać token dostępu do nagłówka żądania HTTP:

Dodaj token jako wartość nagłówka Authorization w formacie Authorization: Bearer <access_token> :

węzeł.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}

Pyton

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

Jawa

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

Autoryzuj żądania wysyłania starszego protokołu

W przypadku starszego protokołu HTTP każde żądanie musi zawierać klucz serwera z karty Cloud Messaging w panelu Ustawienia konsoli Firebase. W przypadku XMPP musisz użyć tego samego klucza serwera, aby nawiązać połączenie.

Przeprowadź migrację starszych kluczy serwera

Od marca 2020 r. firma FCM zaprzestała tworzenia starszych kluczy serwerów. Istniejące starsze klucze serwera będą nadal działać, ale zalecamy zamiast tego użycie nowszej wersji klucza oznaczonego jako Klucz serwera w konsoli Firebase .

Jeśli chcesz usunąć istniejący klucz starszego serwera, możesz to zrobić w konsoli Google Cloud .

Autoryzuj żądania HTTP

Żądanie wiadomości składa się z dwóch części: nagłówka HTTP i treści HTTP. Nagłówek HTTP musi zawierać następujące nagłówki:

  • Authorization : klucz=TWÓJ_KLUCZ_SERWERA
    Upewnij się, że jest to klucz serwera , którego wartość jest dostępna na karcie Cloud Messaging w panelu Ustawienia konsoli Firebase. Android, platforma Apple i klucze przeglądarki są odrzucane przez FCM.
  • Content-Type : application/json dla JSON; application/x-www-form-urlencoded;charset=UTF-8 dla zwykłego tekstu.
    Jeśli pominięto Content-Type , przyjmuje się, że format jest zwykłym tekstem.

Na przykład:

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

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

Zobacz Tworzenie żądań wysłania , aby uzyskać szczegółowe informacje na temat tworzenia żądań wysłania. Dokumentacja starszego protokołu HTTP zawiera listę wszystkich parametrów, jakie może zawierać wiadomość.

Sprawdzanie ważności klucza serwera

Jeśli podczas wysyłania wiadomości otrzymasz błędy uwierzytelnienia, sprawdź ważność klucza serwera. Na przykład w systemie Linux uruchom następujące polecenie:

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\"]}"

Jeśli otrzymasz kod stanu HTTP 401, Twój klucz serwera jest nieprawidłowy.

Autoryzuj połączenie XMPP

Dzięki XMPP możesz utrzymywać trwałe, asynchroniczne, dwukierunkowe połączenie z serwerami FCM. Połączenie może służyć do wysyłania i odbierania wiadomości między Twoim serwerem a urządzeniami użytkowników podłączonymi do FCM.

Do zarządzania długotrwałym połączeniem z FCM można używać większości bibliotek XMPP. Punkt końcowy XMPP działa pod fcm-xmpp.googleapis.com:5235 . Podczas testowania funkcjonalności z użytkownikami nieprodukcyjnymi powinieneś zamiast tego połączyć się z serwerem przedprodukcyjnym pod fcm-xmpp.googleapis.com:5236 (zwróć uwagę na inny port).

Regularne testowanie na etapie przedprodukcyjnym (mniejsze środowisko, w którym działają najnowsze kompilacje FCM) jest korzystne w izolowaniu prawdziwych użytkowników od kodu testowego. Urządzenia testowe i kod testowy łączący się z fcm-xmpp.googleapis.com:5236 powinny używać innego identyfikatora nadawcy FCM, aby uniknąć ryzyka wysyłania wiadomości testowych do użytkowników produkcyjnych lub wysyłania wiadomości nadrzędnych z ruchu produkcyjnego przez połączenia testowe.

Połączenie ma dwa ważne wymagania:

  • Należy zainicjować połączenie Transport Layer Security (TLS). Należy pamiętać, że FCM obecnie nie obsługuje rozszerzenia STARTTLS .
  • FCM wymaga mechanizmu uwierzytelniania SASL PLAIN przy użyciu adresu <your_FCM_Sender_Id>@fcm.googleapis.com ( identyfikator nadawcy FCM) i klucza serwera jako hasła. Te wartości są dostępne na karcie Wiadomości w chmurze w panelu Ustawienia konsoli Firebase.

Jeżeli w jakimkolwiek momencie połączenie ulegnie awarii, należy natychmiast nawiązać połączenie ponownie. Nie ma potrzeby wycofywania się po rozłączeniu, które ma miejsce po uwierzytelnieniu. Dla każdego identyfikatora nadawcy FCM umożliwia równoległe 2500 połączeń.

Poniższe fragmenty ilustrują sposób przeprowadzania uwierzytelniania i autoryzacji połączenia XMPP z FCM.

Serwer XMPP

Serwer XMPP żąda połączenia z FCM

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

FCM

FCM otwiera połączenie i żąda mechanizmu uwierzytelniania, w tym metody 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>

Serwer XMPP

Serwer XMPP musi odpowiedzieć przy użyciu metody uwierzytelniania PLAIN , podając klucz serwera z karty Cloud Messaging w panelu Ustawienia konsoli 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"/>

Serwer 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>

Serwer 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>

Uwaga: FCM nie używa powiązanego zasobu podczas routingu komunikatów.

Zobacz Tworzenie żądań wysłania , aby uzyskać szczegółowe informacje na temat tworzenia żądań wysłania. Dokumentacja starszego protokołu XMPP zawiera listę wszystkich parametrów, jakie może zawierać wiadomość.