迁移Python应用程序以将无密码连接与Azure SQL Database配合使用

适用于：Azure SQL Database

必须对Azure SQL Database的应用程序请求进行身份验证。尽管有多个选项可用于对Azure SQL Database进行身份验证，但应尽可能确定应用程序中的无密码连接优先级。使用密码或密钥的传统身份验证方法会产生安全风险和复杂性。访问 Azure 服务的无密码连接中心，详细了解迁移到无密码连接的优势。以下教程介绍如何迁移现有Python应用程序以连接到Azure SQL Database以使用无密码连接，而不是用户名和密码解决方案。

mssql-python 驱动程序提供对Microsoft Entra身份验证的内置支持，使无密码连接简单明了，只需更改最少的代码。

配置Azure SQL Database

无密码连接使用Microsoft Entra身份验证连接到Azure服务，包括Azure SQL Database。 Microsoft Entra身份验证，可以在中心位置管理标识以简化权限管理。详细了解如何为Azure SQL Database配置Microsoft Entra身份验证：

在此迁移指南中，请确保已在 Azure SQL 数据库中分配了一名 Microsoft Entra 管理员。

请导航到您的逻辑服务器上的Microsoft Entra页面。
选择 Set admin 打开 Microsoft Entra ID 浮出控件菜单。
在 Microsoft Entra ID 浮出控件菜单中，搜索要分配为管理员的用户。
选择该用户，然后选择“选择”。

一个显示如何启用 Microsoft Entra 管理员的屏幕截图。

配置本地开发环境

可以将无密码连接配置为同时适用于本地和Azure托管环境。在本部分中，将应用配置，以允许单个用户向Azure SQL Database进行身份验证，以便进行本地开发。

对于本地开发，请确保使用要用于访问Azure SQL Database的同一Microsoft Entra帐户登录。可以通过常用的开发工具（如Azure CLI或Azure PowerShell）进行身份验证。可用于进行身份验证的开发工具因语言而异。

使用以下命令通过Azure CLI登录Azure。这适用于 Windows、macOS 和 Linux。

az login

对于Visual Studio Code，请使用集成终端中的Azure CLI登录：

在 VS Code 中打开终端（终端 > 新终端）。
使用以下命令登录到Azure：
```
az login
```

此方法可在 Windows、macOS 和 Linux 之间可靠地工作。

通过以下命令使用 PowerShell 登录到Azure：

Connect-AzAccount -Environment AzureChinaCloud

创建数据库用户并分配角色

在Azure SQL Database中创建用户。用户应对应于您在登录到 Azure 部分中本地登录的 Azure 帐户。

在 Azure 门户中，浏览到 SQL 数据库并选择 Query 编辑器（预览版）。
选择屏幕右侧的“以 <your-username> 身份继续”，使用你的帐户登录到数据库。
在查询编辑器视图中，运行以下 T-SQL 命令：
```
CREATE USER [user@domain] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [user@domain];
ALTER ROLE db_datawriter ADD MEMBER [user@domain];
ALTER ROLE db_ddladmin ADD MEMBER [user@domain];
GO
```
运行这些命令会将 SQL DB 参与者角色分配给指定的帐户。此角色允许标识读取、写入和修改数据库的数据和架构。有关分配的角色的详细信息，请参阅固定数据库角色。

更新本地连接配置

迁移到无密码连接的mssql-python只需要更改连接字符串。驱动程序内置了对Microsoft Entra身份验证模式的支持，无需手动处理令牌。

from os import getenv
from dotenv import load_dotenv
from mssql_python import connect

load_dotenv()

connection_string = getenv("AZURE_SQL_CONNECTIONSTRING")

def get_all():
    with connect(connection_string) as conn:
        cursor = conn.cursor()
        cursor.execute("SELECT * FROM Persons")
        # Do something with the data
    return

要更新引用的连接字符串（AZURE_SQL_CONNECTIONSTRING），请在项目文件夹中创建一个 ActiveDirectoryDefault 文件，采用无密码格式的连接字符串，并使用 .env 身份验证。

AZURE_SQL_CONNECTIONSTRING=Server=tcp:<database-server-name>.database.chinacloudapi.cn,1433;Database=<database-name>;Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;Authentication=ActiveDirectoryDefault

ActiveDirectoryDefault无需交互式登录即可自动发现来自多个源（Azure CLI、环境变量、Visual Studio等）的凭据。此方法便于开发，但会增加延迟，因为它按顺序尝试每个凭据源。

重要

ActiveDirectoryDefault 仅用于本地开发。它会按顺序尝试多种身份验证方法，从而增加延迟，并可能导致生产中出现意外行为。在生产环境中，针对您的场景选择合适的身份验证方法。

Azure App Service/Functions：使用 ActiveDirectoryMSI （托管身份）
交互式用户登录：使用 ActiveDirectoryInteractive
服务主体：使用 ActiveDirectoryServicePrincipal

测试应用程序

在本地运行应用，并验证与Azure SQL Database的连接是否按预期工作。请记住，更改Azure用户和角色可能需要几分钟才能通过Azure环境传播。你的应用程序现已配置为在本地运行，开发人员无需管理该应用程序本身的机密。

配置Azure托管环境

将应用配置为在本地使用无密码连接后，相同的代码可以在部署到Azure后对Azure SQL Database进行身份验证。以下各节介绍如何将已部署的应用程序配置为使用托管标识连接到 Azure SQL Database。托管标识在 Microsoft Entra ID（以前称为 Azure Active Directory）中提供自动托管身份，以便应用程序在连接到支持 Microsoft Entra 身份验证的资源时使用。了解有关托管标识的更多信息：

创建托管标识

使用Azure门户或Azure CLI创建用户分配的托管标识。应用程序将使用该标识向其他服务进行身份验证。

Azure 门户
Azure CLI

在 Azure 门户顶部，搜索 托管标识。选择“托管标识”结果。
选择“托管标识”概述页顶部的“+ 创建”。
在“基本信息”选项卡中，输入以下值：
- “订阅”：选择所需的订阅。
- “资源组”：选择所需的资源组。
- 区域：选择你所在位置附近的区域。
- 名称：输入标识的可识别名称，例如 MigrationIdentity。
在页面底部选择查看 + 创建。
验证检查完成后，选择“创建”。 Azure创建新的用户分配标识。

创建资源后，选择“转到资源”以查看托管标识的详细信息。

一张屏幕截图显示如何使用 Azure 门户创建托管标识。

使用 az identity create 命令创建用户分配的托管标识：

az identity create --name MigrationIdentity --resource-group <resource-group>

将托管标识与 Web 应用相关联

配置 Web 应用以使用你创建的用户分配的托管标识。

Azure 门户
Azure CLI

在 Azure 门户中完成以下步骤，将用户分配的托管标识与应用相关联。这些步骤适用于以下Azure服务：

Azure Spring Apps
Azure Container Apps
Azure虚拟机
Azure Kubernetes Service

导航到 Web 应用的概述页面。
从左侧导航中选择“标识”。
在“标识”页上，切换到“用户分配”选项卡。
选择“+ 添加”，打开“添加用户分配的托管标识”浮出控件。
选择之前用于创建标识的订阅。
按名称搜索 MigrationIdentity，并从搜索结果中将其选中。
选择“添加”，以将该标识与应用相关联。

使用以下Azure CLI命令将标识与应用相关联：

检索使用 az identity show 命令创建的托管标识的完全限定资源 ID。复制输出值以在下一步中使用。

az identity show --name MigrationIdentity -g <your-identity-resource-group-name> --query id

可以使用 az webapp identity assign 命令将托管标识分配给Azure App Service实例。参数 --identities 需要在上一步中检索到的托管标识的完全限定资源 ID。完全限定资源 ID 以“/subscriptions/{subscriptionId}”或“/providers/{resourceProviderNamespace}/”开头。

az webapp identity assign \
    --resource-group <resource-group-name> \
    --name <webapp-name> \
    --identities <managed-identity-id>

如果使用 Git Bash，请在使用完全限定的资源 ID 时注意路径转换。若要禁用路径转换，请将 MSYS_NO_PATHCONV=1 添加到命令的开头。有关详细信息，请参阅资源 ID 的自动转换。

可以使用 Azure CLI 中的 az spring app identity assign 命令将托管标识分配给Azure Spring Apps实例。

az spring app identity assign \
    --resource-group <resource-group-name> \
    --name <app-name> \
    --service <service-name> \
    --user-assigned <managed-identity-id>

可以使用 az containerapp identity assign 命令将托管标识分配给虚拟机。

az containerapp identity assign \
    --resource-group <resource-group-name> \
    --name <app-name> \
    --user-assigned <managed-identity-id>

可以使用 az vm identity assign 命令将托管标识分配给虚拟机。

az vm identity assign \
    --resource-group <resource-group-name> \
    --name <virtual-machine-name> \
    --identities <managed-identity-id>

可以使用 az aks update 命令将托管标识分配给Azure Kubernetes Service (AKS)实例。

az aks update \
    --resource-group <resource-group-name> \
    --name <cluster-name> \
    --enable-managed-identity \
    --assign-identity <managed-identity-id> \
    --assign-kubelet-identity <managed-identity-id>

为身份创建数据库用户并分配角色

创建一个映射回用户分配的托管标识的 SQL 数据库用户。向用户分配所需的 SQL 角色，以允许应用读取、写入和修改数据库的数据和架构。

在 Azure 门户中，浏览到 SQL 数据库并选择 Query 编辑器（预览版）。
选择屏幕右侧的“以 <username> 身份继续”，使用你的帐户登录到数据库。

在查询编辑器视图中，运行以下 T-SQL 命令：

CREATE USER [user-assigned-identity-name] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [user-assigned-identity-name];
ALTER ROLE db_datawriter ADD MEMBER [user-assigned-identity-name];
ALTER ROLE db_ddladmin ADD MEMBER [user-assigned-identity-name];
GO

运行这些命令会将 SQL DB 参与者角色分配给用户分配的托管标识。此角色允许标识读取、写入和修改数据库的数据和架构。

重要

在企业生产环境中分配数据库用户角色时请谨慎。在这些情况下，应用程序不应使用单个提升的权限执行所有操作。通过为特定任务配置具有特定权限的多个标识，尝试实现最低特权原则。

若要详细了解如何配置数据库角色和安全性，可以阅读以下资源：

更新连接字符串

更新 Azure 应用配置，以使用与托管标识 ActiveDirectoryMSI 身份验证配合的免密码连接字符串格式。

连接字符串可以作为环境变量存储在应用托管环境中。以下说明侧重于应用服务，但其他Azure托管服务提供类似的配置。

Server=tcp:<database-server-name>.database.chinacloudapi.cn,1433;Database=<database-name>;Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;Authentication=ActiveDirectoryMSI

<database-server-name> 是Azure SQL Database服务器的名称，<database-name>是Azure SQL Database的名称。

为托管标识客户端 ID 创建应用设置

若要使用用户分配的托管标识，请创建一个 AZURE_CLIENT_ID 环境变量，并将其设置为等于托管标识的客户端 ID。可以在Azure门户中应用的 Configuration 部分中设置此变量。可以在 Azure 门户中托管标识资源的 Overview 节中找到客户端 ID。

保存更改并重启应用程序（如果应用程序未自动执行此操作）。

注意事项

使用用户分配的托管标识时，使用 User Id 参数在connection string中包含客户端 ID：

Server=tcp:<database-server-name>.database.chinacloudapi.cn,1433;Database=<database-name>;Encrypt=yes;TrustServerCertificate=no;Connection Timeout=30;Authentication=ActiveDirectoryMSI;User Id=<managed-identity-client-id>

如果省略参数 User Id ，驱动程序将使用系统分配的托管标识（如果已配置）。

测试应用程序

测试应用，确保一切仍然正常。通过Azure环境传播所有更改可能需要几分钟时间。

Last updated on 2026-03-10

通过

迁移Python应用程序以将无密码连接与Azure SQL Database配合使用

配置Azure SQL Database

配置本地开发环境

登录到Azure

创建数据库用户并分配角色

更新本地连接配置

测试应用程序

配置Azure托管环境

创建托管标识

将托管标识与 Web 应用相关联

为身份创建数据库用户并分配角色

更新连接字符串

为托管标识客户端 ID 创建应用设置

测试应用程序

相关内容

其他资源