ADAL.NET アプリと MSAL.NET アプリの違い

アプリケーションを ADAL の使用から MSAL の使用に移行するには、セキュリティと回復性の利点があります。 この記事では、MSAL.NET と ADAL.NET の違いについて説明します。 すべての新しいアプリケーションでは、MSAL.NET とMicrosoft ID プラットフォームを使用する必要があります。これは、Microsoft認証ライブラリの最新世代です。 MSAL.NET を使用すると、ユーザーが Microsoft Entra ID (職場および学校アカウント)、Microsoft (個人) アカウント (MSA)、または AD B2C Azureを使用してアプリケーションにサインインするためのトークンを取得します。 ADAL を使用している既存のアプリケーションがある場合.NET MSAL.NET に移行します。

アプリケーションで以前のバージョンの Active Directory フェデレーション サービス (AD FS) (ADFS) を使用してユーザーをサインインさせる必要がある場合は.NET ADAL を引き続き使用する必要があります。 詳細については、 ADFS のサポートを参照してください。

Prerequisites

MSAL の概要を参照して、MSAL の詳細を確認してください。

相違点

サポートされている許可

パブリック クライアント アプリケーションと機密クライアント アプリケーションの両方.NETサポートされている許可 MSAL.NET と ADAL を比較した概要を次に示します。

パブリック クライアント アプリケーション

次の図は、パブリック クライアント アプリケーションの ADAL.NET と MSAL.NET の違いをいくつかまとめたものです。

デスクトップ アプリケーションとモバイル アプリケーションの ADAL.NETおよび MSAL.NET でサポートされている許可を次に示します。

機密クライアント アプリケーション

次の図は、機密クライアント アプリケーションの ADAL.NET と MSAL.NET の違いをいくつかまとめたものです。

ADAL、.NET、MSAL.NET、Microsoftでサポートされている許可を次に示します。Web アプリケーション、Web API、デーモン アプリケーション用の Identity.Web。

更新トークンを使用した ADAL 2.x からの移行

ADAL では.NET v2 です。X、更新トークンが公開され、これらのトークンをキャッシュし、ADAL 2.x によって提供されるAcquireTokenByRefreshTokenメソッドを使用して、これらのトークンの使用に関するソリューションを開発できるようになりました。

これらのソリューションの一部は、次のようなシナリオで使用されました。

• ユーザーがアプリに接続またはサインインしなくなったときにユーザーのダッシュボードを更新するなど、アクションを実行する実行時間の長いサービス。
• クライアントが更新トークンを Web サービスに持ち込むことができるようにする WebFarm シナリオ (キャッシュはクライアント側で行われ、暗号化された Cookie はサーバー側ではありません)。

MSAL.NET では、セキュリティ上の理由から更新トークンは公開されません。 MSAL は更新トークンを自動的に処理します。

さいわい、MSAL.NET には、以前の更新トークン (ADAL で取得) をIConfidentialClientApplicationに移行できる API があります。

/// <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);

このメソッドを使用すると、以前に使用した更新トークンと、必要なスコープ (リソース) を指定できます。 更新トークンは新しいものと交換され、アプリケーションにキャッシュされます。

この方法は一般的ではないシナリオを対象としているため、最初にIByRefreshTokenにキャストしないと、IConfidentialClientApplicationで簡単にアクセスできません。

次のコード スニペットは、機密クライアント アプリケーションの移行コードを示しています。

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 は、ADAL 2.x を使用するために使用されていた以前のバージョンのアプリケーションによって、ストレージに格納された更新トークンを取得します。 GetTokenCacheForSignedInUser は、サインインしているユーザーのキャッシュを逆シリアル化します (機密クライアント アプリケーションにはユーザーごとに 1 つのキャッシュが必要です)。

新しい更新トークンがキャッシュに格納されている間、アクセス トークンと ID トークンが AuthenticationResult 値で返されます。 このメソッドは、更新トークンを使用できるさまざまな統合シナリオにも使用できます。

v1.0 トークンと v2.0 トークン

トークンには、v1.0 トークンと v2.0 トークンの 2 つのバージョンがあります。 v1.0 エンドポイント (ADAL で使用) は v1.0 ID トークンを出力し、v2.0 エンドポイント (MSAL で使用) は v2.0 ID トークンを出力します。 ただし、両方のエンドポイントは、Web API が受け入れるトークンのバージョンのアクセス トークンを出力します。 Web API のアプリケーション マニフェストのプロパティを使用すると、開発者は受け入れられるトークンのバージョンを選択できます。 アプリケーション マニフェストのリファレンス ドキュメントのaccessTokenAcceptedVersionを参照してください。

v1.0 および v2.0 アクセス トークンの詳細については、「Microsoft Entraアクセス トークン」を参照してください。

例外

相互作用が必要な例外

MSAL.NET を使用すると、「AcquireTokenSilent」の説明に従ってMsalUiRequiredExceptionをキャッチできます

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

詳細については、MSAL.NET でのエラーと例外の処理に関するページを参照してください。

ADAL.NETの明示的な例外は少ありませんでした。 たとえば、ADAL でサイレント認証が失敗した場合、プロシージャは例外をキャッチし、 user_interaction_required エラー コードを探しました。

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

詳細については、ADAL を使用してパブリック クライアント アプリケーションでトークンを取得するために推奨されるパターン.NETを参照してください。

プロンプトの動作

MSAL.NET でのプロンプト動作は、ADAL でのプロンプト動作と同じです.NET:

要求チャレンジ例外の処理

トークンを取得するときに、リソースがユーザーからの要求を増やす必要がある場合 (たとえば、2 要素認証) に対して、Microsoft Entra IDは例外をスローします。

MSAL.NET では、要求チャレンジの例外は次のように処理されます。

• ClaimsがMsalServiceExceptionに表示されます。
• AcquireTokenXXX ビルダーに適用できるWithClaims(String)メソッドがあります。

詳細については、「 MsalUiRequiredException の処理」を参照してください。

ADAL.NET では、要求チャレンジの例外は次のように処理されました。

• AdalClaimChallengeException は例外です ( AdalServiceExceptionから派生)。 Claims メンバーには、要求を含むいくつかの JSON フラグメントが含まれています。これは想定されています。
• この例外を受け取るパブリック クライアント アプリケーションは、要求パラメーターを持つ AcquireTokenInteractive オーバーライドを呼び出す必要があります。 AcquireTokenInteractiveのこのオーバーライドは、必要がないため、キャッシュにヒットしようともしません。 その理由は、キャッシュ内のトークンに適切な要求がないためです (それ以外の場合、 AdalClaimChallengeException はスローされません)。 そのため、キャッシュを見る必要はありません。 ClaimChallengeExceptionは OBO を実行している WebAPI で受信できますが、この Web API を呼び出すパブリック クライアント アプリケーションでAcquireTokenInteractiveを呼び出す必要があります。

サンプルを含む詳細については、 AdalClaimChallengeException の処理を参照してください。

スコープ

ADAL では、resourceId文字列を持つリソースの概念が使用されますが、MSAL.NET ではスコープが使用されます。 Microsoft Entra IDで使用されるロジックは次のとおりです。

• v1.0 アクセス トークン (唯一可能) を持つ ADAL (v1.0) エンドポイントの場合は、 aud=resource。
• v2.0 トークンを受け入れるリソースのアクセス トークンを要求する MSAL (v2.0 エンドポイント) の場合は、 aud=resource.AppId。
• v1.0 アクセス トークンを受け入れるリソースのアクセス トークンを要求する MSAL (v2.0 エンドポイント) の場合、Microsoft Entra IDは要求されたスコープから目的の対象ユーザーを解析します。 これは、最後のスラッシュの前のすべてを取得し、それをリソース識別子として使用することによって行われます。 そのため、https://database.windows.nethttps://database.windows.net/の対象ユーザーが予想される場合は、https://database.windows.net//.defaultのスコープを要求する必要があります (./default の前に二重スラッシュがあることに注意してください)。 以下に、例 1 と 2 を示します。

例 1

v1.0 トークンを受け入れるアプリケーションのトークン (たとえば、https://graph.microsoft.comの Microsoft Graph API) を取得する場合は、目的のリソース識別子をそのリソースの目的の OAuth2 アクセス許可と連結してscopesを作成する必要があります。

たとえば、アプリ ID URI が ResourceId v1.0 Web API 経由でユーザーの名前にアクセスするには、次を使用します。

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

Microsoft Graph API (https://graph.microsoft.com/) を使用して MSAL.NET Microsoft Entra IDで読み書きする場合は、次のコード スニペットのようにスコープの一覧を作成します。

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

例 2

resourceId が '/' で終わる場合は、スコープ値を書き込むときに、二重の '/' が必要です。 たとえば、Azure Resource Manager API (https://management.core.windows.net/) に対応するスコープを記述する場合は、次のスコープを要求します (2 つのスラッシュに注意してください)。

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

これは、Resource Manager API が対象ユーザー要求 (aud) でスラッシュを受け取り、スコープから API 名を区切るスラッシュが存在するためです。

v1.0 アプリケーションのすべての静的スコープのトークンを取得する場合は、次のコード スニペットに示すようにスコープ リストを作成します。

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

クライアント資格情報フローの場合、渡すスコープも /.default。 このスコープは、"管理者がアプリケーション登録で同意したすべてのアプリ レベルのアクセス許可" をMicrosoft Entra IDするように指示します。

次のステップ

ADAL から MSAL にアプリを移行する MSAL.NET を使用する機密クライアント アプリ.NET ADAL を移行する