Solusi Armada Terakhir saat ini hanya tersedia untuk pelanggan tertentu. Hubungi bagian penjualan untuk mempelajari lebih lanjut.

Halaman ini diterjemahkan oleh Cloud Translation API.

Autentikasi dan otorisasi

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

Anda dapat mengonfigurasi kemampuan yang disediakan oleh Last Mile 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 memberikan otorisasi terhadap Fleet Engine harus menggunakan mekanisme Kredensial Default Aplikasi standar.

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

Prinsip desain autentikasi

Alur otentikasi Fleet Engine menggabungkan prinsip-prinsip desain berikut.

Peran IAM menentukan sekumpulan izin pada resource yang diizinkan untuk akun utama. Misalnya, peran Admin diizinkan untuk melakukan semuanya dengan Kredensial Default Aplikasi, sedangkan peran Pengemudi Tidak Tepercaya* hanya diizinkan untuk memperbarui lokasi kendaraan dan dibatasi penggunaan JWT untuk autentikasi dan otorisasi.
Untuk lingkungan yang tidak tepercaya, klaim JWT membatasi lebih lanjut entitas tempat pemanggil dapat beroperasi. Tugas ini bisa berupa tugas atau kendaraan pengiriman.
Kode Anda yang berjalan di lingkungan low-trust harus terlebih dahulu memanggil kode Anda yang berjalan di lingkungan tepercaya untuk menerbitkan 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.

Alur autentikasi

Diagram urutan berikut menunjukkan detail alur autentikasi ini.

Administrator fleet membuat akun layanan.
Administrator fleet menetapkan peran IAM tertentu ke akun layanan.
Administrator fleet mengonfigurasi backend mereka dengan akun layanan dan Kredensial Default Aplikasi.
Aplikasi klien meminta JWT dari backend pelanggan. Pemohon dapat berupa aplikasi Driver, aplikasi Konsumen, atau aplikasi pemantauan.
Backend pelanggan menandatangani dan menerbitkan JWT untuk masing-masing akun layanan. Aplikasi klien menerima JWT.
Aplikasi klien menggunakan JWT untuk terhubung ke Fleet Engine guna membaca atau mengubah data, bergantung pada peran IAM yang ditetapkan ke Fleet Engine selama fase penyiapan.

Diagram urutan autentikasi

Penyiapan project cloud

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

Untuk membuat project Google Cloud:

Membuat Project Google Cloud menggunakan Konsol Google Cloud.
Dengan menggunakan Dasbor API & Layanan, 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 serangkaian 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:

Peran	Deskripsi
Pengguna Pengemudi Tepercaya Pengiriman Fleet Engine `roles/fleetengine.deliveryTrustedDriver`	Memberikan izin untuk membuat dan memperbarui tugas dan kendaraan 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 atau dari server backend Anda.
Pengguna Pengemudi Tidak Tepercaya Pengiriman Fleet Engine `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 Pengiriman Fleet Engine `roles/fleetengine.deliveryConsumer`	Memberikan izin untuk menelusuri tugas menggunakan ID pelacakan, dan 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. Kepala sekolah 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).
~~Fleet Engine Delivery Super User~~ (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 Pengiriman Fleet Engine `roles/fleetengine.deliveryFleetReader`	Memberikan izin untuk membaca tugas dan kendaraan pengiriman serta menelusuri tugas menggunakan ID pelacakan. Token yang dibuat oleh akun layanan dengan peran ini biasanya digunakan dari browser web operator perangkat pengiriman.

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

Organisasi yang mendukung kebijakan Bawa Perangkat Sendiri harus memilih keamanan peran Pengguna Pengemudi Tidak Tepercaya Fleet Engine 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 kumpulan izin arbitrer untuk digabungkan. SDK Driver dan Konsumen akan menampilkan pesan error jika izin yang diperlukan tidak ada. Oleh karena itu, kami sangat merekomendasikan penggunaan 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 Konsol Google Cloud. Dari menu drop-down Peran, pilih Fleet Engine dan tetapkan salah satu peran ke akun layanan. Sebaiknya indikasikan akun yang dikaitkan dengan setiap peran. Misalnya, beri akun layanan nama yang bermakna.

Demi kemudahan, jika Anda perlu membuat JWT untuk klien yang tidak tepercaya, menambahkan pengguna ke Peran Pembuat Token Akun Layanan 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

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 Fleet Engine API di lingkungan yang tidak tepercaya. Library Auth Fleet Engine, tersedia di GitHub, menyederhanakan pembuatan 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 Token Web JSON (JWT) untuk otorisasi

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

Dalam Fleet Engine, JWT menyediakan autentikasi jangka pendek dan memastikan bahwa perangkat hanya dapat memodifikasi kendaraan atau tugas yang diizinkan. 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 oleh token, dan informasi otorisasi lainnya untuk mencakup akses ke bawah; misalnya, ID kendaraan pengiriman.

Bagian header JWT berisi kolom-kolom berikut:

Kolom	Deskripsi
alg	Algoritma yang akan digunakan. `RS256`.
typ	Jenis token. `JWT`.
anak	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:

Kolom	Deskripsi
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 berlalu sejak 00:00:00 UTC, 1 Januari 1970. Tunggu 10 menit untuk kemiringan. Jika stempel waktu terlalu lampau atau di masa mendatang, server mungkin melaporkan error.
exp	Stempel waktu saat token berakhir, yang ditentukan dalam detik yang berlalu sejak 1 Januari 1970 pukul 00.00.00 UTC. Permintaan akan gagal jika stempel waktu lebih dari satu jam pada masa mendatang.
authorization	Bergantung pada kasus penggunaannya, dapat berisi `deliveryvehicleid`, `trackingid`, `taskid`, atau `taskids`.

Membuat token JWT mengacu pada proses penandatanganannya. Untuk petunjuk dan contoh kode cara membuat dan menandatangani JWT, lihat Otorisasi akun layanan tanpa OAuth. Selanjutnya, Anda dapat memasang token yang telah 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 berwenang yang dapat mengakses data mereka sendiri. Misalnya, saat backend Anda menerbitkan Token Web JSON untuk perangkat seluler pengemudi pengiriman, token tersebut harus berisi klaim deliveryvehicleid dengan nilai ID kendaraan pengantaran 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 - digunakan 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 pembawa token, bukan menggunakan token akses OAuth 2.0, baca petunjuk untuk Otorisasi akun layanan tanpa OAuth di dokumentasi Developer Identitas.

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

Contoh berikut menunjukkan token untuk operasi per tugas 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": {
         "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 pengemudi 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 Anda.
Untuk kolom aud, tentukan https://SERVICE_NAME/.
Untuk kolom iat, tentukan stempel waktu saat token dibuat, dalam detik yang berlalu sejak 00:00:00 UTC, 1 Januari 1970. Tunggu 10 menit untuk kemiringan. Jika stempel waktu terlalu lampau atau di masa mendatang, server mungkin melaporkan error.
Untuk kolom exp, tentukan stempel waktu saat 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 seharusnya tidak dapat mereka akses.