桌面應用程式呼叫 Web API：以互動方式取得權杖

適用於：具有白色複選標記符號的 Workforce 租使用者 外部租使用者（深入瞭解）

下列範例顯示以最少程式碼透過互動方式取得權杖，以使用 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。 它包含字串的列舉，這些字串會定義需要權杖的範圍。 如果權杖是用於 Microsoft Graph，則您可以在名為「權限」的區段中，於每個 Microsoft Graph API 的 API 參考中找到所需的範圍。例如，若要 列出用戶的聯繫人 ，您必須同時使用 User.Read 和 Contacts.Read 作為範圍。 如需詳細資訊，請參閱 Microsoft Graph 權限參考。

在桌面和行動應用程式上，請務必使用 .WithParentActivityOrWindow 來指定父代。 在許多情況下，這是一項需求，而且 MSAL 會引發例外狀況。

針對桌面應用程式，請參閱 父視窗控制代碼。

針對行動應用程式，提供 Activity （Android） 或 UIViewController （iOS）。

MSAL.NET 中的選擇性參數

WithParentActivityOrWindow

UI 很重要，因為其為互動式的。 AcquireTokenInteractive 具有一個特定的可選參數，可以（針對支援的平台）指定其父 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 值在 Android 上為 Activity、在 iOS 上為 UIViewController、在 Mac 上為 NSWindow，以及在 Windows 上為 IWin32Window 或 IntPr。

• 在 Windows 上，您必須從 UI 執行緒呼叫 AcquireTokenInteractive，讓內嵌瀏覽器取得適當的 UI 同步處理內容。 若不是從 UI 執行緒呼叫，可能會導致訊息無法正確處理，從而引發與 UI 的死鎖情況。 如果您尚未在 UI 執行緒上，則從 UI 執行緒呼叫 Microsoft 驗證程式庫 (MSAL) 的其中一種方式，是在 Windows Presentation Foundation (WPF) 上使用 Dispatcher。

• 如果您使用的是 WPF，若要從 WPF 控制項取得視窗，可以使用 WindowInteropHelper.Handle 類別。 然後呼叫是來自 WPF 控制項 (this)：

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

帶提示

您使用 WithPrompt() 來透過指定提示，以控制使用者的互動性。 您可以使用 Microsoft.Identity.Client.Prompt 結構來控制確切的行為。

結構會定義下列常數：

• SelectAccount 強制安全權杖服務 (STS) 呈現包含使用者當前工作階段的帳戶的帳戶選擇對話方塊。 這個選項是預設值。 當您想要讓使用者在不同的身分識別之間選擇時，這會很有用。

  此選項會驅動 MSAL，以將 prompt=select_account 傳送至識別提供者。 它會根據可用資訊提供最佳體驗，例如帳戶資訊和用戶會話的存在。 除非您有充分的理由，否則請不要對其進行變更。

• Consent 可讓您強制提示使用者同意，即使之前應用程式已授與同意亦然。 在此情況下，MSAL 會將 prompt=consent 傳送給識別提供者。 您可以在某些以安全性為主的應用程式中使用此選項，在組織治理要求每次使用者開啟應用程式時，向使用者顯示同意對話方塊。

• ForceLogin 可讓您讓應用程式提示使用者輸入認證，即使可能不需要此使用者提示也一樣。 如果取得權杖失敗，此選項有助於讓使用者再次登入。 在此情況下，MSAL 會將 prompt=login 傳送給識別提供者。 組織有時會在以安全性為主的應用程式中使用此選項，其中治理要求使用者在每次存取應用程式的特定部分時登入。

• Create 會透過將 prompt=create 傳送至識別提供者，以觸發用於外部身分識別的註冊體驗。 Azure Active Directory B2C （Azure AD B2C） 應用程式不應該傳送此提示。 如需詳細資訊，請參閱將自助註冊使用者流程新增至應用程式。

• Never (僅限 .NET 4.5 和 Windows 執行階段) 不會提示使用者。 相反地，它會嘗試使用儲存在隱藏內嵌網頁檢視中的 Cookie。

  使用此選項可能會失敗。 在此情況下，AcquireTokenInteractive 會擲回例外狀況，通知您需要 UI 互動。 然後使用另一個 Prompt 參數。

• NoPrompt 不會將任何提示傳送給識別提供者。 身分識別提供者會決定哪個登入體驗最適合使用者（單一登錄或選取帳戶）。

  此選項是編輯 Azure AD B2C 中配置文件原則的必要選項。 如需詳細資訊，請參閱 Azure AD B2C 詳細資料。

WithUseEmbeddedWebView

這個方法可讓您指定是否要強制使用內嵌的 WebView 或系統 WebView (可用時)。 如需詳細資訊，請參閱網頁瀏覽器的使用方式。

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

附加同意範圍

此修飾元適用於您希望使用者事先同意數個資源的進階案例，而且您不想使用增量同意。 開發人員通常會使用增量同意搭配 MSAL.NET 和 Microsoft 身分識別平台。

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

WithCustomWebUi

Web UI 是用來叫用瀏覽器的機制。 這種機制可以是專用的 UI WebBrowser 控制項或委派開啟瀏覽器的方式。 MSAL 為大部分的平台提供 web UI 實作，但在這些情況下，您可能會想要自行裝載瀏覽器：

• 您有 MSAL 未明確涵蓋的平台，例如 Blazor、Unity 和桌上型電腦的 Mono。
• 您要對應用程式進行 UI 測試，並使用可與 Selenium 搭配使用的自動化瀏覽器。
• 執行 MSAL 的瀏覽器和應用程式位於不同的程序中。

為達此目的，您會提供 MSAL start Url，這需要在瀏覽器中顯示，以便使用者可以輸入例如使用者名稱等項目。 驗證完成之後，您的應用程式必須傳送回 MSAL end Url，其中包含 Microsoft Entra ID 提供的程式碼。 end Url 的主機一律為 redirectUri。 若要攔截 end Url，請執行下列其中一項動作：

• 監視瀏覽器重定向，直到達到 redirect Url 為止。
• 讓瀏覽器重新導向至您所監視的 URL。

WithCustomWebUi 是擴充點，可用來在公用用戶端應用程式中提供您自己的 UI。 您也可以讓使用者通過識別提供者的 /Authorize 端點，並讓他們登入和同意。 接著，MSAL.NET 可以兌換驗證碼並取得 token。

例如，您可以使用 Visual Studio 中的 WithCustomWebUi 讓 Electron 應用程式（例如 Visual Studio 意見反應）提供 Web 互動，但將其保留給 MSAL.NET 來執行大部分的工作。 如果您想要提供 UI 自動化，也可以使用 WithCustomWebUi。

在公用用戶端應用程式中，MSAL.NET 會使用程式碼交換證明金鑰 (PKCE) 標準，以確保遵守安全性。 只有 MSAL.NET 可以兌換程式碼。 如需詳細資訊，請參閱 RFC 7636 - OAuth 公用用戶端的程式碼交換證明金鑰。

using Microsoft.Identity.Client.Extensions;

使用 WithCustomWebUI

若要使用 WithCustomWebUI，請遵循下列步驟：

1. 實作 ICustomWebUi 介面。 如需詳細資訊，請參閱此 GitHub 頁面。

2. 實作一個 AcquireAuthorizationCodeAsync 方法，並接受 MSAL.NET 所計算的授權碼 URL。

3. 讓使用者與識別提供者進行身份驗證互動，並返回識別提供者用於回呼到您實作的 URL 和授權碼。 如果您有任何問題，則您的實作應該拋出 MsalExtensionException 例外，以便與 MSAL 合作。

4. 在您的 AcquireTokenInteractive 呼叫中，使用 .WithCustomUI() 修飾元時，傳遞您的自訂網頁 UI 的實例：

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

MSAL.NET 小組已重新撰寫 UI 測試，以使用此擴充性機制。 如果您想了解，請查看 MSAL.NET 原始程式碼中的 SeleniumWebUI 類別。

提供絕佳的 SystemWebViewOptions 體驗

從 MSAL.NET 4.1 SystemWebViewOptions 中，您可以指定：

• 在系統網頁瀏覽器中出現登入或同意錯誤時，所要前往的 URI (BrowserRedirectError) 或所要顯示的 HTML 片段 (HtmlMessageError)。
• 在成功登入或同意時，所要前往的 URI (BrowserRedirectSuccess) 或所要顯示的 HTML 片段 (HtmlMessageSuccess)。
• 要執行以啟動系統瀏覽器的動作。 您可以透過設定 OpenBrowserAsync 委託來提供自己的實作方式。 類別也提供兩個瀏覽器的預設實作：適用於 Microsoft Edge 的 OpenWithEdgeBrowserAsync 以及 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 Node 中，您可以透過授權碼流程取得用於代碼交換的證明密鑰 (PKCE)。 流程有兩個步驟：

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 身分識別平台 桌面程式代碼範例