Mengautentikasi aplikasi .NET ke layanan Azure selama pengembangan lokal menggunakan perwakilan layanan

Artikel
08/05/2024

Pengembang perlu men-debug dan menguji aplikasi cloud di stasiun kerja lokal mereka. Saat aplikasi berjalan di stasiun kerja pengembang selama pengembangan lokal, aplikasi harus tetap mengautentikasi ke layanan Azure apa pun yang digunakan oleh aplikasi. Artikel ini membahas cara menyiapkan objek perwakilan layanan aplikasi khusus yang akan digunakan selama pengembangan lokal.

Diagram yang menunjukkan bagaimana aplikasi .NET lokal menggunakan kredensial pengembang untuk menyambungkan ke Azure dengan menggunakan alat pengembangan yang diinstal secara lokal.

Perwakilan layanan aplikasi khusus untuk pengembangan lokal memungkinkan Anda untuk mengikuti prinsip hak istimewa paling sedikit selama pengembangan aplikasi. Karena izin dilingkupkan ke apa yang diperlukan untuk aplikasi selama pengembangan, kode aplikasi dicegah untuk mengakses sumber daya Azure secara tidak sengaja yang dimaksudkan untuk digunakan oleh aplikasi lain. Ini juga mencegah bug terjadi ketika aplikasi dipindahkan ke produksi karena aplikasi terlalu istimewa di lingkungan dev.

Perwakilan layanan aplikasi disiapkan untuk aplikasi saat aplikasi terdaftar di Azure. Saat mendaftarkan aplikasi untuk pengembangan lokal, disarankan untuk:

Buat pendaftaran aplikasi terpisah untuk setiap pengembang yang bekerja di aplikasi. Hal ini akan membuat perwakilan layanan aplikasi terpisah untuk digunakan setiap pengembang selama pengembangan lokal dan menghindari kebutuhan pengembang untuk berbagi mandat untuk satu perwakilan layanan aplikasi.
Buat pendaftaran aplikasi terpisah per aplikasi. Hal ini mencakup izin aplikasi hanya untuk apa yang diperlukan oleh aplikasi.

Selama pengembangan lokal, variabel lingkungan diatur dengan identitas perwakilan layanan aplikasi. Pustaka Azure Identity membaca variabel lingkungan ini dan menggunakan informasi ini untuk mengautentikasi aplikasi ke sumber daya Azure yang dibutuhkan.

1 - Mendaftarkan aplikasi di Azure

Objek perwakilan layanan aplikasi dibuat dengan pendaftaran aplikasi di Azure. Anda dapat menggunakan portal Azure atau Azure CLI.

Portal Azure
Azure CLI

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 termasuk nama aplikasi, pengguna tempat pendaftaran aplikasi, dan pengidentifikasi seperti 'dev' untuk menunjukkan pendaftaran aplikasi ini digunakan dalam pengembangan lokal. Jenis akun yang didukung hanya → Akun di 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, karena juga akan diperlukan 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.
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.

Perintah Azure CLI dapat dijalankan di Azure Cloud Shell atau pada stasiun kerja dengan Azure CLI terpasang.

Pertama, gunakan perintah az ad sp create-for-rbac untuk membuat perwakilan layanan baru untuk aplikasi. Ini juga akan membuat pendaftaran aplikasi untuk aplikasi secara bersamaan.

az ad sp create-for-rbac \
    --name {service-principal-name}

Output perintah ini menyerupan JSON berikut:

{
  "appId": "00000000-0000-0000-0000-000000000000",
  "displayName": "{service-principal-name}",
  "password": "abcdefghijklmnopqrstuvwxyz",
  "tenant": "11111111-1111-1111-1111-111111111111"
}

Salin output ini ke dalam file sementara di editor teks, karena Anda akan memerlukan nilai-nilai ini di langkah mendatang. Ini adalah satu-satunya tempat Anda pernah melihat rahasia klien (kata sandi) untuk perwakilan layanan. Namun, Anda dapat menambahkan kata sandi baru nanti tanpa membatalkan perwakilan layanan atau kata sandi yang ada, jika diperlukan.

2 - Membuat grup Microsoft Entra untuk pengembangan lokal

Karena biasanya ada beberapa pengembang yang mengerjakan aplikasi, disarankan untuk membuat grup Microsoft Entra untuk merangkum peran (izin) yang dibutuhkan aplikasi dalam pengembangan lokal daripada menetapkan peran ke objek perwakilan layanan individual. Pendekatan ini menawarkan keuntungan berikut:

Setiap pengembang diyakinkan untuk memiliki peran yang sama yang ditetapkan karena peran ditetapkan di tingkat grup.
Jika peran baru diperlukan untuk aplikasi, peran tersebut hanya perlu ditambahkan ke grup untuk aplikasi.
Jika pengembang baru bergabung dengan tim, perwakilan layanan aplikasi baru dibuat untuk pengembang dan ditambahkan ke grup, memastikan pengembang memiliki izin yang tepat untuk bekerja di aplikasi.

Portal Azure
Azure CLI

Petunjuk	Cuplikan layar
Navigasi ke halaman ID Microsoft Entra di portal Azure dengan mengetik ID Microsoft Entra ke dalam kotak pencarian di bagian atas halaman. Pilih ID Microsoft Entra di bawah bagian Layanan .
Pada halaman ID Microsoft Entra, pilih Grup dari menu sebelah kiri.
Pada halaman Semua grup, pilih Grup baru.
Pada halaman Grup Baru: Jenis grup → Keaman Nama grup → Nama untuk grup keamanan, biasanya dibuat dari nama aplikasi. Sangat membantu untuk menyertakan string seperti local-dev dalam nama grup untuk menunjukkan tujuan grup. Deskripsi grup → Deskripsi tujuan grup. Pilih link Tidak ada anggota yang dipilih di bawah Anggota untuk menambahkan anggota ke grup.
Pada kotak dialog Tambahkan anggota : Gunakan kotak pencarian untuk memfilter daftar nama prinsipal dalam daftar. Pilih perwakilan layanan aplikasi untuk pengembangan lokal untuk aplikasi ini. Saat objek dipilih, objek akan berwarna abu-abu dan berpindah ke daftar Item yang dipilih di bagian bawah dialog. Ketika selesai, pilih tombol Pilih.
Pada halaman Grup baru, pilih Buat untuk membuat grup. Grup akan dibuat dan Anda akan dibawa kembali ke halaman Semua grup . Mungkin perlu waktu hingga 30 detik agar grup muncul. Anda mungkin perlu menyegarkan halaman karena penembolokan di portal Azure.

Perintah az ad group create digunakan untuk membuat grup di ID Microsoft Entra. Parameter --display-name dan --mail-nickname dihitung. Nama yang diberikan ke grup harus didasarkan pada nama aplikasi. Ini juga berguna untuk menyertakan frasa seperti 'local-dev' dalam nama grup untuk menunjukkan tujuan grup.

az ad group create \
    --display-name MyDisplay \
    --mail-nickname MyDisplay \
    --description {group-description}

Untuk menambahkan anggota ke grup, Anda memerlukan ID objek dari perwakilan layanan aplikasi, yang berbeda dari ID aplikasi. Gunakan perintah az ad sp list untuk mencantumkan perwakilan layanan yang tersedia. Perintah --filter parameter menerima filter gaya OData dan dapat digunakan untuk memfilter daftar seperti yang ditunjukkan. Parameter --query membatasi kolom hanya untuk kolom yang diminati.

az ad sp list \
    --filter "startswith(displayName, 'msdocs')" \
    --query "[].{objectId:objectId, displayName:displayName}" \
    --output table

Perintah tambahkan anggota grup az ad kemudian dapat digunakan untuk menambahkan anggota ke grup:

az ad group member add \
    --group {group-name} \
    --member-id {object-id}

3 - Menetapkan peran ke aplikasi

Selanjutnya, tentukan peran (izin) apa yang dibutuhkan aplikasi Anda pada sumber daya apa dan tetapkan peran tersebut ke aplikasi Anda. Dalam contoh ini, peran akan ditetapkan ke grup Microsoft Entra yang dibuat di langkah 2. Grup dapat diberi peran di sumber daya, grup sumber daya, atau cakupan langganan. Contoh ini menunjukkan cara menetapkan peran di cakupan grup sumber daya, karena sebagian besar aplikasi mengelompokkan semua sumber daya Azure mereka ke dalam satu grup sumber daya.

Portal Azure
Azure CLI

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 terbuka di sisi kanan portal 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 grup Microsoft Entra pengembangan lokal yang Anda buat untuk aplikasi. Pilih grup Microsoft Entra pengembangan lokal yang terkait dengan aplikasi Anda. Pilih Pilih di bagian bawah dialog untuk melanjutkan.
Grup Microsoft Entra ditampilkan seperti yang dipilih pada layar Tambahkan penetapan peran. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.

Perwakilan layanan aplikasi 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 yang dapat ditetapkan oleh perwakilan layanan, 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 aplikasi 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.

4 - Mengatur variabel lingkungan aplikasi

Saat runtime, DefaultAzureCredential cari informasi perwakilan layanan dalam kumpulan variabel lingkungan. Ada beberapa cara untuk mengonfigurasi variabel lingkungan saat bekerja dengan .NET, tergantung pada alat dan lingkungan Anda.

Terlepas dari pendekatan 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.

Saat bekerja secara lokal dengan Visual Studio, variabel lingkungan dapat diatur dalam file launchsettings.json di folder Properties proyek Anda. Saat aplikasi dimulai, nilai-nilai ini ditarik secara otomatis. Perlu diingat, konfigurasi ini tidak bepergian dengan aplikasi Anda saat disebarkan, jadi Anda perlu menyiapkan variabel lingkungan di lingkungan hosting target Anda.

"profiles": {
    "SampleProject": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7177;http://localhost:5177",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "AZURE_TENANT_ID":"11111111-1111-1111-1111-111111111111",
        "AZURE_CLIENT_SECRET": "=abcdefghijklmnopqrstuvwxyz"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "AZURE_TENANT_ID": "11111111-1111-1111-1111-111111111111",
        "AZURE_CLIENT_SECRET": "=abcdefghijklmnopqrstuvwxyz"
      }
    }
  }

Saat bekerja secara lokal dengan Visual Studio Code, variabel lingkungan dapat diatur dalam file launch.json proyek Anda. Saat aplikasi dimulai, nilai-nilai ini akan ditarik secara otomatis. Perlu diingat, konfigurasi ini tidak bepergian dengan aplikasi Anda saat disebarkan, jadi Anda perlu menyiapkan variabel lingkungan di lingkungan hosting target Anda.

"configurations": [
{
    "env": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "AZURE_TENANT_ID":"11111111-1111-1111-1111-111111111111",
        "AZURE_CLIENT_SECRET": "=abcdefghijklmnopqrstuvwxyz"
    }
}

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

PowerShell juga dapat digunakan 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")

5 - 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
Pengelola Paket NuGet

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

dotnet add package Azure.Identity
dotnet add package 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:

Sertakan Azure.Identity namespace layanan dan Microsoft.Extensions.Azure melalui using arahan.
Daftarkan klien layanan Azure menggunakan metode ekstensi -awalan Addyang sesuai.
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.

Bagikan melalui