Autentikasi dengan Azure Maps

Artikel
10/18/2023

Azure Peta mendukung tiga cara untuk mengautentikasi permintaan: Autentikasi Kunci Bersama, autentikasi ID Microsoft Entra, dan autentikasi Token Tanda Tangan Akses Bersama (SAS). Artikel ini menjelaskan kedua metode autentikasi untuk membantu memandu implementasi layanan Azure Maps Anda. Artikel ini juga menjelaskan kontrol akun lain seperti menonaktifkan autentikasi lokal untuk Azure Policy dan Berbagi Sumber Daya Lintas Asal (CORS).

Catatan

Untuk meningkatkan komunikasi yang aman dengan Azure Maps, kini kami mendukung Transport Layer Security (TLS) 1.2 dan kami menonaktifkan dukungan untuk TLS 1.0 dan 1.1. Jika saat ini Anda menggunakan TLS 1.x, evaluasi kesiapan TLS 1.2 Anda dan kembangkan rencana migrasi dengan pengujian yang dijelaskan di Memecahkan Masalah TLS 1.0.

Autentikasi Kunci Bersama

Untuk informasi tentang menampilkan kunci Anda di portal Azure, lihat Menampilkan detail autentikasi.

Kunci primer dan sekunder dibuat setelah akun Azure Maps dibuat. Anda didorong untuk menggunakan kunci primer sebagai kunci langganan saat memanggil Azure Maps dengan autentikasi kunci bersama. Autentikasi Kunci Bersama meneruskan kunci yang dihasilkan oleh akun Azure Maps ke layanan Azure Maps. Untuk setiap permintaan ke layanan Azure Maps, tambahkan kunci langganan sebagai parameter ke URL. Kunci sekunder dapat digunakan dalam skenario seperti perubahan kunci gulir.

Contoh menggunakan kunci langganan sebagai parameter di URL Anda:

https://atlas.microsoft.com/mapData/upload?api-version=1.0&dataFormat=zip&subscription-key={Your-Azure-Maps-Subscription-key}

Penting

Kunci Primer dan Sekunder harus diperlakukan sebagai data sensitif. Kunci bersama digunakan untuk mengautentikasi semua Azure Peta REST API. Pengguna yang menggunakan kunci bersama harus mengabstraksikan kunci API, baik melalui variabel lingkungan atau penyimpanan rahasia yang aman, di mana ia dapat dikelola secara terpusat.

Autentikasi Microsoft Entra

Langganan Azure disediakan dengan penyewa Microsoft Entra untuk mengaktifkan kontrol akses yang halus. Azure Peta menawarkan autentikasi untuk layanan Azure Peta menggunakan ID Microsoft Entra. MICROSOFT Entra ID menyediakan autentikasi berbasis identitas untuk pengguna dan aplikasi yang terdaftar di penyewa Microsoft Entra.

Azure Peta menerima token akses OAuth 2.0 untuk penyewa Microsoft Entra yang terkait dengan langganan Azure yang berisi akun Azure Peta. Azure Maps juga menerima token untuk:

Pengguna Microsoft Entra
Aplikasi mitra yang menggunakan izin yang didelegasikan oleh pengguna
Identitas terkelola untuk sumber daya Azure

Azure Maps menciptakan pengidentifikasi unik (ID klien) untuk setiap akun Azure Maps. Anda dapat meminta token dari ID Microsoft Entra saat menggabungkan ID klien ini dengan parameter lain.

Untuk informasi selengkapnya tentang cara mengonfigurasi ID Microsoft Entra dan meminta token untuk Azure Peta, lihat Mengelola autentikasi di Azure Peta.

Untuk informasi umum tentang mengautentikasi dengan ID Microsoft Entra, lihat Autentikasi vs. otorisasi.

Identitas terkelola untuk sumber daya Azure dan Azure Maps

Identitas terkelola untuk sumber daya Azure menyediakan layanan Azure dengan prinsip keamanan berbasis aplikasi yang dikelola secara otomatis yang dapat mengautentikasi dengan ID Microsoft Entra. Dengan kontrol akses berbasis peran Azure (Azure RBAC), prinsip keamanan identitas terkelola dapat diberi wewenang untuk mengakses layanan Azure Maps. Beberapa contoh identitas terkelola termasuk: Azure App Service, Azure Functions, dan Azure Virtual Machines. Untuk daftar identitas terkelola, lihat Layanan Azure yang dapat menggunakan identitas terkelola untuk mengakses layanan lain. Untuk informasi selengkapnya tentang identitas terkelola, lihat Mengelola autentikasi di Azure Peta.

Mengonfigurasi autentikasi Microsoft Entra aplikasi

Aplikasi mengautentikasi dengan penyewa Microsoft Entra menggunakan satu atau beberapa skenario yang didukung yang disediakan oleh ID Microsoft Entra. Setiap skenario aplikasi Microsoft Entra mewakili persyaratan yang berbeda berdasarkan kebutuhan bisnis. Beberapa aplikasi dapat memerlukan pengalaman masuk pengguna dan aplikasi lain mungkin memerlukan pengalaman masuk aplikasi. Untuk informasi selengkapnya, lihat Alur autentikasi dan skenario aplikasi.

Setelah aplikasi menerima token akses, SDK dan/atau aplikasi mengirimkan permintaan HTTPS dengan kumpulan header HTTP yang diperlukan berikut sebagai tambahan dari header HTTP REST API lainnya:

Nama header	Value
x-ms-client-id	30d7cc... 9f55
Otorisasi	Pembawa eyJ0e... HNIVN

Catatan

x-ms-client-id adalah GUID berbasis akun Azure Maps yang muncul di halaman autentikasi Azure Maps.

Berikut adalah contoh permintaan rute Azure Peta yang menggunakan token Microsoft Entra ID OAuth Bearer:

GET /route/directions/json?api-version=1.0&query=52.50931,13.42936:52.50274,13.43872
Host: atlas.microsoft.com
x-ms-client-id: 30d7cc….9f55
Authorization: Bearer eyJ0e…HNIVN

Untuk informasi tentang menampilkan ID klien Anda, lihat Menampilkan detail autentikasi.

Tip

Mendapatkan ID Klien secara terprogram

Saat menggunakan PowerShell, ID Klien disimpan sebagai UniqueId Properti dalam IMapsAccount objek. Anda mengambil properti ini menggunakan Get-AzMapsAccount, misalnya:

$maps = Get-AzMapsAccount -Name {Azure-Maps_Account-Name} -ResourceGroupName {Resource-Group-Name} -SubscriptionId {SubscriptionId}
$ClientId = $maps.UniqueId

Saat menggunakan Azure CLI gunakan az maps account show perintah dengan --query parameter, misalnya:

$ClientId = az maps account show --name {Azure-Maps_Account-Name} --resource-group {Resource-Group-Name} --subscription {SubscriptionId} --query properties.uniqueId

Otorisasi dengan kontrol akses berbasis peran

Prasyarat

Jika Anda baru menggunakan Azure RBAC, gambaran umum kontrol akses berbasis peran Azure (Azure RBAC) menyediakan jenis Utama diberikan serangkaian izin, juga dikenal sebagai definisi peran. Definisi peran menyediakan izin untuk tindakan REST API. Azure Peta mendukung akses ke semua jenis utama untuk kontrol akses berbasis peran Azure (Azure RBAC) termasuk: pengguna Microsoft Entra individu, grup, aplikasi, sumber daya Azure, dan identitas terkelola Azure. Menerapkan akses ke satu atau beberapa akun Azure Maps dikenal sebagai cakupan. Penetapan peran dibuat saat prinsipal, definisi peran, dan cakupan diterapkan.

Gambaran Umum

Bagian berikutnya membahas konsep dan komponen integrasi Azure Maps dengan Azure RBAC. Sebagai bagian dari proses untuk menyiapkan akun Azure Peta Anda, direktori Microsoft Entra dikaitkan dengan langganan Azure, yang berada di akun Azure Peta.

Saat mengonfigurasi Azure RBAC, Anda memilih prinsip keamanan dan menerapkannya ke penetapan peran. Untuk mempelajari cara menambahkan penetapan peran di portal Azure, lihat Menetapkan peran Azure menggunakan portal Azure.

Memilih definisi peran

Jenis definisi peran berikut ada untuk mendukung skenario aplikasi.

Definisi Peran Azure	Deskripsi
Pencarian Azure Maps dan Render Pembaca Data	Menyediakan akses hanya untuk mencari dan merender API REST Azure Maps untuk membatasi akses ke kasus penggunaan browser web dasar.
Pembaca Data Azure Maps	Menyediakan akses ke API REST Azure Maps yang tidak dapat diubah.
Kontributor Data Azure Maps	Menyediakan akses ke API REST Azure Maps yang dapat diubah. Mutabilitas, didefinisikan oleh tindakan: tulis dan hapus.
Peran Baca dan Batch Data Azure Peta	Peran ini dapat digunakan untuk menetapkan tindakan baca dan batch di Azure Peta.
Definisi Peran Kustom	Membuat peran yang dibuat untuk mengaktifkan akses terbatas yang fleksibel ke API REST Azure Maps.

Beberapa layanan Azure Maps mungkin memerlukan hak istimewa yang ditingkatkan untuk melakukan tindakan tulis atau hapus pada API REST Azure Maps. Peran Kontributor Data Azure Maps diperlukan untuk layanan yang menyediakan tindakan tulis atau hapus. Tabel berikut ini menjelaskan layanan mana yang berlaku untuk Kontributor Data Azure Maps saat menggunakan tindakan tulis atau hapus pada layanan tertentu. Ketika hanya tindakan baca yang diperlukan, peran Pembaca Data Azure Maps dapat digunakan sebagai pengganti peran Kontributor Data Azure Maps.

Layanan Azure Maps	Definisi Peran Azure Maps
Data	Kontributor Data Azure Maps
Pembuat	Kontributor Data Azure Maps
Spasial	Kontributor Data Azure Maps
Pencarian dan Rute Batch	Kontributor Data Azure Maps

Untuk informasi tentang menampilkan pengaturan RBAC Azure Anda, lihat Cara mengonfigurasi Azure RBAC untuk Azure Maps.

Definisi peran kustom

Salah satu aspek keamanan aplikasi adalah prinsip hak istimewa paling sedikit, praktik membatasi hak akses terhadap hak yang diperlukan untuk pekerjaan saat ini. Membatasi hak akses dicapai dengan membuat definisi peran kustom yang mendukung kasus penggunaan yang membutuhkan granularitas lebih lanjut untuk kontrol akses. Untuk membuat definisi peran kustom, Anda dapat memilih tindakan data tertentu untuk disertakan atau dikecualikan untuk definisi.

Definisi peran kustom kemudian dapat digunakan dalam penetapan peran untuk setiap prinsip keamanan. Untuk mempelajari selengkapnya tentang definisi peran kustom Azure, lihat Peran kustom Azure.

Berikut adalah beberapa contoh skenario saat peran kustom dapat meningkatkan keamanan aplikasi.

Skenario	Tindakan Data Peran Kustom
Halaman web masuk publik atau interaktif dengan petak peta dasar dan tanpa API REST lainnya.	`Microsoft.Maps/accounts/services/render/read`
Aplikasi yang hanya memerlukan pengkodean geografis terbalik dan tanpa API REST lainnya.	`Microsoft.Maps/accounts/services/search/read`
Peran untuk keamanan utama yang meminta pembacaan data peta berbasis Azure Maps Creator dan API REST petak peta dasar.	`Microsoft.Maps/accounts/services/data/read`, `Microsoft.Maps/accounts/services/render/read`
Peran untuk prinsip keamanan yang memerlukan membaca, menulis, dan menghapus data peta berbasis Kreator. Didefinisikan sebagai peran editor data peta yang tidak mengizinkan akses ke REST API lain seperti petak peta dasar.	`Microsoft.Maps/accounts/services/data/read`, , `Microsoft.Maps/accounts/services/data/writeMicrosoft.Maps/accounts/services/data/delete`

Memahami lingkup

Saat membuat penetapan peran, penetapan peran ditentukan dalam hierarki sumber daya Azure. Bagian atas hierarki adalah grup manajemen dan yang terendah adalah sumber daya Azure, seperti akun Azure Peta. Menetapkan penetapan peran ke grup sumber daya dapat mengaktifkan akses ke beberapa akun atau sumber daya Azure Maps dalam grup.

Tip

Rekomendasi umum Microsoft adalah menetapkan akses ke cakupan akun Azure Maps karena mencegah akses yang tidak diinginkan ke akun Azure Maps lain yang ada di langganan Azure yang sama.

Nonaktifkan autentikasi lokal

Akun Azure Peta mendukung properti Azure standar di API Manajemen untuk Microsoft.Maps/accounts dipanggil .disableLocalAuth Ketika true, semua autentikasi ke Azure Peta data-plane REST API dinonaktifkan, kecuali autentikasi Microsoft Entra. Ini dikonfigurasi menggunakan Azure Policy untuk mengontrol distribusi dan pengelolaan kunci bersama dan token SAS. Untuk informasi selengkapnya, lihat Apa itu Kebijakan Azure?.

Menonaktifkan autentikasi lokal tidak segera berlaku. Biarkan beberapa menit agar layanan memblokir permintaan autentikasi di masa mendatang. Untuk mengaktifkan kembali autentikasi lokal, atur properti ke false dan setelah beberapa menit autentikasi lokal dilanjutkan.

{
  // omitted other properties for brevity.
  "properties": {
    "disableLocalAuth": true
  }
}

Autentikasi token shared access signature

Token shared access signature (SAS) adalah token autentikasi yang dibuat menggunakan format JSON Web token (JWT) dan ditandatangani secara kriptografis untuk membuktikan autentikasi untuk aplikasi ke Azure Maps REST API. Token SAS, dibuat dengan mengintegrasikan identitas terkelola yang ditetapkan pengguna dengan akun Azure Peta di langganan Azure Anda. Identitas terkelola yang ditetapkan pengguna diberikan otorisasi ke akun Azure Peta melalui Azure RBAC menggunakan definisi peran bawaan atau kustom.

Perbedaan utama fungsi dari token SAS dari token akses Microsoft Entra:

Masa pakai token untuk kedaluwarsa maksimum satu hari (24 jam).
Kontrol akses lokasi dan geografi Azure per token.
Batas tarif per token untuk perkiraan 1 hingga 500 permintaan per detik.
Kunci pribadi token adalah kunci utama dan sekunder dari sumber daya akun Azure Maps.
Objek Perwakilan Layanan untuk otorisasi disediakan oleh identitas terkelola yang ditetapkan pengguna.

Token SAS tidak dapat berubah. Ini berarti bahwa setelah token dibuat, token SAS valid hingga kedaluwarsa terpenuhi dan konfigurasi wilayah yang diizinkan, batas tarif, dan identitas terkelola yang ditetapkan pengguna tidak dapat diubah. Baca selengkapnya di bawah ini tentang memahami kontrol akses untuk pencabutan token SAS dan perubahan pada kontrol akses.

Memahami batas tarif token SAS

Batas tarif maksimum token SAS dapat mengontrol penagihan untuk sumber daya Azure Maps

Saat menentukan batas tarif maksimum pada token (maxRatePerSecond), kelebihan tarif tidak ditagih ke akun yang memungkinkan Anda menetapkan batas atas transaksi yang dapat ditagih untuk akun, saat menggunakan token. Namun, aplikasi menerima respons kesalahan klien dengan 429 (TooManyRequests) untuk semua transaksi setelah batas itu tercapai. Ini adalah tanggung jawab aplikasi untuk mengelola coba lagi dan distribusi token SAS. Tidak ada batasan berapa banyak token SAS yang dapat dibuat untuk akun. Untuk memungkinkan peningkatan atau penurunan batas token yang ada; token SAS baru harus dibuat. Token SAS lama masih berlaku hingga kedaluwarsa.

Contoh Perkiraan:

Perkiraan Tingkat Maksimum Per Detik	Tarif Aktual Per Detik	Durasi tingkat berkelanjutan dalam hitungan detik	Total transaksi yang dapat ditagih
10	20	600	6.000

Batas tarif aktual bervariasi berdasarkan kemampuan Azure Peta untuk memberlakukan konsistensi dalam rentang waktu tertentu. Namun, ini memungkinkan kontrol preventif biaya penagihan.

Batas tarif diberlakukan per lokasi Azure, bukan secara global atau geografis

Misalnya, satu token SAS dengan 10 maxRatePerSecond dapat digunakan untuk membatasi keluaran di East US lokasi. Jika token yang sama digunakan West US 2, penghitung baru dibuat untuk membatasi keluaran hingga 10 di lokasi tersebut, terlepas dari lokasinya East US. Untuk mengontrol biaya dan meningkatkan kemungkinan untuk melakukan prediksi, kami sarankan:

Buat token SAS dengan lokasi Azure yang diizinkan untuk geografi yang ditargetkan. Lanjutkan membaca untuk memahami pembuatan token SAS.
Gunakan titik akhir REST API bidang data geografis, https://us.atlas.microsoft.com atau https://eu.atlas.microsoft.com.

Pertimbangkan topologi aplikasi tempat titik akhir https://us.atlas.microsoft.com merutekan ke lokasi AS yang sama dengan layanan Azure Maps yang dihosting, seperti East US, West Central US, atau West US 2. Gagasan yang sama berlaku untuk titik akhir geografis lainnya seperti https://eu.atlas.microsoft.com antara West Europe dan North Europe. Untuk mencegah penolakan otorisasi yang tidak terduga, gunakan token SAS yang menggunakan lokasi Azure yang sama dengan yang digunakan aplikasi. Lokasi titik akhir ditentukan menggunakan Azure Maps Management REST API.

Batas tarif bawaan menjadi patokan batas tarif token SAS

Seperti yang dijelaskan dalam batas tarif Azure Peta, penawaran layanan individual memiliki berbagai batas tarif yang diberlakukan sebagai agregat akun.

Pertimbangkan kasus layanan Pencarian - Non-Batch Reverse, dengan batas 250 kueri per detik (QPS) untuk tabel berikut. Setiap tabel mewakili perkiraan total transaksi yang berhasil dari penggunaan contoh.

Tabel pertama menunjukkan satu token yang memiliki permintaan maksimum per detik 500, dan penggunaan aktual aplikasi adalah 500 permintaan per detik selama durasi 60 detik. layanan Pencarian - Non-Batch Reverse memiliki batas tarif 250, yang berarti dari total 30.000 permintaan yang dibuat dalam 60 detik; 15.000 permintaan tersebut adalah transaksi yang dapat ditagih. Permintaan yang tersisa menghasilkan kode 429 (TooManyRequests)status .

Nama	Perkiraan Tingkat Maksimum Per Detik	Tarif Aktual Per Detik	Durasi tingkat berkelanjutan dalam hitungan detik	Perkiraan total transaksi yang berhasil
token	500	500	60	~15.000

Misalnya, jika dua token SAS dibuat, dan menggunakan lokasi yang sama dengan akun Azure Maps, setiap token sekarang berbagi batas tarif default 250 QPS. Jika setiap token digunakan pada saat yang sama dengan throughput yang sama, token 1 dan token 2 akan berhasil memberikan masing-masing 7500 transaksi yang berhasil.

Nama	Perkiraan Tingkat Maksimum Per Detik	Tarif Aktual Per Detik	Durasi tingkat berkelanjutan dalam hitungan detik	Perkiraan total transaksi yang berhasil
token 1	250	250	60	~7500
token 2	250	250	60	~7500

Memahami kontrol akses token SAS

Token SAS menggunakan RBAC untuk mengontrol akses ke REST API. Saat Anda membuat token SAS, identitas terkelola prasyarat di Akun Peta diberi peran Azure RBAC yang memberikan akses ke tindakan REST API tertentu. Lihat Memilih definisi peran untuk menentukan API mana yang diizinkan aplikasi.

Jika Anda ingin menetapkan akses sementara dan menghapus akses sebelum token SAS kedaluwarsa, cabut token. Alasan lain untuk mencabut akses mungkin jika token didistribusikan dengan Azure Maps Data Contributor penetapan peran secara tidak sengaja dan siapa pun dengan token SAS mungkin dapat membaca dan menulis data ke Azure Peta REST API yang dapat mengekspos data sensitif atau biaya keuangan yang tidak terduga dari penggunaan.

ada dua opsi untuk mencabut akses untuk token SAS:

Regenerasi kunci yang digunakan oleh token SAS atau secondaryKey dari akun peta.
Hapus penetapan peran untuk identitas terkelola pada akun peta terkait.

Peringatan

Menghapus identitas terkelola yang digunakan oleh token SAS atau mencabut kontrol akses identitas terkelola akan menyebabkan instans aplikasi Anda menggunakan token SAS dan identitas terkelola dengan sengaja mengembalikan 401 Unauthorized atau 403 Forbidden dari Azure Maps REST API yang akan membuat gangguan aplikasi.

Untuk menghindari gangguan:

Tambahkan identitas terkelola kedua ke Akun Map dan berikan identitas terkelola baru tugas peran yang benar.
Buat token SAS menggunakan secondaryKey, atau identitas terkelola yang berbeda dari yang sebelumnya, sebagai signingKey dan distribusikan token SAS baru ke aplikasi.
Meregenerasi kunci utama, menghapus identitas terkelola dari akun, dan menghapus penetapan peran untuk identitas terkelola.

Membuat token SAS

Untuk membuat token SAS, Anda harus memiliki Contributor akses peran untuk mengelola akun Peta Azure dan identitas yang ditetapkan pengguna di langganan Azure.

Penting

Akun Azure Maps yang ada yang dibuat di lokasi global Azure tidak mendukung identitas terkelola.

Pertama, Anda harus Membuat identitas terkelola yang ditetapkan pengguna di lokasi yang sama dengan akun Azure Maps.

Tip

Anda harus menggunakan lokasi yang sama untuk identitas terkelola dan akun Azure Maps.

Setelah identitas terkelola dibuat, Anda dapat membuat atau memperbarui akun Azure Maps dan melampirkannya. Untuk informasi selengkapnya, lihat Mengelola akun Azure Peta Anda.

Setelah akun berhasil dibuat atau diperbarui dengan identitas terkelola; tetapkan kontrol akses berbasis peran untuk identitas terkelola ke peran data Azure Peta di cakupan akun. Hal ini memungkinkan identitas terkelola mendapatkan akses ke Azure Maps REST API untuk akun map Anda.

Selanjutnya, buat token SAS menggunakan alat Azure Management SDK, cantumkan operasi SAS di API Manajemen Akun, atau halaman portal Azure Tanda Tangan Akses Bersama dari sumber daya akun Peta.

Parameter token SAS:

Nama Parameter	Contoh Nilai	Deskripsi
signingKey	`primaryKey`	Diperlukan, nilai enum string untuk signingKey baik `primaryKey`, `secondaryKey` atau identitas terkelola digunakan untuk membuat tanda tangan SAS.
principalId	`<GUID>`	Diperlukan, principalId adalah ID Objek (utama) dari identitas terkelola yang ditetapkan pengguna yang dilampirkan ke akun peta.
wilayah	`[ "eastus", "westus2", "westcentralus" ]`	Optional, nilai default adalah `null`. Wilayah mengontrol wilayah mana yang dapat digunakan token SAS di Azure Peta REST data-plane API. Menghilangkan parameter wilayah memungkinkan token SAS digunakan tanpa batasan apa pun. Saat digunakan dalam kombinasi dengan titik akhir geografis bidang data Azure Peta seperti `us.atlas.microsoft.com` dan `eu.atlas.microsoft.com` memungkinkan aplikasi mengontrol penggunaan dengan dalam geografi yang ditentukan. Hal ini memungkinkan pencegahan penggunaan di geografi lain.
maxRatePerSecond	500	Diperlukan, perkiraan permintaan maksimum yang ditentukan per detik yang diberikan token SAS. Setelah batas tercapai, lebih banyak throughput dibatasi dengan kode `429 (TooManyRequests)`status HTTP .
mulai	`2021-05-24T10:42:03.1567373Z`	Diperlukan, tanggal UTC yang menentukan tanggal dan waktu token menjadi aktif.
expiry	`2021-05-24T11:42:03.1567373Z`	Diperlukan, tanggal UTC yang menentukan tanggal dan waktu token berakhir. Durasi antara mulai dan kedaluwarsa tidak boleh lebih dari 24 jam.

Mengonfigurasi aplikasi dengan token SAS

Setelah aplikasi menerima token SAS, Azure Maps SDK dan/atau aplikasi akan mengirimkan permintaan HTTPS dengan kumpulan header HTTP yang diperlukan berikut sebagai tambahan dari header HTTP REST API lainnya:

Nama header	Value
Otorisasi	jwt-sas eyJ0e....HNIVN

Catatan

jwt-sas adalah skema autentikasi menggunakan token SAS. Jangan sertakan x-ms-client-id atau header Otorisasi lainnya atau subscription-key parameter string kueri.

CORS adalah fitur HTTP yang mengaktifkan aplikasi web yang berjalan dalam satu domain untuk mengakses sumber daya di domain lain. Browser web menerapkan pembatasan keamanan yang dikenal sebagai kebijakan asal yang sama yang mencegah halaman web memanggil API di domain yang berbeda; CORS menyediakan cara yang aman untuk memungkinkan satu domain (domain asal) untuk memanggil API di domain lain. Dengan menggunakan sumber daya akun Azure Peta, Anda dapat mengonfigurasi asal mana yang diizinkan untuk mengakses Azure Peta REST API dari aplikasi Anda.

Penting

CORS bukanlah mekanisme otorisasi. Setiap permintaan yang dibuat ke akun peta menggunakan REST API, saat CORS diaktifkan, juga memerlukan skema autentikasi akun peta yang valid seperti Kunci Bersama, ID Entra Microsoft, atau token SAS.

CORS dapat digunakan untuk semua tingkatan harga akun map, titik akhir bidang data, dan lokasi.

Prasyarat

Untuk mencegah eksekusi kode berbahaya pada klien, browser modern memblokir permintaan dari aplikasi web ke sumber daya yang berjalan di domain terpisah.

Jika Anda tidak terbiasa dengan CORS, lihat Berbagi sumber daya lintas asal (CORS), ini memungkinkan Access-Control-Allow-Origin header mendeklarasikan asal mana yang diizinkan untuk memanggil titik akhir akun Azure Peta. Protokol CORS tidak spesifik untuk Azure Peta.

Permintaan CORS

Permintaan CORS dari domain asal dapat terdiri dari dua permintaan terpisah:

Permintaan preflight, yang menanyakan pembatasan CORS yang diberlakukan oleh layanan. Permintaan preflight diperlukan kecuali permintaan adalah metode standar GET, HEAD, POST, atau permintaan yang berisi Authorization header permintaan.
Permintaan yang sebenarnya, dibuat karena sumber daya yang diinginkan.

Permintaan Preflight

Permintaan preflight dilakukan tidak hanya sebagai langkah keamanan untuk memastikan bahwa server memahami metode dan header yang dikirim dalam permintaan aktual dan bahwa server mengetahui dan mempercayai sumber permintaan, tetapi juga meminta pembatasan CORS yang telah ditetapkan untuk akun peta. Browser web (atau agen pengguna lainnya) mengirimkan permintaan OPTIONS yang mencakup header permintaan, metode, dan domain asal. Layanan akun map mencoba mengambil aturan CORS apa pun jika autentikasi akun memungkinkan melalui protokol preflight CORS.

Jika autentikasi tidak memungkinkan, layanan peta mengevaluasi serangkaian aturan CORS yang telah dikonfigurasi sebelumnya yang menentukan domain asal, metode permintaan, dan header permintaan mana yang dapat ditentukan pada permintaan aktual terhadap layanan peta. Secara default, akun map dikonfigurasi untuk memungkinkan semua asal agar dapat mengaktifkan integrasi yang lancar ke browser web.

Layanan merespons permintaan preflight dengan header Access-Control yang diperlukan jika kriteria berikut terpenuhi:

Permintaan OPTIONS berisi header CORS yang diperlukan (header Asal dan Access-Control-Request-Method)
Autentikasi berhasil dan aturan CORS diaktifkan untuk akun yang cocok dengan permintaan preflight.
Autentikasi dilewati karena header permintaan yang diperlukan Authorization yang tidak dapat ditentukan pada permintaan preflight.

Ketika permintaan preflight berhasil, layanan merespons dengan kode status 200 (OK), dan menyertakan header Access-Control yang diperlukan dalam respons.

Layanan menolak permintaan preflight jika kondisi berikut terjadi:

Jika permintaan OPTIONS tidak berisi header CORS yang diperlukan (header Asal dan Access-Control-Request-Method), layanan merespons dengan kode 400 (Bad request)status .
Jika autentikasi berhasil pada permintaan preflight dan tidak ada aturan CORS yang cocok dengan permintaan preflight, layanan merespons dengan kode 403 (Forbidden)status . Ini dapat terjadi jika aturan CORS dikonfigurasi untuk menerima asal yang tidak cocok dengan header permintaan asal klien browser saat ini.

Catatan

Permintaan preflight dievaluasi terhadap layanan dan bukan terhadap sumber daya yang diminta. Pemilik akun harus mengaktifkan CORS dengan mengatur properti akun yang sesuai agar permintaan berhasil.

Permintaan Aktual

Setelah permintaan preflight diterima dan respons dikembalikan, browser mengirimkan permintaan aktual terhadap layanan peta. Browser segera menolak permintaan aktual jika permintaan preflight ditolak.

Permintaan aktual diperlakukan sebagai permintaan normal terhadap layanan map. Kehadiran Origin header menunjukkan bahwa permintaan adalah permintaan CORS dan layanan kemudian memvalidasi terhadap aturan CORS. Jika kecocokan ditemukan, header Access-Control ditambahkan ke respons dan dikirim kembali ke klien. Jika kecocokan tidak ditemukan, respons mengembalikan yang 403 (Forbidden) menunjukkan kesalahan asal CORS.

Mengaktifkan kebijakan CORS

Saat akun Peta dibuat atau diperbarui, propertinya menentukan asal yang diizinkan untuk dikonfigurasi. Anda dapat mengatur aturan CORS pada properti akun Azure Maps melalui Azure Maps Management SDK, Azure Maps Management REST API, dan portal. Setelah Anda menetapkan aturan CORS untuk layanan, maka permintaan yang diotorisasi dengan benar yang dibuat ke layanan dari domain lain dievaluasi untuk menentukan apakah aturan tersebut diizinkan sesuai dengan aturan yang telah Anda tentukan. Misalnya:

{
  "location": "eastus",
  "sku": {
    "name": "G2"
  },
  "kind": "Gen2",
  "properties": {
    "cors": {
      "corsRules": [
        {
          "allowedOrigins": [
            "https://www.azure.com",
            "https://www.microsoft.com"
          ]
        }
      ]
    }
  }
}

Hanya satu aturan CORS dengan daftar asal yang diizinkan yang dapat ditetapkan. Setiap asal memungkinkan permintaan HTTP dibuat ke Azure Maps REST API di browser web dari asal yang ditentukan.

Hapus kebijakan CORS

Anda dapat menghapus CORS:

Secara manual di portal Azure
Secara terprogram menggunakan:
- Azure Peta SDK
- REST API manajemen Azure Peta
- Templat ARM

Tip

Jika Anda menggunakan REST API manajemen Azure Maps, gunakan PUT atau PATCH dengan daftar kosong corsRule di badan permintaan.

{
  "location": "eastus",
  "sku": {
    "name": "G2"
  },
  "kind": "Gen2",
  "properties": {
        "cors": {
          "corsRules": []
        }
    }
  }
}

Memahami transaksi penagihan

Azure Peta tidak menghitung transaksi penagihan untuk:

Kode Status HTTP 5xx
401 (TidakDiizinkan)
403 (Terlarang)
408 (Waktu Habis)
429 (PermintaanTerlaluBanyak)
Permintaan Preflight CORS

Untuk informasi selengkapnya tentang transaksi penagihan dan informasi harga Azure Peta lainnya, lihat Harga Azure Peta.

Langkah berikutnya

Untuk mempelajari selengkapnya tentang praktik terbaik keamanan, lihat:

Praktik terbaik autentikasi dan otorisasi

Untuk mempelajari selengkapnya tentang mengautentikasi aplikasi dengan MICROSOFT Entra ID dan Azure Peta, lihat:

Kelola autentikasi di Azure Maps

Untuk mempelajari selengkapnya tentang mengautentikasi Azure Peta Control dengan ID Microsoft Entra, lihat:

Menggunakan Kontrol Peta Azure Maps

Autentikasi dengan Azure Maps

Autentikasi Kunci Bersama

Autentikasi Microsoft Entra

Identitas terkelola untuk sumber daya Azure dan Azure Maps

Mengonfigurasi autentikasi Microsoft Entra aplikasi

Otorisasi dengan kontrol akses berbasis peran

Prasyarat

Gambaran Umum

Memilih definisi peran

Definisi peran kustom

Memahami lingkup

Nonaktifkan autentikasi lokal

Autentikasi token shared access signature

Memahami batas tarif token SAS

Batas tarif maksimum token SAS dapat mengontrol penagihan untuk sumber daya Azure Maps

Batas tarif diberlakukan per lokasi Azure, bukan secara global atau geografis

Batas tarif bawaan menjadi patokan batas tarif token SAS

Memahami kontrol akses token SAS

Membuat token SAS

Mengonfigurasi aplikasi dengan token SAS

Cross origin resource sharing (CORS)

Prasyarat

Permintaan CORS

Permintaan Preflight

Permintaan Aktual

Mengaktifkan kebijakan CORS

Hapus kebijakan CORS

Memahami transaksi penagihan

Langkah berikutnya

Sumber Daya Tambahan: