Autentikasi dan otorisasi

Bagian ini menjelaskan konsep autentikasi dan otorisasi terkait integrasi dengan Fleet Engine.

Anda dapat mengonfigurasi kemampuan yang disediakan oleh Last Milet Fleet Solution melalui Konsol Google Cloud. Fleet Engine SDK memerlukan penggunaan Token Web JSON (JWT) yang telah ditandatangani oleh Akun Layanan yang sesuai.

Ringkasan

Backend pelanggan yang mengautentikasi dan memberi otorisasi terhadap Fleet Engine harus menggunakan mekanisme Kredensial Default Aplikasi standar.

Fleet Engine juga menerima panggilan yang berasal dari lingkungan kepercayaan rendah seperti smartphone dan browser. Untuk mengamankan kunci rahasia Akun Layanan yang hanya cocok untuk lingkungan tepercaya, backend pelanggan diharapkan membuat JSON Web Token (JWT) yang ditandatangani dengan klaim tambahan khusus untuk Fleet Engine yang kemudian dapat dikeluarkan ke lingkungan tidak tepercaya seperti ponsel.

Prinsip desain otentikasi

Alur autentikasi Fleet Engine menerapkan prinsip-prinsip desain berikut.

  • Peran IAM menentukan sekumpulan izin pada resource yang diizinkan untuk akun utama. Misalnya, peran Admin diizinkan untuk melakukan apa pun dengan Kredensial Default Aplikasi, sedangkan peran Pengemudi Tidak Tepercaya* hanya diizinkan untuk memperbarui lokasi kendaraan dan dibatasi pada penggunaan JWT untuk autentikasi dan otorisasi.

  • Untuk lingkungan yang tidak tepercaya, JWT mengklaim lebih membatasi entity yang dapat dioperasikan oleh pemanggil. Ini dapat berupa tugas tertentu atau kendaraan pengiriman.

  • Kode Anda yang dijalankan di lingkungan kepercayaan rendah harus terlebih dahulu memanggil kode Anda yang berjalan di lingkungan tepercaya untuk mengeluarkan JWT.

  • Fleet Engine melakukan pemeriksaan keamanan berikut pada panggilan API untuk resource:

    1. Akun utama yang melakukan panggilan memiliki izin yang sesuai (melalui penetapan peran) untuk tindakan pada resource.

    2. Untuk peran non-Admin, klaim JWT yang diteruskan dalam permintaan memberikan izin yang diperlukan untuk resource tersebut.

Alur autentikasi

Diagram urutan berikut menunjukkan detail alur autentikasi ini.

  1. Administrator fleet membuat akun layanan.

  2. Administrator fleet menetapkan peran IAM tertentu ke akun layanan.

  3. Administrator fleet mengonfigurasi backend mereka dengan akun layanan dan Kredensial Default Aplikasi.

  4. Aplikasi klien meminta JWT dari backend pelanggan. Pemohon dapat berupa aplikasi Driver, aplikasi Konsumen, atau aplikasi pemantauan.

  5. Backend pelanggan menandatangani dan menerbitkan JWT untuk masing-masing akun layanan. Aplikasi klien menerima JWT.

  6. Aplikasi klien menggunakan JWT untuk terhubung ke Fleet Engine guna membaca atau mengubah data, bergantung pada peran IAM yang ditetapkan pada aplikasi tersebut selama fase penyiapan.

Diagram urutan autentikasi

Penyiapan project cloud

Untuk menyiapkan project cloud, buat project Anda terlebih dahulu, lalu buat akun layanan.

Untuk membuat project Google Cloud:

  1. Membuat Project Google Cloud menggunakan Konsol Google Cloud.
  2. Dengan menggunakan Dashboard APIs and Services, aktifkan Local Rides and Deliveries API.

Akun Layanan & Peran IAM

Akun layanan adalah jenis akun khusus yang digunakan oleh aplikasi, bukan orang. Biasanya, akun layanan digunakan untuk membuat JWT yang memberikan kumpulan izin berbeda, bergantung pada perannya. Untuk mengurangi kemungkinan penyalahgunaan, Anda dapat membuat beberapa akun layanan, masing-masing dengan serangkaian peran minimum yang diperlukan ().

Last Mile Fleet Solution menggunakan peran berikut:

PeranDeskripsi
Pengguna Pengemudi Tepercaya Pengiriman Fleet Engine

roles/fleetengine.deliveryTrustedDriver
Memberikan izin untuk membuat dan memperbarui kendaraan dan tugas pengiriman, termasuk memperbarui lokasi kendaraan pengiriman dan status atau hasil tugas. Token yang dibuat oleh akun layanan dengan peran ini biasanya digunakan dari perangkat seluler pengemudi pengiriman Anda atau dari server backend Anda.
Pengiriman Fleet Engine Pengguna Pengemudi Tidak Tepercaya

roles/fleetengine.deliveryUntrustedDriver
Memberikan izin untuk memperbarui lokasi kendaraan pengiriman. Token yang dibuat oleh akun layanan dengan peran ini biasanya digunakan dari perangkat seluler pengemudi pengiriman Anda.
Pengguna Konsumen Fleet Engine Delivery

roles/fleetengine.deliveryConsumer
Memberikan izin untuk menelusuri tugas menggunakan ID pelacakan, dan untuk membaca, tetapi tidak memperbarui informasi tugas. Token yang dibuat oleh akun layanan dengan peran ini biasanya digunakan dari browser web konsumen pengiriman.
Admin Pengiriman Fleet Engine

roles/fleetengine.deliveryAdmin
Memberikan izin baca dan tulis untuk resource pengiriman. Principal dengan peran ini tidak perlu menggunakan JWT dan sebaiknya menggunakan Kredensial Default Aplikasi. Klaim JWT kustom akan diabaikan. Peran ini harus dibatasi untuk lingkungan tepercaya (backend pelanggan).
Super User Cepat Pengiriman Mesin Perangkat **(TIDAK DIGUNAKAN LAGI)**

roles/fleetengine.deliverySuperUser
Memberikan izin ke semua API tugas dan kendaraan pengiriman. Token yang dibuat oleh akun layanan dengan peran ini biasanya digunakan dari server backend Anda.
Pembaca Armada Fleet Engine Delivery

roles/fleetengine.deliveryFleetReader
Memberikan izin untuk membaca kendaraan dan tugas pengiriman dan untuk menelusuri tugas menggunakan ID pelacakan. Token yang dibuat oleh akun layanan dengan peran ini biasanya digunakan dari browser web operator layanan pengiriman.

Organisasi yang melengkapi driver pengiriman dengan perangkat yang dikelola oleh IT perusahaan dapat memanfaatkan fleksibilitas yang ditawarkan oleh peran Pengguna Pengemudi Tepercaya Feet Engine dan memilih untuk mengintegrasikan beberapa atau semua interaksi Feet Engine di aplikasi seluler.

Organisasi yang mendukung kebijakan Bawa Perangkat Sendiri harus memilih keamanan peran Pengguna Pengemudi Fleet Engine Tidak Tepercaya dan hanya mengandalkan aplikasi seluler untuk mengirim pembaruan lokasi kendaraan ke Fleet Engine. Semua interaksi lainnya harus berasal dari server backend pelanggan.

Driver dan Consumer SDK dibuat berdasarkan peran standar ini. Namun, Anda dapat membuat peran khusus yang memungkinkan serangkaian izin arbitrer untuk dipaketkan bersama. Driver dan Consumer SDK akan menampilkan pesan error jika izin yang diperlukan tidak ada. Oleh karena itu, kami sangat merekomendasikan untuk menggunakan kumpulan peran standar yang ditampilkan di atas, bukan peran khusus.

Membuat Akun Layanan

Anda dapat membuat akun layanan menggunakan tab IAM & Admin > Service Accounts di Google Cloud Console. Dari menu drop-down Role, pilih Fleet Engine, lalu tetapkan salah satu peran ke akun layanan. Praktik yang baik adalah menunjukkan akun yang terkait dengan setiap peran. Misalnya, berikan nama yang bermakna untuk akun layanan.

Untuk memudahkan, jika Anda perlu membuat JWT untuk klien yang tidak tepercaya, menambahkan pengguna ke Service Account Token Creator Role akan memungkinkan mereka membuat token dengan alat command line gcloud.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

Dengan my-user@example.com adalah email yang digunakan untuk melakukan autentikasi dengan gcloud (gcloud auth list --format='value(account)').

Library Auth Fleet Engine

Fleet Engine menggunakan JWT untuk membatasi akses ke API Fleet Engine di lingkungan yang tidak tepercaya. Library Autentikasi Fleet Engine, tersedia di GitHub, menyederhanakan konstruksi JWT Fleet Engine dan menandatanganinya dengan aman.

Library ini memberikan manfaat berikut:

  • Menyederhanakan proses pembuatan Token Fleet Engine.
  • Menyediakan mekanisme penandatanganan token selain menggunakan file kredensial (seperti meniru identitas akun layanan).

Membuat JSON Web Token (JWT) untuk otorisasi

Jika tidak menggunakan Library Auth Fleet Engine, JWT harus dibuat langsung dalam codebase Anda. Hal ini mengharuskan Anda memiliki pemahaman yang mendalam tentang JWT dan bagaimana kaitannya dengan Fleet Engine. Inilah alasan kami SANGAT merekomendasikan penggunaan Library Auth Fleet Engine.

Dalam Fleet Engine, JWT menyediakan autentikasi berumur pendek dan memastikan bahwa perangkat hanya dapat memodifikasi kendaraan atau tugas yang diotorisasi. JWT berisi header dan bagian klaim. Bagian header berisi informasi seperti kunci pribadi yang akan digunakan (diperoleh dari akun layanan) dan algoritma enkripsi. Bagian klaim berisi informasi seperti waktu pembuatan token, waktu aktif token, layanan yang aksesnya diklaim token, dan informasi otorisasi lainnya untuk menentukan cakupan akses; misalnya, ID kendaraan pengiriman.

Bagian header JWT berisi kolom-kolom berikut:

KolomDeskripsi
alg Algoritma yang akan digunakan. `RS256`.
typ Jenis token. `JWT`.
kid ID kunci pribadi akun layanan Anda. Anda dapat menemukan nilai ini di kolom `private_key_id` pada file JSON akun layanan Anda. Pastikan untuk menggunakan kunci dari akun layanan dengan tingkat izin yang benar.

Bagian klaim JWT berisi kolom-kolom berikut:

KolomDeskripsi
iss Alamat email akun layanan Anda.
sub Alamat email akun layanan Anda.
aud SERVICE_NAME akun layanan Anda, dalam hal ini https://fleetengine.googleapis.com/
iat Stempel waktu saat token dibuat, yang ditentukan dalam detik yang telah berlalu sejak 00:00:00 UTC, 1 Januari 1970. Tunggu 10 menit agar miring. Jika stempel waktu sudah terlalu lampau, atau di masa mendatang, server mungkin melaporkan error.
exp Stempel waktu saat token berakhir, yang ditentukan dalam detik yang telah berlalu sejak 00:00:00 UTC, 1 Januari 1970. Permintaan gagal jika stempel waktu lebih dari satu jam.
authorization Bergantung pada kasus penggunaannya, konten dapat berisi `deliveryvehicleid`, `trackingid`, `taskid`, atau `taskids`.

Membuat token JWT mengacu pada menandatanganinya. Untuk petunjuk dan contoh kode guna membuat dan menandatangani JWT, lihat Otorisasi akun layanan tanpa OAuth. Selanjutnya, Anda dapat melampirkan token yang dibuat ke panggilan gRPC atau metode lain yang digunakan untuk mengakses Fleet Engine.

Klaim JWT

Last Mile Fleet Solution menggunakan klaim pribadi. Menggunakan klaim pribadi memastikan bahwa hanya klien yang diotorisasi yang dapat mengakses data mereka sendiri. Misalnya, saat backend Anda mengeluarkan Token Web JSON untuk perangkat seluler pengemudi pengiriman, token tersebut harus berisi klaim deliveryvehicleid dengan nilai ID kendaraan pengiriman pengemudi tersebut. Kemudian, bergantung pada peran pengemudi, token hanya mengaktifkan akses untuk ID kendaraan pengiriman tertentu, bukan ID kendaraan arbitrer lainnya.

Last Mile Fleet Solution menggunakan klaim pribadi berikut:

  • deliveryvehicleid - digunakan saat memanggil API per-pengiriman kendaraan.
  • taskid - gunakan saat memanggil API per tugas.
  • taskids - gunakan saat memanggil BatchCreateTasksAPI. Klaim ini harus berupa array, dan array harus berisi semua ID tugas yang diperlukan untuk menyelesaikan permintaan. Jangan sertakan klaim delivervehicleid, trackingid, atau taskid.
  • trackingid - gunakan saat memanggil GetTaskTrackingInfoAPI. Klaim harus cocok dengan ID pelacakan dalam permintaan. Jangan sertakan klaim delivervehicleid, taskid, atau taskids.

Token juga harus berisi klaim yang sesuai saat Anda memanggil API dari server backend, tetapi Anda dapat menggunakan nilai khusus tanda bintang ("*") untuk klaim deliveryvehicleid, taskid, dan trackingid. Tanda bintang ("*") juga dapat digunakan dalam klaim taskids, tetapi harus menjadi satu-satunya elemen dalam array.

Jika Anda ingin membuat dan menandatangani JSON secara langsung sebagai pembuat token, bukan menggunakan token akses OAuth 2.0, baca petunjuk untuk Otorisasi akun layanan tanpa OAuth dalam dokumentasi Developer Identitas.

Mekanisme untuk melampirkan token ke panggilan gRPC bergantung pada bahasa dan framework yang digunakan untuk melakukan panggilan. Mekanisme penetapan token ke panggilan HTTP adalah dengan menyertakan header Otorisasi dengan token pemilik yang nilainya adalah token, seperti yang tercantum dalam catatan otorisasi untuk kasus penggunaan pelacakan pengiriman individual atau performa armada.

Contoh berikut menunjukkan token untuk operasi per tugas dari server backend:

    {
      "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 berikut menunjukkan token untuk operasi pembuatan tugas batch dari server backend Anda:

    {
      "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 berikut menunjukkan token untuk operasi per kendaraan pengiriman dari server backend Anda:

    {
      "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": "*"
       }
    }

Contoh berikut menunjukkan token untuk pelanggan pengguna akhir:

    {
      "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 berikut menunjukkan token untuk aplikasi driver Anda:

    {
      "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"
       }
    }
  • Untuk kolom kid di header, tentukan ID kunci pribadi akun layanan Anda. Anda dapat menemukan nilai ini di kolom private_key_id pada file JSON akun layanan Anda.
  • Untuk kolom iss dan sub, tentukan alamat email akun layanan Anda. Anda dapat menemukan nilai ini di kolom client_email pada file JSON akun layanan.
  • Untuk kolom aud, tentukan https://SERVICE_NAME/.
  • Untuk kolom iat, tentukan stempel waktu saat token dibuat, dalam detik yang telah berlalu sejak 00:00:00 UTC, 1 Januari 1970. Tunggu 10 menit agar miring. Jika stempel waktu sudah terlalu lampau, atau di masa mendatang, server mungkin akan melaporkan error.
  • Untuk kolom exp, tentukan stempel waktu saat masa berlaku token berakhir, dalam detik sejak 00:00:00 UTC, 1 Januari 1970. Nilai yang direkomendasikan adalah iat + 3600.

Saat menandatangani token untuk diteruskan ke perangkat seluler atau pengguna akhir, pastikan Anda menggunakan file kredensial untuk peran Pengemudi Pengiriman atau Konsumen. Jika tidak, perangkat seluler atau pengguna akhir akan dapat mengubah atau melihat informasi yang tidak dapat mereka akses.