Vertrouwelijke clienttoepassingen migreren van ADAL.NET naar MSAL.NET

Daemon-apps migreren

Daemon-scenario's maken gebruik van de OAuth2.0-clientreferentiestroom. Ze worden ook wel service-naar-service-aanroepen genoemd. Uw app verwerft zelf een token, niet namens een gebruiker.

Ontdek of uw code daemon-scenario's gebruikt

De ADAL-code voor uw app maakt gebruik van daemon-scenario's als deze een aanroep bevat AuthenticationContext.AcquireTokenAsync met de volgende parameters:

• Een resource (app-id-URI) als eerste parameter
• IClientAssertionCertificate of ClientAssertion als de tweede parameter

AuthenticationContext.AcquireTokenAsync heeft geen parameter van het type UserAssertion. Als dit het geval is, is uw app een web-API en wordt het scenario voor het aanroepen van downstream-web-API's gebruikt.

De code van daemon-scenario's bijwerken

De volgende stappen voor het bijwerken van code zijn van toepassing op alle vertrouwelijke clientscenario's:

1. Voeg de MSAL.NET naamruimte toe in de broncode: using Microsoft.Identity.Client;.
2. Gebruik ConfidentialClientApplicationBuilder.Create om IConfidentialClientApplication te instantiëren in plaats van AuthenticationContext.
3. In plaats van de tekenreeks resourceId gebruikt MSAL.NET scopes. Omdat toepassingen die ADAL.NET gebruiken vooraf zijn geautoriseerd, kunt u altijd de volgende machtigingen gebruiken: new string[] { $"{resourceId}/.default" }
4. Vervang de aanroep naar AuthenticationContext.AcquireTokenAsync door een aanroep naar IConfidentialClientApplication.AcquireTokenXXX, waarbij XXX afhankelijk is van uw scenario.

Vervang in dit geval de aanroep naar AuthenticationContext.AcquireTokenAsync een aanroep naar IConfidentialClientApplication.AcquireTokenClient.

Hier volgt een vergelijking van ADAL.NET en MSAL.NET code voor daemon-scenario's:

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;
}
}

Profiteer van token-caching

Als u geen tokencaching instelt, wordt u door de tokenverlener beperkt, wat resulteert in fouten. Het kost ook veel minder om een token op te halen uit de cache (10-20 ms) dan van ESTS (500-30000ms).

Als u een gedistribueerde tokencache wilt implementeren, raadpleegt u tokencache voor een web-app of web-API (vertrouwelijke clienttoepassing).

Meer informatie over het daemon-scenario en hoe het wordt geïmplementeerd met MSAL.NET of Microsoft. Identity.Web in nieuwe toepassingen.

Een web-API migreren die downstream-web-API's aanroept

Web-API's die onderliggende web-API's aanroepen, gebruiken de OAuth 2.0-on-behalf-of (OBO)-stroom. De web-API maakt gebruik van het toegangstoken dat is opgehaald uit de HTTP-autorisatieheader en valideert dit token. Dit token wordt vervolgens uitgewisseld met een token om de downstream web-API aan te roepen. Dit token wordt gebruikt als een UserAssertion instantie in zowel ADAL.NET als MSAL.NET.

Ontdek of uw code gebruikmaakt van OBO

De ADAL-code voor uw app gebruikt OBO als deze een aanroep bevat AuthenticationContext.AcquireTokenAsync met de volgende parameters:

• Een resource (app-id-URI) als eerste parameter
• IClientAssertionCertificate of ClientAssertion als de tweede parameter
• Een parameter van het type UserAssertion

De code bijwerken met behulp van OBO

De volgende stappen voor het bijwerken van code zijn van toepassing op alle vertrouwelijke clientscenario's:

1. Voeg de MSAL.NET naamruimte toe in de broncode: using Microsoft.Identity.Client;.
2. Gebruik ConfidentialClientApplicationBuilder.Create om IConfidentialClientApplication te instantiëren in plaats van AuthenticationContext.
3. In plaats van de tekenreeks resourceId gebruikt MSAL.NET scopes. Omdat toepassingen die ADAL.NET gebruiken vooraf zijn geautoriseerd, kunt u altijd de volgende machtigingen gebruiken: new string[] { $"{resourceId}/.default" }
4. Vervang de aanroep naar AuthenticationContext.AcquireTokenAsync door een aanroep naar IConfidentialClientApplication.AcquireTokenXXX, waarbij XXX afhankelijk is van uw scenario.

In dit geval vervangen we de aanroep van AuthenticationContext.AcquireTokenAsync door een aanroep van IConfidentialClientApplication.AcquireTokenOnBehalfOf.

Hier volgt een vergelijking van voorbeeld-OBO-code voor ADAL.NET en 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;
}
}

Profiteer van token-caching

Voor tokencaching in OBO's gebruikt u een gedistribueerde tokencache. Zie Tokencache voor een web-app of web-API (vertrouwelijke client-app) voor meer informatie.

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

Meer informatie over web-API's die downstream-web-API's aanroepen en hoe deze worden geïmplementeerd met MSAL.NET of Microsoft. Identity.Web in nieuwe apps.

Een web-app migreren die web-API's aanroept

Als uw app gebruikmaakt van ASP.NET Core, raden we u ten zeerste aan om bij te werken naar Microsoft. Identity.Web omdat alles voor u wordt verwerkt. Zie voor een korte presentatie de aankondiging van algemene beschikbaarheid van Microsoft.Identity.Web. Zie Waarom Microsoft.Identity.Web gebruiken in web-apps? voor meer informatie over hoe u het in een web-app gebruikt.

Web-apps die gebruikers aanmelden en web-API's aanroepen namens gebruikers, maken gebruik van de OAuth2.0-autorisatiecodestroom. Meestal:

1. De app meldt een gebruiker aan door de eerste stap van de autorisatiecodestroom uit te voeren via het autorisatie-eindpunt van het Microsoft identity platform. De gebruiker meldt zich aan en voert indien nodig meervoudige verificaties uit. Als resultaat van deze bewerking ontvangt de app de autorisatiecode. De verificatiebibliotheek wordt in deze fase niet gebruikt.
2. De app voert het tweede deel van de autorisatiecodestroom uit. Hierbij wordt de autorisatiecode gebruikt om een toegangstoken, een id-token en een vernieuwingstoken op te halen. Uw toepassing moet de waarde opgeven. Dit is de redirectUri URI waarin het Microsoft identity platform-eindpunt de beveiligingstokens levert. Nadat de app die URI heeft ontvangen, roept deze doorgaans AcquireTokenByAuthorizationCode aan voor ADAL of MSAL om de code in te wisselen en een token op te halen dat wordt opgeslagen in de tokencache.
3. De app gebruikt ADAL of MSAL om AcquireTokenSilent aan te roepen en tokens op te halen voor het aanroepen van de benodigde web-API's vanuit de web-appcontrollers.

Controleren of uw code gebruikmaakt van de verificatiecodestroom

De ADAL-code voor uw app maakt gebruik van een verificatiecodestroom als deze een aanroep naar AuthenticationContext.AcquireTokenByAuthorizationCodeAsyncbevat.

De code bijwerken met behulp van de autorisatiecodestroom

De volgende stappen voor het bijwerken van code zijn van toepassing op alle vertrouwelijke clientscenario's:

1. Voeg de MSAL.NET naamruimte toe in de broncode: using Microsoft.Identity.Client;.
2. Gebruik ConfidentialClientApplicationBuilder.Create om IConfidentialClientApplication te instantiëren in plaats van AuthenticationContext.
3. In plaats van de tekenreeks resourceId gebruikt MSAL.NET scopes. Omdat toepassingen die ADAL.NET gebruiken vooraf zijn geautoriseerd, kunt u altijd de volgende machtigingen gebruiken: new string[] { $"{resourceId}/.default" }
4. Vervang de aanroep naar AuthenticationContext.AcquireTokenAsync door een aanroep naar IConfidentialClientApplication.AcquireTokenXXX, waarbij XXX afhankelijk is van uw scenario.

Vervang in dit geval de aanroep naar AuthenticationContext.AcquireTokenAsync een aanroep naar IConfidentialClientApplication.AcquireTokenByAuthorizationCode.

Hier volgt een vergelijking van voorbeeldautorisatiecodestromen voor ADAL.NET en 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;
}
}

Aanroepen AcquireTokenByAuthorizationCode voegt een token toe aan de tokencache wanneer de autorisatiecode wordt ontvangen. Als u extra tokens voor andere bronnen of tenants wilt verkrijgen, gebruikt u AcquireTokenSilent in uw controllers.

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;
 }
}

Profiteer van token-caching

Omdat uw web-app gebruikmaakt AcquireTokenByAuthorizationCode, moet deze een gedistribueerde tokencache gebruiken voor tokencaching. Zie Tokencache voor een web-app of web-API voor meer informatie.

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

MsalUiRequiredException verwerken

Wanneer uw controller probeert geruisloos een token te verkrijgen voor verschillende scopes/resources, kan MSAL.NET zoals verwacht een MsalUiRequiredException veroorzaken als de gebruiker zich opnieuw moet aanmelden, of als voor toegang tot de resource meer claims vereist zijn (vanwege een beleid voor voorwaardelijke toegang). Zie voor meer informatie over beperking hoe u fouten en uitzonderingen in MSAL.NET afhandelt.

Meer informatie over web-apps die web-API's aanroepen en hoe deze worden geïmplementeerd met MSAL.NET of Microsoft. Identity.Web in nieuwe toepassingen.