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 penerapan Fleet Engine. Panduan ini menjelaskan prosedur yang perlu dilakukan untuk mengamankan panggilan fungsi Fleet Engine.

Anda dapat mengonfigurasi kemampuan yang disediakan oleh Last Milet Fleet Solution melalui Konsol Google Cloud. API dan SDK ini memerlukan penggunaan Token Web JSON (JWT) yang telah ditandatangani menggunakan akun layanan yang dibuat dari Konsol Cloud.

Ringkasan

Sebagai bagian dari mekanisme otorisasinya, Fleet Engine memberikan keamanan tambahan dari panggilan yang berasal dari lingkungan rendah. Lingkungan kepercayaan rendah mencakup smartphone dan browser. Selain itu, Fleet Engine menggunakan Prinsip hak istimewa terendah, di mana panggilan harus diberikan hanya hak istimewa yang diperlukan agar dapat menyelesaikan tugasnya.

Untuk mengamankan panggilan fungsi yang berasal dari lingkungan kepercayaan rendah, Google rancang mekanisme yang digunakan kode Anda untuk membuat token di server backend yang merupakan lingkungan yang tepercaya sepenuhnya. Setiap panggilan memiliki deskripsi keamanan lengkap yang kemudian dienkripsi ke dalam JWT yang Anda teruskan dengan panggilan dari lingkungan apa pun.

Prinsip desain otentikasi

Alur autentikasi Fleet Engine menerapkan prinsip-prinsip desain berikut.

Peran IAM menentukan cakupan aktivitas yang diizinkan untuk pemanggil. Misalnya, peran SuperUser diizinkan untuk melakukan apa saja, sedangkan peran Untrusted Driver hanya diizinkan untuk melakukan pembaruan lokasi minimal.
Peran IAM dikaitkan dengan akun layanan.
JWT mengklaim lebih membatasi entity yang dapat dioperasikan oleh pemanggil. Ini bisa berupa tugas tertentu atau kendaraan pengiriman.
Permintaan yang dikirim ke Fleet Engine selalu berisi JWT.
- Karena JWT dikaitkan dengan akun layanan, permintaan yang dikirim ke Fleet Engine secara implisit terkait dengan akun layanan yang terkait dengan JWT.
Untuk meminta JWT yang sesuai yang kemudian dapat Anda teruskan ke Fleet Engine, kode Anda yang berjalan di lingkungan kepercayaan rendah harus terlebih dahulu memanggil kode Anda yang berjalan di lingkungan yang sepenuhnya tepercaya.
Fleet Engine melakukan pemeriksaan keamanan berikut:
1. Peran IAM yang terkait dengan akun layanan memberikan otorisasi yang benar bagi pemanggil untuk melakukan panggilan API.
2. Klaim JWT yang diteruskan dalam permintaan memberikan otorisasi yang benar untuk pemanggil untuk beroperasi pada entity.

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.
Aplikasi klien meminta JWT dari backend partner. Pemohon dapat berupa aplikasi Driver, aplikasi Konsumen, atau aplikasi pemantauan.
Fleet Engine menerbitkan JWT untuk akun layanan masing-masing. Aplikasi klien menerima JWT.
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:

Membuat Project Google Cloud menggunakan Konsol Google Cloud.
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:

Role	Deskripsi
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.
Super User Fleet Engine Delivery `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. Library Auth Fleet Engine baru, 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).
Melampirkan token bertanda tangan ke permintaan keluar yang dibuat dari stub gRPC atau klien GAPIC.

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:

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