Mengautentikasi ke sumber daya Azure dari aplikasi .NET yang dihosting secara lokal

Aplikasi yang dihosting di luar Azure (misalnya, lokal atau di pusat data pihak ketiga) harus menggunakan perwakilan layanan aplikasi untuk mengautentikasi ke Azure saat mengakses sumber daya Azure. Objek perwakilan layanan aplikasi dibuat menggunakan proses pendaftaran aplikasi di Azure. Saat perwakilan layanan aplikasi dibuat, ID klien dan rahasia klien akan dibuat untuk aplikasi Anda. ID klien, rahasia klien, dan ID penyewa Anda kemudian disimpan dalam variabel lingkungan sehingga dapat digunakan oleh pustaka Identitas Azure untuk mengautentikasi aplikasi Anda ke Azure saat runtime.

Pendaftaran aplikasi yang berbeda harus dibuat untuk setiap lingkungan tempat aplikasi dihosting. Ini memungkinkan izin sumber daya khusus lingkungan dikonfigurasi untuk setiap perwakilan layanan dan memastikan aplikasi yang disebarkan ke satu lingkungan tidak berbicara dengan sumber daya Azure yang merupakan bagian dari lingkungan lain.

1 - Mendaftarkan aplikasi di Azure

Aplikasi dapat didaftarkan dengan Azure menggunakan portal Microsoft Azure atau Azure CLI.

Portal Azure

Masuk ke portal Azure dan ikuti langkah-langkah berikut.

Petunjuk	Cuplikan layar
Di portal Azure: Masukkan pendaftaran aplikasi di bilah pencarian di bagian atas portal Azure. Pilih item berlabel Pendaftaran aplikasi pada judul Layanan pada menu yang muncul di bawah bilah pencarian.
Pada halaman Pendaftaran aplikasi, pilih + Pendaftaran baru.
Pada halaman Daftarkan aplikasi , isi formulir sebagai berikut: Nama → Masukkan nama untuk pendaftaran aplikasi di Azure. Disarankan nama ini mencakup nama aplikasi dan lingkungan (pengujian, prod) untuk pendaftaran aplikasi. Jenis akun yang didukung → Hanya akun dalam direktori organisasi ini. Pilih Daftar untuk mendaftarkan aplikasi Anda dan membuat perwakilan layanan aplikasi.
Pada halaman Pendaftaran aplikasi untuk aplikasi Anda: ID Aplikasi (klien) → Ini adalah id aplikasi yang akan digunakan aplikasi untuk mengakses Azure selama pengembangan lokal. Salin nilai ini ke lokasi sementara di editor teks karena Anda akan membutuhkannya di langkah mendatang. Id direktori (penyewa) → Nilai ini juga akan diperlukan oleh aplikasi Anda saat mengautentikasi ke Azure. Salin nilai ini ke lokasi sementara di editor teks. Nilai ini juga akan dibutuhkan di langkah mendatang. Mandat klien → Anda harus mengatur mandat klien untuk aplikasi sebelum aplikasi Anda dapat mengautentikasi ke Azure dan menggunakan layanan Azure. Pilih Tambahkan sertifikat atau rahasia untuk menambahkan mandat untuk aplikasi Anda.
Pada halaman Sertifikat & rahasia , pilih + Rahasia klien baru.
Dialog Tambahkan rahasia klien akan muncul dari sisi kanan halaman. Dalam dialog ini: Deskripsi → Masukkan nilai Saat Ini. Kedaluwarsa → Pilih nilai 24 bulan. Pilih Buat untuk menambahkan rahasia. PENTING: Atur pengingat di kalender Anda sebelum tanggal kedaluwarsa rahasia. Dengan cara ini, Anda dapat menambahkan rahasia baru sebelum dan memperbarui aplikasi sebelum kedaluwarsa rahasia ini dan menghindari gangguan layanan di aplikasi Anda.
Pada halaman Sertifikat & rahasia , Anda akan ditampilkan nilai rahasia klien. Salin nilai ini ke lokasi sementara di editor teks, karena Anda akan membutuhkannya di langkah mendatang. PENTING: Ini adalah satu-satunya waktu Anda akan melihat nilai ini. Setelah Keluar atau menyegarkan halaman ini, Anda tidak akan dapat melihat nilai ini lagi. Anda dapat menambahkan rahasia klien tambahan tanpa membatalkan rahasia klien ini, tetapi Anda tidak akan melihat nilai ini lagi.

Azure CLI

az ad sp create-for-rbac --name <app-name>

Output perintah akan mirip dengan yang berikut ini. Catat nilai-nilai ini atau tetap buka jendela ini karena Anda akan membutuhkan nilai-nilai ini di langkah berikutnya dan tidak akan dapat melihat nilai kata sandi (rahasia klien) lagi.

{
  "appId": "00000000-1111-2222-3333-444444444444",
  "displayName": "msdocs-dotnet-sdk-auth-prod",
  "password": "abcdefghijklmnopqrstuvwxyz",
  "tenant": "00000000-0000-0000-0000-000000000000"
}

2 - Menetapkan peran ke perwakilan layanan aplikasi

Selanjutnya, Anda perlu menentukan peran (izin) apa yang dibutuhkan aplikasi Anda pada sumber daya apa dan menetapkan peran tersebut ke aplikasi Anda. Peran dapat diberi peran di sumber daya, grup sumber daya, atau cakupan langganan. Contoh ini menunjukkan cara menetapkan peran untuk perwakilan layanan di cakupan grup sumber daya, karena sebagian besar aplikasi mengelompokkan semua sumber daya Azure mereka ke dalam satu grup sumber daya.

Portal Azure

Petunjuk	Cuplikan layar
Temukan grup sumber daya untuk aplikasi Anda dengan mencari nama grup sumber daya menggunakan kotak pencarian di bagian atas portal Azure. Navigasi ke grup sumber daya Anda dengan memilih nama grup sumber daya di bawah judul Grup Sumber Daya dalam kotak dialog.
Pada halaman untuk grup sumber daya, pilih Kontrol akses (IAM) dari menu sebelah kiri.
Pada halaman Kontrol akses (IAM): Pilih tab Penetapan peran. Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.
Halaman Tambahkan penetapan peran mencantumkan semua peran yang dapat ditetapkan untuk grup sumber daya. Gunakan kotak pencarian untuk memfilter daftar ke ukuran yang lebih mudah dikelola. Contoh ini menunjukkan cara memfilter peran Blob Penyimpanan. Pilih peran yang ingin ditetapkan. Pilih Berikutnya untuk masuk ke layar berikutnya.
Halaman Tambahkan penetapan peran berikutnya memungkinkan Anda menentukan pengguna yang akan ditetapkan perannya. Pilih Pengguna, grup, atau perwakilan layanan di bawah Tetapkan akses ke. Pilih + Pilih anggota di bawah Anggota. Kotak dialog akan terbuka di sisi kanan portal Microsoft Azure.
Dalam dialog Pilih anggota: Kotak teks Pilih dapat digunakan untuk memfilter daftar pengguna dan grup di langganan Anda. Jika diperlukan, ketik beberapa karakter pertama dari perwakilan layanan yang Anda buat untuk aplikasi guna memfilter daftar. Pilih perwakilan layanan yang terkait dengan aplikasi Anda. Pilih Pilih di bagian bawah dialog untuk melanjutkan.
Perwakilan layanan sekarang akan ditampilkan seperti yang dipilih di layar Tambahkan penetapan peran. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.

Azure CLI

Perwakilan layanan diberi peran di Azure menggunakan perintah az role assignment create :

az role assignment create --assignee "{appId}" \
    --role "{roleName}" \
    --resource-group "{resourceGroupName}"

Untuk mendapatkan nama peran tempat perwakilan layanan dapat ditetapkan, gunakan perintah az role definition list :

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

Misalnya, untuk mengizinkan perwakilan layanan dengan appId 00000000-0000-0000-0000-000000000000 akses baca, tulis, dan hapus ke kontainer dan data blob Azure Storage ke semua akun penyimpanan dalam grup sumber daya msdocs-dotnet-sdk-auth-example , tetapkan perwakilan layanan aplikasi ke peran Kontributor Data Blob Penyimpanan menggunakan perintah berikut:

az role assignment create --assignee "00000000-0000-0000-0000-000000000000" \
    --role "Storage Blob Data Contributor" \
    --resource-group "msdocs-dotnet-sdk-auth-example"

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

3 - Mengonfigurasi variabel lingkungan untuk aplikasi

Objek DefaultAzureCredential akan mencari mandat perwakilan layanan dalam himpunan variabel lingkungan saat runtime bahasa umum. Ada beberapa cara untuk mengonfigurasi variabel lingkungan saat bekerja dengan .NET tergantung pada alat dan lingkungan Anda.

Terlepas dari pendekatan mana yang Anda pilih, konfigurasikan variabel lingkungan berikut saat bekerja dengan perwakilan layanan:

• AZURE_CLIENT_ID → Nilai ID aplikasi.
• AZURE_TENANT_ID → Nilai ID penyewa.
• AZURE_CLIENT_SECRET → Kata sandi/mandat yang dihasilkan untuk aplikasi.

IIS

Jika aplikasi Anda dihosting di IIS, disarankan agar Anda mengatur variabel lingkungan per kumpulan aplikasi untuk mengisolasi pengaturan antar aplikasi.

appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='ASPNETCORE_ENVIRONMENT',value='Production']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_CLIENT_ID',value='00000000-0000-0000-0000-000000000000']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_TENANT_ID',value='11111111-1111-1111-1111-111111111111']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_CLIENT_SECRET',value='=abcdefghijklmnopqrstuvwxyz']" /commit:apphost

Anda juga dapat mengonfigurasi pengaturan ini secara langsung menggunakan elemen di applicationPools dalam applicationHost.config file:

<applicationPools>
   <add name="CorePool" managedRuntimeVersion="v4.0" managedPipelineMode="Classic">
      <environmentVariables>
         <add name="ASPNETCORE_ENVIRONMENT" value="Development" />
         <add name="AZURE_CLIENT_ID" value="00000000-0000-0000-0000-000000000000" />
         <add name="AZURE_TENANT_ID" value="11111111-1111-1111-1111-111111111111" />
         <add name="AZURE_CLIENT_SECRET" value="=abcdefghijklmnopqrstuvwxyz" />
      </environmentVariables>
   </add>
</applicationPools>

Windows

Anda dapat mengatur variabel lingkungan untuk Windows dari baris perintah. Namun, saat menggunakan pendekatan ini, nilai dapat diakses oleh semua aplikasi yang berjalan pada sistem operasi tersebut dan dapat menyebabkan konflik jika Anda tidak berhati-hati. Variabel lingkungan dapat diatur pada tingkat pengguna atau sistem.

# Set user environment variables
setx ASPNETCORE_ENVIRONMENT "Development"
setx AZURE_CLIENT_ID "00000000-0000-0000-0000-000000000000"
setx AZURE_TENANT_ID "11111111-1111-1111-1111-111111111111"
setx AZURE_CLIENT_SECRET "=abcdefghijklmnopqrstuvwxyz"

# Set system environment variables - requires running as admin
setx ASPNETCORE_ENVIRONMENT "Development"
setx AZURE_CLIENT_ID "00000000-0000-0000-0000-000000000000" /m
setx AZURE_TENANT_ID "11111111-1111-1111-1111-111111111111" /m
setx AZURE_CLIENT_SECRET "=abcdefghijklmnopqrstuvwxyz" /m

Anda juga dapat menggunakan PowerShell untuk mengatur variabel lingkungan di tingkat pengguna atau komputer:

# Set user environment variables
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "00000000-0000-0000-0000-000000000000", "User")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "11111111-1111-1111-1111-111111111111", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "=abcdefghijklmnopqrstuvwxyz", "User")

# Set system environment variables - requires running as admin
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "00000000-0000-0000-0000-000000000000", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "11111111-1111-1111-1111-111111111111", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "=abcdefghijklmnopqrstuvwxyz", "Machine")

4 - Menerapkan DefaultAzureCredential di aplikasi Anda

DefaultAzureCredential adalah urutan mekanisme yang diurutkan dan diurutkan untuk mengautentikasi ke Microsoft Entra. Setiap mekanisme autentikasi adalah kelas yang berasal dari kelas TokenCredential dan dikenal sebagai kredensial. Pada runtime, DefaultAzureCredential upaya untuk mengautentikasi menggunakan kredensial pertama. Jika kredensial tersebut gagal memperoleh token akses, kredensial berikutnya dalam urutan dicoba, dan sebagainya, hingga token akses berhasil diperoleh. Dengan cara ini, aplikasi Anda dapat menggunakan kredensial yang berbeda di lingkungan yang berbeda tanpa menulis kode khusus lingkungan.

Urutan dan lokasi di mana DefaultAzureCredential mencari kredensial ditemukan di DefaultAzureCredential.

Untuk menggunakan DefaultAzureCredential, tambahkan Azure.Identity dan secara opsional paket Microsoft.Extensions.Azure ke aplikasi Anda:

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 sehingga dapat diakses melalui injeksi dependensi di seluruh aplikasi Anda. Di Program.cs, selesaikan langkah-langkah berikut untuk mendaftarkan kelas klien dan DefaultAzureCredential:

1. Sertakan Azure.Identity namespace layanan dan Microsoft.Extensions.Azure melalui using arahan.
2. Daftarkan klien layanan Azure menggunakan metode ekstensi -awalan Addyang sesuai.
3. Teruskan instans DefaultAzureCredential ke UseCredential metode .

Contohnya:

using Microsoft.Extensions.Azure;
using Azure.Identity;

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Alternatifnya UseCredential adalah membuat instans DefaultAzureCredential secara langsung:

using Azure.Identity;

builder.Services.AddSingleton<BlobServiceClient>(_ =>
    new BlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"),
        new DefaultAzureCredential()));

Saat kode sebelumnya berjalan di stasiun kerja pengembangan lokal Anda, kode tersebut akan melihat variabel lingkungan untuk perwakilan layanan aplikasi atau di alat pengembang yang diinstal secara lokal, seperti Visual Studio, untuk serangkaian kredensial pengembang. Salah satu pendekatan dapat digunakan untuk mengautentikasi aplikasi ke sumber daya Azure selama pengembangan lokal.

Saat disebarkan ke Azure, kode yang sama ini juga dapat mengautentikasi aplikasi Anda ke sumber daya Azure lainnya. DefaultAzureCredential dapat mengambil pengaturan lingkungan dan konfigurasi identitas terkelola untuk mengautentikasi ke layanan lain secara otomatis.