Otorisasi permintaan pengiriman

Permintaan yang dikirim ke FCM dari server aplikasi Anda atau lingkungan tepercaya harus diotorisasi. Perhatikan perbedaan penting antara HTTP lawas dan otorisasi HTTP v1 API:

• FCM HTTP v1 API mengotorisasi permintaan dengan token akses OAuth 2.0 berumur pendek. Untuk membuat token ini, Anda dapat menggunakan Kredensial Default Aplikasi Google (di lingkungan server Google) dan/atau mendapatkan kredensial yang diperlukan secara manual dari file kunci pribadi JSON yang dibuat untuk akun layanan. Jika Anda menggunakan Firebase Admin SDK untuk mengirim pesan, library akan menangani token untuk Anda.
• Protokol lama hanya dapat menggunakan kunci API berumur panjang yang diperoleh dari konsol Firebase.

Perhatian: Selalu pastikan untuk menggunakan jenis kredensial yang tepat. Kunci API hanya akan berfungsi untuk mengotorisasi permintaan ke API lama.

Izinkan permintaan pengiriman HTTP v1

Bergantung pada detail lingkungan server Anda, gunakan kombinasi strategi berikut untuk mengotorisasi permintaan server ke layanan Firebase:

• Kredensial Default Aplikasi Google (ADC)
• File JSON akun layanan
• Token akses OAuth 2.0 berumur pendek yang berasal dari akun layanan

Jika aplikasi Anda berjalan di Compute Engine, Google Kubernetes Engine, App Engine, atau Cloud Functions (termasuk Cloud Functions for Firebase), gunakan Application Default Credentials (ADC). ADC menggunakan akun layanan default Anda yang ada untuk mendapatkan kredensial guna mengotorisasi permintaan, dan ADC mengaktifkan pengujian lokal yang fleksibel melalui variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS . Untuk otomatisasi alur otorisasi sepenuhnya, gunakan ADC bersama dengan pustaka server Admin SDK.

Jika aplikasi Anda berjalan di lingkungan server non-Google , Anda harus mengunduh file JSON akun layanan dari proyek Firebase Anda. Selama Anda memiliki akses ke sistem file yang berisi file kunci pribadi, Anda dapat menggunakan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS untuk mengotorisasi permintaan dengan kredensial yang diperoleh secara manual ini. Jika Anda tidak memiliki akses file tersebut, Anda harus mereferensikan file akun layanan dalam kode Anda— yang harus dilakukan dengan sangat hati-hati karena risiko kredensial Anda terungkap.

Berikan kredensial menggunakan ADC

Kredensial Default Aplikasi Google (ADC) memeriksa kredensial Anda dalam urutan berikut:

1. ADC memeriksa apakah variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS disetel. Jika variabel disetel, ADC menggunakan file akun layanan yang ditunjuk oleh variabel tersebut.

2. Jika variabel lingkungan tidak disetel, ADC menggunakan akun layanan default yang disediakan oleh Compute Engine, Google Kubernetes Engine, App Engine, dan Cloud Functions untuk aplikasi yang berjalan di layanan tersebut.

3. Jika ADC tidak dapat menggunakan salah satu dari kredensial di atas, sistem akan melontarkan kesalahan.

Contoh kode Admin SDK berikut mengilustrasikan strategi ini. Contoh tidak secara eksplisit menentukan kredensial aplikasi. Namun, ADC dapat menemukan kredensial secara implisit selama variabel lingkungan disetel, atau selama aplikasi berjalan di Compute Engine, Google Kubernetes Engine, App Engine, atau 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);

Piton

default_app = firebase_admin.initialize_app()

Pergi

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(),
});

Berikan kredensial secara manual

Proyek Firebase mendukung akun layanan Google , yang dapat Anda gunakan untuk memanggil API server Firebase dari server aplikasi atau lingkungan tepercaya. Jika Anda mengembangkan kode secara lokal atau menerapkan aplikasi secara lokal, Anda dapat menggunakan kredensial yang diperoleh melalui akun layanan ini untuk mengotorisasi permintaan server.

Untuk mengautentikasi akun layanan dan mengotorisasinya untuk mengakses layanan Firebase, Anda harus membuat file kunci pribadi dalam format JSON.

Untuk menghasilkan file kunci pribadi untuk akun layanan Anda:

1. Di konsol Firebase, buka Pengaturan > Akun Layanan .

2. Klik Generate New Private Key , lalu konfirmasikan dengan mengklik Generate Key .

3. Simpan file JSON yang berisi kunci dengan aman.

Saat memberi otorisasi melalui akun layanan, Anda memiliki dua pilihan untuk memberikan kredensial ke aplikasi Anda. Anda dapat menyetel variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS , atau secara eksplisit meneruskan jalur ke kunci akun layanan dalam kode. Opsi pertama lebih aman dan sangat disarankan.

Untuk mengatur variabel lingkungan:

Setel variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur file dari file JSON yang berisi kunci akun layanan Anda. Variabel ini hanya berlaku untuk sesi shell Anda saat ini, jadi jika Anda membuka sesi baru, atur kembali variabel tersebut.

Linux atau macOS

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

Windows

Dengan PowerShell:

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

Setelah Anda menyelesaikan langkah-langkah di atas, Application Default Credentials (ADC) dapat menentukan kredensial Anda secara implisit, memungkinkan Anda menggunakan kredensial akun layanan saat menguji atau menjalankan di lingkungan non-Google.

Gunakan kredensial untuk membuat token akses

Kecuali jika Anda menggunakan Admin SDK , yang menangani otorisasi secara otomatis, Anda harus membuat token akses dan menambahkannya untuk mengirimkan permintaan.

Gunakan kredensial Firebase Anda bersama dengan Google Auth Library untuk bahasa pilihan Anda guna mengambil token akses OAuth 2.0 berumur pendek:

node.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

Dalam contoh ini, pustaka klien Google API mengautentikasi permintaan dengan token web JSON, atau JWT. Untuk informasi selengkapnya, lihat token web JSON .

Piton

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

Jawa

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

Setelah token akses Anda kedaluwarsa, metode penyegaran token dipanggil secara otomatis untuk mengambil token akses yang diperbarui.

Untuk mengotorisasi akses ke FCM, minta cakupan https://www.googleapis.com/auth/firebase.messaging .

Untuk menambahkan token akses ke header permintaan HTTP:

Tambahkan token sebagai nilai header Authorization dalam format Authorization: Bearer <access_token> :

node.js

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

Piton

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

Jawa

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

Izinkan permintaan pengiriman protokol lama

Dengan protokol lama HTTP, setiap permintaan harus berisi kunci server dari tab Cloud Messaging di panel Pengaturan Firebase console. Untuk XMPP, Anda harus menggunakan kunci server yang sama untuk membuat sambungan.

Penting: Kunci server yang ditemukan di konsol tidak dapat mengotorisasi permintaan pengiriman yang dibuat melalui HTTP v1 API—ini hanya digunakan untuk permintaan HTTP dan XMPP lama.

Migrasikan kunci server lama

Mulai Maret 2020, FCM berhenti membuat kunci server lama. Kunci server lawas yang ada akan terus berfungsi, tetapi sebaiknya gunakan versi terbaru dari kunci berlabel Server key di Firebase console .

Jika ingin menghapus kunci server lawas yang ada, Anda dapat melakukannya di Google Cloud Console .

Perhatian: Jika Anda membuat ulang kunci API di Google Cloud Console , kunci tersebut tidak dapat digunakan untuk mengotorisasi permintaan FCM.

Izinkan permintaan HTTP

Permintaan pesan terdiri dari dua bagian: HTTP header dan HTTP body. Header HTTP harus berisi header berikut:

• Authorization : key=YOUR_SERVER_KEY
  Pastikan ini adalah kunci server , yang nilainya tersedia di tab Cloud Messaging di panel Pengaturan Firebase console. Android, platform Apple, dan kunci browser ditolak oleh FCM.
• Content-Type : application/json untuk JSON; application/x-www-form-urlencoded;charset=UTF-8 untuk teks biasa.
  Jika Content-Type dihilangkan, format dianggap sebagai teks biasa.

Sebagai contoh:

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

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

Lihat Buat Permintaan Kirim untuk detail selengkapnya tentang cara membuat permintaan pengiriman. Referensi Protokol HTTP Lama menyediakan daftar semua parameter yang dapat berisi pesan Anda.

Memeriksa validitas kunci server

Jika Anda menerima kesalahan autentikasi saat mengirim pesan, periksa validitas kunci Server Anda. Misalnya, di Linux, jalankan perintah berikut:

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

Jika Anda menerima kode status HTTP 401, kunci Server Anda tidak valid.

Otorisasi koneksi XMPP

Dengan XMPP, Anda dapat mempertahankan koneksi dua arah yang persisten, asinkron, ke server FCM. Koneksi dapat digunakan untuk mengirim dan menerima pesan antara server Anda dan perangkat yang terhubung dengan FCM milik pengguna Anda.

Anda dapat menggunakan sebagian besar library XMPP untuk mengelola koneksi jangka panjang ke FCM. Titik akhir XMPP berjalan di fcm-xmpp.googleapis.com:5235 . Saat menguji fungsionalitas dengan pengguna non-produksi, Anda harus terhubung ke server praproduksi di fcm-xmpp.googleapis.com:5236 (perhatikan port yang berbeda).

Pengujian reguler pada praproduksi (lingkungan yang lebih kecil tempat build FCM terbaru berjalan) bermanfaat untuk mengisolasi pengguna sebenarnya dari kode pengujian. Perangkat pengujian dan kode pengujian yang terhubung ke fcm-xmpp.googleapis.com:5236 harus menggunakan ID pengirim FCM yang berbeda untuk menghindari risiko pengiriman pesan pengujian ke pengguna produksi atau pengiriman pesan upstream dari traffic produksi melalui koneksi pengujian.

Koneksi memiliki dua persyaratan penting:

• Anda harus memulai koneksi Transport Layer Security (TLS). Perhatikan bahwa FCM saat ini tidak mendukung ekstensi STARTTLS .
• FCM memerlukan mekanisme autentikasi SASL PLAIN menggunakan <your_FCM_Sender_Id>@fcm.googleapis.com (FCM sender ID ) dan kunci Server sebagai sandi. Nilai-nilai ini tersedia di tab Cloud Messaging di panel Settings Firebase console.

Jika suatu saat koneksi gagal, Anda harus segera menyambung kembali. Tidak perlu mundur setelah pemutusan yang terjadi setelah autentikasi. Untuk setiap ID pengirim , FCM mengizinkan 2500 koneksi secara paralel.

Cuplikan berikut mengilustrasikan cara melakukan autentikasi dan otorisasi untuk koneksi XMPP ke FCM.

Server XMPP

Server XMPP meminta koneksi ke FCM

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

FCM

FCM membuka koneksi dan meminta mekanisme autentikasi, termasuk metode 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

Server XMPP harus merespons menggunakan metode autentikasi PLAIN , memberikan kunci server dari tab Cloud Messaging di panel Pengaturan konsol 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>[e-mail]/RESOURCE</jid>
  </bind>
</iq>

Catatan: FCM tidak menggunakan resource terikat saat merutekan pesan.

Lihat Buat Permintaan Kirim untuk detail selengkapnya tentang cara membuat permintaan pengiriman. Referensi Protokol XMPP Legacy menyediakan daftar semua parameter yang dapat berisi pesan Anda.