Diferenças entre as aplicações ADAL.NET e MSAL.NET

Migrar as suas aplicações de ADAL para MSAL traz benefícios de segurança e resiliência. Este artigo descreve as diferenças entre MSAL.NET e ADAL.NET. Todas as novas aplicações devem utilizar o MSAL.NET e a plataforma de identidades da Microsoft, que é a geração mais recente de Bibliotecas de Autenticação Microsoft. Usando o MSAL.NET, adquire tokens para os utilizadores que iniciam sessão na sua aplicação com Microsoft Entra ID (contas de trabalho e escola), contas Microsoft (pessoais) (MSA) ou Azure AD B2C. Se tiver uma aplicação existente que está a usar ADAL.NET, migre-a para o MSAL.NET.

Ainda precisa de usar ADAL.NET se a sua aplicação precisar de iniciar sessão com utilizadores com versões anteriores do Serviços de Federação do Active Directory (AD FS) (ADFS). Para mais informações, consulte o apoio ADFS.

Pré-requisitos

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

Diferenças

Subsídios apoiados

Segue-se um resumo que compara subsídios apoiados pelo MSAL.NET e ADAL.NET para candidaturas públicas e confidenciais de clientes.

Aplicações para clientes públicos

A imagem seguinte resume algumas das diferenças entre ADAL.NET e MSAL.NET para uma aplicação cliente pública.

Aqui estão os subsídios apoiados no ADAL.NET e MSAL.NET para aplicações de desktop e móveis.

Aplicações confidenciais para clientes

A imagem seguinte resume algumas das diferenças entre ADAL.NET e MSAL.NET para uma aplicação cliente confidencial.

Aqui estão as bolsas apoiadas no ADAL.NET, MSAL.NET e Microsoft. Identity.Web para aplicações web, APIs web e aplicações daemon.

Migração do ADAL 2.x com tokens de atualização

No ADAL.NET v2. X, os tokens de refresh foram expostos, permitindo-lhe desenvolver soluções para o uso destes tokens, armazenando-os em cache e utilizando os AcquireTokenByRefreshToken métodos fornecidos pelo ADAL 2.x.

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

• Serviços de longa duração que realizam ações, incluindo a atualização dos painéis de controlo para os utilizadores quando estes já não estão ligados/iniciados sessão na aplicação.
• Cenários WebFarm para permitir que o cliente traga o token de atualização para o serviço web (a cache é feita do lado do cliente, do cookie encriptado e não do lado do servidor).

O MSAL.NET não expõe tokens de atualização por razões de segurança. A MSAL trata de tokens refrescantes para ti.

Felizmente, o MSAL.NET tem uma API que permite migrar os seus tokens de atualização anteriores (adquiridos com ADAL) para o 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 este método, podes fornecer o token de atualização usado anteriormente juntamente com quaisquer escopos (recursos) que queiras. O token de atualização será trocado por um novo e armazenado em cache na sua aplicação.

Como este método é pensado para cenários que não são típicos, não é facilmente acessível com o IConfidentialClientApplication sem primeiro o lançar para IByRefreshToken.

O excerto de código abaixo mostra algum código de migração numa aplicação 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 que estava armazenado em algum armazenamento por uma versão anterior da aplicação que costumava usar ADAL 2.x. GetTokenCacheForSignedInUser desserializa uma cache para o utilizador iniciado sessão (pois as aplicações clientes confidenciais devem ter uma cache por utilizador).

Um token de acesso e um token ID são devolvidos no AuthenticationResult valor enquanto o novo token de atualização é armazenado na cache. Também pode usar este método em vários cenários de integração onde tem um token de atualização disponível.

Tokens v1.0 e v2.0

Existem duas versões de tokens: tokens v1.0 e tokens v2.0. O endpoint v1.0 (usado pela ADAL) emite tokens ID v1.0, enquanto o endpoint v2.0 (usado pela MSAL) emite tokens ID v2.0. No entanto, ambos os endpoints emitem tokens de acesso da versão do token que a API web aceita. Uma propriedade do manifesto da aplicação da API web permite aos programadores escolher qual a versão do token aceite. Consulte accessTokenAcceptedVersion a documentação de referência do manifesto da candidatura .

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

Exceptions

Interação exigia exceções

Usando o MSAL.NET, apanha MsalUiRequiredException conforme descrito no AcquireTokenSilent

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

Para detalhes, veja Lidar com erros e exceções no MSAL.NET

O ADAL.NET tinha exceções menos explícitas. Por exemplo, quando a autenticação silenciosa falhava no ADAL, o procedimento era apanhar 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 mais detalhes, consulte o padrão recomendado para adquirir um token em aplicações clientes públicas com ADAL.NET.

Comportamento rápido

O comportamento dos prompts no MSAL.NET é equivalente ao comportamento dos prompts no ADAL.NET:

Gestão de exceções a contestação de reclamações

Por vezes, ao adquirir um token, o Microsoft Entra ID lança uma exceção caso um recurso exija mais reivindicações do utilizador (por exemplo, autenticação de dois fatores).

No MSAL.NET, as exceções de contestação de reivindicações são tratadas da seguinte forma:

• Os Claims estão à superfície no MsalServiceException.
• Há um WithClaims(String) método que pode aplicar-se aos AcquireTokenXXX construtores.

Para mais detalhes, veja Handling MsalUiRequiredException.

No ADAL.NET, as exceções de contestação de reivindicações eram tratadas da seguinte forma:

• AdalClaimChallengeException é uma exceção (derivando de AdalServiceException). O Claims membro contém algum fragmento JSON com as reivindicações, que são esperadas.
• A aplicação pública do cliente que recebia esta exceção precisava de chamar a AcquireTokenInteractive sobreposição como tendo um parâmetro de reclamações. Este override nem AcquireTokenInteractive sequer tenta aceder à cache porque não é necessário. A razão é que o token na cache não tem as reivindicações corretas (caso contrário AdalClaimChallengeException , não teria sido descartado). Assim, não há necessidade de olhar para a cache. Podem ClaimChallengeException ser recebidos numa WebAPI a fazer OBO, mas AcquireTokenInteractive precisam de ser chamados numa aplicação cliente pública que chama esta API web.

Para detalhes, incluindo exemplos, consulte tratamento AdalClaimChallengeException.

Scopes

O ADAL utiliza o conceito de recursos com resourceId string, enquanto o MSAL.NET, no entanto, usa escopos. A lógica usada pelo Microsoft Entra ID é a seguinte:

• Para o endpoint ADAL (v1.0) com um token de acesso v1.0 (o único possível), aud=resource.
• Para MSAL (endpoint v2.0) que pede um token de acesso para um recurso que aceita tokens v2.0, aud=resource.AppId.
• Para MSAL (endpoint v2.0) que pede um token de acesso para um recurso que aceita um token de acesso v1.0, o Microsoft Entra ID analisa o público desejado a partir do âmbito solicitado. Isto faz-se pegando em tudo o que há antes da última barra e usando-o como identificador de recurso. Assim, se https://database.windows.net esperar uma audiência de https://database.windows.net/, terá de pedir um âmbito de https://database.windows.net//.default (repare na barra dupla antes de ./default). Isto é ilustrado pelos exemplos 1 e 2 abaixo.

Exemplo 1

Se quiser adquirir tokens para uma aplicação que aceite tokens v1.0 (por exemplo, a Microsoft Graph API, que é https://graph.microsoft.com), terá de criar scopes concatenando um identificador de recurso desejado com uma permissão OAuth2 desejada para esse recurso.

Por exemplo, para aceder ao nome do utilizador através de uma API web v1.0 cujo URI de ID de Aplicação é ResourceId, deveria usar:

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

Se quiseres ler e escrever com MSAL.NET Microsoft Entra ID usando o Microsoft Graph API (),https://graph.microsoft.com/ deves criar uma lista de escopos como no excerto de código abaixo:

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

Exemplo 2

Se o resourceId terminar com '/', vais precisar de ter um duplo '/' ao escrever o valor do escopo. Por exemplo, se quiser escrever o âmbito correspondente à API do Azure Resource Manager (https://management.core.windows.net/), peça o seguinte âmbito (note 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

Isto acontece porque a API do Resource Manager espera uma barra na sua reivindicação de audiência (aud), e depois há uma barra para separar o nome da API do âmbito.

Se quiser adquirir um token para todos os escopos estáticos de uma aplicação v1.0, deve criar a sua lista de escopos conforme mostrado no excerto de código abaixo:

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

Para um fluxo de credenciais de cliente, o âmbito a passar também seria /.default. Este âmbito diz ao Microsoft Entra ID: "todas as permissões ao nível da aplicação que o administrador consentiu no registo da aplicação.

Passos seguintes

Migre as suas aplicações de ADAL para MSALMigre as suas aplicações clientes confidenciais ADAL.NET para usar MSAL.NET