教程：代表已登录用户将应用服务应用连接到 SQL 数据库

本教程演示如何通过模拟已登录用户（也称为代理流）将 Azure 应用服务应用连接到后端 Azure SQL 数据库。 若要配置此流，请使用 Microsoft Entra 标识提供者启用应用服务 内置身份验证 。

此连接方法比教程中的托管标识方法更高级 ：使用托管标识访问数据，并在企业方案中具有以下优势：

• 与托管标识方法一样，这种方法也消除了与后端服务的连接密钥。
• 为后端数据库或其他 Azure 服务提供更多控制权，以控制向谁授予多少访问权限。
• 允许应用向已登录用户定制其数据呈现。

本教程将Microsoft Entra 身份验证添加到具有 Azure SQL 数据库后端的 .NET Web 应用。 你将学会如何：

完成本教程后，应用将代表已登录用户安全地连接到 SQL 数据库。

先决条件

• 有权访问其中包含用户和组的 Microsoft Entra 租户。

• 完成教程：在 Azure 应用服务 中构建 ASP.NET Core 和 SQL 数据库应用，并在本教程中使用完成后的应用。

  或者，调整步骤，并将自己的 .NET 应用与 SQL 数据库配合使用。 本教程中的步骤支持以下 .NET 版本：

  • .NET Framework 4.8 及更高版本
  • .NET 6.0 及更高版本

• 登录到 Azure Cloud Shell 或准备环境以使用 Azure CLI。

  • 如需在本地运行 CLI 参考命令，请安装 Azure CLI。 如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。 有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。

    • 如果使用本地安装，请使用 az login 命令登录到Azure CLI。 若要完成身份验证过程，请遵循终端中显示的步骤。 有关其他登录选项，请参阅使用 Azure CLI 登录。

    • 出现提示时，请在首次使用时安装 Azure CLI 扩展。 有关扩展的详细信息，请参阅 将扩展与 Azure CLI 配合使用。

    • 运行az version命令，以查看已安装的版本和依赖库。 若要升级到最新版本，请运行az upgrade。

1.为数据库服务器配置 Microsoft Entra 身份验证

通过将 Microsoft Entra 用户分配为 Azure SQL 服务器的管理员，启用对 Azure SQL 数据库的Microsoft Entra 身份验证。 Microsoft Entra 管理员必须是创建、导入、同步或邀请到 Microsoft Entra ID 的用户。 Microsoft Entra 用户可能与 Azure 订阅的 Microsoft 帐户用户不同。

若要将 Microsoft Entra ID 用户添加为 Azure SQL Server 的管理员，请运行以下 Azure CLI 命令。

1. 使用 az ad user list 以及 display-name、filter 或 upn 参数，获取要设为管理员的 Microsoft Entra ID 用户的对象 ID。例如，以下命令列出了 display-name 为 Firstname Lastname 的 Microsoft Entra ID 用户的信息。

   az ad user list --display-name "Firstname Lastname"
   

   id复制输出中的值，以在下一步中使用。

   提示

   可以独立运行 az ad user list ，以显示Microsoft Entra 目录中所有用户的信息。

2. 使用az sql server ad-admin createobject-id参数将 Microsoft Entra ID 用户添加为 Azure SQL Server 上的管理员。 在以下命令中，将 <group-name> 替换为服务器的资源组名称，将 <server-name> 替换为去掉 .database.chinacloudapi.cn 后缀后的服务器名称，并将 <entra-id> 替换为前面的 az ad user list 命令的 id 输出。

   az sql server ad-admin create --resource-group <group-name> --server-name <server-name> --display-name ADMIN --object-id <entra-id>
   

3. 仅将数据库服务器身份验证限制为Microsoft Entra 身份验证。 此步骤禁用 SQL 用户名和密码身份验证。

   az sql server ad-only-auth enable --resource-group <group-name> --name <server-name>
   

• 有关创建 Microsoft Entra 用户的详细信息，请参阅 使用 Microsoft Entra ID 添加或删除用户。
• 有关 SQL 数据库的允许Microsoft Entra 用户的详细信息，请参阅 SQL 数据库中Microsoft Entra 功能和限制。
• 有关添加 Azure SQL Server 管理员的详细信息，请参阅 为服务器预配Microsoft Entra 管理员。

2. 为应用启用Microsoft Entra ID 身份验证

将Microsoft Entra ID 添加为应用的标识提供者。 有关详细信息，请参阅为应用程序服务应用程序配置 Microsoft Entra 身份验证。

1. 在应用的 Azure 门户页上，在左侧导航菜单中的“设置”下选择“身份验证”。

2. 在“身份验证”页上，选择“添加标识提供者”，或在“标识提供者”部分选择“添加提供程序”。

3. 在 “添加标识提供者 ”页上，选择 Microsoft 作为提供程序。

4. 对于 客户端密码过期，请选择下拉列表选项之一，例如 建议：180 天。

5. 保留所有默认设置，然后选择“ 添加”。

   

3. 配置 SQL 数据库的用户模拟

授予应用程序权限，使其能够以已登录的 Microsoft Entra 用户身份访问 SQL 数据库。

1. 在应用的 “身份验证 ”页上，选择 标识提供者下的应用名称。

   此时会打开应用注册页。 添加 Microsoft Entra 提供程序时，会自动生成此注册。

2. 在左侧导航菜单中的“管理”下选择 API 权限。

3. 在 “API 权限 ”页上，选择“ 添加权限”。

4. 在 “请求 API 权限 ”屏幕上，选择 组织使用的 API 选项卡。

5. 在搜索框中输入 Azure SQL 数据库 ，然后选择结果。

6. 在 应用程序所需的权限类型下，选择 “委派权限”，然后选择 user_impersonation旁边的复选框，然后选择“ 添加权限”。

   

Microsoft Entra 中的应用注册现在具有通过模拟登录用户连接到 SQL 数据库所需的权限。

4. 配置应用服务，使之返回可用的访问令牌

若要将你的应用配置为可为 SQL 数据库提供可用的访问令牌，请将https://database.chinacloudapi.cn/user_impersonation作为scope添加到该应用的 Microsoft Entra 提供程序loginParameters中。 以下命令将 loginParameters 具有自定义作用域的属性添加到 Microsoft Entra 标识提供者 login 设置。

在所请求的作用域中，App Service 默认已请求 openid、profile 和 email 作用域。 之所以包含 offline_access scope，是为了让你能够刷新令牌。 有关详细信息，请参阅 OpenID Connect 作用域。

该 https://database.chinacloudapi.cn/user_impersonation 范围是指 Azure SQL 数据库，并提供一个 JSON Web 令牌（JWT），该令牌将 SQL 数据库指定为令牌接收方。 此命令用于 jq JSON 处理。

authSettings=$(az webapp auth show --resource-group <group-name> --name <app-name>)
authSettings=$(echo "$authSettings" | jq '.properties' | jq '.identityProviders.azureActiveDirectory.login += {"loginParameters":["scope=openid profile email offline_access https://database.chinacloudapi.cn/user_impersonation"]}')
az webapp auth set --resource-group <group-name> --name <app-name> --body "$authSettings"

应用现已配置为生成 SQL 数据库接受的访问令牌。

5. 在应用程序代码中使用访问令牌

更新应用程序代码，将应用服务身份验证提供的访问令牌添加到连接对象。

1. DbContext在DatabaseContext.cs或其他配置数据库上下文的文件的对象中，更改默认构造函数以将 Microsoft Entra ID 访问令牌添加到连接对象。

   public MyDatabaseContext (DbContextOptions<MyDatabaseContext> options, IHttpContextAccessor accessor)
       : base(options)
   {
       var conn = Database.GetDbConnection() as SqlConnection;
       conn.AccessToken = accessor.HttpContext.Request.Headers["X-MS-TOKEN-AAD-ACCESS-TOKEN"];
   }
   

2. 如果你在应用服务中有一个名为 defaultConnection 的连接字符串，并且它使用带用户名和密码的 SQL 身份验证，请使用以下命令删除连接字符串中的机密信息。 将 <group-name>、<app-name>、<db-server-name> 和 <db-name> 替换为自定义值。

   az webapp config connection-string set --resource-group <group-name> --name <app-name> --connection-string-type SQLAzure --settings defaultConnection="server=tcp:<db-server-name>.database.chinacloudapi.cn;database=<db-name>;"
   

6. 发布更改

如果在浏览器中使用 Visual Studio Code 在 GitHub 分支中进行更改，请从左侧菜单中选择 源代码管理 。 输入如下所示 OBO connect 的提交消息，然后选择 “提交”。

该提交会触发 GitHub Actions 到应用服务的部署。 请等待几分钟以便完成部署。

还可以使用以下命令在 Git Bash 中发布更改：

git commit -am "configure managed identity"
git push azure main

如果代码在 Visual Studio 中：

1. 在 解决方案资源管理器 中右键单击项目，然后选择“ 发布”。

   

2. 在“发布”页上选择“发布”。

当新应用页显示应用时，应用将代表已登录Microsoft Entra 用户连接到 Azure SQL 数据库。 应能够像往常一样使用和编辑应用。

7.清理资源

在前面的步骤中，你在资源组中创建了 Azure 资源。 如果不再需要这些资源，请运行以下命令删除资源组：

az group delete --name <group-name>

此命令可能需要一些时间才能运行。

常见问题

• 为什么会出现“用户 '<token-identified principal>' 登录失败”错误？
• 如何在 Azure SQL 数据库中添加其他 Microsoft Entra 用户或组？
• 使用应用服务身份验证时，如何在本地调试？
• 访问令牌过期时会发生什么情况？

为什么会出现“用户‘<令牌标识的主体>’登录失败”错误？

导致 Login failed for user '<token-identified principal>' 错误的最常见原因包括：

• 未为 Azure SQL 数据库配置 Microsoft Entra 身份验证。 请参阅 使用 Microsoft Entra 身份验证配置数据库服务器。
• X-MS-TOKEN-AAD-ACCESS-TOKEN 请求标头中没有有效令牌。 此代码在本地环境中不起作用。 有关详细信息和替代方法，请参阅 使用应用服务身份验证时在本地调试。
• 用户无权连接到数据库。 若要添加用户和权限，请参阅 在 Azure SQL 数据库中添加其他Microsoft Entra 用户或组。

如何在 Azure SQL 数据库中添加其他 Microsoft Entra 用户或组？

若要添加更多用户或组，请使用 sqlcmd 或 SQL Server Management Studio（SSMS）连接到数据库服务器，并创建映射到 Microsoft Entra 标识的 包含的数据库用户 。

以下 Transact-SQL 示例向 SQL Server 添加Microsoft Entra 标识，并为标识提供一些数据库角色：

CREATE USER [<user-or-group-name>] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [<user-or-group-name>];
ALTER ROLE db_datawriter ADD MEMBER [<user-or-group-name>];
ALTER ROLE db_ddladmin ADD MEMBER [<user-or-group-name>];
GO

使用应用服务身份验证时，如何在本地调试？

由于应用服务身份验证是一项 Azure 功能，因此本教程中的代码在本地环境中不起作用。 与在 Azure 中运行的应用不同，本地代码不会受益于应用服务身份验证中间件。 可以使用以下替代方法进行本地调试：

• 使用 Active Directory Interactive 身份验证从本地环境连接到 SQL 数据库。 此身份验证流不会登录用户本身，而是使用已登录用户连接到后端数据库，以便在本地测试数据库授权。
• 将访问令牌手动复制到代码中，代替 X-MS-TOKEN-AAD-ACCESS-TOKEN 请求标头。
• 如果从 Visual Studio 进行部署，请使用应用服务应用远程调试。

相关内容

• 教程：使用托管标识从应用服务连接到 Azure 数据库，而无需使用密钥

• 教程：以应用的形式从安全的 .NET 应用中访问 Microsoft Graph

• 将现有的自定义 DNS 名称映射到 Azure 应用服务