Migrer des applications clientes confidentielles d’ADAL.NET vers MSAL.NET

Migrer des applications de démon

Les scénarios démon utilisent le flux d’informations d’identification du client OAuth2.0. On les appelle également appels entre services. Votre application acquiert un jeton pour son propre compte, et non pour le compte d’un utilisateur.

Déterminer si votre code utilise des scénarios démon

Le code ADAL de votre application utilise des scénarios de démon s’il contient un appel à AuthenticationContext.AcquireTokenAsync avec les paramètres suivants :

• Ressource (URI d’ID d’application) en tant que premier paramètre
• IClientAssertionCertificate ou ClientAssertion en tant que deuxième paramètre

AuthenticationContext.AcquireTokenAsync n’a pas de paramètre de type UserAssertion. Si c’est le cas, votre application est une API web et relève du scénario d’API web appelant des API web en aval.

Mettre à jour le code des scénarios de démon

Les étapes suivantes pour mettre à jour le code s’appliquent à tous les scénarios clients confidentiels :

1. Ajoutez l’espace de noms MSAL.NET dans votre code source : using Microsoft.Identity.Client;.
2. Au lieu d’instancier AuthenticationContext, utilisez ConfidentialClientApplicationBuilder.Create pour instancier IConfidentialClientApplication.
3. Au lieu de la resourceId chaîne, MSAL.NET utilise des étendues. Étant donné que les applications qui utilisent ADAL.NET sont pré-autorisées, vous pouvez toujours utiliser les étendues suivantes : new string[] { $"{resourceId}/.default" }.
4. Remplacez l’appel à AuthenticationContext.AcquireTokenAsync par un appel à IConfidentialClientApplication.AcquireTokenXXX, où XXX dépend de votre scénario.

Dans ce cas, remplacez l’appel à AuthenticationContext.AcquireTokenAsync par un appel à IConfidentialClientApplication.AcquireTokenClient.

Voici une comparaison de la bibliothèque ADAL.NET et du code MSAL.NET pour les scénarios de démon :

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;

public partial class AuthWrapper
{
const string ClientId = "Guid (AppID)";
const string authority 
= "https://login.microsoftonline.com/{tenant}";
// App ID URI of web API to call
const string resourceId = "https://target-api.domain.com";
X509Certificate2 certificate = LoadCertificate();



public async Task<AuthenticationResult> GetAuthenticationResult()
{


var authContext = new AuthenticationContext(authority);
var clientAssertionCert = new ClientAssertionCertificate(
ClientId,
certificate);


var authResult = await authContext.AcquireTokenAsync(
resourceId,
clientAssertionCert,
);

return authResult;
}
}

using Microsoft.Identity.Client;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;

public partial class AuthWrapper
{
const string ClientId = "Guid (Application ID)";
const string authority 
= "https://login.microsoftonline.com/{tenant}";
// App ID URI of web API to call
const string resourceId = "https://target-api.domain.com";
X509Certificate2 certificate = LoadCertificate();

IConfidentialClientApplication app;

public async Task<AuthenticationResult> GetAuthenticationResult()
{

var app = ConfidentialClientApplicationBuilder.Create(ClientId)
.WithCertificate(certificate)
.WithAuthority(authority)
.Build();

// Setup token caching https://learn.microsoft.com/azure/active-directory/develop/msal-net-token-cache-serialization?tabs=aspnet
// For example, for an in-memory cache with 1GB limit, use  
app.AddInMemoryTokenCache(services =>
{
// Configure the memory cache options
services.Configure<MemoryCacheOptions>(options =>
{
options.SizeLimit = 1024 * 1024 * 1024; // in bytes (1 GB of memory)
});
}

var authResult = await app.AcquireTokenForClient(
new [] { $"{resourceId}/.default" })
// .WithTenantId(specificTenant)
// See https://aka.ms/msal.net/withTenantId
.ExecuteAsync()
.ConfigureAwait(false);

return authResult;
}
}

Tirer parti de la mise en cache des jetons

Si vous ne configurez pas la mise en cache des jetons, l’émetteur de jeton vous limite, ce qui entraîne des erreurs. Il faut également beaucoup moins d’obtenir un jeton à partir du cache (10-20 ms) que celui d’ESTS (500-30000 ms).

Si vous souhaitez implémenter un cache de jetons distribué, consultez Cache de jetons pour une application web ou une API web (application cliente confidentielle).

En savoir plus sur le scénario démon et la façon dont il est implémenté avec MSAL.NET ou Microsoft. Identity.Web dans les nouvelles applications.

Migrer une API web qui appelle des API web en aval

Les API web qui appellent des API web en aval utilisent le flux on-behalf-of (OBO) OAuth 2.0. L’API web utilise le jeton d’accès récupéré à partir de l’en-tête d’autorisation HTTP et valide ce jeton. Ce jeton est ensuite échangé contre un jeton pour appeler l’API web en aval. Ce jeton est utilisé comme UserAssertion instance dans ADAL.NET et MSAL.NET.

Déterminer si votre code utilise OBO

Le code ADAL de votre application utilise OBO s’il contient un appel à AuthenticationContext.AcquireTokenAsync avec les paramètres suivants :

• Ressource (URI d’ID d’application) en tant que premier paramètre
• IClientAssertionCertificate ou ClientAssertion en tant que deuxième paramètre
• Paramètre de type UserAssertion

Mettre à jour le code à l’aide de OBO

Les étapes suivantes pour mettre à jour le code s’appliquent à tous les scénarios clients confidentiels :

1. Ajoutez l’espace de noms MSAL.NET dans votre code source : using Microsoft.Identity.Client;.
2. Au lieu d’instancier AuthenticationContext, utilisez ConfidentialClientApplicationBuilder.Create pour instancier IConfidentialClientApplication.
3. Au lieu de la resourceId chaîne, MSAL.NET utilise des étendues. Étant donné que les applications qui utilisent ADAL.NET sont pré-autorisées, vous pouvez toujours utiliser les étendues suivantes : new string[] { $"{resourceId}/.default" }.
4. Remplacez l’appel à AuthenticationContext.AcquireTokenAsync par un appel à IConfidentialClientApplication.AcquireTokenXXX, où XXX dépend de votre scénario.

Dans ce cas, nous remplaçons l’appel à AuthenticationContext.AcquireTokenAsync par un appel à IConfidentialClientApplication.AcquireTokenOnBehalfOf.

Voici une comparaison de l'exemple de code OBO pour ADAL.NET et MSAL.NET :

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;

public partial class AuthWrapper
{
const string ClientId = "Guid (AppID)";
const string authority 
= "https://login.microsoftonline.com/common";
X509Certificate2 certificate = LoadCertificate();



public async Task<AuthenticationResult> GetAuthenticationResult(
string resourceId, 
string tokenUsedToCallTheWebApi)
{


var authContext = new AuthenticationContext(authority);
var clientAssertionCert = new ClientAssertionCertificate(
ClientId,
certificate);



var userAssertion = new UserAssertion(tokenUsedToCallTheWebApi);

var authResult = await authContext.AcquireTokenAsync(
resourceId,
clientAssertionCert,
userAssertion,
);

return authResult;
}
}

using Microsoft.Identity.Client;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;

public partial class AuthWrapper
{
const string ClientId = "Guid (Application ID)";
const string authority 
= "https://login.microsoftonline.com/common";
X509Certificate2 certificate = LoadCertificate();

IConfidentialClientApplication app;

public async Task<AuthenticationResult> GetAuthenticationResult(
string resourceId,
string tokenUsedToCallTheWebApi)
{

var app = ConfidentialClientApplicationBuilder.Create(ClientId)
.WithCertificate(certificate)
.WithAuthority(authority)
.Build();

// Setup token caching https://learn.microsoft.com/azure/active-directory/develop/msal-net-token-cache-serialization?tabs=aspnet
// For example, for an in-memory cache with 1GB limit. For OBO, it is recommended to use a distributed cache like Redis.
app.AddInMemoryTokenCache(services =>
{
// Configure the memory cache options
services.Configure<MemoryCacheOptions>(options =>
{
options.SizeLimit = 1024 * 1024 * 1024; // in bytes (1 GB of memory)
});
}

var userAssertion = new UserAssertion(tokenUsedToCallTheWebApi);

var authResult = await app.AcquireTokenOnBehalfOf(
new string[] { $"{resourceId}/.default" },
userAssertion)
// .WithTenantId(specificTenant) 
// See https://aka.ms/msal.net/withTenantId
.ExecuteAsync()
.ConfigureAwait(false);

return authResult;
}
}

Tirer parti de la mise en cache des jetons

Pour la mise en cache des tokens dans les OBO, utilisez un cache distribué de tokens. Pour plus d’informations, consultez Cache de jeton pour une application web ou une API web (application cliente confidentielle).

app.UseInMemoryTokenCaches(); // or a distributed token cache.

En savoir plus sur les API web appelant des API web en aval et comment elles sont implémentées avec MSAL.NET ou Microsoft. Identity.Web dans les nouvelles applications.

Migrer une application web qui appelle des API web

Si votre application utilise ASP.NET Core, nous vous recommandons vivement de mettre à jour Microsoft. Identity.Web, car il traite tout pour vous. Pour une présentation rapide, consultez l’annonce de disponibilité générale de Microsoft.Identity.Web. Pour plus d’informations sur l’utilisation dans une application web, consultez Pourquoi utiliser Microsoft. Identity.Web dans les applications web ?.

Les applications web qui connectent des utilisateurs et appellent des API web pour le compte des utilisateurs utilisent le flux de code d’autorisation OAuth2.0. Typiquement:

1. L’application connecte un utilisateur en exécutant une première étape du flux de code d’autorisation en accédant au point de terminaison d’autorisation de la plateforme d’identités Microsoft. L’utilisateur se connecte et effectue des authentifications multifacteur si nécessaire. En conséquence de cette opération, l’application reçoit le code d’autorisation. La bibliothèque d’authentification n’est pas utilisée à ce stade.
2. L’application exécute la deuxième étape du flux de code d’autorisation. Il utilise le code d’autorisation pour obtenir un jeton d’accès, un jeton d’ID et un jeton d’actualisation. Votre application doit fournir la valeur redirectUri, qui correspond à l’URI auquel le point de terminaison de la plateforme d’identités Microsoft fournit les jetons de sécurité. Une fois que l’application reçoit cet URI, il appelle AcquireTokenByAuthorizationCode généralement ADAL ou MSAL pour échanger le code et obtenir un jeton qui sera stocké dans le cache de jetons.
3. L’application utilise ADAL ou MSAL pour appeler AcquireTokenSilent afin d’obtenir des jetons permettant d’appeler les API web nécessaires depuis les contrôleurs de l’application web.

Déterminer si votre code utilise le flux de code d’authentification

Le code ADAL de votre application utilise le flux de code d’authentification s’il contient un appel à AuthenticationContext.AcquireTokenByAuthorizationCodeAsync.

Mettre à jour le code à l’aide du flux de code d’autorisation

Les étapes suivantes pour mettre à jour le code s’appliquent à tous les scénarios clients confidentiels :

1. Ajoutez l’espace de noms MSAL.NET dans votre code source : using Microsoft.Identity.Client;.
2. Au lieu d’instancier AuthenticationContext, utilisez ConfidentialClientApplicationBuilder.Create pour instancier IConfidentialClientApplication.
3. Au lieu de la resourceId chaîne, MSAL.NET utilise des étendues. Étant donné que les applications qui utilisent ADAL.NET sont pré-autorisées, vous pouvez toujours utiliser les étendues suivantes : new string[] { $"{resourceId}/.default" }.
4. Remplacez l’appel à AuthenticationContext.AcquireTokenAsync par un appel à IConfidentialClientApplication.AcquireTokenXXX, où XXX dépend de votre scénario.

Dans ce cas, remplacez l’appel à AuthenticationContext.AcquireTokenAsync par un appel à IConfidentialClientApplication.AcquireTokenByAuthorizationCode.

Voici une comparaison des exemples de flux de code d'autorisation pour ADAL.NET et MSAL.NET :

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;

public partial class AuthWrapper
{
const string ClientId = "Guid (AppID)";
const string authority 
= "https://login.microsoftonline.com/common";
private Uri redirectUri = new Uri("host/login_oidc");
X509Certificate2 certificate = LoadCertificate();



public async Task<AuthenticationResult> GetAuthenticationResult(
string resourceId,
string authorizationCode)
{


var ac = new AuthenticationContext(authority);
var clientAssertionCert = new ClientAssertionCertificate(
ClientId,
certificate);



var authResult = await ac.AcquireTokenByAuthorizationCodeAsync(
authorizationCode,
redirectUri,
clientAssertionCert,
resourceId,
);
return authResult;
}
}

using Microsoft.Identity.Client;
using Microsoft.Identity.Web;
using System;
using System.Security.Claims;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;

public partial class AuthWrapper
{
const string ClientId = "Guid (Application ID)";
const string authority
= "https://login.microsoftonline.com/{tenant}";
private Uri redirectUri = new Uri("host/login_oidc");
X509Certificate2 certificate = LoadCertificate();

public IConfidentialClientApplication CreateApplication()
{
IConfidentialClientApplication app;

app = ConfidentialClientApplicationBuilder.Create(ClientId)
.WithCertificate(certificate)
.WithAuthority(authority)
.WithRedirectUri(redirectUri.ToString())
.WithLegacyCacheCompatibility(false)
.Build();

// Add a token cache. For details about other serialization
// see https://aka.ms/msal-net-cca-token-cache-serialization
app.AddInMemoryTokenCache();

return app;
}

// Called from 'code received event'.
public async Task<AuthenticationResult> GetAuthenticationResult(
string resourceId,
string authorizationCode)
{
IConfidentialClientApplication app = CreateApplication();

var authResult = await app.AcquireTokenByAuthorizationCode(
new[] { $"{resourceId}/.default" },
authorizationCode)
.ExecuteAsync()
.ConfigureAwait(false);

return authResult;
}
}

L’appel AcquireTokenByAuthorizationCode ajoute un jeton au cache de jetons lorsque le code d’autorisation est reçu. Pour obtenir des jetons supplémentaires pour d’autres ressources ou locataires, utilisez AcquireTokenSilent dans vos contrôleurs.

public partial class AuthWrapper
{
 // Called from controllers
 public async Task<AuthenticationResult> GetAuthenticationResult(
      string resourceId2,
      string authority)
 {
  IConfidentialClientApplication app = CreateApplication();
  AuthenticationResult authResult;

  var scopes = new[] { $"{resourceId2}/.default" };
  var account = await app.GetAccountAsync(ClaimsPrincipal.Current.GetMsalAccountId());

  try
  {
   // try to get an already cached token
   authResult = await app.AcquireTokenSilent(
               scopes,
               account)
                // .WithTenantId(specificTenantId) 
                // See https://aka.ms/msal.net/withTenantId
                .ExecuteAsync().ConfigureAwait(false);
  }
  catch (MsalUiRequiredException)
  {
   // The controller will need to challenge the user
   // including asking for claims={ex.Claims}
   throw;
  }
  return authResult;
 }
}

Tirer parti de la mise en cache des jetons

Étant donné que votre application web utilise AcquireTokenByAuthorizationCode, elle doit utiliser un cache de jetons distribué pour la mise en cache des jetons. Pour plus d’informations, consultez Le cache de jetons pour une application web ou une API web.

app.UseInMemoryTokenCaches(); // or a distributed token cache.

Gestion de MsalUiRequiredException

Lorsque votre contrôleur tente d’acquérir un jeton en mode silencieux pour différentes étendues/ressources, MSAL.NET risque de lever une MsalUiRequiredException, ce qui est normal si l’utilisateur doit se reconnecter ou si l’accès à la ressource nécessite davantage de revendications (en raison d’une stratégie d’accès conditionnel). Pour plus d’informations sur l’atténuation, consultez comment gérer les erreurs et les exceptions dans MSAL.NET.

En savoir plus sur les applications web appelant des API web et comment elles sont implémentées avec MSAL.NET ou Microsoft. Identity.Web dans les nouvelles applications.