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 menghasilkan 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:
Akun utama yang melakukan panggilan memiliki izin yang sesuai (melalui penetapan peran) untuk tindakan pada resource.
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.
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). |
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`. |
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:
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 memanggilBatchCreateTasksAPI
. Klaim ini harus berupa array, dan array harus berisi semua ID tugas yang diperlukan untuk menyelesaikan permintaan. Jangan sertakan klaimdelivervehicleid
,trackingid
, atautaskid
.trackingid
- gunakan saat memanggilGetTaskTrackingInfoAPI
. Klaim harus cocok dengan ID pelacakan dalam permintaan. Jangan sertakan klaimdelivervehicleid
,taskid
, atautaskids
.
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 kolomprivate_key_id
pada file JSON akun layanan Anda. - Untuk kolom
iss
dansub
, tentukan alamat email akun layanan Anda. Anda dapat menemukan nilai ini di kolomclient_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 adalahiat
+ 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.