Różnice między aplikacjami ADAL.NET i MSAL.NET

Migrowanie aplikacji z używania biblioteki ADAL do korzystania z biblioteki MSAL zapewnia korzyści związane z zabezpieczeniami i odpornością. W tym artykule opisano różnice między MSAL.NET a biblioteką ADAL.NET. Wszystkie nowe aplikacje powinny używać MSAL.NET i Platforma tożsamości Microsoft, czyli najnowszej generacji bibliotek uwierzytelniania Microsoft. Korzystając z MSAL.NET, uzyskujesz tokeny dla użytkowników logujący się do aplikacji przy użyciu Microsoft Entra ID (kont służbowych), kont Microsoft (osobistych) (MSA) lub Azure AD B2C. Jeśli masz istniejącą aplikację korzystającą z biblioteki ADAL.NET zmigruj ją do MSAL.NET.

Nadal musisz używać biblioteki ADAL.NET jeśli aplikacja musi logować użytkowników z wcześniejszymi wersjami Active Directory Federation Services (ADFS). Aby uzyskać więcej informacji, zobacz Obsługa usług AD FS.

Wymagania wstępne

Zapoznaj się z omówieniem biblioteki MSAL , aby dowiedzieć się więcej na temat biblioteki MSAL.

Differences

Obsługiwane dotacje

Poniżej znajduje się podsumowanie porównujące MSAL.NET i bibliotekę ADAL.NET obsługiwane dotacje zarówno dla publicznych, jak i poufnych aplikacji klienckich.

Publiczne aplikacje klienckie

Na poniższej ilustracji przedstawiono podsumowanie niektórych różnic między biblioteką ADAL.NET a MSAL.NET dla publicznej aplikacji klienckiej.

Poniżej przedstawiono dotacje obsługiwane w bibliotekach ADAL.NET i MSAL.NET dla aplikacji klasycznych i mobilnych.

Poufne aplikacje klienckie

Na poniższej ilustracji przedstawiono podsumowanie niektórych różnic między biblioteką ADAL.NET a MSAL.NET dla poufnej aplikacji klienckiej.

Oto granty obsługiwane w bibliotekach ADAL.NET, MSAL.NET i Microsoft. Identity.Web dla aplikacji internetowych, internetowych interfejsów API i aplikacji demona.

Migrowanie z biblioteki ADAL 2.x z tokenami odświeżania

W biblioteki ADAL.NET v2. X, tokeny odświeżania zostały ujawnione, umożliwiając opracowywanie rozwiązań dotyczących korzystania z tych tokenów przez buforowanie ich i używanie AcquireTokenByRefreshToken metod dostarczonych przez bibliotekę ADAL 2.x.

Niektóre z tych rozwiązań były używane w scenariuszach, takich jak:

• Długotrwałe usługi, które wykonują akcje, w tym odświeżanie pulpitów nawigacyjnych dla użytkowników, gdy użytkownicy nie są już połączeni/ zalogowani do aplikacji.
• Scenariusze WebFarm umożliwiające klientowi przełączenie tokenu odświeżania do usługi internetowej (buforowanie odbywa się po stronie klienta, zaszyfrowany plik cookie, a nie po stronie serwera).

MSAL.NET nie uwidacznia tokenów odświeżania ze względów bezpieczeństwa. Biblioteka MSAL obsługuje odświeżanie tokenów.

Na szczęście MSAL.NET ma interfejs API, który umożliwia migrację poprzednich tokenów odświeżania (uzyskanych za pomocą biblioteki ADAL) do elementu 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);

Ta metoda umożliwia podanie wcześniej używanego tokenu odświeżania wraz z dowolnymi zakresami (zasobami). Token odświeżania zostanie zamieniony na nowy i zapisany w pamięci podręcznej do aplikacji.

Ponieważ ta metoda jest przeznaczona dla scenariuszy, które nie są typowe, nie jest łatwo dostępne bez uprzedniego IConfidentialClientApplication rzutowania go do IByRefreshTokenelementu .

Poniższy fragment kodu przedstawia kod migracji w poufnej aplikacji klienckiej.

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 Pobiera token odświeżania przechowywany w magazynie przez poprzednią wersję aplikacji, która korzystała z biblioteki ADAL 2.x. GetTokenCacheForSignedInUser deserializuje pamięć podręczną zalogowanego użytkownika (ponieważ poufne aplikacje klienckie powinny mieć jedną pamięć podręczną na użytkownika).

Token dostępu i token identyfikatora są zwracane w AuthenticationResult wartości, gdy nowy token odświeżania jest przechowywany w pamięci podręcznej. Możesz również użyć tej metody w różnych scenariuszach integracji, w których dostępny jest token odświeżania.

Tokeny w wersji 1.0 i 2.0

Istnieją dwie wersje tokenów: tokeny w wersji 1.0 i tokeny w wersji 2.0. Punkt końcowy w wersji 1.0 (używany przez bibliotekę ADAL) emituje tokeny identyfikatorów w wersji 1.0, podczas gdy punkt końcowy w wersji 2.0 (używany przez bibliotekę MSAL) emituje tokeny identyfikatorów w wersji 2.0. Jednak oba punkty końcowe emitują tokeny dostępu wersji tokenu akceptowanego przez internetowy interfejs API. Właściwość manifestu aplikacji internetowego interfejsu API umożliwia deweloperom wybranie, która wersja tokenu jest akceptowana. Zobacz accessTokenAcceptedVersion dokumentację referencyjną manifestu aplikacji .

Aby uzyskać więcej informacji na temat tokenów dostępu w wersji 1.0 i 2.0, zobacz Microsoft Entra tokeny dostępu.

Exceptions

Wymagane wyjątki interakcji

Używanie MSAL.NET przechwytuje MsalUiRequiredException się zgodnie z opisem w artykule AcquireTokenSilent

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

Aby uzyskać szczegółowe informacje, zobacz Obsługa błędów i wyjątków w MSAL.NET

Biblioteka ADAL.NET miała mniej jawne wyjątki. Na przykład gdy uwierzytelnianie dyskretne nie powiodło się w usłudze ADAL, procedura miała na celu przechwycenie wyjątku i wyszukanie kodu błędu user_interaction_required :

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

Aby uzyskać szczegółowe informacje, zobacz zalecany wzorzec uzyskiwania tokenu w publicznych aplikacjach klienckich z biblioteką ADAL.NET.

Pilne działanie

Zachowanie monitu w MSAL.NET jest równoważne zachowaniu monitu w biblioteki ADAL.NET:

Obsługa wyjątków żądań oświadczeń

Czasami podczas uzyskiwania tokenu Microsoft Entra ID zgłasza wyjątek w przypadku, gdy zasób wymaga większej liczby oświadczeń od użytkownika (na przykład uwierzytelniania dwuskładnikowego).

W MSAL.NET wyjątki dotyczące żądań oświadczeń są obsługiwane w następujący sposób:

• Są Claims one wyświetlane w obiekcie MsalServiceException.
• WithClaims(String) Istnieje metoda, która może być stosowana do AcquireTokenXXX konstruktorów.

Aby uzyskać szczegółowe informacje, zobacz Handling MsalUiRequiredException (Obsługa wyjątku MsalUiRequiredException).

W usłudze ADAL.NET wyjątki dotyczące żądań zostały obsłużone w następujący sposób:

• AdalClaimChallengeException jest wyjątkiem (wyprowadzanym z AdalServiceExceptionelementu ). Element Claims członkowski zawiera fragment kodu JSON z oświadczeniami, które są oczekiwane.
• Publiczna aplikacja kliencka, która otrzymuje ten wyjątek, musi wywołać AcquireTokenInteractive przesłoń o parametrze oświadczeń. To zastąpienie AcquireTokenInteractive nie powoduje nawet próby trafienia w pamięć podręczną, ponieważ nie jest to konieczne. Przyczyną jest to, że token w pamięci podręcznej nie ma odpowiednich oświadczeń (w przeciwnym razie AdalClaimChallengeException nie zostałby zgłoszony). W związku z tym nie ma potrzeby przyjrzenia się pamięci podręcznej. Element ClaimChallengeException można odebrać w interfejsie WebAPI wykonującym funkcję OBO, ale AcquireTokenInteractive należy go wywołać w publicznej aplikacji klienckiej wywołującej ten internetowy interfejs API.

Aby uzyskać szczegółowe informacje, w tym przykłady, zobacz obsługa wyjątku AdalClaimChallengeException.

Scopes

Biblioteka ADAL używa koncepcji zasobów z ciągiemresourceId, MSAL.NET jednak używa zakresów. Logika używana przez Microsoft Entra ID jest następująca:

• W przypadku punktu końcowego biblioteki ADAL (wersja 1.0) z tokenem dostępu w wersji 1.0 (jedynym możliwym) aud=resourcejest .
• W przypadku punktu końcowego biblioteki MSAL (wersja 2.0) z pytaniem o token dostępu dla zasobu akceptującego tokeny w wersji 2.0, aud=resource.AppId.
• W przypadku punktu końcowego biblioteki MSAL (wersja 2.0) z pytaniem o token dostępu dla zasobu akceptującego token dostępu w wersji 1.0 Microsoft Entra ID analizuje żądanych odbiorców z żądanego zakresu. Jest to wykonywane przez pobranie wszystkiego przed ostatnim ukośnikiem i użycie go jako identyfikatora zasobu. W związku z tym, jeśli https://database.windows.net oczekuje się grupy odbiorców https://database.windows.net/, musisz zażądać zakresu https://database.windows.net//.default (zwróć uwagę na podwójny ukośnik przed znakiem ./default). Jest to zilustrowane przykładami 1 i 2 poniżej.

Przykład 1

Jeśli chcesz uzyskać tokeny dla aplikacji akceptującej tokeny w wersji 1.0 (na przykład microsoft interfejs Graph API, czyli https://graph.microsoft.com), należy utworzyć przez scopes połączenie żądanego identyfikatora zasobu z żądanym uprawnieniem OAuth2 dla tego zasobu.

Aby na przykład uzyskać dostęp do nazwy użytkownika za pośrednictwem internetowego interfejsu API w wersji 1.0, którego identyfikator URI identyfikatora aplikacji to ResourceId, należy użyć:

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

Jeśli chcesz czytać i zapisywać przy użyciu MSAL.NET Microsoft Entra ID przy użyciu interfejs Graph API (https://graph.microsoft.com/), utwórz listę zakresów, takich jak w poniższym fragmencie kodu:

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

Przykład 2

Jeśli identyfikator resourceId kończy się znakiem "/", podczas zapisywania wartości zakresu musisz mieć dwukrotnie wartość "/". Jeśli na przykład chcesz napisać zakres odpowiadający interfejsowi API Azure Resource Manager (), zażądaj następującego zakresu (https://management.core.windows.net/zwróć uwagę na dwa ukośniki).

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

Dzieje się tak, ponieważ interfejs API Resource Manager oczekuje ukośnika w oświadczeniu odbiorców (aud), a następnie ukośnik oddziela nazwę interfejsu API od zakresu.

Jeśli chcesz uzyskać token dla wszystkich zakresów statycznych aplikacji w wersji 1.0, utwórz listę zakresów, jak pokazano w poniższym fragmencie kodu:

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

W przypadku przepływu poświadczeń klienta zakres do przekazania będzie również miał wartość /.default. Ten zakres informuje o Microsoft Entra ID: "wszystkie uprawnienia na poziomie aplikacji, na które administrator wyraził zgodę w rejestracji aplikacji.

Następne kroki

Migrowanie aplikacji z biblioteki ADAL dobiblioteki MSAL Migrate your ADAL.NET confidential client apps to use MSAL.NET