Diferenças entre aplicativos ADAL.NET e MSAL.NET

A migração de seus aplicativos do uso da ADAL para o uso da MSAL vem com benefícios de segurança e resiliência. Este artigo descreve as diferenças entre MSAL.NET e a ADAL.NET. Todos os novos aplicativos devem usar MSAL.NET e o plataforma de identidade da Microsoft, que é a última geração de bibliotecas de autenticação Microsoft. Usando MSAL.NET, você adquire tokens para usuários que se conectam ao seu aplicativo com Microsoft Entra ID (contas corporativas e de estudante), contas Microsoft (pessoais) (MSA) ou Azure AD B2C. Se você tiver um aplicativo existente que esteja usando a ADAL.NET, migre-o para MSAL.NET.

Você ainda precisará usar a ADAL.NET se o aplicativo precisar conectar usuários com versões anteriores do Serviços de Federação do Active Directory (AD FS) (ADFS). Para obter mais informações, consulte o suporte do ADFS.

Pré-requisitos

Confira a visão geral da MSAL para saber mais sobre a MSAL.

Diferenças

Concessões com suporte

Veja abaixo um resumo comparando MSAL.NET e a ADAL.NET concessões com suporte para aplicativos cliente públicos e confidenciais.

Aplicativos cliente públicos

A imagem a seguir resume algumas das diferenças entre a ADAL.NET e MSAL.NET para um aplicativo cliente público.

Aqui estão as concessões com suporte na ADAL.NET e MSAL.NET para aplicativos desktop e móveis.

Aplicativos cliente confidenciais

A imagem a seguir resume algumas das diferenças entre a ADAL.NET e MSAL.NET para um aplicativo cliente confidencial.

Aqui estão as concessões com suporte na ADAL.NET, MSAL.NET e Microsoft. Identity.Web para aplicativos Web, APIs Web e aplicativos daemon.

Migrando da ADAL 2.x com tokens de atualização

Na ADAL.NET v2. X, os tokens de atualização foram expostos, permitindo que você desenvolva soluções em torno do uso desses tokens armazenando-os em cache e usando os AcquireTokenByRefreshToken métodos fornecidos pela ADAL 2.x.

Algumas dessas soluções foram usadas em cenários como:

• Serviços de execução longa que executam ações, incluindo a atualização de painéis para os usuários quando os usuários não estão mais conectados/conectados ao aplicativo.
• Cenários de WebFarm para permitir que o cliente traga o token de atualização para o serviço Web (o cache é feito no lado do cliente, cookie criptografado e não no lado do servidor).

MSAL.NET não expõe tokens de atualização por motivos de segurança. A MSAL manipula tokens de atualização para você.

Felizmente, MSAL.NET tem uma API que permite migrar seus tokens de atualização anteriores (adquiridos com a ADAL) para :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);

Com esse método, você pode fornecer o token de atualização usado anteriormente junto com todos os escopos (recursos) desejados. O token de atualização será trocado por um novo e armazenado em cache em seu aplicativo.

Como esse método destina-se a cenários que não são típicos, ele não é facilmente acessível com o IConfidentialClientApplication sem primeiro lanhá-lo para IByRefreshToken.

O snippet de código abaixo mostra algum código de migração em um aplicativo cliente confidencial.

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 recupera o token de atualização armazenado em algum armazenamento por uma versão anterior do aplicativo que costumava usar a ADAL 2.x. GetTokenCacheForSignedInUser desserializa um cache para o usuário conectado (como os aplicativos cliente confidenciais devem ter um cache por usuário).

Um token de acesso e um token de ID são retornados no AuthenticationResult valor enquanto o novo token de atualização é armazenado no cache. Você também pode usar esse método para vários cenários de integração em que você tem um token de atualização disponível.

Tokens v1.0 e v2.0

Há duas versões de tokens: tokens v1.0 e tokens v2.0. O ponto de extremidade v1.0 (usado pela ADAL) emite tokens de ID v1.0 enquanto o ponto de extremidade v2.0 (usado pela MSAL) emite tokens de ID v2.0. No entanto, ambos os pontos de extremidade emitem tokens de acesso da versão do token que a API Web aceita. Uma propriedade do manifesto do aplicativo da API Web permite que os desenvolvedores escolham qual versão do token é aceita. Consulte accessTokenAcceptedVersion a documentação de referência do manifesto do aplicativo .

Para obter mais informações sobre tokens de acesso v1.0 e v2.0, consulte Microsoft Entra tokens de acesso.

Exceptions

Exceções necessárias para interação

Usando MSAL.NET, você captura MsalUiRequiredException conforme descrito em AcquireTokenSilent

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

Para obter detalhes, consulte Manipular erros e exceções no MSAL.NET

A ADAL.NET tinha exceções menos explícitas. Por exemplo, quando a autenticação silenciosa falhou na ADAL, o procedimento foi capturar a exceção e procurar o user_interaction_required código de erro:

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

Para obter detalhes, consulte o padrão recomendado para adquirir um token em aplicativos cliente públicos com a ADAL.NET.

Comportamento da solicitação

O comportamento do prompt no MSAL.NET é equivalente ao comportamento de prompt na ADAL.NET:

Tratamento de exceções de desafio de declaração

Às vezes, ao adquirir um token, Microsoft Entra ID gera uma exceção caso um recurso exija mais declarações do usuário (por exemplo, autenticação de dois fatores).

Em MSAL.NET, as exceções de desafio de declaração são tratadas da seguinte maneira:

• Eles Claims são exibidos no MsalServiceException.
• Há um WithClaims(String) método que pode se aplicar aos AcquireTokenXXX construtores.

Para obter detalhes, consulte Como lidar com MsalUiRequiredException.

Na ADAL.NET, as exceções de desafio de declaração foram tratadas da seguinte maneira:

• AdalClaimChallengeException é uma exceção (derivada de AdalServiceException). O Claims membro contém algum fragmento JSON com as declarações, que são esperadas.
• O aplicativo cliente público que recebe essa exceção precisava chamar a AcquireTokenInteractive substituição com um parâmetro de declarações. Essa substituição AcquireTokenInteractive nem sequer tenta atingir o cache, pois não é necessário. O motivo é que o token no cache não tem as declarações certas (caso contrário, um AdalClaimChallengeException não teria sido lançado). Dessa forma, não é necessário examinar o cache. Pode ClaimChallengeException ser recebido em uma WebAPI fazendo OBO, mas é AcquireTokenInteractive necessário chamar um aplicativo cliente público chamando essa API Web.

Para obter detalhes, incluindo exemplos, consulte como lidar com AdalClaimChallengeException.

Escopos

A ADAL usa o conceito de recursos com resourceId cadeia de caracteres, MSAL.NET, no entanto, usa escopos. A lógica usada por Microsoft Entra ID é a seguinte:

• Para o ponto de extremidade ADAL (v1.0) com um token de acesso v1.0 (o único possível), aud=resource.
• Para MSAL (ponto de extremidade v2.0) solicitando um token de acesso para um recurso que aceita tokens v2.0. aud=resource.AppId
• Para MSAL (ponto de extremidade v2.0) solicitando um token de acesso para um recurso que aceita um token de acesso v1.0, Microsoft Entra ID analisa o público desejado do escopo solicitado. Isso é feito usando tudo antes da última barra e usando-o como o identificador de recurso. Como tal, se https://database.windows.net espera um público-alvo de https://database.windows.net/, você precisará solicitar um escopo de https://database.windows.net//.default (observe a barra dupla antes de ./default). Isso é ilustrado pelos exemplos 1 e 2 abaixo.

Exemplo 1

Se você quiser adquirir tokens para um aplicativo que aceita tokens v1.0 (por exemplo, o Microsoft API do Graph, que é https://graph.microsoft.com), você precisaria criar scopes concatenando um identificador de recurso desejado com uma permissão OAuth2 desejada para esse recurso.

Por exemplo, para acessar o nome do usuário por meio de uma API Web v1.0 cujo URI de ID de Aplicativo é ResourceId, você deseja usar:

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

Se você quiser ler e gravar com MSAL.NET Microsoft Entra ID usando o Microsoft API do Graph (https://graph.microsoft.com/), crie uma lista de escopos, como no snippet de código abaixo:

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

Exemplo 2

Se resourceId terminar com um '/', você precisará ter um '/' duplo ao escrever o valor do escopo. Por exemplo, se você quiser gravar o escopo correspondente à API de Azure Resource Manager (https://management.core.windows.net/), solicite o escopo a seguir (observe as duas barras).

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

Isso ocorre porque a API Resource Manager espera uma barra em sua declaração de audiência (aud) e, em seguida, há uma barra para separar o nome da API do escopo.

Se você quiser adquirir um token para todos os escopos estáticos de um aplicativo v1.0, crie sua lista de escopos, conforme mostrado no snippet de código abaixo:

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

Para um fluxo de credenciais do cliente, o escopo a ser passado também seria /.default. Esse escopo informa para Microsoft Entra ID: "todas as permissões no nível do aplicativo às quais o administrador consentiu no registro do aplicativo.

Próximas Etapas 

Migre seus aplicativos da ADAL para a MSALMigrar sua ADAL.NET aplicativos cliente confidenciais para usar MSAL.NET