Migrate confidential client applications from ADAL.NET to MSAL.NET

Migrate daemon apps

Daemon scenarios use the OAuth2.0 client credential flow. They're also called service-to-service calls. Your app acquires a token on its own behalf, not on behalf of a user.

Find out if your code uses daemon scenarios

The ADAL code for your app uses daemon scenarios if it contains a call to AuthenticationContext.AcquireTokenAsync with the following parameters:

• A resource (app ID URI) as a first parameter
• IClientAssertionCertificate or ClientAssertion as the second parameter

AuthenticationContext.AcquireTokenAsync doesn't have a parameter of type UserAssertion. If it does, then your app is a web API, and it uses the web API calling downstream web APIs scenario.

Update the code of daemon scenarios

The following steps for updating code apply across all the confidential client scenarios:

1. Add the MSAL.NET namespace in your source code: using Microsoft.Identity.Client;.
2. Instead of instantiating AuthenticationContext, use ConfidentialClientApplicationBuilder.Create to instantiate IConfidentialClientApplication.
3. Instead of the resourceId string, MSAL.NET uses scopes. Because applications that use ADAL.NET are preauthorized, you can always use the following scopes: new string[] { $"{resourceId}/.default" }.
4. Replace the call to AuthenticationContext.AcquireTokenAsync with a call to IConfidentialClientApplication.AcquireTokenXXX, where XXX depends on your scenario.

In this case, replace the call to AuthenticationContext.AcquireTokenAsync with a call to IConfidentialClientApplication.AcquireTokenClient.

Here's a comparison of ADAL.NET and MSAL.NET code for daemon scenarios:

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://zcusa.951200.xyz/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;
}
}

Benefit from token caching

If you don't setup token caching, the token issuer will throttle you, resulting in errors. It also takes a lot less to get a token from the cache (10-20ms) than it is from ESTS (500-30000ms).

If you want to implement a distributed token cache, see Token cache for a web app or web API (confidential client application).

Learn more about the daemon scenario and how it's implemented with MSAL.NET or Microsoft.Identity.Web in new applications.

Migrate a web API that calls downstream web APIs

Web APIs that call downstream web APIs use the OAuth2.0 on-behalf-of (OBO) flow. The web API uses the access token retrieved from the HTTP Authorize header and it validates this token. This token is then exchanged against a token to call the downstream web API. This token is used as a UserAssertion instance in both ADAL.NET and MSAL.NET.

Find out if your code uses OBO

The ADAL code for your app uses OBO if it contains a call to AuthenticationContext.AcquireTokenAsync with the following parameters:

• A resource (app ID URI) as a first parameter
• IClientAssertionCertificate or ClientAssertion as the second parameter
• A parameter of type UserAssertion

Update the code by using OBO

The following steps for updating code apply across all the confidential client scenarios:

1. Add the MSAL.NET namespace in your source code: using Microsoft.Identity.Client;.
2. Instead of instantiating AuthenticationContext, use ConfidentialClientApplicationBuilder.Create to instantiate IConfidentialClientApplication.
3. Instead of the resourceId string, MSAL.NET uses scopes. Because applications that use ADAL.NET are preauthorized, you can always use the following scopes: new string[] { $"{resourceId}/.default" }.
4. Replace the call to AuthenticationContext.AcquireTokenAsync with a call to IConfidentialClientApplication.AcquireTokenXXX, where XXX depends on your scenario.

In this case, we replace the call to AuthenticationContext.AcquireTokenAsync with a call to IConfidentialClientApplication.AcquireTokenOnBehalfOf.

Here's a comparison of sample OBO code for ADAL.NET and 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://zcusa.951200.xyz/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;
}
}

Benefit from token caching

For token caching in OBOs, use a distributed token cache. For details, see Token cache for a web app or web API (confidential client app).

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

Learn more about web APIs calling downstream web APIs and how they're implemented with MSAL.NET or Microsoft.Identity.Web in new apps.

Migrate a web app that calls web APIs

If your app uses ASP.NET Core, we strongly recommend that you update to Microsoft.Identity.Web because it processes everything for you. For a quick presentation, see the Microsoft.Identity.Web announcement of general availability. For details about how to use it in a web app, see Why use Microsoft.Identity.Web in web apps?.

Web apps that sign in users and call web APIs on behalf of users employ the OAuth2.0 authorization code flow. Typically:

1. The app signs in a user by executing a first leg of the authorization code flow by going to the Microsoft identity platform authorize endpoint. The user signs in and performs multi-factor authentications if needed. As an outcome of this operation, the app receives the authorization code. The authentication library isn't used at this stage.
2. The app executes the second leg of the authorization code flow. It uses the authorization code to get an access token, an ID token, and a refresh token. Your application needs to provide the redirectUri value, which is the URI where the Microsoft identity platform endpoint will provide the security tokens. After the app receives that URI, it typically calls AcquireTokenByAuthorizationCode for ADAL or MSAL to redeem the code and to get a token that will be stored in the token cache.
3. The app uses ADAL or MSAL to call AcquireTokenSilent to get tokens for calling the necessary web APIs from the web app controllers.

Find out if your code uses the auth code flow

The ADAL code for your app uses auth code flow if it contains a call to AuthenticationContext.AcquireTokenByAuthorizationCodeAsync.

Update the code by using the authorization code flow

The following steps for updating code apply across all the confidential client scenarios:

1. Add the MSAL.NET namespace in your source code: using Microsoft.Identity.Client;.
2. Instead of instantiating AuthenticationContext, use ConfidentialClientApplicationBuilder.Create to instantiate IConfidentialClientApplication.
3. Instead of the resourceId string, MSAL.NET uses scopes. Because applications that use ADAL.NET are preauthorized, you can always use the following scopes: new string[] { $"{resourceId}/.default" }.
4. Replace the call to AuthenticationContext.AcquireTokenAsync with a call to IConfidentialClientApplication.AcquireTokenXXX, where XXX depends on your scenario.

In this case, replace the call to AuthenticationContext.AcquireTokenAsync with a call to IConfidentialClientApplication.AcquireTokenByAuthorizationCode.

Here's a comparison of sample authorization code flows for ADAL.NET and 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;
}
}

Calling AcquireTokenByAuthorizationCode adds a token to the token cache when the authorization code is received. To acquire extra tokens for other resources or tenants, use AcquireTokenSilent in your 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;
 }
}

Benefit from token caching

Because your web app uses AcquireTokenByAuthorizationCode, it needs to use a distributed token cache for token caching. For details, see Token cache for a web app or web API.

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

Handling MsalUiRequiredException

When your controller attempts to acquire a token silently for different scopes/resources, MSAL.NET might throw an MsalUiRequiredException as expected if the user needs to re-sign-in, or if the access to the resource requires more claims (because of a Conditional Access policy). For details on mitigation see how to Handle errors and exceptions in MSAL.NET.

Learn more about web apps calling web APIs and how they're implemented with MSAL.NET or Microsoft.Identity.Web in new applications.