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

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

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:

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.

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

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

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.

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

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.

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:

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:

1. Buat token SAS dengan lokasi Azure yang diizinkan yang ditunjuk untuk geografi yang ditargetkan.
2. 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 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 .

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.

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:

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

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.

Pertama, Anda harus Membuat identitas terkelola yang ditetapkan pengguna di lokasi yang sama dengan 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:

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:

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.

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:

1. Permintaan OPTIONS berisi header CORS yang diperlukan (header Asal dan Access-Control-Request-Method)
2. Autentikasi berhasil dan aturan CORS diaktifkan untuk akun yang cocok dengan permintaan preflight.
3. 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:

1. Jika permintaan OPTIONS tidak berisi header CORS yang diperlukan (header Asal dan Access-Control-Request-Method), layanan merespons dengan kode 400 (Bad request)status .
2. 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.

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

{
  "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: