Autentikasi dengan Azure Maps
Azure Maps mendukung tiga metode autentikasi: Kunci Bersama, ID Microsoft Entra, dan Token Tanda Tangan Akses Bersama (SAS). Artikel ini menjelaskan metode autentikasi ini termasuk detail tentang kontrol akun 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 secara otomatis saat membuat Akun Azure Maps. 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/map/tile?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2024-04-01&tilesetId=microsoft.base.road&zoom=15&x=5236&y=12665&tileSize=256
Penting
Kunci Primer dan Sekunder harus diperlakukan sebagai data sensitif. Kunci bersama digunakan untuk mengautentikasi semua REST API Azure Maps. 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 Maps menawarkan autentikasi untuk layanan Azure Maps menggunakan ID Microsoft Entra. MICROSOFT Entra ID menyediakan autentikasi berbasis identitas untuk pengguna dan aplikasi yang terdaftar di penyewa Microsoft Entra.
Azure Maps menerima token akses OAuth 2.0 untuk penyewa Microsoft Entra yang terkait dengan langganan Azure yang berisi akun Azure Maps. 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 Maps, lihat Mengelola autentikasi di Azure Maps.
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 Maps.
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 mungkin 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 | Nilai |
---|---|
x-ms-client-id | 30d7cc... 9f55 |
Authorization | 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 Maps 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 Maps 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 Maps Anda, direktori Microsoft Entra dikaitkan dengan langganan Azure, yang berada di akun Azure Maps.
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 Maps | Peran ini dapat digunakan untuk menetapkan tindakan baca dan batch di Azure Maps. |
Definisi Peran Kustom | Membuat peran yang dibuat untuk mengaktifkan akses terbatas yang fleksibel ke API REST Azure Maps. |
Beberapa layanan Azure Maps memerlukan hak istimewa yang ditingkatkan untuk melakukan tindakan tulis atau hapus di REST API 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 |
---|---|
Pembuat (Tidak digunakan lagi1) | Kontributor Data Azure Maps |
Spasial (Tidak digunakanlagi 1) | Kontributor Data Azure Maps |
Pencarian dan Rute Batch | Kontributor Data Azure Maps |
1 Pembuat Azure Maps, dan registri data dan layanan Spasial sekarang tidak digunakan lagi dan akan dihentikan pada 30/9/25.
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/write Microsoft.Maps/accounts/services/data/delete |
Memahami lingkup
Penetapan peran ditentukan dalam hierarki sumber daya Azure, dari grup manajemen tingkat atas ke tingkat terendah seperti akun Azure Maps.
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 Maps mendukung properti Azure standar di API Manajemen untuk dipanggil disableLocalAuth
.Microsoft.Maps/accounts
Jika benar, semua autentikasi ke REST API bidang data Azure Maps 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 tanda tangan akses bersama (SAS) adalah token autentikasi yang dibuat menggunakan format JSON Web Token (JWT). Token ini ditandatangani secara kriptografis untuk mengautentikasi aplikasi dengan REST API Azure Maps. Token SAS ini dibuat dengan mengintegrasikan identitas terkelola yang ditetapkan pengguna dengan akun Azure Maps di langganan Azure Anda. Identitas terkelola yang ditetapkan pengguna diberikan otorisasi ke akun Azure Maps 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. Setelah dibuat, mereka tetap valid hingga kedaluwarsa dan pengaturannya seperti wilayah yang diizinkan, batas tarif, dan identitas terkelola yang ditetapkan pengguna tidak dapat diubah. Untuk informasi selengkapnya tentang pencabutan dan modifikasi token SAS untuk kontrol akses, lihat memahami kontrol akses.
Memahami batas tarif token SAS
Batas tarif maksimum token SAS dapat mengontrol penagihan untuk sumber daya Azure Maps
Saat menetapkan batas tarif maksimum pada token (maxRatePerSecond
), tarif apa pun yang melebihi batas ini tidak ditagih ke akun, memungkinkan Anda untuk menetapkan batas transaksi yang dapat ditagih. Namun, aplikasi menerima respons kesalahan klien dengan 429 (TooManyRequests)
untuk semua transaksi setelah batas tersebut tercapai. Ini adalah tanggung jawab aplikasi untuk mengelola percobaan ulang dan distribusi token SAS. Tidak ada batasan jumlah token SAS yang dapat dibuat untuk akun. Untuk mengubah batas token yang ada, token SAS baru harus dibuat. Token SAS lama tetap valid 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 laju aktual bervariasi berdasarkan kemampuan Azure Maps 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
. Saran untuk mengontrol biaya dan meningkatkan prediksi:
- Buat token SAS dengan lokasi Azure yang diizinkan yang ditunjuk untuk geografi yang ditargetkan.
- Gunakan titik akhir REST API bidang data geografis,
https://us.atlas.microsoft.com
atauhttps://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 Maps, batas tarif untuk penawaran layanan individual diberlakukan secara kolektif di tingkat 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 berbagi batas tarif default 250 QPS. Jika kedua token digunakan secara bersamaan dengan throughput yang sama, setiap token akan memberikan 7.500 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.
Untuk menetapkan akses sementara dan menghapusnya sebelum token SAS kedaluwarsa, cabut token. Alasan lain untuk mencabut akses adalah jika token didistribusikan secara tidak sengaja dengan peran Kontributor Data Azure Maps, yang dapat memungkinkan data yang tidak sah dibaca/ditulis di REST API Azure Maps, yang mengarah ke paparan data sensitif atau biaya yang tidak terduga.
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 dapat mengakibatkan instans aplikasi Anda menggunakan token SAS dan identitas terkelola untuk mengembalikan 401 Unauthorized
atau 403 Forbidden
dari REST API Azure Maps, yang menyebabkan potensi 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, sebagaisigningKey
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 Azure Maps 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 Maps Anda.
Setelah akun berhasil dibuat atau diperbarui dengan identitas terkelola; tetapkan kontrol akses berbasis peran untuk identitas terkelola ke peran data Azure Maps 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 Maps 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 Maps seperti us.atlas.microsoft.com dan eu.atlas.microsoft.com memungkinkan aplikasi mengontrol penggunaan 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 | Nilai |
---|---|
Authorization | jwt-sas eyJ0e....HNIVN |
Catatan
jwt-sas
adalah skema autentikasi menggunakan token SAS. Jangan sertakan x-ms-client-id
atau header Otorisasi atau subscription-key
parameter string kueri lainnya.
Cross origin resource sharing (CORS)
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 Maps, Anda dapat mengonfigurasi asal mana yang diizinkan untuk mengakses REST API Azure Maps dari aplikasi Anda.
Penting
CORS bukan mekanisme otorisasi. Permintaan yang dibuat ke akun peta menggunakan REST API, saat CORS diaktifkan, juga memerlukan skema autentikasi akun peta yang valid seperti Kunci Bersama, ID Microsoft Entra, 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 menyatakan asal mana yang diizinkan untuk memanggil titik akhir akun Azure Maps. Protokol CORS tidak spesifik untuk Azure Maps.
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 adalah langkah keamanan tetapi juga memastikan bahwa server memahami metode dan header yang dikirim dalam permintaan aktual, memverifikasi sumber permintaan, dan mengkueri pembatasan CORS yang ditetapkan untuk akun peta. Browser web (atau agen pengguna lain) mengirim permintaan OPTIONS yang menyertakan 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. Aturan CORS dapat diatur pada properti akun Azure Maps melalui Azure Maps Management SDK, Azure Maps Management REST API, dan portal. Setelah mengatur aturan CORS untuk layanan, permintaan resmi dari domain yang berbeda dievaluasi untuk memastikan kepatuhan terhadap aturan yang ditentukan. Contohnya:
{
"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:
- The Azure Maps SDK
- REST API manajemen Azure Maps
- Templat ARM
Tip
Jika Anda menggunakan REST API manajemen Azure Maps, gunakan PUT
atau PATCH
dengan daftar kosong corsRule
di isi permintaan.
{
"location": "eastus",
"sku": {
"name": "G2"
},
"kind": "Gen2",
"properties": {
"cors": {
"corsRules": []
}
}
}
}
Memahami transaksi penagihan
Azure Maps 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 Maps lainnya, lihat Harga Azure Maps.
Langkah berikutnya
Untuk mempelajari selengkapnya tentang praktik terbaik keamanan, lihat:
Untuk mempelajari selengkapnya tentang mengautentikasi aplikasi dengan ID Microsoft Entra dan Azure Maps, lihat:
Untuk mempelajari selengkapnya tentang mengautentikasi Kontrol Azure Maps dengan ID Microsoft Entra, lihat: