Menginisialisasi aplikasi klien

  • 3 menit

Dengan MSAL.NET 3.x, cara yang disarankan untuk membuat instans aplikasi adalah dengan menggunakan penyusun aplikasi: PublicClientApplicationBuilder dan ConfidentialClientApplicationBuilder. Mereka menawarkan mekanisme yang kuat untuk mengonfigurasi aplikasi baik dari kode, atau dari file konfigurasi, atau bahkan dengan mencampur kedua pendekatan.

Sebelum menginisialisasi aplikasi, Anda harus mendaftarkannya sebelumnya agar aplikasi Anda dapat diintegrasikan dengan platform identitas Microsoft. Setelah pendaftaran, Anda mungkin memerlukan informasi berikut (yang dapat ditemukan di portal Microsoft Azure):

  • ID aplikasi (klien) - Ini adalah string yang mewakili GUID.
  • ID Direktori (penyewa) - Menyediakan kemampuan manajemen identitas dan akses (IAM) ke aplikasi dan sumber daya yang digunakan oleh organisasi Anda. Ini dapat menentukan apakah Anda menulis lini aplikasi bisnis hanya untuk organisasi Anda (juga bernama aplikasi penyewa tunggal).
  • URL penyedia identitas (bernama instans) dan audiens masuk untuk aplikasi Anda. Kedua parameter ini secara bersama-sama dikenal sebagai otoritas.
  • Kredensial klien - yang dapat berbentuk rahasia aplikasi (string rahasia klien) atau sertifikat (jenis X509Certificate2) jika itu adalah aplikasi klien rahasia.
  • Untuk aplikasi web, dan terkadang untuk aplikasi klien publik (khususnya saat aplikasi Anda perlu menggunakan broker), Anda perlu mengatur URI Pengalihan tempat IdP mengirim token keamanan kembali ke aplikasi Anda.

Menginisialisasi aplikasi klien publik dan rahasia dari kode

Kode berikut ini membuat instans aplikasi klien publik, memasukkan pengguna di cloud publik Microsoft Azure, dengan akun kantor dan sekolah mereka, atau akun Microsoft pribadi mereka.

IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId).Build();

Dengan cara yang sama, kode berikut ini membuat instans aplikasi rahasia (aplikasi Web yang terletak di https://myapp.azurewebsites.net) menangani token dari pengguna di cloud publik Microsoft Azure, dengan akun kantor dan sekolah mereka, atau akun Microsoft pribadi mereka. Aplikasi ini diidentifikasi dengan penyedia identitas dengan membagikan rahasia klien:

string redirectUri = "https://myapp.azurewebsites.net";
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithClientSecret(clientSecret)
    .WithRedirectUri(redirectUri )
    .Build();

Pengubah pembangun

Dalam cuplikan kode menggunakan penyusun aplikasi, .With metode dapat diterapkan sebagai pengubah (misalnya, .WithAuthority dan .WithRedirectUri).

  • .WithAuthority pengubah: Pengubah .WithAuthority menetapkan otoritas default aplikasi ke otoritas Microsoft Entra, dengan kemungkinan memilih Azure Cloud, audiens, penyewa (ID penyewa atau nama domain), atau memberikan URI otoritas secara langsung.

    IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
    .Build();

  • Pengubah .WithRedirectUri: Pengubah .WithRedirectUri mengambil alih URI pengalihan default.

    IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(client_id)
    .WithAuthority(AzureCloudInstance.AzurePublic, tenant_id)
    .WithRedirectUri("http://localhost")
    .Build();

Pengubah umum untuk aplikasi klien publik dan rahasia

Tabel di bawah ini mencantumkan beberapa pengubah yang dapat Anda atur pada klien publik, atau rahasia.

Pengubah Deskripsi
.WithAuthority() Mengatur otoritas default aplikasi ke otoritas Microsoft Entra, dengan kemungkinan memilih Azure Cloud, audiens, penyewa (ID penyewa atau nama domain), atau menyediakan langsung URI otoritas.
.WithTenantId(string tenantId) Mengambil alih ID penyewa, atau deskripsi penyewa.
.WithClientId(string) Mengambil alih ID klien.
.WithRedirectUri(string redirectUri) Mengambil alih URI pengalihan default. Ini berguna untuk skenario yang memerlukan broker.
.WithComponent(string) Menetapkan nama pustaka menggunakan MSAL.NET (karena alasan telemetri).
.WithDebugLoggingCallback() Jika dipanggil, aplikasi memanggil Debug.Write hanya mengaktifkan jejak penelusuran kesalahan.
.WithLogging() Jika dipanggil, aplikasi memanggil panggilan balik dengan jejak penelusuran kesalahan.
.WithTelemetry(TelemetryCallback telemetryCallback) Menetapkan delegasi yang digunakan untuk mengirim telemetri.

Pengubah khusus untuk aplikasi klien rahasia

Pengubah khusus untuk penyusun aplikasi klien rahasia dapat ditemukan di ConfidentialClientApplicationBuilder kelas . Metode yang berbeda dapat ditemukan di Azure SDK untuk dokumentasi .NET.

Pengubah seperti .WithCertificate(X509Certificate2 certificate) dan .WithClientSecret(string clientSecret) saling eksklusif. Jika Anda menyediakan keduanya, MSAL melemparkan pengecualian yang bermakna.