Mengautentikasi aplikasi .NET yang dihosting Azure ke sumber daya Azure menggunakan identitas terkelola yang ditetapkan pengguna

Pendekatan yang disarankan untuk mengautentikasi aplikasi yang dihosting Azure ke sumber daya Azure lainnya adalah dengan menggunakan identitas terkelola . Pendekatan ini didukung untuk sebagian besar layanan Azure, termasuk aplikasi yang dihosting di Azure App Service, Azure Container Apps, dan Azure Virtual Machines. Temukan selengkapnya tentang berbagai teknik dan pendekatan autentikasi pada halaman gambaran umum autentikasi. Di bagian depan, Anda akan mempelajari:

• Konsep identitas terkelola yang penting
• Cara membuat identitas terkelola yang ditetapkan pengguna untuk aplikasi Anda
• Cara menetapkan sebuah peran ke identitas terkelola yang ditetapkan oleh pengguna
• Cara mengautentikasi menggunakan identitas terkelola yang ditetapkan pengguna dari kode aplikasi Anda

Konsep identitas terkelola yang penting

Identitas terkelola memungkinkan aplikasi Anda terhubung dengan aman ke sumber daya Azure lainnya tanpa menggunakan kunci rahasia atau rahasia aplikasi lainnya. Secara internal, Azure melacak identitas dan sumber daya mana yang diizinkan untuk disambungkan. Azure menggunakan informasi ini untuk mendapatkan token Microsoft Entra secara otomatis untuk aplikasi agar dapat tersambung ke sumber daya Azure lainnya.

Ada dua jenis identitas terkelola yang perlu dipertimbangkan saat mengonfigurasi aplikasi yang dihosting:

• Identitas terkelola yang ditetapkan sistem diaktifkan langsung pada sumber daya Azure dan terkait dengan siklus hidupnya. Saat sumber daya dihapus, Azure secara otomatis menghapus identitas untuk Anda. Identitas yang ditetapkan sistem memberikan pendekatan minimalis untuk menggunakan identitas terkelola.
• Identitas terkelola yang ditetapkan pengguna dibuat sebagai sumber daya Azure mandiri dan menawarkan fleksibilitas dan kemampuan yang lebih besar. Mereka ideal untuk solusi yang melibatkan beberapa sumber daya Azure yang perlu berbagi identitas dan izin yang sama. Misalnya, jika beberapa komputer virtual perlu mengakses set sumber daya Azure yang sama, identitas terkelola yang ditetapkan pengguna menyediakan penggunaan kembali dan manajemen yang dioptimalkan.

Tips

Pelajari selengkapnya tentang memilih dan mengelola identitas terkelola yang ditetapkan sistem dan identitas terkelola yang ditetapkan pengguna di artikel Rekomendasi praktik terbaik identitas terkelola.

Bagian di depan menjelaskan langkah-langkah untuk mengaktifkan dan menggunakan identitas terkelola yang ditetapkan pengguna untuk aplikasi yang dihosting Azure. Jika Anda perlu menggunakan identitas terkelola yang ditetapkan sistem, kunjungi artikel identitas terkelola yang ditetapkan sistem untuk informasi selengkapnya.

Membuat identitas terkelola yang ditetapkan pengguna

Identitas terkelola yang ditetapkan pengguna dibuat sebagai sumber daya mandiri di langganan Azure Anda menggunakan portal Microsoft Azure atau Azure CLI. Perintah Azure CLI dapat dijalankan di Azure Cloud Shell atau di stasiun kerja dengan Azure CLI yang diinstal.

portal Azure

1. Di portal Microsoft Azure, masukkan identitas terkelola di bilah pencarian utama dan pilih hasil yang cocok di bawah bagian Layanan.

2. Pada halaman Identitas Terkelola , pilih + Buat.

   

3. Pada halaman Buat Identitas Terkelola yang Ditetapkan Pengguna, pilih langganan, grup sumber daya, dan wilayah untuk identitas terkelola yang ditetapkan pengguna, lalu berikan nama.

4. Pilih Ulas dan buat untuk meninjau dan memvalidasi input Anda.

   

5. Pilih Buat untuk membuat identitas terkelola yang ditetapkan pengguna.

6. Setelah identitas dibuat, pilih Buka sumber daya.

7. Pada halaman Gambaran Umum identitas baru, salin nilai ID Klien untuk digunakan saat mengonfigurasi kode aplikasi nanti.

Gunakan perintah Azure CLI az identity create untuk membuat identitas terkelola:

az identity create \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query 'clientId' \
    --output json

Output perintah menampilkan ID klien dari identitas terkelola yang ditetapkan oleh pengguna yang telah dibuat. ID klien digunakan untuk mengonfigurasi kode aplikasi yang bergantung pada identitas.

Anda selalu dapat melihat properti identitas terkelola lagi menggunakan perintah az identity show:

az identity show \
    --resource-group <your-resource-group> \
    --name <your-managed-identity-name> \
    --output json

Menetapkan identitas terkelola ke aplikasi Anda

Identitas terkelola yang ditetapkan pengguna dapat dikaitkan dengan satu atau beberapa sumber daya Azure. Semua sumber daya yang menggunakan identitas tersebut memperoleh izin yang diterapkan melalui peran-peran identitas tersebut.

portal Azure

1. Di portal Microsoft Azure, navigasikan ke sumber daya yang menghosting kode aplikasi Anda, seperti Azure App Service atau instans Aplikasi Kontainer Azure.

2. Dari Halaman Gambaran Umum sumber daya, perluas Pengaturan dan pilih Identitas dari menu navigasi.

3. Pada halaman Identitas, beralihlah ke tab yang ditetapkan Pengguna.

4. Pilih + Tambahkan untuk membuka panel Tambahkan identitas terkelola yang ditetapkan pengguna.

5. Pada panel Tambahkan identitas terkelola yang ditetapkan pengguna, gunakan menu dropdown Langganan untuk memfilter hasil pencarian untuk identitas Anda. Gunakan kotak pencarian Identitas terkelola yang ditetapkan pengguna untuk menemukan identitas terkelola yang ditetapkan pengguna yang Anda aktifkan untuk sumber daya Azure yang menghosting aplikasi Anda.

6. Pilih identitas dan pilih Tambahkan di bagian bawah panel untuk melanjutkan.

   

Azure CLI menyediakan perintah yang berbeda untuk menetapkan identitas terkelola yang ditetapkan pengguna ke berbagai jenis layanan hosting.

1. Untuk menetapkan identitas terkelola yang ditetapkan pengguna ke sumber daya seperti aplikasi web Azure App Service menggunakan Azure CLI, Anda memerlukan ID sumber daya identitas tersebut. Gunakan perintah az identity show untuk mengambil ID sumber daya:

   az identity show \
       --resource-group <your-resource-group> \
       --name <your-managed-identity-name> \
       --output json \
       --query id
   

2. Setelah Anda memiliki ID sumber daya, gunakan perintah Azure CLI az <resourceType> identity assign untuk mengaitkan identitas terkelola yang ditetapkan pengguna dengan sumber daya yang berbeda, seperti berikut ini:

   Untuk Azure App Service, gunakan perintah Azure CLI az webapp identity assign:

   az webapp identity assign \
       --resource-group <resource-group-name> \
       --name <webapp-name> \
       --identities <user-assigned-identity-resource-id>
   

   Untuk Azure Container Apps, gunakan perintah Azure CLI az containerapp identity assign:

   az containerapp identity assign \
       --resource-group <resource-group-name> \
       --name <containerapp-name> \
       --identities <user-assigned-identity-resource-id>
   

   Untuk Azure Virtual Machines, gunakan perintah Azure CLI az vm identity assign:

   az vm identity assign \
       --resource-group <resource-group-name> \
       --name <vm-name> \
       --identities <user-assigned-identity-resource-id>
   

Menetapkan peran kepada identitas terkelola

Selanjutnya, tentukan peran mana yang dibutuhkan aplikasi Anda dan tetapkan peran tersebut ke identitas terkelola. Anda dapat menetapkan peran ke identitas terkelola dalam lingkup berikut:

• Resource: Peran yang ditetapkan hanya berlaku untuk sumber daya tertentu tersebut.
• Grup sumber daya: Peran yang ditetapkan berlaku untuk semua sumber daya yang terkandung dalam grup sumber daya.
• Langganan: Peran yang ditetapkan berlaku untuk semua sumber daya yang terkandung dalam langganan.

Contoh berikut menunjukkan cara menetapkan peran di cakupan grup sumber daya, karena banyak aplikasi mengelola semua sumber daya Azure terkait menggunakan satu grup sumber daya.

portal Azure

1. Arahkan ke halaman Gambaran Umum dari grup sumber daya yang berisi aplikasi dengan identitas terkelola yang ditetapkan pengguna.

2. Pilih kontrol akses (IAM) di navigasi kiri.

3. Pada halaman Kontrol akses (IAM), pilih + Tambahkan di menu atas lalu pilih Tambahkan penetapan peran untuk menavigasi ke halaman Tambahkan penetapan peran.

   

4. Halaman Tambahkan penetapan peran menyajikan alur kerja bertab yang bertahap untuk menetapkan peran ke identitas. Pada tab Peran awal, gunakan kotak pencarian di bagian atas untuk menemukan peran yang ingin Anda tetapkan ke identitas.

5. Pilih peran dari hasil pencarian dan kemudian pilih Berikutnya untuk pindah ke tab Anggota.

6. Untuk opsi "Tetapkan akses ke", pilih "Identitas terkelola".

7. Untuk opsi Anggota , pilih + Pilih anggota untuk membuka panel Pilih identitas terkelola .

8. Pada panel Pilih identitas terkelola, gunakan dropdown Langganan dan dropdown Identitas terkelola untuk memfilter hasil pencarian identitas Anda. Gunakan kotak pencarian Pilih untuk menemukan identitas terkelola yang ditetapkan pengguna yang Anda aktifkan untuk sumber daya Azure yang menghosting aplikasi Anda.

   

9. Pilih identitas dan pilih Pilih di bagian bawah panel untuk melanjutkan.

10. Pilih Tinjau + berikan tugas di bagian bawah halaman.

11. Pada tab Tinjau + tetapkan terakhir, pilih Tinjau + tetapkan untuk menyelesaikan alur kerja.

1. Untuk menetapkan peran ke identitas terkelola yang ditetapkan pengguna menggunakan Azure CLI, Anda memerlukan ID utama identitas tersebut. Gunakan perintah az identity show untuk mengambil ID utama:

   az identity show \
       --resource-group <your-resource-group> \
       --name <your-managed-identity-name> \
       --output json \
       --query principalId
   

2. Gunakan perintah az role definition list untuk menjelajahi peran mana yang dapat ditetapkan kepada identitas terkelola:

   az role definition list \
       --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
       --output table
   

3. Tetapkan peran pada identitas terkelola dengan menggunakan perintah az role assignment create:

   az role assignment create \
       --assignee <your-principal-id> \
       --role <role-name> \
       --scope <scope>
   

   Misalnya, untuk mengizinkan identitas terkelola dengan ID 99999999-9999-9999-9999-999999999999 membaca, menulis, dan menghapus akses ke kontainer blob Azure Storage dan data ke semua akun penyimpanan dalam msdocs-dotnet-sdk-auth-example grup sumber daya, tetapkan perwakilan layanan aplikasi ke peran Kontributor Data Blob Penyimpanan menggunakan perintah berikut:

   az role assignment create \
       --assignee 99999999-9999-9999-9999-999999999999 \
       --role "Storage Blob Data Contributor" \
       --scope "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-dotnet-sdk-auth-example"
   

Untuk informasi tentang menetapkan izin di tingkat sumber daya atau langganan menggunakan Azure CLI, lihat artikel Menetapkan peran Azure menggunakan Azure CLI.

Mengautentikasi ke layanan Azure dari aplikasi Anda

Pustaka Azure Identity menyediakan berbagai kredensial —implementasi TokenCredential disesuaikan untuk mendukung skenario yang berbeda dan alur autentikasi Microsoft Entra. Karena identitas terkelola tidak tersedia saat berjalan secara lokal, langkah-langkah di depan menunjukkan kredensial mana yang akan digunakan dalam skenario mana:

• Lingkungan pengembangan lokal: Selama hanya pengembangan lokal, gunakan kelas bernama DefaultAzureCredential untuk rantai kredensial yang disesuaikan dan sudah dikonfigurasi sebelumnya. DefaultAzureCredential menemukan kredensial pengguna dari alat lokal atau IDE Anda, seperti Azure CLI atau Visual Studio. Ini juga memberikan fleksibilitas dan kenyamanan untuk percobaan ulang, waktu tunggu untuk respons, dan dukungan untuk beberapa opsi autentikasi. Kunjungi artikel tentang autentikasi ke layanan Azure selama pengembangan lokal untuk mempelajari lebih lanjut.
• aplikasi yang dihosting Azure: Saat aplikasi Anda berjalan di Azure, gunakan ManagedIdentityCredential untuk menemukan identitas terkelola yang dikonfigurasi untuk aplikasi Anda dengan aman. Menentukan jenis kredensial yang tepat ini mencegah kredensial lain yang tersedia diambil secara tak terduga.

Menerapkan kode

Tambahkan paket Azure.Identity. Dalam proyek ASP.NET Core, instal juga paket Microsoft.Extensions.Azure:

Baris Perintah

Di terminal pilihan Anda, navigasikan ke direktori proyek aplikasi dan jalankan perintah berikut:

dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.Azure

Pengelola Paket NuGet

Klik kanan proyek Anda di jendela Penjelajah Solusi Visual Studio dan pilih Kelola Paket NuGet. Cari Azure.Identity, dan instal paket yang cocok. Ulangi proses ini untuk paket Microsoft.Extensions.Azure.

Layanan Azure diakses menggunakan kelas klien khusus dari berbagai pustaka klien Azure SDK. Kelas-kelas ini dan layanan kustom Anda sendiri harus didaftarkan untuk injeksi dependensi sehingga dapat digunakan di seluruh aplikasi Anda. Di Program.cs, selesaikan langkah-langkah berikut untuk mengonfigurasi kelas klien untuk injeksi dependensi dan autentikasi berbasis token:

1. Sertakan namespace Azure.Identity dan Microsoft.Extensions.Azure melalui arahan using.
2. Daftarkan klien layanan Azure dengan menggunakan metode ekstensi yang diawali dengan Add yang sesuai.
3. Teruskan instans TokenCredential yang sesuai ke metode UseCredential:
   • Gunakan DefaultAzureCredential saat aplikasi Anda berjalan secara lokal
   • Gunakan ManagedIdentityCredential saat aplikasi Anda berjalan di Azure dan konfigurasikan ID klien, ID sumber daya, atau ID objek.

ID Klien

ID klien digunakan untuk mengidentifikasi identitas terkelola saat mengonfigurasi aplikasi atau layanan yang perlu mengautentikasi menggunakan identitas tersebut.

1. Ambil ID klien yang ditetapkan ke identitas terkelola yang ditetapkan oleh pengguna menggunakan perintah berikut:

   az identity show \
       --resource-group <resource-group-name> \
       --name <identity-name> \
       --query 'clientId'
   

2. Konfigurasikan ManagedIdentityCredential dengan ID klien:

   builder.Services.AddAzureClients(clientBuilder =>
   {
       clientBuilder.AddBlobServiceClient(
           new Uri("https://<account-name>.blob.core.windows.net"));
   
       TokenCredential credential = null;
   
       if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
       {
           // Managed identity token credential discovered when running in Azure environments
           credential = new ManagedIdentityCredential(
               ManagedIdentityId.FromUserAssignedClientId("<client-id>"));
       } 
       else 
       {
           // Running locally on dev machine - DO NOT use in production or outside of local dev
           credential = new DefaultAzureCredential();
       }
   
       clientBuilder.UseCredential(credential);
   });
   

   Alternatif untuk metode UseCredential adalah memberikan kredensial kepada klien layanan secara langsung:

   TokenCredential credential = null;
   
   if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
   {
       // Managed identity token credential discovered when running in Azure environments
       credential = new ManagedIdentityCredential(
           ManagedIdentityId.FromUserAssignedClientId("<client-id>"));
   }
   else
   {
       // Running locally on dev machine - DO NOT use in production or outside of local dev
       credential = new DefaultAzureCredential();
   }
   
   builder.Services.AddSingleton<BlobServiceClient>(_ =>
       new BlobServiceClient(
           new Uri("https://<account-name>.blob.core.windows.net"), credential));
   

ID Sumber Daya

ID sumber daya secara unik mengidentifikasi sumber daya identitas terkelola dalam langganan Azure Anda menggunakan struktur berikut:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}

ID sumber daya dapat dibangun oleh konvensi, yang membuatnya lebih nyaman saat bekerja dengan sejumlah besar identitas terkelola yang ditetapkan pengguna di lingkungan Anda.

1. Ambil ID sumber daya untuk identitas terkelola yang ditetapkan pengguna menggunakan perintah berikut:

   az identity show \
       --resource-group <resource-group-name> \
       --name <identity-name> \
       --query 'id'
   

2. Konfigurasikan ManagedIdentityCredential dengan ID sumber daya:

   builder.Services.AddAzureClients(clientBuilder =>
   {
       clientBuilder.AddBlobServiceClient(
           new Uri("https://<account-name>.blob.core.windows.net"));
   
       TokenCredential credential = null;
   
       if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
       {
           // Managed identity token credential discovered when running in Azure environments
           credential = new ManagedIdentityCredential(
               ManagedIdentityId.FromUserAssignedResourceId(new ResourceIdentifier("<resource-id>")));
       }
       else
       {
           // Running locally on dev machine - DO NOT use in production or outside of local dev
           credential = new DefaultAzureCredential();
       }
   
       clientBuilder.UseCredential(credential);
   });
   

   Alternatif untuk metode UseCredential adalah memberikan kredensial kepada klien layanan secara langsung:

   TokenCredential credential = null;
   
   if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
   {
       // Managed identity token credential discovered when running in Azure environments
       credential = new ManagedIdentityCredential(
           ManagedIdentityId.FromUserAssignedResourceId(new ResourceIdentifier("<resource-id>")));
   }
   else
   {
       // Running locally on dev machine - DO NOT use in production or outside of local dev
       credential = new DefaultAzureCredential();
   }
   
   builder.Services.AddSingleton<BlobServiceClient>(_ =>
       new BlobServiceClient(
           new Uri("https://<account-name>.blob.core.windows.net"), credential));
   

ID Objek

ID utama adalah nama lain untuk ID objek.

1. Ambil ID objek untuk identitas terkelola yang ditetapkan pengguna menggunakan perintah berikut:

   az identity show \
       --resource-group <resource-group-name> \
       --name <identity-name> \
       --query 'principalId'
   

2. Konfigurasikan ManagedIdentityCredential dengan ID objek:

   builder.Services.AddAzureClients(clientBuilder =>
   {
       clientBuilder.AddBlobServiceClient(
           new Uri("https://<account-name>.blob.core.windows.net"));
           
       TokenCredential credential = null;
   
       if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
       {
           // Managed identity token credential discovered when running in Azure environments
           credential = new ManagedIdentityCredential(
               ManagedIdentityId.FromUserAssignedObjectId("<object-id>"));
       }
       else
       {
           // Running locally on dev machine - DO NOT use in production or outside of local dev
           credential = new DefaultAzureCredential();
       }
   
       clientBuilder.UseCredential(credential);
   });
   

   Alternatif untuk metode UseCredential adalah memberikan kredensial kepada klien layanan secara langsung:

   TokenCredential credential = null;
   
   if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
   {
       // Managed identity token credential discovered when running in Azure environments
       credential = new ManagedIdentityCredential(
           ManagedIdentityId.FromUserAssignedObjectId("<object-id>"));
   }
   else
   {
       // Running locally on dev machine - DO NOT use in production or outside of local dev
       credential = new DefaultAzureCredential();
   }
   
   builder.Services.AddSingleton<BlobServiceClient>(_ =>
       new BlobServiceClient(
           new Uri("https://<account-name>.blob.core.windows.net"), credential));
   

Kode di atas berperilaku berbeda tergantung pada lingkungan berjalannya:

• Di stasiun kerja pengembangan lokal Anda, DefaultAzureCredential mencari dalam variabel lingkungan untuk prinsip layanan aplikasi atau di alat pengembang yang diinstal secara lokal, seperti Visual Studio, untuk serangkaian kredensial pengembang.
• Saat disebarkan ke Azure, ManagedIdentityCredential menemukan konfigurasi identitas terkelola Anda untuk mengautentikasi ke layanan lain secara otomatis.