Web API を呼び出すデスクトップ アプリ: 対話式でトークンを取得する

次の例は、Microsoft Graph を使用してユーザーのプロファイルを読み取るためにトークンを対話形式で取得する最小限のコードを示しています。

.NET

MSAL.NET のコード

string[] scopes = new string[] { "user.read" };

var app = PublicClientApplicationBuilder.Create("YOUR_CLIENT_ID")
    .WithDefaultRedirectUri()
    .Build();

var accounts = await app.GetAccountsAsync();

AuthenticationResult result;
try
{
    result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())
      .ExecuteAsync();
}
catch (MsalUiRequiredException)
{
    result = await app.AcquireTokenInteractive(scopes).ExecuteAsync();
}

必須のパラメーター

AcquireTokenInteractive の必須パラメーターは scopes の 1 つだけです。 これには、トークンを必要とするスコープを定義する文字列の列挙型が含まれています。 Microsoft Graph 用のトークンの場合、必要なスコープは各 Microsoft Graph API の API リファレンスの「アクセス許可」というセクションにあります。たとえば、ユーザーの連絡先を一覧表示するには、User.Read および Contacts.Read の両方をスコープとして使用する必要があります。 詳細については、「Microsoft Graph のアクセス許可のリファレンス」を参照してください。

デスクトップ アプリケーションとモバイル アプリケーションの両方で、.WithParentActivityOrWindow を使用して親を指定することが重要です。 多くの場合、これは必須であり、MSAL は例外をスローします。

デスクトップ アプリケーションについては、「親ウィンドウ ハンドル」を参照してください。

モバイル アプリケーションの場合は、Activity (Android) または UIViewController (iOS) を指定します。

MSAL.NET の特定の省略可能なパラメーター

WithParentActivityOrWindow

UI は対話型であるため、重要です。 AcquireTokenInteractive には、特定の省略可能なパラメーターが 1 つあり、(それをサポートするプラットフォームに対する) 親 UI を指定できます。 デスクトップ アプリケーションで .WithParentActivityOrWindow を使用する場合、その型はプラットフォームによって異なります。

または、サインイン ダイアログが画面のどこに表示されるかを制御する必要がない場合は、省略可能な親ウィンドウ パラメーターを省略してウィンドウを作成することができます。 このオプションは、コマンド ラインに基づいたアプリケーション、他の任意のバックエンド サービスへの呼び出しを渡すために使用されるアプリケーション、ユーザーの操作のためのウィンドウを必要としないアプリケーションに適用されます。

// net45
WithParentActivityOrWindow(IntPtr windowPtr)
WithParentActivityOrWindow(IWin32Window window)

// Mac
WithParentActivityOrWindow(NSWindow window)

// .NET Standard (this will be on all platforms at runtime, but only on .NET Standard platforms at build time)
WithParentActivityOrWindow(object parent).

解説:

• .NET Standard では、想定される object の値は Activity (Android の場合)、UIViewController (iOS の場合)、NSWindow (Mac の場合)、IWin32Window または IntPr (Windows の場合) です。

• Windows では、埋め込みブラウザーが適切な UI 同期コンテキストを取得するように、UI スレッドから AcquireTokenInteractive を呼び出す必要があります。 UI スレッドからの呼び出しでない場合は、メッセージが適切にポンプされなかったり、UI によるデッドロック シナリオの原因となったりする可能性があります。 UI スレッドでない場所で UI スレッドから Microsoft 認証ライブラリ (MSAL) を呼び出す方法の 1 つとしては、Windows Presentation Foundation (WPF) で Dispatcher を使用する方法があります。

• WPF を使用している場合に WPF コントロールからウィンドウを取得するには、WindowInteropHelper.Handle クラスを使用できます。 そして、呼び出しは WPF コントロール (this) から次のように行われます。

  result = await app.AcquireTokenInteractive(scopes)
                    .WithParentActivityOrWindow(new WindowInteropHelper(this).Handle)
                    .ExecuteAsync();
  

WithPrompt

WithPrompt() を使用して、プロンプトを指定してユーザーとのインタラクティビティを制御します。 厳密な動作を Microsoft.Identity.Client.Prompt 構造体で制御できます。

この構造体では次の定数を定義します。

• SelectAccount により、ユーザーがセッションを確立しているアカウントを含む、アカウントの選択ダイアログがセキュリティ トークン サービス (STS) で強制的に表示されます。 これは既定のオプションです。 これは、さまざまな ID からの選択をユーザーにさせる場合に有用です。

  このオプションを使用すると、MSAL から ID プロバイダーに prompt=select_account が送信されます。 これにより、使用可能な情報 (アカウント、ユーザーのセッションの有無など) に基づいて最適なエクスペリエンスが提供されます。 正当な理由がない限り、変更しないでください。

• Consent により、アプリケーションで以前に同意が得られている場合であっても、ユーザーの同意を強制的に求めることができます。 この場合、MSAL から ID プロバイダーに prompt=consent が送信されます。 このオプションは、組織のガバナンスによって、アプリケーションを開くたびに同意のダイアログ ボックスをユーザーに対して表示することを求めるような、セキュリティを重視する一部のアプリケーションで使用できます。

• ForceLogin により、このユーザー プロンプトが不要な場合でも、アプリケーションでユーザーに資格情報の入力を求めるようにすることができます。 このオプションは、トークンの取得に失敗した場合に、ユーザーが再度サインインできるようにするのに役立ちます。 この場合、MSAL から ID プロバイダーに prompt=login が送信されます。 組織では、このオプションを、アプリケーションの特定の部分にアクセスするたびにユーザーが再度サインインすることがガバナンスとして求められる、セキュリティを重視するアプリケーションで使用することがあります。

• Create により、prompt=create を ID プロバイダーに送信することで、外部 ID のためのサインアップ エクスペリエンスがトリガーされます。 Azure Active Directory B2C (Azure AD B2C) アプリでは、このプロンプトを送信しないでください。 詳細については、「セルフサービス サインアップのユーザー フローをアプリに追加する」を参照してください。

• Never(.NET 4.5 および Windows ランタイム のみ) では、ユーザーにプロンプトは表示されません。 代わりに、非表示の埋め込み Web ビューに格納された Cookie の使用を試みます。

  このオプションを使用すると、失敗する場合があります。 その場合、AcquireTokenInteractive は、UI 操作が必要であることを通知するために例外をスローします。 次に、別の Prompt パラメーターが使用されます。

• NoPrompt は、ID プロバイダーにプロンプトを送信しません。 ID プロバイダーは、ユーザーに最適なサインイン エクスペリエンスを決定します (シングル サインオンまたはアカウントの選択)。

  このオプションは、Azure AD B2C でプロファイル ポリシーを編集する場合には必須です。 詳細については、Azure AD B2C での詳細に関するページを参照してください。

WithUseEmbeddedWebView

このメソッドを使用すると、埋め込みの WebView またはシステム WebView (使用可能な場合) を強制的に使用するかどうかを指定できます。 詳細については、Web ブラウザーの使用に関する記事を参照してください。

var result = await app.AcquireTokenInteractive(scopes)
                    .WithUseEmbeddedWebView(true)
                    .ExecuteAsync();

WithExtraScopeToConsent

この修飾子は、ユーザーが前もって複数のリソースへの同意を行い、追加の同意を使用しない、高度なシナリオのためのものです。 開発者は通常、MSAL.NET とMicrosoft ID プラットフォームでは追加の同意を使用します。

var result = await app.AcquireTokenInteractive(scopesForCustomerApi)
                     .WithExtraScopeToConsent(scopesForVendorApi)
                     .ExecuteAsync();

WithCustomWebUi

Web UI は、ブラウザーを起動するメカニズムです。 このメカニズムは、専用の UI WebBrowser コントロール、またはブラウザーを開くことを委任する方法の場合があります。 MSAL によりほとんどのプラットフォームに Web UI の実装が提供されますが、これらの場合には、ブラウザーを自分でホストする必要があることがあります。

• デスクトップ上の Blazor、Unity、Mono など、MSAL が明示的にカバーしていないプラットフォームがあります。
• UI でアプリケーションのテストを行い、Selenium で使用できる自動化されたブラウザーを使用する必要がある場合。
• ブラウザーと MSAL を実行するアプリが別々のプロセスにある場合。

これを実現するには、MSAL に start Url を指定します。これは、ユーザーが自分のユーザー名などの項目を入力できるように、ブラウザーに表示される必要があります。 認証が完了したら、Microsoft Entra ID によって提供されるコードが含まれる MSAL end Url にアプリを返す必要があります。 end Url のホストは常に redirectUri です。 end Url をインターセプトするには、次のいずれかを行います。

• redirect Url にヒットするまでブラウザーのリダイレクトを監視します。
• ブラウザーを監視する URL にリダイレクトさせます。

WithCustomWebUi は、パブリック クライアント アプリケーションで独自の UI を提供するために使用できる拡張ポイントです。 また、ユーザーが ID プロバイダーの /Authorize エンドポイントを経由し、サインインして同意できるようにすることもできます。 MSAL.NET では、その後で認証コードを引き換えて、トークンを取得できます。

たとえば、Visual Studio で WithCustomWebUi を使用して、電子アプリケーション (Visual Studio フィードバックなど) に Web 操作を提供させて、ほとんどの処理を MSAL.NET に任せることができます。 また、WithCustomWebUi を使用して UI オートメーションを提供することもできます。

パブリック クライアント アプリケーションの場合、MSAL.NET では Proof Key for Code Exchange (PKCE) 標準を使用してセキュリティが確保されるようにします。 コードを引き換えることができるのは MSAL.NET のみです。 詳細については、「RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients」を参照してください。

using Microsoft.Identity.Client.Extensions;

WithCustomWebUi を使用する

WithCustomWebUI を使用するには、次の手順に従います。

1. ICustomWebUi インターフェイスを実装します。 詳細については、こちらの GitHub ページを参照してください。

2. 1 つの AcquireAuthorizationCodeAsync メソッドを実装し、MSAL.NET が計算する認証コード URL を受け入れます。

3. ユーザーに ID プロバイダーとの対話を実行させ、ID プロバイダーが実装のコールバックに使用した URL (認証コードを含む) を返します。 問題がある場合は、MSAL と連携する MsalExtensionException 例外が実装によってスローされます。

4. AcquireTokenInteractive の呼び出しで、カスタム Web UI のインスタンスを渡して .WithCustomUI() 修飾子を使用します。

   result = await app.AcquireTokenInteractive(scopes)
                     .WithCustomWebUi(yourCustomWebUI)
                     .ExecuteAsync();
   

MSAL.NET チームでは、この拡張メカニズムを使用するように UI テストを書き換えました。 関心がある場合は、MSAL.NET のソース コードで SeleniumWebUI クラスをご確認ください。

SystemWebViewOptions を使用して優れたエクスペリエンスを提供する

MSAL.NET 4.1 SystemWebViewOptions から、以下を指定できます。

• システム Web ブラウザーでサインイン エラーまたは同意エラーが表示される場合に、(BrowserRedirectError) に移動する URI または (HtmlMessageError) を表示する HTML フラグメント。
• サインインあるいは同意が成功した場合に、(BrowserRedirectSuccess) に移動する URI または (HtmlMessageSuccess) を表示する HTML フラグメント。
• システム ブラウザーを起動するために実行するアクション。 OpenBrowserAsync デリゲートを設定して、独自の実装を提供できます。 このクラスでは、2 つのブラウザー (Microsoft Edge 用の OpenWithEdgeBrowserAsync と Chromium に基づく Microsoft Edge 用 の OpenWithChromeEdgeBrowserAsync) の既定の実装も用意されています。

この構造体を使用するには、次の例のように記述します。

IPublicClientApplication app;
...

options = new SystemWebViewOptions
{
 HtmlMessageError = "<b>Sign-in failed. You can close this tab ...</b>",
 BrowserRedirectSuccess = "https://contoso.com/help-for-my-awesome-commandline-tool.html"
};

var result = app.AcquireTokenInteractive(scopes)
                .WithEmbeddedWebView(false)       // The default in .NET
                .WithSystemWebViewOptions(options)
                .Build();

その他の省略可能なパラメーター

AcquireTokenInteractive のその他の省略可能なパラメーターについては、AcquireTokenInteractiveParameterBuilder に関する記事を参照してください。

Java

private static IAuthenticationResult acquireTokenInteractive() throws Exception {

    // Load the token cache from the file and initialize the token cache aspect. The token cache will have
    // dummy data, so the acquireTokenSilently call will fail.
    TokenCacheAspect tokenCacheAspect = new TokenCacheAspect("sample_cache.json");

    PublicClientApplication pca = PublicClientApplication.builder(CLIENT_ID)
            .authority(AUTHORITY)
            .setTokenCacheAccessAspect(tokenCacheAspect)
            .build();

    Set<IAccount> accountsInCache = pca.getAccounts().join();
    // Take the first account in the cache. In a production application, you would filter
    // accountsInCache to get the right account for the user who is authenticating.
    IAccount account = accountsInCache.iterator().next();

    IAuthenticationResult result;
    try {
        SilentParameters silentParameters =
                SilentParameters
                        .builder(SCOPE, account)
                        .build();

        // try to acquire the token silently. This call will fail because the token cache
        // does not have any data for the user you're trying to acquire a token for
        result = pca.acquireTokenSilently(silentParameters).join();
    } catch (Exception ex) {
        if (ex.getCause() instanceof MsalException) {

            InteractiveRequestParameters parameters = InteractiveRequestParameters
                    .builder(new URI("http://localhost"))
                    .scopes(SCOPE)
                    .build();

            // Try to acquire a token interactively with the system browser. If successful, you should see
            // the token and account information printed out to the console
            result = pca.acquireToken(parameters).join();
        } else {
            // Handle other exceptions accordingly
            throw ex;
        }
    }
    return result;
}

macOS

iOS および macOS 用の MSAL のコード

MSALInteractiveTokenParameters *interactiveParams = [[MSALInteractiveTokenParameters alloc] initWithScopes:scopes webviewParameters:[MSALWebviewParameters new]];
[application acquireTokenWithParameters:interactiveParams completionBlock:^(MSALResult *result, NSError *error) {
    if (!error)
    {
        // You'll want to get the account identifier to retrieve and reuse the account
        // for later acquireToken calls
        NSString *accountIdentifier = result.account.identifier;

        NSString *accessToken = result.accessToken;
    }
}];

let interactiveParameters = MSALInteractiveTokenParameters(scopes: scopes, webviewParameters: MSALWebviewParameters())
application.acquireToken(with: interactiveParameters, completionBlock: { (result, error) in

    guard let authResult = result, error == nil else {
        print(error!.localizedDescription)
        return
    }

    // Get the access token from the result
    let accessToken = authResult.accessToken
})

Node.js

MSAL ノードでは、コード交換のための証明鍵 (PKCE) を使用して認可コード フロー経由でトークンを取得します。 このプロセスは 2 つの手順で構成されます。

1. アプリケーションで、認可コードを生成するために使用できる URL が取得されます。 ユーザーはブラウザーで URL を開き、資格情報を入力できます。 その後、認可コードによって、redirectUri (アプリの登録で登録された) にリダイレクトされます。
2. アプリケーションでは受け取った認可コードを acquireTokenByCode() メソッドに渡し、そこでアクセス トークンに交換されます。

const msal = require("@azure/msal-node");

const msalConfig = {
    auth: {
        clientId: "your_client_id_here",
        authority: "your_authority_here",
    }
};

const pca = new msal.PublicClientApplication(msalConfig);

const {verifier, challenge} = await msal.cryptoProvider.generatePkceCodes();

const authCodeUrlParameters = {
    scopes: ["User.Read"],
    redirectUri: "your_redirect_uri",
    codeChallenge: challenge, // PKCE code challenge
    codeChallengeMethod: "S256" // PKCE code challenge method 
};

// Get the URL to sign in the user and consent to scopes needed for the application
pca.getAuthCodeUrl(authCodeUrlParameters).then((response) => {
    console.log(response);

    const tokenRequest = {
        code: response["authorization_code"],
        codeVerifier: verifier // PKCE code verifier 
        redirectUri: "your_redirect_uri",
        scopes: ["User.Read"],
    };

    // Acquire a token by exchanging the code
    pca.acquireTokenByCode(tokenRequest).then((response) => {
        console.log("\nResponse: \n:", response);
    }).catch((error) => {
        console.log(error);
    });
}).catch((error) => console.log(JSON.stringify(error)));

Python

MSAL Python 1.7 以降では、トークンを取得するための対話型メソッドが提供されています。

result = None

# Check the cache to see if this user has signed in before
accounts = app.get_accounts(username=config["username"])
if accounts:
    result = app.acquire_token_silent(config["scope"], account=accounts[0])

if not result:
    result = app.acquire_token_interactive(  # It automatically provides PKCE protection
         scopes=config["scope"])

次のステップ

• 複数パートのチュートリアル シリーズで、ユーザーをサインインさせる React シングルページ アプリケーション (SPA) を構築して、さらに詳しく学習します。

• Microsoft ID プラットフォームのデスクトップ コード サンプルを確認する