Perbedaan antara aplikasi ADAL.NET dan MSAL.NET

Memigrasikan aplikasi Anda dari menggunakan ADAL ke MSAL dilengkapi dengan keuntungan keamanan dan ketahanan. Artikel ini menguraikan perbedaan antara MSAL.NET dan ADAL.NET. Dalam kebanyakan kasus, Anda ingin menggunakan MSAL.NET dan platform identitas Microsoft, yang merupakan generasi terbaru dari Pustaka Autentikasi Microsoft. Dengan MSAL.NET, Anda mendapatkan token untuk pengguna yang masuk ke aplikasi Anda dengan Microsoft Azure Active Directory (akun kantor dan sekolah), akun Microsoft (personal) (MSA), atau Azure Active Directory B2C.

Jika Anda sudah terbiasa dengan ADAL.NET dan titik akhir Azure AD untuk pengembang (v1.0), kenali Apa yang berbeda tentang platform identitas Microsoft?. Anda masih perlu menggunakan ADAL.NET jika aplikasi Anda perlu memasukkan pengguna dengan versi sebelumnya dari Layanan Federasi Direktori Aktif (ADFS). Untuk informasi selengkapnya, lihat Dukungan Layanan Federasi Direktori Aktif.

ADAL NET MSAL NET
Paket NuGet dan Namespace ADAL digunakan dari paket NuGet Microsoft.IdentityModel.Clients.ActiveDirectory. Namespace layanannya adalah Microsoft.IdentityModel.Clients.ActiveDirectory. Tambahkan paket NuGet Microsoft.Identity.Client dan gunakan namespace layanan Microsoft.Identity.Client. Jika Anda membangun aplikasi klien rahasia, lihat Microsoft.Identity.Web.
Cakupan dan sumber daya ADAL.NET memperoleh token untuk sumber daya. MSAL.NET memperoleh token untuk cakupan. Beberapa pengambilalihan MSAL.NET AcquireTokenXXX memerlukan parameter yang disebut scopes(IEnumerable<string> scopes). Parameter ini adalah daftar string sederhana yang menyatakan izin dan sumber daya yang diminta. Cakupan terkenal adalah cakupan Microsoft Graph. Anda juga dapat mengakses sumber daya v1.0 menggunakan MSAL.NET.
Kelas core ADAL.NET menggunakan AuthenticationContext sebagai representasi koneksi Anda ke Layanan Token Keamanan (STS) atau server otorisasi, melalui Otoritas. MSAL.NET dirancang di sekitar aplikasi klien. Ini menentukan antarmuka IPublicClientApplication untuk aplikasi klien publik dan IConfidentialClientApplication untuk aplikasi klien rahasia, serta antarmuka dasar IClientApplicationBase untuk kontrak umum untuk kedua jenis aplikasi.
Akuisisi token Di klien publik, ADAL menggunakan AcquireTokenAsync dan AcquireTokenSilentAsync untuk panggilan autentikasi. Di klien publik, MSAL menggunakan AcquireTokenInteractive dan AcquireTokenSilent untuk panggilan autentikasi yang sama. Parameternya berbeda dengan ADAL.

Dalam aplikasi klien Rahasia, ada metode akuisisi token dengan nama eksplisit bergantung pada skenario. Perbedaan lainnya adalah, di MSAL.NET, Anda tidak lagi harus memasukkan ClientID aplikasi Anda di setiap panggilan AcquireTokenXX. ClientID diatur hanya sekali saat membangun IPublicClientApplication atau IConfidentialClientApplication.
IAccount dan IUser ADAL menentukan gagasan pengguna melalui antarmuka IUser. Namun, pengguna adalah manusia atau agen perangkat lunak. Dengan demikian, pengguna dapat memiliki satu atau beberapa akun di platform identitas Microsoft (beberapa akun Azure AD, Azure AD B2C, akun pribadi Microsoft). Pengguna juga dapat bertanggung jawab atas satu atau lebih akun platform identitas Microsoft. MSAL.NET menentukan konsep akun (melalui antarmuka IACcount). Antarmuka IACcount mewakili informasi tentang satu akun. Pengguna dapat memiliki beberapa akun di penyewa yang berbeda. MSAL.NET menyediakan informasi yang lebih baik dalam skenario tamu, karena informasi akun beranda disediakan. Anda dapat membaca selengkapnya tentang perbedaan antara IUser dan IAccount.
Persistensi cache ADAL.NET memungkinkan Anda memperluas kelas TokenCache untuk mengimplementasikan fungsi persistensi yang diinginkan pada platform tanpa penyimpanan yang aman (.NET Framework dan .NET core) menggunakan metode BeforeAccess, dan BeforeWrite. Untuk detailnya, lihat serialisasi cache token di ADAL.NET. MSAL.NET membuat cache token kelas tertutup, yang menghilangkan kemampuan untuk memperluasnya. Dengan demikian, implementasi persistensi cache token Anda harus dalam bentuk kelas pembantu yang berinteraksi dengan cache token yang disegel. Interaksi ini dijelaskan dalam artikel serialisasi cache token di MSAL.NET. Serialisasi untuk aplikasi klien publik (Lihat cache token untuk aplikasi klien publik), berbeda dengan serial untuk aplikasi klien rahasia (Lihat token untuk aplikasi web atau API web).
Otoritas umum ADAL menggunakan Azure AD v1.0. https://login.microsoftonline.com/common otoritas di Azure AD v1.0 (yang digunakan ADAL) memungkinkan pengguna untuk masuk menggunakan akun organisasi AAD (kantor atau sekolah). Azure AD v1.0 tidak mengizinkan masuk dengan akun pribadi Microsoft. Untuk informasi selengkapnya, lihat validasi otoritas di ADAL.NET. MSAL menggunakan Azure AD v2.0. https://login.microsoftonline.com/common otoritas di Azure AD v2.0 (yang digunakan MSAL) memungkinkan pengguna masuk dengan akun organisasi AAD (kantor atau sekolah) atau dengan akun pribadi Microsoft. Untuk membatasi masuk hanya menggunakan akun organisasi (akun kantor atau sekolah) di MSAL, Anda harus menggunakan titik akhir https://login.microsoftonline.com/organizations. Untuk detailnya, lihat parameter authority di aplikasi klien publik.

Pemberian yang didukung

Di bawah ini adalah ringkasan yang membandingkan pemberian yang didukung MSAL.NET dan ADAL.NET untuk aplikasi klien publik dan rahasia.

Aplikasi klien publik

Gambar berikut meringkas beberapa perbedaan antara ADAL.NET dan MSAL.NET untuk aplikasi klien publik.

Screenshot showing some of the differences between ADAL.NET and MSAL.NET for a public client application.

Berikut adalah pemberian yang didukung di ADAL.NET dan MSAL.NET untuk aplikasi Desktop dan Seluler.

Pemberian MSAL.NET ADAL.NET
Interaktif Memperoleh token secara interaktif di MSAL.NET Auth Interaktif
Autentikasi Windows yang Terintegrasi Autentikasi Windows terintegrasi Otentikasi terpadu pada Windows (Kerberos)
Nama Pengguna / Kata Sandi Autentikasi nama pengguna-kata sandi Memperoleh token dengan nama pengguna dan kata sandi
Aliran kode perangkat Aliran kode perangkat Profil perangkat untuk perangkat tanpa browser web

Aplikasi klien rahasia

Gambar berikut meringkas beberapa perbedaan antara ADAL.NET dan MSAL.NET untuk aplikasi klien rahasia.

Screenshot showing some of the differences between ADAL.NET and MSAL.NET for a confidential client application.

Berikut adalah pemberian yang didukung di ADAL.NET, MSAL.NET, dan Microsoft.Identity.Web untuk aplikasi web, API web, dan aplikasi daemon.

Jenis Aplikasi Pemberian MSAL.NET ADAL.NET
Aplikasi web, API web, daemon Kredensial Klien Alur kredensial klien di MSAL.NET Alur kredensial klien di ADAL.NET
API Web Atas nama Atas nama di MSAL.NET Panggilan di antara layanan atas nama pengguna dengan ADAL.NET
Aplikasi web Kode Auth Memperoleh token dengan kode otorisasi pada aplikasi web dengan MSAL.NET Memperoleh token dengan kode otorisasi pada aplikasi web dengan ADAL.NET

Bermigrasi dari ADAL 2.x dengan token refresh

Di ADAL.NET v2. X, token refresh diekspos yang memungkinkan Anda mengembangkan solusi seputar penggunaan token ini dengan men-cache token dan menggunakan metode AcquireTokenByRefreshToken yang disediakan oleh ADAL 2.x.

Beberapa solusi tersebut digunakan dalam skenario seperti:

  • Layanan jangka panjang yang melakukan tindakan termasuk me-refresh dasbor untuk pengguna saat pengguna tidak lagi tersambung/masuk ke aplikasi.
  • Skenario WebFarm untuk memungkinkan klien membawa token refresh ke layanan web (penembolokan dilakukan di sisi klien, cookie terenkripsi, dan bukan sisi server).

MSAL.NET tidak mengekspos token refresh untuk alasan keamanan. MSAL menangani token yang me-refresh untuk Anda.

Untungnya, MSAL.NET memiliki API yang memungkinkan Anda untuk memigrasikan token refresh sebelumnya (diperoleh dengan ADAL) ke dalam IConfidentialClientApplication:

/// <summary>
/// Acquires an access token from an existing refresh token and stores it and the refresh token into
/// the application user token cache, where it will be available for further AcquireTokenSilent calls.
/// This method can be used in migration to MSAL from ADAL v2 and in various integration
/// scenarios where you have a RefreshToken available.
/// (see https://aka.ms/msal-net-migration-adal2-msal2)
/// </summary>
/// <param name="scopes">Scope to request from the token endpoint.
/// Setting this to null or empty will request an access token, refresh token and ID token with default scopes</param>
/// <param name="refreshToken">The refresh token from ADAL 2.x</param>
IByRefreshToken.AcquireTokenByRefreshToken(IEnumerable<string> scopes, string refreshToken);

Dengan metode ini, Anda dapat memberikan token refresh yang digunakan sebelumnya bersama dengan cakupan (sumber daya) apa pun yang Anda inginkan. Token refresh akan ditukar dengan yang baru dan di-cache ke aplikasi Anda.

Karena metode ini ditujukan untuk skenario yang tidak umum, metode ini tidak mudah diakses dengan IConfidentialClientApplication tanpa terlebih dahulu mentransmisikannya ke IByRefreshToken.

Cuplikan kode di bawah ini menunjukkan beberapa kode migrasi dalam aplikasi klien rahasia.

TokenCache userCache = GetTokenCacheForSignedInUser();
string rt = GetCachedRefreshTokenForSignedInUser();

IConfidentialClientApplication app;
app = ConfidentialClientApplicationBuilder.Create(clientId)
 .WithAuthority(Authority)
 .WithRedirectUri(RedirectUri)
 .WithClientSecret(ClientSecret)
 .Build();
IByRefreshToken appRt = app as IByRefreshToken;

AuthenticationResult result = await appRt.AcquireTokenByRefreshToken(null, rt)
                                         .ExecuteAsync()
                                         .ConfigureAwait(false);

GetCachedRefreshTokenForSignedInUser mengambil token refresh yang disimpan di beberapa penyimpanan oleh versi aplikasi sebelumnya yang digunakan untuk menggunakan ADAL 2.x. GetTokenCacheForSignedInUser mendeserialisasi cache untuk pengguna yang masuk (karena aplikasi klien rahasia harus memiliki satu cache per pengguna).

Token akses dan token ID dikembalikan dalam nilai AuthenticationResult sementara token refresh baru disimpan dalam cache. Anda juga dapat menggunakan metode ini untuk berbagai skenario integrasi yang Anda memiliki token refresh yang tersedia.

Token v1.0 dan v2.0

Ada dua versi token: token v1.0 dan token v2.0. Titik akhir v1.0 (digunakan oleh ADAL) mengeluarkan token ID v1.0 sedangkan titik akhir v2.0 (digunakan oleh MSAL) mengeluarkan token ID v2.0. Namun, kedua titik akhir mengeluarkan token akses dari versi token yang diterima oleh API web. Properti manifes aplikasi API web memungkinkan pengembang untuk memilih versi token yang diterima. Lihat accessTokenAcceptedVersion di referensi dokumentasi Manifes aplikasi.

Untuk informasi selengkapnya tentang token akses v1.0 dan v2.0, lihat Token akses Azure Active Directory.

Pengecualian

Interaksi memerlukan pengecualian

Dengan menggunakan MSAL.NET, Anda menangkap MsalUiRequiredException seperti yang dijelaskan di AcquireTokenSilent.

catch(MsalUiRequiredException exception)
{
 try {"try to authenticate interactively"}
}

Untuk detailnya, lihat Menangani kesalahan dan pengecualian di MSAL.NET

ADAL.NET memiliki pengecualian yang kurang eksplisit. Misalnya, ketika autentikasi diam gagal di ADAL, prosedurnya adalah menangkap pengecualian dan mencari kode galat user_interaction_required:

catch(AdalException exception)
{
 if (exception.ErrorCode == "user_interaction_required")
 {
  try
  {“try to authenticate interactively”}}
 }
}

Untuk detailnya, lihat pola yang disarankan untuk memperoleh token di aplikasi klien publik dengan ADAL.NET.

Perilaku permintaan

Meminta perilaku di MSAL.NET setara dengan meminta perilaku di ADAL.NET:

ADAL.NET MSAL.NET Deskripsi
PromptBehavior.Auto NoPrompt Azure Active Directory memilih perilaku terbaik (memasukkan pengguna secara diam-diam jika mereka masuk hanya dengan satu akun, atau menampilkan pemilih akun jika mereka masuk dengan beberapa akun).
PromptBehavior.Always ForceLogin Atur ulang kotak masuk dan paksa pengguna untuk memasukkan kembali kredensial mereka.
PromptBehavior.RefreshSession Consent Paksa pengguna untuk menyetujui lagi semua izin.
PromptBehavior.Never Never Jangan gunakan; sebagai gantinya, gunakan pola yang disarankan untuk aplikasi klien publik.
PromptBehavior.SelectAccount SelectAccount Tampilkan pemilih akun dan paksa pengguna untuk memilih akun.

Menangani pengecualian tantangan klaim

Saat memperoleh token, Azure AD melemparkan pengecualian jika sumber daya memerlukan lebih banyak klaim dari pengguna (misalnya autentikasi dua faktor).

Di MSAL.NET, pengecualian tantangan klaim ditangani dengan cara berikut:

  • Claims ditampilkan di MsalServiceException.
  • Ada metode .WithClaim(claims) yang dapat diterapkan ke penyusun AcquireTokenXXX.

Untuk detailnya, lihat Menangani MsalUiRequiredException.

Di ADAL.NET, pengecualian tantangan klaim ditangani dengan cara berikut:

  • AdalClaimChallengeException adalah pengecualian (berasal dari AdalServiceException). Anggota Claims berisi beberapa fragmen JSON dengan klaim, yang diharapkan.
  • Aplikasi klien publik yang menerima pengecualian ini perlu memanggil pengambilalihan AcquireTokenInteractive yang memiliki parameter klaim. Pengambilalihan AcquireTokenInteractive ini bahkan tidak mencoba menekan cache karena tidak perlu. Alasannya adalah token dalam cache tidak memiliki klaim yang tepat (jika tidak, AdalClaimChallengeException tidak akan dilemparkan). Dengan demikian, tidak perlu melihat cache. ClaimChallengeException dapat diterima dalam WebAPI yang melakukan OBO, tetapi AcquireTokenInteractive perlu dipanggil dalam aplikasi klien publik yang memanggil API web ini.

Untuk detailnya, termasuk contoh, lihat menangani AdalClaimChallengeException.

Cakupan

ADAL menggunakan konsep sumber daya dengan string resourceId, MSAL.NET, bagaimanapun, menggunakan cakupan. Logika yang digunakan oleh Azure AD adalah sebagai berikut:

  • Untuk titik akhir ADAL (v1.0) dengan token akses v1.0 (satu-satunya kemungkinan), aud=resource.
  • Untuk MSAL (titik akhir v2.0) yang meminta token akses untuk sumber daya yang menerima token v2.0, aud=resource.AppId.
  • Untuk MSAL (titik akhir v2.0) yang meminta token akses untuk sumber daya yang menerima token akses v1.0, Azure AD mengurai audiens yang diinginkan dari cakupan yang diminta. Ini dilakukan dengan mengambil semuanya sebelum garis miring terakhir dan menggunakannya sebagai pengenal sumber daya. Dengan demikian, jika https://database.windows.net mengharapkan audiens https://database.windows.net/, Anda harus meminta cakupan https://database.windows.net//.default (perhatikan garis miring ganda sebelum ./default). Hal ini diilustrasikan oleh contoh 1 dan 2 di bawah ini.

Contoh 1

Jika Anda ingin memperoleh token untuk aplikasi yang menerima token v1.0 (misalnya Microsoft Graph API, yaitu https://graph.microsoft.com), Anda harus membuat scopes dengan menggabungkan pengenal sumber daya yang diinginkan dengan izin OAuth2 yang diinginkan untuk sumber daya tersebut.

Misalnya, untuk mengakses nama pengguna melalui API web v1.0 yang URI ID Aplikasinya adalah ResourceId, Anda ingin menggunakan:

var scopes = new [] { ResourceId+"/user_impersonation" };

Jika Anda ingin membaca dan menulis dengan MSAL.NET Azure Active Directory menggunakan Microsoft Graph API (https://graph.microsoft.com/), Anda akan membuat daftar cakupan seperti dalam cuplikan kode di bawah ini:

string ResourceId = "https://graph.microsoft.com/"; 
string[] scopes = { ResourceId + "Directory.Read", ResourceId + "Directory.Write" }

Contoh 2

Jika resourceId diakhiri dengan '/', Anda harus memiliki '/' ganda saat menulis nilai cakupan. Misalnya, jika Anda ingin menulis cakupan yang terkait dengan Azure Resource Manager API (https://management.core.windows.net/), minta cakupan berikut (perhatikan dua garis miring).

var resource = "https://management.core.windows.net/"
var scopes = new[] {"https://management.core.windows.net//user_impersonation"};
var result = await app.AcquireTokenInteractive(scopes).ExecuteAsync();

// then call the API: https://management.azure.com/subscriptions?api-version=2016-09-01

Ini karena Resource Manager API mengharapkan garis miring dalam klaim audiensnya (aud), lalu ada garis miring untuk memisahkan nama API dari cakupan.

Jika Anda ingin memperoleh token untuk semua cakupan statis aplikasi v1.0, Anda akan membuat daftar cakupan seperti yang ditunjukkan dalam cuplikan kode di bawah ini:

ResourceId = "someAppIDURI";
var scopes = new [] { ResourceId+"/.default" };

Untuk aliran info masuk klien, cakupan yang akan diteruskan juga adalah /.default. Cakupan ini memberi tahu Microsoft Azure Active Directory: "semua izin tingkat aplikasi yang telah disetujui admin dalam pendaftaran aplikasi.

Langkah berikutnya

Memigrasikan aplikasi Anda dari ADAL ke MSALMemigrasikan aplikasi klien rahasia ADAL.NET Anda untuk menggunakan MSAL.NET