Cara menggunakan identitas terkelola untuk App Service dan Azure Functions

Artikel
09/30/2024

Catatan

Mulai 1 Juni 2024, semua aplikasi App Service yang baru dibuat akan memiliki opsi untuk menghasilkan nama host default yang unik menggunakan konvensi <app-name>-<random-hash>.<region>.azurewebsites.netpenamaan . Nama aplikasi yang ada akan tetap tidak berubah.

Contoh: myapp-ds27dh7271aah175.westus-01.azurewebsites.net

Untuk detail lebih lanjut, lihat Nama Host Default Unik untuk Sumber Daya App Service.

Artikekl ini menunjukkan cara membuat identitas terkelola untuk aplikasi App Service dan Azure Functions dan cara menggunakannya untuk mengakses sumber daya lainnya.

Penting

Karena identitas terkelola tidak mendukung skenario lintas direktori, identitas tersebut tidak akan berperilaku seperti yang diharapkan jika aplikasi Anda dimigrasikan di seluruh langganan atau penyewa. Untuk membuat ulang identitas terkelola setelah pemindahan tersebut, lihat Akankah identitas terkelola dibuat ulang secara otomatis jika saya memindahkan langganan ke direktori lain?. Sumber daya hilir juga perlu memperbarui kebijakan akses untuk menggunakan identitas baru.

Catatan

Identitas terkelola tidak tersedia untuk aplikasi yang disebarkan di Azure Arc.

Identitas terkelola dari MICROSOFT Entra ID memungkinkan aplikasi Anda mengakses sumber daya lain yang dilindungi Microsoft Entra dengan mudah seperti Azure Key Vault. Identitas dikelola oleh platform Azure dan tidak mengharuskan Anda memprovisikan atau memutar rahasia. Untuk informasi selengkapnya tentang identitas terkelola di ID Microsoft Entra, lihat Identitas terkelola untuk sumber daya Azure.

Aplikasi Anda dapat diberikan dua jenis identitas:

Identitas yang ditetapkan sistem terkait dengan aplikasi dan dihapus jika aplikasi dihapus. Aplikasi hanya dapat memiliki satu identitas yang ditetapkan sistem.
Identitas yang ditetapkan pengguna adalah sumber daya Azure mandiri yang dapat ditetapkan ke aplikasi Anda. Aplikasi dapat memiliki beberapa identitas yang ditetapkan pengguna, dan satu identitas yang ditetapkan pengguna dapat ditetapkan ke beberapa sumber daya Azure, seperti dua aplikasi App Service.

Konfigurasi identitas terkelola khusus untuk slot. Untuk mengonfigurasi identitas terkelola untuk slot penyebaran di portal, navigasikan ke slot terlebih dahulu. Untuk menemukan identitas terkelola untuk aplikasi web atau slot penyebaran di penyewa Microsoft Entra Anda dari portal Azure, cari langsung dari halaman Gambaran Umum penyewa Anda. Biasanya, nama slotnya mirip dengan <app-name>/slots/<slot-name>.

Video ini menunjukkan kepada Anda cara menggunakan identitas terkelola untuk App Service.

Langkah-langkah dalam video juga dijelaskan di bagian berikut.

Tambahkan identitas yang ditetapkan sistem

Akses pengaturan aplikasi Anda di portal Azure di bawah grup Pengaturan di panel navigasi kiri.
Pilih Identitas.
Dalam tab Ditetapkan oleh sistem, alihkan Status ke Aktif. Klik Simpan.

Jalankan perintah az webapp identity assign untuk membuat identitas yang ditetapkan sistem:

az webapp identity assign --name myApp --resource-group myResourceGroup

Untuk App Service

Jalankan perintah Set-AzWebApp -AssignIdentity untuk membuat identitas yang ditetapkan sistem untuk App Service:

Set-AzWebApp -AssignIdentity $true -Name <app-name> -ResourceGroupName <group-name>

Untuk Azure Functions

Jalankan perintah Update-AzFunctionApp -IdentityType untuk membuat identitas yang ditetapkan sistem untuk aplikasi fungsi:

Update-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -IdentityType SystemAssigned

Templat Azure Resource Manager dapat digunakan untuk mengotomatiskan penyebaran sumber daya Azure Anda. Untuk mempelajari selengkapnya tentang penyebaran ke App Service dan Azure Functions, lihat Mengotomatiskan penyebaran sumber daya di App Service dan Mengotomatiskan penyebaran sumber daya di Azure Functions.

Sumber daya dari Microsoft.Web/sites jenis apa pun dapat dibuat dengan identitas dengan menyertakan properti berikut dalam definisi sumber daya:

"identity": {
    "type": "SystemAssigned"
}

Menambahkan jenis yang ditetapkan sistem memberi tahu Azure untuk membuat dan mengelola identitas untuk aplikasi Anda.

Misalnya, template aplikasi web mungkin tampak seperti JSON berikut:

{
    "apiVersion": "2022-03-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "SystemAssigned"
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]"
    ]
}

Saat situs dibuat, situs tersebut memiliki properti tambahan berikut:

"identity": {
    "type": "SystemAssigned",
    "tenantId": "<tenant-id>",
    "principalId": "<principal-id>"
}

Properti tenantId mengidentifikasi identitas milik penyewa Microsoft Entra. principalId adalah pengidentifikasi unik untuk identitas baru aplikasi. Dalam ID Microsoft Entra, perwakilan layanan memiliki nama yang sama dengan yang Anda berikan ke instans App Service atau Azure Functions Anda.

Jika Anda perlu mereferensikan properti ini pada tahap selanjutnya dalam templat, Anda dapat melakukannya melalui reference() fungsi templat dengan bendera 'Full', seperti dalam contoh ini:

{
    "tenantId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.tenantId]",
    "objectId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.principalId]",
}

Menambahkan identitas yang ditetapkan pengguna

Membuat aplikasi dengan identitas yang ditetapkan pengguna mengharuskan Anda membuat identitas lalu menambahkan pengidentifikasi sumber dayanya ke konfigurasi aplikasi Anda.

Pertama, Anda harus membuat sumber daya identitas yang ditetapkan pengguna.

Buat sumber daya identitas terkelola yang ditetapkan pengguna sesuai dengan petunjuk ini.
Pada navigasi kiri untuk halaman aplikasi Anda, gulir ke bawah ke grup Pengaturan.
Pilih Identitas.
Pilih Tambahkan yang> ditetapkan pengguna.
Cari identitas yang Anda buat sebelumnya, pilih identitas tersebut, dan pilih Tambahkan.

Setelah Anda memilih Tambahkan, aplikasi dimulai ulang.

Membuat identitas yang ditetapkan pengguna.

az identity create --resource-group <group-name> --name <identity-name>

Jalankan perintah az webapp identity assign untuk menetapkan identitas ke aplikasi.

az webapp identity assign --resource-group <group-name> --name <app-name> --identities <identity-id>

Untuk App Service

Menambahkan identitas yang ditetapkan pengguna di App Service saat ini tidak didukung.

Untuk Azure Functions

Membuat identitas yang ditetapkan pengguna.

Install-Module -Name Az.ManagedServiceIdentity -AllowPrerelease
$userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName <group-name>

Jalankan perintah Update-AzFunctionApp -IdentityType UserAssigned -IdentityId untuk menetapkan identitas dalam Azure Functions:

Update-AzFunctionApp -Name <app-name> -ResourceGroupName <group-name> -IdentityType UserAssigned -IdentityId $userAssignedIdentity.Id

Sumber daya dari Microsoft.Web/sites jenis apa pun dapat dibuat dengan identitas dengan menyertakan blok berikut dalam definisi sumber daya, menggantikan <resource-id> dengan ID sumber daya dari identitas yang diinginkan:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<resource-id>": {}
    }
}

Catatan

Sebuah aplikasi dapat memiliki identitas yang ditetapkan sistem dan identitas yang ditetapkan pengguna secara bersamaan. Dalam kasus ini, properti type akan menjadi SystemAssigned,UserAssigned

Menambahkan jenis yang ditetapkan pengguna memberi tahu Azure untuk menggunakan identitas yang ditetapkan pengguna yang ditentukan untuk aplikasi Anda.

Misalnya, template aplikasi web mungkin tampak seperti JSON berikut:

{
    "apiVersion": "2022-03-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
            "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]": {}
        }
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
    ]
}

Saat situs dibuat, situs tersebut memiliki properti tambahan berikut:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<resource-id>": {
            "principalId": "<principal-id>",
            "clientId": "<client-id>"
        }
    }
}

PrincipalId adalah pengidentifikasi unik untuk identitas yang digunakan untuk administrasi Microsoft Entra. clientId adalah pengidentifikasi unik untuk identitas baru aplikasi yang digunakan untuk menentukan identitas mana yang akan digunakan selama panggilan runtime bahasa umum.

Mengonfigurasi sumber daya target

Anda mungkin perlu mengonfigurasi sumber daya target untuk mengizinkan akses dari aplikasi atau fungsi Anda. Misalnya, jika Anda meminta token untuk mengakses Key Vault, Anda juga harus menambahkan kebijakan akses yang menyertakan identitas terkelola aplikasi atau fungsi Anda. Jika tidak, panggilan Anda ke Key Vault akan ditolak, bahkan jika panggilan tersebut menyertakan token. Hal yang sama berlaku untuk Azure SQL Database. Untuk mempelajari selengkapnya tentang sumber daya mana yang mendukung token Microsoft Entra, lihat Layanan Azure yang mendukung autentikasi Microsoft Entra.

Penting

Layanan back-end untuk identitas terkelola mempertahankan cache per URI sumber daya selama sekitar 24 jam. Hal ini berarti diperlukan waktu beberapa jam agar perubahan pada grup identitas terkelola atau keanggotaan peran diterapkan. Saat ini, tidak memungkinkan untuk memaksa token identitas yang dikelola untuk direfresh sebelum berakhir. Jika Anda mengubah grup identitas terkelola atau keanggotaan peran untuk menambah atau menghapus izin, Anda mungkin perlu menunggu beberapa jam agar sumber daya Azure menggunakan identitas tersebut sehingga memiliki akses yang benar. Untuk alternatif grup atau keanggotaan peran, lihat Batasan penggunaan identitas terkelola untuk otorisasi.

Sambungkan ke layanan Azure dalam kode aplikasi

Dengan identitas terkelolanya, aplikasi dapat memperoleh token untuk sumber daya Azure yang dilindungi oleh ID Microsoft Entra, seperti Azure SQL Database, Azure Key Vault, dan Azure Storage. Token tersebut mewakili aplikasi yang mengakses sumber daya, dan bukan pengguna aplikasi tertentu.

App Service dan Azure Functions menyediakan titik akhir REST yang dapat diakses secara internal untuk pengambilan token. Titik akhir REST dapat diakses dari dalam aplikasi dengan GET HTTP standar, yang dapat diimplementasikan dengan klien HTTP generik dalam setiap bahasa. Untuk .NET, JavaScript, Java, dan Python, pustaka klien Azure Identity menyediakan abstraksi melalui titik akhir REST ini dan menyederhanakan pengalaman pengembangan. Menghubungkan ke layanan Azure lainnya semudah menambahkan objek kredensial ke klien khusus layanan.

Permintaan HTTP GET mentah menggunakan dua variabel lingkungan yang disediakan dan terlihat seperti contoh berikut:

GET /MSI/token?resource=https://vault.azure.net&api-version=2019-08-01 HTTP/1.1
Host: <ip-address-:-port-in-IDENTITY_ENDPOINT>
X-IDENTITY-HEADER: <value-of-IDENTITY_HEADER>

Dan sampel respons mungkin terlihat seperti berikut ini:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJ0eXAi…",
    "expires_on": "1586984735",
    "resource": "https://vault.azure.net",
    "token_type": "Bearer",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

Respons ini sama dengan respons untuk permintaan token akses layanan-ke-layanan Microsoft Entra. Untuk mengakses Key Vault, Anda kemudian akan menambahkan nilai access_token ke koneksi klien dengan brankas.

Catatan

Saat menyambungkan ke sumber data Azure SQL dengan Entity Framework Core, pertimbangkan untuk menggunakan Microsoft.Data.SqlClient, yang menyediakan string koneksi khusus untuk konektivitas identitas terkelola. Misalnya, lihat Tutorial: Mengamankan koneksi Azure SQL Database dari App Service menggunakan identitas terkelola.

Untuk aplikasi dan fungsi .NET, cara paling sederhana untuk bekerja dengan identitas terkelola adalah melalui pustaka klien Azure Identity untuk .NET. Untuk panduan mendetail, lihat Tutorial: Terhubung ke database Azure dari App Service tanpa rahasia menggunakan identitas terkelola.

Lihat judul dokumentasi setiap pustaka klien untuk mendapatkan informasi:

Contoh terkait menggunakan DefaultAzureCredential. Ini berguna untuk sebagian besar skenario karena pola yang sama berfungsi di Azure (dengan identitas terkelola) dan di komputer lokal Anda (tanpa identitas terkelola).

Untuk aplikasi Node.js dan fungsi JavaScript, cara paling sederhana untuk bekerja dengan identitas terkelola melalui pustaka klien Azure Identity untuk JavaScript. Untuk panduan mendetail, lihat Tutorial: Terhubung ke database Azure dari App Service tanpa rahasia menggunakan identitas terkelola.

Lihat judul dokumentasi setiap pustaka klien untuk mendapatkan informasi:

Untuk contoh kode lainnya dari pustaka klien Azure Identity untuk JavaScript, lihat contoh Azure Identity.

Untuk aplikasi dan fungsi Python, cara paling sederhana untuk bekerja dengan identitas terkelola adalah melalui pustaka klien Azure Identity untuk Python. Untuk panduan mendetail, lihat Tutorial: Terhubung ke database Azure dari App Service tanpa rahasia menggunakan identitas terkelola.

Lihat judul dokumentasi setiap pustaka klien untuk mendapatkan informasi:

Untuk aplikasi dan fungsi Java, cara paling sederhana untuk bekerja dengan identitas terkelola adalah melalui pustaka klien Azure Identity untuk Java. Untuk panduan mendetail, lihat Tutorial: Terhubung ke database Azure dari App Service tanpa rahasia menggunakan identitas terkelola.

Lihat judul dokumentasi setiap pustaka klien untuk mendapatkan informasi:

Untuk contoh kode lainnya dari pustaka klien Azure Identity untuk Java, lihat Contoh Azure Identity.

Gunakan skrip berikut untuk mengambil token dari titik akhir lokal dengan menentukan URI sumber daya layanan Azure:

$resourceURI = "https://<AAD-resource-URI-for-resource-to-obtain-token>"
$tokenAuthURI = $env:IDENTITY_ENDPOINT + "?resource=$resourceURI&api-version=2019-08-01"
$tokenResponse = Invoke-RestMethod -Method Get -Headers @{"X-IDENTITY-HEADER"="$env:IDENTITY_HEADER"} -Uri $tokenAuthURI
$accessToken = $tokenResponse.access_token

Untuk informasi selengkapnya tentang titik akhir REST, lihat referensi titik akhir REST.

Menghapus sebuah identitas

Saat Anda menghapus identitas yang ditetapkan sistem, identitas tersebut akan dihapus dari ID Microsoft Entra. Identitas yang ditetapkan sistem juga secara otomatis dihapus dari ID Microsoft Entra saat Anda menghapus sumber daya aplikasi itu sendiri.

Di navigasi kiri halaman aplikasi Anda, gulir ke bawah ke grup Pengaturan.
Pilih Identitas. Kemudian ikuti langkah-langkah berdasarkan jenis identitas:
- Identitas ditetapkan sistem: Dalam tab Sistem yang ditetapkan, alihkan Status menjadi Nonaktif. Klik Simpan.
- Identitas yang ditetapkan pengguna: Pilih tab Ditetapkan pengguna, centang kotak untuk identitas, dan pilih Hapus. Pilih Ya untuk mengonfirmasi.

Untuk menghapus identitas yang ditetapkan sistem:

az webapp identity remove --name <app-name> --resource-group <group-name>

Untuk menghapus satu atau beberapa identitas yang ditetapkan pengguna:

az webapp identity remove --name <app-name> --resource-group <group-name> --identities <identity-id1> <identity-id2> ...

Anda juga dapat menghapus identitas yang ditetapkan sistem dengan menentukan [system] di --identities.

Untuk App Service

Jalankan perintah Set-AzWebApp -AssignIdentity untuk menghapus identitas yang ditetapkan sistem untuk App Service:

Set-AzWebApp -AssignIdentity $false -Name <app-name> -ResourceGroupName <group-name>

Untuk Azure Functions

Untuk menghapus semua identitas di Azure PowerShell (khusus Azure Functions):

# Update an existing function app to have IdentityType "None".
Update-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -IdentityType None

Untuk menghapus semua identitas dalam templat ARM:

"identity": {
    "type": "None"
}

Catatan

Ada juga pengaturan aplikasi yang dapat diatur, WEBSITE_DISABLE_MSI, yang hanya menonaktifkan layanan token lokal. Namun, identitas tetap di tempatnya, dan alat akan tetap menampilkan identitas terkelola sebagai "on" atau "enabled". Akibatnya, penggunaan pengaturan ini tidak disarankan.

Referensi titik akhir REST

Aplikasi dengan identitas terkelola membuat titik akhir ini tersedia dengan mendefinisikan dua variabel lingkungan:

IDENTITY_ENDPOINT - URL ke layanan token lokal.
IDENTITY_HEADER - header yang digunakan untuk membantu meredakan serangan pemalsuan permintaan sisi server (SSRF). Nilai diputar oleh platform.

IDENTITY_ENDPOINT adalah URL lokal tempat aplikasi Anda dapat meminta token. Untuk mendapatkan token sumber daya, buat permintaan HTTP GET ke titik akhir ini, termasuk parameter berikut:

Nama Parameter Dalam Deskripsi

resource Kueri URI sumber daya Microsoft Entra dari sumber daya tempat token harus diperoleh. Ini bisa menjadi salah satu layanan Azure yang mendukung autentikasi Microsoft Entra atau URI sumber daya lainnya.

versi-api Kueri Versi API token yang akan digunakan. Gunakan 2019-08-01.

X-IDENTITY-HEADER Header Nilai variabel lingkungan IDENTITY_HEADER. Header ini digunakan untuk membantu meredakan serangan pemalsuan permintaan sisi server (SSRF).

client_id Kueri (Opsional) ID klien dari identitas yang ditetapkan pengguna yang akan digunakan. Tidak dapat digunakan pada permintaan yang menyertakan principal_id, mi_res_id, atau object_id. Jika semua parameter ID (client_id, principal_id, object_id, dan mi_res_id) dihilangkan, identitas yang ditetapkan sistem akan digunakan.

principal_id Kueri (Opsional) ID utama dari identitas yang ditetapkan pengguna yang akan digunakan. object_id adalah alias yang dapat digunakan sebagai gantinya. Tidak dapat digunakan pada permintaan yang menyertakan client_id, mi_res_id, atau object_id. Jika semua parameter ID (client_id, principal_id, object_id, dan mi_res_id) dihilangkan, identitas yang ditetapkan sistem akan digunakan.

mi_res_id Kueri (Opsional) ID sumber daya Azure dari identitas yang ditetapkan pengguna yang akan digunakan. Tidak dapat digunakan pada permintaan yang menyertakan principal_id, client_id, atau object_id. Jika semua parameter ID (client_id, principal_id, object_id, dan mi_res_id) dihilangkan, identitas yang ditetapkan sistem akan digunakan.

Nama Parameter	Dalam	Deskripsi
resource	Kueri	URI sumber daya Microsoft Entra dari sumber daya tempat token harus diperoleh. Ini bisa menjadi salah satu layanan Azure yang mendukung autentikasi Microsoft Entra atau URI sumber daya lainnya.
versi-api	Kueri	Versi API token yang akan digunakan. Gunakan `2019-08-01`.
X-IDENTITY-HEADER	Header	Nilai variabel lingkungan IDENTITY_HEADER. Header ini digunakan untuk membantu meredakan serangan pemalsuan permintaan sisi server (SSRF).
client_id	Kueri	(Opsional) ID klien dari identitas yang ditetapkan pengguna yang akan digunakan. Tidak dapat digunakan pada permintaan yang menyertakan `principal_id`, `mi_res_id`, atau `object_id`. Jika semua parameter ID (`client_id`, `principal_id`, `object_id`, dan `mi_res_id`) dihilangkan, identitas yang ditetapkan sistem akan digunakan.
principal_id	Kueri	(Opsional) ID utama dari identitas yang ditetapkan pengguna yang akan digunakan. `object_id` adalah alias yang dapat digunakan sebagai gantinya. Tidak dapat digunakan pada permintaan yang menyertakan client_id, mi_res_id, atau object_id. Jika semua parameter ID (`client_id`, `principal_id`, `object_id`, dan `mi_res_id`) dihilangkan, identitas yang ditetapkan sistem akan digunakan.
mi_res_id	Kueri	(Opsional) ID sumber daya Azure dari identitas yang ditetapkan pengguna yang akan digunakan. Tidak dapat digunakan pada permintaan yang menyertakan `principal_id`, `client_id`, atau `object_id`. Jika semua parameter ID (`client_id`, `principal_id`, `object_id`, dan `mi_res_id`) dihilangkan, identitas yang ditetapkan sistem akan digunakan.

Penting

Jika Anda mencoba mendapatkan token untuk identitas yang ditetapkan pengguna, Anda harus menyertakan salah satu properti opsional. Jika tidak, layanan token akan berusaha mendapatkan token untuk identitas yang ditetapkan sistem, yang mungkin ada atau tidak ada.

Bagikan melalui

Cara menggunakan identitas terkelola untuk App Service dan Azure Functions

Tambahkan identitas yang ditetapkan sistem

Untuk App Service

Untuk Azure Functions

Menambahkan identitas yang ditetapkan pengguna

Untuk App Service

Untuk Azure Functions

Mengonfigurasi sumber daya target

Sambungkan ke layanan Azure dalam kode aplikasi

Menghapus sebuah identitas

Untuk App Service

Untuk Azure Functions

Referensi titik akhir REST

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: