Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
BERLAKU UNTUK: Semua tingkatan manajemen API
Artikel ini memperlihatkan cara membuat identitas terkelola untuk instans Azure API Management dan cara menggunakannya untuk mengakses sumber daya lain. Identitas terkelola yang dihasilkan oleh MICROSOFT Entra ID memungkinkan API Management mengakses sumber daya lain dengan mudah dan aman yang dilindungi oleh Microsoft Entra, seperti Azure Key Vault. Azure mengelola identitas ini, sehingga Anda tidak perlu menyediakan atau memutar rahasia apa pun. Untuk informasi selengkapnya tentang identitas terkelola, lihat Apa yang dimaksud dengan identitas terkelola untuk sumber daya Azure?.
Anda dapat memberikan dua jenis identitas ke instans API Management:
- Identitas yang ditetapkan sistem terkait dengan layanan Anda dan dihapus jika layanan Anda dihapus. Layanan ini hanya dapat memiliki satu identitas yang ditetapkan sistem.
- Identitas yang ditetapkan pengguna adalah sumber daya Azure mandiri yang dapat ditetapkan ke layanan Anda. Layanan ini dapat memiliki beberapa identitas yang ditetapkan pengguna.
Nota
Identitas terkelola khusus untuk penyewa Microsoft Entra tempat langganan Azure Anda dihosting. Langganan tidak diperbarui jika langganan dipindahkan ke direktori lain. Jika langganan dipindahkan, Anda perlu membuat ulang dan mengonfigurasi ulang identitas.
Nota
Saat ini, fitur ini tidak tersedia di ruang kerja.
Membuat identitas terkelola yang ditetapkan sistem
Portal Microsoft Azure
Untuk menyiapkan identitas terkelola di portal Microsoft Azure, Anda membuat instans API Management lalu mengaktifkan fitur tersebut.
Buat instans API Management di portal seperti biasa. Pergi ke dalam portal.
Di menu sebelah kiri, di bawah Keamanan, pilih Identitas terkelola.
Pada tab Sistem yang ditetapkan , ubah Status menjadi Aktif. Pilih Simpan.
Azure PowerShell
Nota
Kami merekomendasikan agar Anda menggunakan modul Azure Az PowerShell untuk berinteraksi dengan Azure. Untuk memulai, lihat Install Azure PowerShell. Untuk mempelajari cara bermigrasi ke modul Az PowerShell, lihat Memigrasikan Azure PowerShell dari AzureRM ke Az.
Langkah-langkah berikut mengarahkan Anda membuat instans API Management dan menetapkannya identitas dengan menggunakan Azure PowerShell.
Jika perlu, instal Azure PowerShell dengan mengikuti instruksi di panduan Azure PowerShell. Kemudian jalankan
Connect-AzAccount
untuk membuat koneksi dengan Azure.Gunakan kode berikut untuk membuat instans dengan identitas terkelola yang ditetapkan sistem. Untuk contoh selengkapnya tentang cara menggunakan Azure PowerShell dengan API Management, lihat sampel API Management PowerShell.
# Create a resource group. New-AzResourceGroup -Name $resourceGroupName -Location $location # Create an API Management Consumption SKU service. New-AzApiManagement -ResourceGroupName $resourceGroupName -Name consumptionskuservice -Location $location -Sku Consumption -Organization contoso -AdminEmail contoso@contoso.com -SystemAssignedIdentity
Anda juga dapat memperbarui instans yang ada untuk membuat identitas:
# Get an API Management instance
$apimService = Get-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apiManagementName
# Update an API Management instance
Set-AzApiManagement -InputObject $apimService -SystemAssignedIdentity
Templat Azure Resource Manager (ARM)
Anda dapat membuat instans API Management dengan identitas yang ditetapkan sistem dengan menyertakan properti berikut dalam definisi sumber daya templat ARM:
"identity" : {
"type" : "SystemAssigned"
}
Properti ini menginstruksikan Azure untuk membuat dan mengelola identitas untuk instans API Management Anda.
Misalnya, templat ARM lengkap mungkin terlihat seperti ini:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "0.9.0.0",
"resources": [{
"apiVersion": "2021-08-01",
"name": "contoso",
"type": "Microsoft.ApiManagement/service",
"location": "[resourceGroup().location]",
"tags": {},
"sku": {
"name": "Developer",
"capacity": "1"
},
"properties": {
"publisherEmail": "admin@contoso.com",
"publisherName": "Contoso"
},
"identity": {
"type": "systemAssigned"
}
}]
}
Saat instans dibuat, instans memiliki properti tambahan berikut:
"identity": {
"type": "SystemAssigned",
"tenantId": "<TENANTID>",
"principalId": "<PRINCIPALID>"
}
Properti tenantId
mengidentifikasi tenant Microsoft Entra yang terkait dengan identitas tersebut. Properti principalId
adalah pengidentifikasi unik untuk identitas baru instans. Dalam ID Microsoft Entra, perwakilan layanan memiliki nama yang sama dengan yang Anda berikan ke instans API Management Anda.
Nota
Instans API Management dapat memiliki identitas yang ditetapkan sistem dan ditetapkan pengguna. Dalam skenario itu, properti type
adalah SystemAssigned,UserAssigned
.
Mengonfigurasi akses Key Vault dengan menggunakan identitas terkelola
Konfigurasi berikut diperlukan jika Anda ingin menggunakan API Management untuk mengakses sertifikat dari brankas kunci Azure.
Mengonfigurasi akses ke Key Vault
- Di portal, buka brankas kunci Anda.
- Di menu sebelah kiri, pilih Konfigurasi akses. Perhatikan Model izin yang dikonfigurasi.
- Bergantung pada model izin, konfigurasikan kebijakan akses ke brankas kunci atau akses Azure RBAC untuk identitas terkelola API Management.
Untuk menambahkan kebijakan akses Key Vault:
- Di menu sebelah kiri, pilih Kebijakan akses.
- Pada halaman Kebijakan akses , pilih + Buat.
- Pada tab Izin , di bawah Izin rahasia, pilih Dapatkan dan Daftar, lalu pilih Berikutnya.
- Pada tab Utama , pilih Utama, cari nama sumber daya identitas terkelola Anda, lalu pilih Berikutnya. Jika Anda menggunakan identitas yang diberikan oleh sistem, prinsipal adalah nama instans Pengelolaan API Anda.
- Pilih Berikutnya lagi. Di tab Tinjau + buat, pilih Buat.
Untuk mengonfigurasi akses Azure RBAC:
- Di menu sebelah kiri, pilih Kontrol akses (IAM).
- Pada halaman Kontrol akses (IAM), pilih Tambahkan penetapan peran.
- Pada tab Peran , pilih Pengguna Sertifikat Key Vault.
- Pada tab Anggota, pilih Identitas> terkelola+ Pilih anggota.
- Di jendela Pilih identitas terkelola , pilih identitas terkelola yang ditetapkan sistem atau identitas terkelola yang ditetapkan pengguna yang terkait dengan instans API Management Anda, lalu klik Pilih.
- Pilih Tinjau + beri tugas.
Persyaratan untuk firewall Key Vault
Jika firewall Key Vault diaktifkan di brankas kunci, Anda harus memenuhi persyaratan berikut:
Anda harus menggunakan identitas terkelola yang diberikan oleh sistem pada instans API Management untuk mengakses penyimpanan kunci.
Di firewall Key Vault, aktifkan opsi Izinkan Layanan Microsoft Tepercaya untuk melewati firewall ini.
Pastikan bahwa alamat IP klien lokal Anda diizinkan untuk mengakses brankas kunci untuk sementara saat Anda memilih sertifikat atau rahasia untuk ditambahkan ke Azure API Management. Untuk informasi lebih lanjut, lihat Mengonfigurasi pengaturan jaringan Azure Key Vault.
Setelah menyelesaikan konfigurasi, Anda dapat memblokir alamat klien di firewall brankas kunci.
Persyaratan jaringan virtual
Jika instance Manajemen API diterapkan di jaringan virtual, konfigurasikan juga pengaturan jaringan berikut:
- Aktifkan titik akhir layanan ke Key Vault pada subnet API Management.
- Mengonfigurasi aturan grup keamanan jaringan (NSG) untuk memungkinkan lalu lintas keluar ke tag layanan AzureKeyVault dan AzureActiveDirectory.
Untuk detailnya, lihat Konfigurasi jaringan saat menyiapkan API Management di jaringan virtual.
Skenario yang didukung yang menggunakan identitas yang ditetapkan sistem
Berikut ini adalah beberapa skenario umum untuk menggunakan identitas terkelola yang ditetapkan sistem di Azure API Management.
Mendapatkan sertifikat TLS/SSL kustom untuk instans API Management dari Key Vault
Anda dapat menggunakan identitas instans API Management yang ditetapkan sistem untuk mengambil sertifikat TLS/SSL kustom yang disimpan di Key Vault. Anda kemudian dapat menetapkan sertifikat ini ke domain kustom di instans API Management. Pertimbangkan pertimbangan ini:
- Jenis konten rahasia harus aplikasi/x-pkcs12. Untuk informasi selengkapnya, lihat Opsi sertifikat domain.
- Anda harus menggunakan titik akhir rahasia sertifikat Key Vault, yang berisi rahasia.
Penting
Jika Anda tidak memberikan versi objek sertifikat, API Management secara otomatis mendapatkan versi sertifikat yang lebih baru dalam waktu empat jam setelah diperbarui di Key Vault.
Contoh berikut menunjukkan templat ARM yang menggunakan identitas terkelola yang ditetapkan sistem dari instans API Management untuk mengambil sertifikat domain kustom dari Key Vault.
Prasyarat
- Instans API Management yang dikonfigurasi dengan identitas terkelola yang ditetapkan sistem. Untuk membuat instance, Anda dapat menggunakan Templat Mulai Cepat Azure.
- Instans Key Vault dalam grup sumber daya yang sama. Instans harus menghosting sertifikat yang akan digunakan sebagai sertifikat domain kustom di API Management.
Templat berisi langkah-langkah berikut.
- Perbarui kebijakan akses instans Key Vault dan izinkan instans API Management untuk mendapatkan rahasia darinya.
- Perbarui instans API Management dengan mengatur nama domain kustom melalui sertifikat dari instans Key Vault.
Saat Anda menjalankan templat, berikan nilai parameter yang sesuai untuk lingkungan Anda.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"apiManagementServiceName": {
"type": "string",
"minLength": 8,
"metadata":{
"description": "The name of the API Management instance"
}
},
"publisherEmail": {
"type": "string",
"minLength": 1,
"metadata": {
"description": "The email address of the owner of the instance"
}
},
"publisherName": {
"type": "string",
"minLength": 1,
"metadata": {
"description": "The name of the owner of the instance"
}
},
"sku": {
"type": "string",
"allowedValues": ["Developer",
"Standard",
"Premium"],
"defaultValue": "Developer",
"metadata": {
"description": "The pricing tier of the API Management instance"
}
},
"skuCount": {
"type": "int",
"defaultValue": 1,
"metadata": {
"description": "The instance size of the API Management instance"
}
},
"keyVaultName": {
"type": "string",
"metadata": {
"description": "The name of the key vault"
}
},
"proxyCustomHostname1": {
"type": "string",
"metadata": {
"description": "Gateway custom hostname 1. Example: api.contoso.com"
}
},
"keyVaultIdToCertificate": {
"type": "string",
"metadata": {
"description": "Reference to the key vault certificate. Example: https://contoso.vault.azure.net/secrets/contosogatewaycertificate"
}
}
},
"variables": {
"apimServiceIdentityResourceId": "[concat(resourceId('Microsoft.ApiManagement/service', parameters('apiManagementServiceName')),'/providers/Microsoft.ManagedIdentity/Identities/default')]"
},
"resources": [
{
"apiVersion": "2021-08-01",
"name": "[parameters('apiManagementServiceName')]",
"type": "Microsoft.ApiManagement/service",
"location": "[resourceGroup().location]",
"tags": {
},
"sku": {
"name": "[parameters('sku')]",
"capacity": "[parameters('skuCount')]"
},
"properties": {
"publisherEmail": "[parameters('publisherEmail')]",
"publisherName": "[parameters('publisherName')]"
},
"identity": {
"type": "systemAssigned"
}
},
{
"type": "Microsoft.KeyVault/vaults/accessPolicies",
"name": "[concat(parameters('keyVaultName'), '/add')]",
"apiVersion": "2018-02-14",
"properties": {
"accessPolicies": [{
"tenantId": "[reference(variables('apimServiceIdentityResourceId'), '2018-11-30').tenantId]",
"objectId": "[reference(variables('apimServiceIdentityResourceId'), '2018-11-30').principalId]",
"permissions": {
"secrets": ["get", "list"]
}
}]
}
},
{
"apiVersion": "2021-04-01",
"type": "Microsoft.Resources/deployments",
"name": "apimWithKeyVault",
"dependsOn": [
"[resourceId('Microsoft.ApiManagement/service', parameters('apiManagementServiceName'))]"
],
"properties": {
"mode": "incremental",
"template": {
"$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {},
"resources": [{
"apiVersion": "2021-08-01",
"name": "[parameters('apiManagementServiceName')]",
"type": "Microsoft.ApiManagement/service",
"location": "[resourceGroup().location]",
"tags": {
},
"sku": {
"name": "[parameters('sku')]",
"capacity": "[parameters('skuCount')]"
},
"properties": {
"publisherEmail": "[parameters('publisherEmail')]",
"publisherName": "[parameters('publisherName')]",
"hostnameConfigurations": [{
"type": "Proxy",
"hostName": "[parameters('proxyCustomHostname1')]",
"keyVaultId": "[parameters('keyVaultIdToCertificate')]"
}]
},
"identity": {
"type": "systemAssigned"
}
}]
}
}
}
]
}
Menyimpan dan mengelola nilai bernama dari Key Vault
Anda dapat menggunakan identitas terkelola yang ditetapkan sistem untuk mengakses Key Vault guna menyimpan dan mengelola rahasia untuk digunakan dalam kebijakan API Management. Untuk informasi selengkapnya, lihat Menggunakan nilai bernama dalam kebijakan Azure API Management.
Mengautentikasi ke backend dengan menggunakan identitas API Management
Anda dapat menggunakan identitas yang ditetapkan sistem untuk mengautentikasi ke layanan backend melalui kebijakan identitas terkelola autentikasi .
Menyambungkan ke sumber daya Azure di belakang firewall IP dengan menggunakan identitas terkelola yang ditetapkan sistem
API Management adalah layanan Microsoft tepercaya untuk sumber daya berikut. Status tepercaya ini memungkinkan layanan tersambung ke sumber daya berikut di belakang firewall. Setelah Anda secara eksplisit menetapkan peran Azure yang sesuai ke identitas terkelola yang ditetapkan sistem untuk instans sumber daya, cakupan akses untuk instans sesuai dengan peran Azure yang ditetapkan ke identitas terkelola.
- Akses tepercaya untuk Key Vault
- Akses tepercaya untuk Azure Storage
- Akses tepercaya untuk Azure Services Bus
- Akses tepercaya untuk Azure Event Hubs
Mencatat kejadian ke event hub
Anda dapat mengonfigurasi dan menggunakan identitas terkelola yang ditetapkan sistem untuk mengakses hub peristiwa untuk mencatat peristiwa dari instans API Management. Untuk informasi selengkapnya, lihat Cara mencatat peristiwa ke Azure Event Hubs di Azure API Management.
Buat identitas terkelola yang ditetapkan pengguna
Nota
Anda dapat mengaitkan instans API Management dengan sebanyak 10 identitas terkelola yang ditetapkan pengguna.
Portal Microsoft Azure
Untuk menyiapkan identitas terkelola di portal, Anda harus terlebih dahulu membuat instans API Management dan membuat identitas yang ditetapkan pengguna. Kemudian selesaikan langkah-langkah berikut.
Buka instans API Management Anda di portal.
Di menu sebelah kiri, di bawah Keamanan, pilih Identitas terkelola.
Pada tab Ditetapkan pengguna, pilih Tambahkan.
Cari identitas yang Anda buat sebelumnya dan pilih identitas tersebut. Pilih Tambahkan.
Azure PowerShell
Nota
Kami merekomendasikan agar Anda menggunakan modul Azure Az PowerShell untuk berinteraksi dengan Azure. Untuk memulai, lihat Install Azure PowerShell. Untuk mempelajari cara bermigrasi ke modul Az PowerShell, lihat Memigrasikan Azure PowerShell dari AzureRM ke Az.
Langkah-langkah berikut mengarahkan Anda membuat instans API Management dan menetapkannya identitas dengan menggunakan Azure PowerShell.
Jika perlu, instal Azure PowerShell dengan mengikuti instruksi di panduan Azure PowerShell. Kemudian jalankan
Connect-AzAccount
untuk membuat koneksi dengan Azure.Gunakan kode berikut untuk membuat instans. Untuk contoh selengkapnya tentang cara menggunakan Azure PowerShell dengan API Management, lihat sampel API Management PowerShell.
# Create a resource group. New-AzResourceGroup -Name $resourceGroupName -Location $location # Create a user-assigned identity. This code requires installation of the Az.ManagedServiceIdentity module. $userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName # Create an API Management Consumption SKU service. $userIdentities = @($userAssignedIdentity.Id) New-AzApiManagement -ResourceGroupName $resourceGroupName -Location $location -Name $apiManagementName -Organization contoso -AdminEmail admin@contoso.com -Sku Consumption -UserAssignedIdentity $userIdentities
Anda juga dapat memperbarui layanan yang ada untuk menetapkan identitas ke layanan:
# Get an API Management instance.
$apimService = Get-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apiManagementName
# Create a user-assigned identity. This code requires installation of the Az.ManagedServiceIdentity module.
$userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName
# Update the API Management instance.
$userIdentities = @($userAssignedIdentity.Id)
Set-AzApiManagement -InputObject $apimService -UserAssignedIdentity $userIdentities
Templat ARM
Anda dapat membuat instans API Management yang memiliki identitas dengan menyertakan properti berikut dalam definisi sumber daya:
"identity": {
"type": "UserAssigned",
"userAssignedIdentities": {
"<RESOURCEID>": {}
}
}
Menambahkan jenis yang ditetapkan pengguna menginformasikan Azure untuk menggunakan identitas yang ditetapkan pengguna yang ditentukan untuk instans Anda.
Misalnya, templat ARM lengkap mungkin terlihat seperti ini:
{
"$schema": "https://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
"contentVersion": "0.9.0.0",
"resources": [{
"apiVersion": "2021-08-01",
"name": "contoso",
"type": "Microsoft.ApiManagement/service",
"location": "[resourceGroup().location]",
"tags": {},
"sku": {
"name": "Developer",
"capacity": "1"
},
"properties": {
"publisherEmail": "admin@contoso.com",
"publisherName": "Contoso"
},
"identity": {
"type": "UserAssigned",
"userAssignedIdentities": {
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]": {}
}
},
"dependsOn": [
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
]
}]
}
Saat layanan dibuat, layanan ini memiliki properti tambahan berikut:
"identity": {
"type": "UserAssigned",
"userAssignedIdentities": {
"<RESOURCEID>": {
"principalId": "<PRINCIPALID>",
"clientId": "<CLIENTID>"
}
}
}
Properti principalId
adalah pengidentifikasi unik untuk akun yang digunakan dalam administrasi Microsoft Entra. Properti clientId
adalah pengidentifikasi unik untuk identitas baru aplikasi yang digunakan untuk menentukan identitas mana yang akan digunakan selama panggilan runtime.
Nota
Instans API Management dapat memiliki identitas yang ditetapkan sistem dan ditetapkan pengguna. Dalam skenario itu, properti type
akan menjadi SystemAssigned,UserAssigned
.
Skenario yang didukung yang menggunakan identitas terkelola yang ditetapkan pengguna
Berikut ini adalah beberapa skenario umum untuk menggunakan identitas terkelola yang ditetapkan pengguna di Azure API Management.
Mendapatkan sertifikat TLS/SSL kustom untuk instans API Management dari Key Vault
Anda dapat menggunakan identitas yang ditetapkan pengguna untuk membangun kepercayaan antara instans API Management dan Key Vault. Kepercayaan ini kemudian dapat digunakan untuk mengambil sertifikat TLS/SSL kustom yang disimpan di Key Vault. Anda kemudian dapat menetapkan sertifikat ini ke domain kustom di instans API Management.
Penting
Jika firewall Key Vault diaktifkan pada brankas kunci Anda, Anda tidak dapat menggunakan identitas pengguna yang ditetapkan untuk akses dari API Management. Anda dapat menggunakan identitas yang ditetapkan sistem sebagai gantinya. Di firewall Key Vault, opsi Izinkan Layanan Microsoft Tepercaya untuk melewati firewall ini harus diaktifkan.
Pertimbangkan pertimbangan ini:
- Jenis konten rahasia harus aplikasi/x-pkcs12.
- Anda harus menggunakan titik akhir rahasia sertifikat Key Vault, yang berisi rahasia.
Penting
Jika Anda tidak memberikan versi objek sertifikat, API Management secara otomatis mendapatkan versi sertifikat yang lebih baru dalam waktu empat jam setelah diperbarui di Key Vault.
Menyimpan dan mengelola nilai bernama dari Key Vault
Anda dapat menggunakan identitas terkelola yang ditetapkan pengguna untuk mengakses Key Vault guna menyimpan dan mengelola rahasia untuk digunakan dalam kebijakan API Management. Untuk informasi selengkapnya, lihat Menggunakan nilai bernama dalam kebijakan Azure API Management.
Nota
Jika firewall Key Vault diaktifkan pada brankas kunci Anda, Anda tidak dapat menggunakan identitas pengguna yang ditetapkan untuk akses dari API Management. Anda dapat menggunakan identitas yang ditetapkan sistem sebagai gantinya. Di firewall Key Vault, opsi Izinkan Layanan Microsoft Tepercaya untuk melewati firewall ini harus diaktifkan.
Mengautentikasi ke backend dengan menggunakan identitas yang ditetapkan pengguna
Anda dapat menggunakan identitas yang ditetapkan pengguna untuk mengautentikasi ke layanan backend melalui kebijakan identitas terkelola autentikasi .
Mencatat kejadian ke event hub
Anda dapat mengonfigurasi dan menggunakan identitas terkelola yang ditetapkan pengguna untuk mengakses hub peristiwa untuk mencatat peristiwa dari instans API Management. Untuk informasi selengkapnya, lihat Cara mencatat peristiwa ke Azure Event Hubs di Azure API Management.
Menghapus sebuah identitas
Anda dapat menghapus identitas yang ditetapkan sistem dengan menonaktifkan fitur melalui portal atau templat ARM dengan cara yang sama seperti yang dibuat. Identitas yang ditetapkan pengguna dapat dihapus satu per satu. Untuk menghapus semua identitas, atur jenis identitas ke "None"
.
Menghapus identitas yang ditetapkan sistem dengan cara ini juga menghapusnya dari ID Microsoft Entra. Identitas yang ditetapkan sistem juga secara otomatis dihapus dari ID Microsoft Entra saat instans API Management dihapus.
Untuk menghapus semua identitas dengan menggunakan templat ARM, perbarui bagian ini:
"identity": {
"type": "None"
}
Penting
Jika instans API Management dikonfigurasi dengan sertifikat SSL kustom dari Key Vault dan Anda mencoba menonaktifkan identitas terkelola, permintaan gagal.
Anda dapat mengatasinya dengan beralih dari sertifikat Key Vault ke sertifikat yang dikodekan sebaris lalu menonaktifkan identitas terkelola. Untuk informasi selengkapnya, lihat Mengonfigurasi nama domain kustom.