迁移 Node.js 应用程序以使用 Azure SQL Database 的无密码连接

适用于：Azure SQL Database

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

以下教程介绍如何迁移现有 Node.js 应用程序以连接到Azure SQL Database以使用无密码连接，而不是用户名和密码解决方案。

配置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 参与者角色分配给指定的帐户。此角色允许标识读取、写入和修改数据库的数据和架构。有关分配的角色的详细信息，请参阅固定数据库角色。

更新本地连接配置

为应用程序创建环境设置。

AZURE_SQL_SERVER=<YOURSERVERNAME>.database.chinacloudapi.cn
AZURE_SQL_DATABASE=<YOURDATABASENAME>
AZURE_SQL_PORT=1433

现有使用Node.js SQL 驱动程序（tedious）连接到 Azure SQL 数据库的应用程序代码在无密码连接方面仅需做少量更改。若要使用用户分配的托管标识，请传递和authentication.type属性。

import sql from 'mssql';

// Environment settings - no user or password
const server = process.env.AZURE_SQL_SERVER;
const database = process.env.AZURE_SQL_DATABASE;
const port = parseInt(process.env.AZURE_SQL_PORT);

// Passwordless configuration
const config = {
    server,
    port,
    database,
    authentication: {
        type: 'azure-active-directory-default',
    },
    options: {
        encrypt: true,
        clientId: process.env.AZURE_CLIENT_ID  // <----- user-assigned managed identity        
    }
};

// Existing application code
export default class Database {
    config = {};
    poolconnection = null;
    connected = false;

    constructor(config) {
        this.config = config;
        console.log(`Database: config: ${JSON.stringify(config)}`);
    }

    async connect() {
        try {
            console.log(`Database connecting...${this.connected}`);
            if (this.connected === false) {
                this.poolconnection = await sql.connect(this.config);
                this.connected = true;
                console.log('Database connection successful');
            } else {
                console.log('Database already connected');
            }
        } catch (error) {
            console.error(`Error connecting to database: ${JSON.stringify(error)}`);
        }
    }

    async disconnect() {
        try {
            this.poolconnection.close();
            console.log('Database connection closed');
        } catch (error) {
            console.error(`Error closing database connection: ${error}`);
        }
    }

    async executeQuery(query) {
        await this.connect();
        const request = this.poolconnection.request();
        const result = await request.query(query);

        return result.rowsAffected[0];
    }
}

const databaseClient = new Database(config);
const result = await databaseClient.executeQuery(`select * from mytable where id = 10`);

环境变量 AZURE_CLIENT_ID 将在本教程的后面部分创建。

测试应用程序

在本地运行应用，并验证与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 参与者角色分配给用户分配的托管标识。此角色允许标识读取、写入和修改数据库的数据和架构。

重要

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

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

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

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

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

如果需要使用系统分配的托管身份标识，请省略属性。仍需要传递 authentication.type 属性。

const config = {
  server,
  port,
  database,
  authentication: {
    type: 'azure-active-directory-default'
  },
  options: {
    encrypt: true
  }
};

测试应用程序

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

Last updated on 2026-03-10

通过

迁移 Node.js 应用程序以使用 Azure SQL Database 的无密码连接

配置Azure SQL Database

配置本地开发环境

登录到Azure

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

更新本地连接配置

测试应用程序

配置Azure托管环境

创建托管标识

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

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

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

测试应用程序

相关内容

其他资源