Menerbitkan Token Web JSON

Dokumen ini membahas cara menerbitkan Token Web JSON sebagai bagian dari pemberian akses aplikasi berbasis web dan seluler ke data Fleet Engine. Jika belum melakukannya, baca Token Web JSON di bagian Keamanan di Fleet Engine. Dengan layanan Fleet Engine, Anda dapat menerbitkan JWT dengan salah satu cara berikut:

  • Menggunakan library otorisasi—Google merekomendasikan Anda menggunakan pendekatan ini jika codebase Anda ditulis dalam Java. Library ini menangani penerbitan JWT untuk semua skenario kasus penggunaan yang mungkin Anda perlukan dengan layanan ini dan sangat menyederhanakan penerapan Anda.
  • Membuat JWT Anda sendiri—Jika tidak dapat menggunakan library JWT kami, Anda harus mem-build-nya ke dalam codebase Anda sendiri. Bagian ini memberikan berbagai contoh JWT untuk setiap skenario.

Cara kerja JWT

Untuk lingkungan yang tidak tepercaya, seperti ponsel dan browser web, server backend Anda menerbitkan JWT yang berfungsi sebagai berikut:

  • Kode klien Anda yang berjalan di lingkungan dengan tingkat kepercayaan rendah memanggil kode server Anda yang berjalan di lingkungan yang sepenuhnya tepercaya untuk meminta JWT yang sesuai untuk diteruskan ke Fleet Engine.

  • JWT dikaitkan dengan akun layanan, sehingga permintaan yang dikirim ke Fleet Engine secara implisit dikaitkan dengan akun layanan yang menandatangani JWT.

  • Klaim JWT lebih lanjut membatasi resource yang dapat dioperasikan klien, seperti kendaraan, perjalanan, atau tugas tertentu.

Menggunakan library otorisasi untuk Java

Untuk menggunakan library otorisasi Fleet Engine untuk Java, buka repositori GitHub. Library ini menyederhanakan pembuatan JWT Fleet Engine dan menandatanganinya dengan aman. Library ini menyediakan hal berikut:

  • Deklarasi dependensi project
  • Daftar lengkap semua peran akun layanan untuk perjalanan sesuai permintaan atau tugas terjadwal
  • Mekanisme penandatanganan token selain menggunakan file kredensial, seperti meniru identitas akun layanan
  • Melampirkan token yang ditandatangani ke permintaan keluar yang dibuat dari stub gRPC atau library klien Google API Codegen (GAPIC)
  • Petunjuk tentang cara mengintegrasikan penandatangan dengan library klien Fleet Engine

Jika Anda menerbitkan JWT dari kode Anda

Jika tidak dapat menggunakan library otorisasi untuk Java, Anda harus menerapkan JWT di codebase Anda sendiri. Bagian ini memberikan beberapa panduan untuk membuat token Anda sendiri. Lihat Token Web JSON di bagian Keamanan di Fleet Engine untuk mengetahui daftar kolom dan klaim JWT. Lihat Peran akun layanan roles untuk mengetahui peran akun layanan yang digunakan oleh Fleet Engine. Lihat bagian berikut untuk mengetahui daftar contoh JWT untuk perjalanan sesuai permintaan atau tugas terjadwal.

Panduan umum

  • Gunakan akun layanan dan peran yang sesuai. Akun layanan dan peran terkait memastikan bahwa pengguna yang meminta token diizinkan untuk melihat informasi yang diberikan akses oleh token tersebut. Secara khusus:
    • Jika menandatangani JWT untuk diteruskan ke perangkat seluler, gunakan akun layanan untuk peran SDK Pengemudi atau Konsumen. Jika tidak, perangkat seluler dapat mengubah dan mengakses data yang seharusnya tidak dapat diakses.
    • Jika menandatangani JWT yang akan digunakan untuk panggilan istimewa, gunakan akun layanan dengan peran Admin Fleet Engine yang benar saat menggunakan ADC atau JWT. Jika tidak, operasi akan gagal.
  • Hanya bagikan token yang dibuat. Jangan pernah membagikan kredensial yang digunakan untuk membuat token.
  • Untuk panggilan gRPC, mekanisme untuk melampirkan token bergantung pada bahasa dan framework yang digunakan untuk melakukan panggilan. Mekanisme untuk menentukan token ke panggilan HTTP adalah dengan menyertakan header Authorization dengan token pembawa yang nilainya adalah token.
  • Menampilkan waktu habis masa berlaku. Server Anda harus menampilkan expiry time untuk token, biasanya dalam hitungan detik.
  • Jika Anda perlu membuat dan menandatangani JSON secara langsung sebagai pembawa token, bukan menggunakan token akses OAuth 2.0, baca petunjuk untuk Otorisasi akun layanan tanpa OAuth dalam dokumentasi Developer Identitas.

Untuk perjalanan sesuai permintaan

  • Saat membuat payload JWT, tambahkan klaim tambahan di bagian otorisasi dengan kunci vehicleid atau tripid yang ditetapkan ke nilai ID kendaraan atau ID perjalanan yang akan dipanggil.

Untuk tugas terjadwal

  • Saat server Anda memanggil API lain, token juga harus berisi klaim yang sesuai. Untuk itu, Anda dapat melakukan hal berikut:
    • Tetapkan nilai setiap kunci ke *.
    • Beri pengguna akses ke semua taskids dan deliveryvehicleids. Untuk melakukannya, tambahkan klaim tambahan di bagian otorisasi dengan kunci taskid dan deliveryvehicleid.
    • Saat menggunakan tanda bintang (*) dalam klaim taskids, tanda bintang tersebut harus menjadi satu-satunya elemen dalam array.

Contoh JWT untuk perjalanan sesuai permintaan

Bagian ini memberikan contoh JWT untuk skenario umum jika Anda menggunakan perjalanan sesuai permintaan.

Contoh token untuk operasi aplikasi pengemudi

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
  "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}

Contoh token untuk operasi aplikasi pelanggan

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

Contoh JWT untuk tugas terjadwal

Bagian ini memberikan contoh JWT untuk skenario umum jika Anda menggunakan tugas terjadwal.

Contoh token untuk aplikasi pengemudi

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_driver_service_account"
    }
    .
    {
      "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
      "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "driver_12345"
       }
    }

Contoh token untuk aplikasi pelanggan

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_consumer_service_account"
    }
    .
    {
      "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "trackingid": "shipment_12345"
       }
    }

Contoh JWT untuk operasi fleet

Bagian ini memberikan contoh JWT untuk skenario umum dalam operasi fleet.

Contoh token untuk melacak semua tugas dan kendaraan dalam fleet

Contoh berikut adalah token yang melacak semua tugas dan kendaraan dalam fleet dari aplikasi berbasis web yang digunakan oleh operator. Izin yang diperlukan untuk operasi ini lebih besar daripada untuk aplikasi klien. Lihat Menyiapkan Library Pelacakan Fleet JavaScript untuk penerapan sisi klien yang akan menggunakan token ini:

  • Tandatangani token menggunakan peran Cloud IAM Fleet Engine Delivery Fleet Reader.

   {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_consumer_service_account"
    }
    .
    {
      "iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "scope": "https://www.googleapis.com/auth/xapi",
      "authorization": {
         "taskid": "*",
         "deliveryvehicleid": "*",
       }
    }

Metode autentikasi alternatif untuk operasi server backend

Google merekomendasikan Anda menggunakan ADC untuk mengautentikasi operasi server backend. Jika tidak dapat menggunakan ADC dan perlu menggunakan JWT, lihat contoh ini.

Contoh token untuk operasi server backend sesuai permintaan

  {
    "alg": "RS256",
    "typ": "JWT",
    "kid": "private_key_id_of_provider_service_account"
  }

  {
    "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
    "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
    "aud": "https://fleetengine.googleapis.com/",
    "iat": 1511900000,
    "exp": 1511903600,
    "authorization": {
       "vehicleid": "*",
       "tripid": "*"
     }
  }

Contoh token untuk operasi server backend terjadwal

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskid": "*"
       }
    }

Contoh token untuk operasi server backend terjadwal membuat tugas batch

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskids": ["*"]
       }
    }

Contoh token untuk operasi server backend terjadwal per kendaraan pengiriman

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "*"
       }
    }

Langkah berikutnya

  • Verifikasi penyiapan Anda sehingga Anda dapat membuat kendaraan uji coba dan memastikan token Anda berfungsi sesuai harapan
  • Untuk mengetahui informasi tentang cara menggunakan ADC, bukan JWT, untuk operasi server backend, lihat Ringkasan keamanan.