调用 Web API 的桌面应用：代码配置

2025-10-17

本文包含有关如何使用应用程序坐标配置代码的说明。

先决条件

在 Microsoft Entra 管理中心注册一个新应用，并配置为仅适用于此组织目录中的帐户。有关更多详细信息，请参阅注册应用程序。在应用程序概述页中记录以下值供以后使用：
- 应用程序（客户端）ID
- 目录（租户）ID

添加平台重定向 URI

若要将应用类型指定到应用注册，请执行以下步骤：

在“管理”下，选择“身份验证>添加平台>移动和桌面应用程序”
根据所使用的身份验证方法，选择以下选项之一：
- 对于使用嵌入式浏览器的应用，请使用确切值： https://login.partner.microsoftonline.cn/common/oauth2/nativeclient
- 对于使用系统浏览器的应用，请使用确切值： http://localhost
- 适用于 macOS 的 Objective-C 或 Swift 应用： msauth.<your.app.bundle.id>://auth.
- Node.js Electron 应用： msal{Your_Application/Client_Id}://auth

注释

对于 Web 身份验证管理器（WAM）应用，MSAL 中不需要重定向 URI。

启用公共客户端流

若要使用守护程序应用程序中使用的客户端凭据流区分设备代码流、集成的 Windows 身份验证以及用户名和密码，无需重定向 URI，请将其配置为公共客户端应用程序。实现此配置

若要将应用标识为公共客户端，请执行以下步骤：

在“管理”下，选择“身份验证”。
在“高级设置”下，对于“允许公共客户端流”，选择“是”。
选择保存以保存更改。

支持桌面应用的 Microsoft 库

以下 Microsoft 库支持桌面应用：

语言/框架	项目 GitHub	包	获取 started	正式发布 (GA) 或公共预览版¹
Electron	MSAL Node.js	msal-node	—	公共预览版
Java	MSAL4J	msal4j	—	GA
macOS （Swift/Obj-C）	适用于 iOS 和 macOS 的 MSAL	MSAL	教程	GA
UWP	MSAL.NET	Microsoft.Identity.Client	教程	GA
WPF	MSAL.NET	Microsoft.Identity.Client	教程	GA

¹联机服务通用许可条款适用于公共预览版中的库。

公共客户端应用程序

从代码的角度看，桌面应用程序是公共客户端应用程序。根据是否使用交互式身份验证，配置将略有不同。

需要生成并操作 MSAL.NET IPublicClientApplication。

IPublicClientApplication

以独占方式通过代码来完成

以下代码实例化公共客户端应用程序，使用工作或学校帐户在由世纪互联运营的 Microsoft Azure 中将用户登录。

IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)
    .Build();

如果打算使用交互式身份验证或设备代码流，如上所示，请使用 .WithRedirectUri 修饰符。

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithDefaultRedirectUri()
        .Build();

使用配置文件

以下代码通过一个配置对象实例化公共客户端应用程序，该对象可以通过编程方式进行填充，也可以从配置文件读取。

PublicClientApplicationOptions options = GetOptions(); // your own method
IPublicClientApplication app = PublicClientApplicationBuilder.CreateWithApplicationOptions(options)
        .WithDefaultRedirectUri()
        .Build();

更详细的配置

可以通过添加多个修饰符来详细阐述应用程序的构建。

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithDefaultRedirectUri()
        .WithAadAuthority(AzureCloudInstance.AzureChina,
                         AadAuthorityAudience.AzureAdMultipleOrgs)
        .Build();

MSAL.NET 还包含 Active Directory 联合身份验证服务 2019 的修饰符：

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAdfsAuthority("https://consoso.com/adfs")
        .Build();

最后，如果要获取 Azure Active Directory (Azure AD) B2C 租户的令牌，请指定你的租户，如以下代码片段所示：

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithB2CAuthority("https://fabrikamb2c.b2clogin.cn/tfp/{tenant}/{PolicySignInSignUp}")
        .Build();

了解详细信息

若要详细了解如何配置 MSAL.NET 桌面应用程序，请执行以下操作：

如需 PublicClientApplicationBuilder 上提供的所有修饰符的列表，请参阅参考文档 PublicClientApplicationBuilder。
如需 PublicClientApplicationOptions 中公开的所有选项的说明，请参阅参考文档中的 PublicClientApplicationOptions。

包含配置选项的完整示例

假设有一个 .NET 控制台应用程序，其中包含以下 appsettings.json 配置文件：

{
  "Authentication": {
    "AzureCloudInstance": "AzureChina",
    "AadAuthorityAudience": "AzureAdMultipleOrgs",
    "ClientId": "00001111-aaaa-2222-bbbb-3333cccc4444"
  },

  "WebAPI": {
    "MicrosoftGraphBaseEndpoint": "https://microsoftgraph.chinacloudapi.cn"
  }
}

使用 .NET 提供的配置框架时，此文件中只有少量代码可以读取：

public class SampleConfiguration
{
 /// <summary>
 /// Authentication options
 /// </summary>
 public PublicClientApplicationOptions PublicClientApplicationOptions { get; set; }

 /// <summary>
 /// Base URL for Microsoft Graph (it varies depending on whether the application runs
 /// in Azure public clouds or national or sovereign clouds)
 /// </summary>
 public string MicrosoftGraphBaseEndpoint { get; set; }

 /// <summary>
 /// Reads the configuration from a JSON file
 /// </summary>
 /// <param name="path">Path to the configuration json file</param>
 /// <returns>SampleConfiguration as read from the json file</returns>
 public static SampleConfiguration ReadFromJsonFile(string path)
 {
  // .NET configuration
  IConfigurationRoot Configuration;
  var builder = new ConfigurationBuilder()
                    .SetBasePath(Directory.GetCurrentDirectory())
                    .AddJsonFile(path);
  Configuration = builder.Build();

  // Read the auth and graph endpoint configuration
  SampleConfiguration config = new SampleConfiguration()
  {
   PublicClientApplicationOptions = new PublicClientApplicationOptions()
  };
  Configuration.Bind("Authentication", config.PublicClientApplicationOptions);
  config.MicrosoftGraphBaseEndpoint =
  Configuration.GetValue<string>("WebAPI:MicrosoftGraphBaseEndpoint");
  return config;
 }
}

现在，若要创建你的应用程序，请编写以下代码：

SampleConfiguration config = SampleConfiguration.ReadFromJsonFile("appsettings.json");
var app = PublicClientApplicationBuilder.CreateWithApplicationOptions(config.PublicClientApplicationOptions)
           .WithDefaultRedirectUri()
           .Build();

在调用 .Build() 方法之前，可以通过调用 .WithXXX 方法来重写配置，如前所示。

下面是 MSAL Java 开发示例中用于配置示例的类：TestData。

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

以下代码实例化公共客户端应用程序，使用工作或学校帐户在 Azure 公有云中将用户登录。

快速配置

Objective-C：

NSError *msalError = nil;

MSALPublicClientApplicationConfig *config = [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"];
MSALPublicClientApplication *application = [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&msalError];

Swift：

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>")
if let application = try? MSALPublicClientApplication(configuration: config){ /* Use application */}

更详细的配置

可以通过添加多个修饰符来详细阐述应用程序的构建。例如，如果希望应用程序成为国家/地区云（例如此处显示的美国政府）中的多租户应用程序，可以编写：

Objective-C：

MSALAADAuthority *aadAuthority =
                [[MSALAADAuthority alloc] initWithCloudInstance:MSALAzureUsGovernmentCloudInstance
                                                   audienceType:MSALAzureADMultipleOrgsAudience
                                                      rawTenant:nil
                                                          error:nil];

MSALPublicClientApplicationConfig *config =
                [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"
                                                                redirectUri:@"<your-redirect-uri-here>"
                                                                  authority:aadAuthority];

NSError *applicationError = nil;
MSALPublicClientApplication *application =
                [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&applicationError];

Swift：

let authority = try? MSALAADAuthority(cloudInstance: .usGovernmentCloudInstance, audienceType: .azureADMultipleOrgsAudience, rawTenant: nil)

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>", redirectUri: "<your-redirect-uri-here>", authority: authority)
if let application = try? MSALPublicClientApplication(configuration: config) { /* Use application */}

可以从多个源（如 JavaScript 文件或环境变量）加载配置参数。下面使用了 authConfig.js 文件。

/*
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */

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

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL.js configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
const AAD_ENDPOINT_HOST = "Enter_the_Cloud_Instance_Id_Here"; // include the trailing slash

const msalConfig = {
    auth: {
        clientId: "Enter_the_Application_Id_Here",
        authority: `${AAD_ENDPOINT_HOST}Enter_the_Tenant_Info_Here`,
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: LogLevel.Verbose,
        },
    },
};

/**
 * Add here the endpoints and scopes when obtaining an access token for protected web APIs. For more information, see:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/resources-and-scopes.md
 */
const GRAPH_ENDPOINT_HOST = "Enter_the_Graph_Endpoint_Here"; // include the trailing slash

const protectedResources = {
    graphMe: {
        endpoint: `${GRAPH_ENDPOINT_HOST}v1.0/me`,
        scopes: ["User.Read"],
    }
};


module.exports = {
    msalConfig: msalConfig,
    protectedResources: protectedResources,
};

从 authConfig.js 文件导入配置对象。 MSAL 节点能够最低限度进行初始化，如下所示。请参阅可用的配置选项。

const { PublicClientApplication } = require('@azure/msal-node');
const { msalConfig } = require('./authConfig')

/**
* Initialize a public client application. For more information, visit:
* https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/initialize-public-client-application.md
*/
clientApplication = new PublicClientApplication(msalConfig);

config = json.load(open(sys.argv[1]))

app = msal.PublicClientApplication(
    config["client_id"], authority=config["authority"],
    # token_cache=...  # Default cache is in memory only.
                       # You can learn how to use SerializableTokenCache from
                       # https://msal-python.rtfd.io/en/latest/#msal.SerializableTokenCache
    )

后续步骤

转到此方案中的下一篇文章：获取桌面应用的令牌。

共用方式為

调用 Web API 的桌面应用：代码配置

先决条件

添加平台重定向 URI

启用公共客户端流

支持桌面应用的 Microsoft 库

公共客户端应用程序

以独占方式通过代码来完成

使用配置文件

更详细的配置

了解详细信息

包含配置选项的完整示例

后续步骤

其他資源