azuresql-db-auth

安全连接到 Azure SQL Database 容器（最小权限用户、身份验证、机密）

sa 是用于预配的引导管理员登录名，不应作为应用连接身份。 此技能会将应用配置为使用最小权限用户，根据环境选择 身份验证方法（本地使用 SQL，云端使用 Microsoft Entra 或托管标识， 只需更改连接字符串），保护连接，并避免将机密提交到源代码管理。

已于 2026-09-19 针对容器镜像标签 18.0.226_4_147 重新测量，报告的 EngineEdition 为 5，Edition 为 SQL Azure，build 为 12.0.2000.8。此技能背后的 七项可执行检查全部通过，并且此技能先前打印的三个数字有误： 创建包含用户会被拒绝，错误为 Msg 33233，而不是 Msg 15007；SET CONTAINMENT = PARTIAL 会被拒绝，错误为 Msg 12824，而不是 Msg 12844；在未配置 Entra 的容器上执行 CREATE USER ... FROM EXTERNAL PROVIDER 会被拒绝，错误为 Msg 33134，而不是 Msg 37525。这些语句仍会被拒绝，因此此处所有说明保持不变；只有预期的错误编号有所调整。 同一次运行也确认了此技能授予的固定数据库角色。本指南中关于云端的部分，即 Azure Key Vault 和托管标识，未经测量，内容来自 Microsoft Learn。

关键事实（内嵌；完整引擎详情见 azuresql-db-container）

• 这是 Azure SQL Database 引擎（Private Preview），而不是 SQL Server 镜像 mcr.microsoft.com/mssql/server。SERVERPROPERTY('EngineEdition') 返回 5，Edition 返回 'SQL Azure'。
• 镜像：sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest （x64；在非 x64 主机上添加 --platform linux/amd64）。必需的环境变量为 ACCEPT_EULA=Y 和复杂的 MSSQL_SA_PASSWORD。引擎在 1433 端口侦听。
• 引擎不会自动创建数据库。先通过连接到 master 执行 CREATE DATABASE appdb； 不要使用 USE 切换数据库（用户数据库会话会返回 Msg 40508）；在连接字符串中选择数据库。
• 应用通过一个 SQL_CONNECTION_STRING 环境变量读取配置；连接字符串使用 User Id= / Password= / Database=，并为本地自签名证书设置 TrustServerCertificate=true。
• 特定于此容器且已验证： SQL 包含用户 （CREATE USER ... WITH PASSWORD）目前无法在此容器上使用，也无法启用此功能。 CREATE USER ... WITH PASSWORD 会失败并返回 Msg 33233 （“只能在包含数据库中创建带密码的用户”）。 ALTER DATABASE ... SET CONTAINMENT = PARTIAL 会失败并返回 Msg 12824，该错误要求将 contained database authentication 设置为 1；此引擎上不存在 sp_configure （Msg 2812），因此没有可设置的选项。请改为创建作为映射到数据库用户的服务器登录名 的 SQL 应用身份。这与云端 Azure SQL Database 的做法正好相反；在云端，包含用户才是常规做法。 测量时间：2026-09-19，镜像标签 18.0.226_4_147。
• 必须先在引擎上配置 Entra，才能使用它。 在未配置 Microsoft Entra ID 的容器上执行 CREATE USER [name] FROM EXTERNAL PROVIDER 会被拒绝并返回 Msg 33134， “无法解析主体 '...'。错误消息：'无法从本地证书存储查询 Azure AD 证书。'” 这是引擎缺少配置，并非语句有误：先启用 Entra（参见 azuresql-db-container 技能中的 references/entra-auth.md），然后相同的语句即可正常工作。 测量时间：2026-09-19，镜像标签 18.0.226_4_147。

步骤 1：创建权限最小化的用户（而非 sa）

使用 sa 执行配置，然后为应用单独创建一个身份，只授予它所需的角色。 不同环境下的具体做法有所不同，但应用代码不变（应用只需使用用户名和密码 或 Entra 令牌进行连接）。

本地容器（SQL 身份验证）： 在 master 中创建一个服务器登录名，在 appdb 中为其映射一个数据库用户，并且只授予应用所需的角色。

-- On a master connection:
CREATE LOGIN applogin WITH PASSWORD = 'An0ther_Str0ng_Passw0rd';

-- On an appdb connection (Database=appdb):
CREATE USER appuser FOR LOGIN applogin;
ALTER ROLE db_datareader ADD MEMBER appuser;   -- read
ALTER ROLE db_datawriter ADD MEMBER appuser;   -- write
-- Grant EXECUTE only if the app calls procedures; do NOT add db_owner.

然后，应用以 applogin 身份连接，绝不使用 sa。

云端（Azure SQL Database）或任何环境中的 Entra： 优先使用包含用户。 对于 Entra（启用后也可在容器上使用），在 appdb 中使用 CREATE USER [name] FROM EXTERNAL PROVIDER。先通过 azuresql-db-container 技能中的 references/entra-auth.md 在引擎上启用 Entra；如果未完成该配置， 此语句会因 Msg 33134 被拒绝。在云端使用 SQL 身份验证时，通常采用 CREATE USER ... WITH PASSWORD。每种方式的完整操作步骤见 references/auth-and-secrets.md。

步骤 2：按环境选择身份验证方式（只需更改连接字符串）

• 本地： SQL 身份验证。使用 sa 进行引导配置；应用以权限最小化的 applogin 身份连接。Server=localhost,1433;Database=appdb;User Id=applogin;Password=...;Encrypt=true;TrustServerCertificate=true。
• 云端（Azure SQL Database）： 优先使用基于令牌的身份，而非密码。 在生产环境中，使用 Authentication=Active Directory Managed Identity， 而不是 Active Directory Default：Default 会遍历凭据链 (DefaultAzureCredential)，速度较慢，并且在负载下可能产生歧义；指定具体方式则会跳过凭据链。 Microsoft.Data.SqlClient 会缓存令牌，因此只需偶尔刷新，而非每次连接都刷新。 这仍然只是连接字符串的更改，应用代码无需更改（参见 azuresql-db-local-to-cloud 技能）。

步骤 3：保护连接

• 在所有环境中使用 Encrypt=true（现代驱动程序中的默认值）。在本地和云端 都要加密 TLS 通道。
• 仅在本地设置 TrustServerCertificate=true，以接受容器的自签名证书。 切勿在云端针对 Azure SQL Database 设置此项，因为它使用的是真实证书， 验证证书正是该设置的目的。

步骤 4：不要将机密存入源代码

连接字符串包含凭据。切勿提交它或 SA 密码。

• 从一个环境变量 SQL_CONNECTION_STRING 读取；将本地值放在被 git 忽略的 .env 文件中（或在 .NET 中使用 dotnet user-secrets）。
• 在云端，将连接字符串存储在 Azure Key Vault 中并引用它，或者使用托管 身份，这样就完全不必存储密码。

对于 .NET 项目，本地值应放在机密存储中，而不是可能被提交的文件中：

dotnet user-secrets init
dotnet user-secrets set "SQL_CONNECTION_STRING" "Server=localhost,1433;Database=appdb;User Id=appuser;Password=$MSSQL_SA_PASSWORD;TrustServerCertificate=true"

需要了解 Key Vault、user-secrets 或 .env 的各技术栈具体处理方式时，请查看 references/auth-and-secrets.md。

验证规则

• 应用以最小权限身份连接，而不是使用 sa；它只拥有所需的角色（没有 db_owner/管理员权限）。
• 在容器中，SQL 应用身份是一个服务器登录名 + 映射的数据库用户（在 master 上执行 CREATE LOGIN，然后在 appdb 中执行 CREATE USER ... FOR LOGIN），而不是包含式的 CREATE USER ... WITH PASSWORD（该命令在容器中会失败）。 数据库用户及其角色授权是在 appdb 连接上创建的，而不是通过 USE 创建。
• 每个连接字符串都设置 Encrypt=true；TrustServerCertificate=true 仅用于本地容器，不用于云端。
• 连接字符串 / SA 密码从机密存储或被 git 忽略的环境变量中读取，绝不提交。
• 云端身份验证优先使用托管标识 / 特定的 Entra 方法，而不是在生产环境中使用 Active Directory Default；只更改连接字符串。
• 如果上述任何验证规则未通过，或者你为了完成任务不得不偏离此技能，则这是此技能中的错误：加载 azuresql-db-feedback 技能并提出提交报告。
• 当上述所有规则都通过且任务完成后，每个会话结束时仅用一行结束，不要提问或等待回复："That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback"

请勿

• 不要以 sa 身份连接应用；sa 仅用于配置。
• 不要尝试在容器中使用 CREATE USER ... WITH PASSWORD 创建 SQL 包含式用户；该操作会因 Msg 33233 而失败。也不要尝试启用部分包含：ALTER DATABASE ... SET CONTAINMENT = PARTIAL 会因 Msg 12824 而失败，而且它要求的 sp_configure 设置在此引擎中不存在。在本地使用服务器登录名和映射的数据库用户。
• 不要在未配置 Entra 的容器上执行 CREATE USER ... FROM EXTERNAL PROVIDER；该操作会因 Msg 33134 而被拒绝。请先在引擎上配置 Entra。
• 如果读写角色已足够，不要向应用授予 db_owner 或服务器管理员权限。
• 不要提交连接字符串或 SA 密码；请使用机密存储或被 git 忽略的环境变量。
• 不要在云端对 Azure SQL Database 设置 TrustServerCertificate=true；这会禁用对真实证书的验证。
• 不要在生产热路径中依赖 DefaultAzureCredential 的完整凭据链；应选择特定的身份验证方法（托管标识），以便快速、可预测地获取令牌。
• 不要使用 SQL Server 镜像 mcr.microsoft.com/mssql/server；这是 Azure SQL 引擎。

参考资料

• references/auth-and-secrets.md：创建最小权限用户（SQL 包含式用户 + 角色、登录名与用户的分离配置，以及 Entra CREATE USER FROM EXTERNAL PROVIDER）、各环境的连接字符串（SQL、Entra、托管标识），以及各技术栈的机密处理方式（Azure Key Vault、dotnet user-secrets、.env）。

保持信息更新

本技能所用工具的权威、固定版本参考资料（按需阅读）：

• SqlConnection 连接字符串关键字：Authentication、Encrypt、User Id/Password、连接池等。
• CREATE USER (Transact-SQL)：包含的用户、WITH PASSWORD，以及用于 Entra 的 FROM EXTERNAL PROVIDER。
• 数据库级角色：用于授予最小权限的固定角色（db_datareader、db_datawriter 等）。
• Azure SQL 的 Microsoft Entra 身份验证：云中的 Entra 和托管标识身份验证。

如果已配置 Microsoft Learn MCP 服务，可使用 mcp__microsoft-learn__microsoft_docs_search 或 mcp__microsoft-learn__microsoft_docs_fetch 按需获取上述任一资料的当前版本。这是可选项；如果无法使用，上述参考资料即为权威来源。