Azure Data Studio - Azure 连接

项目
01/05/2024

Azure Data Studio 默认使用Microsoft身份验证库（MSAL）从 Microsoft Entra ID 获取访问令牌。讨论适用于Microsoft Entra 身份验证的设置，以及常见的问题及其解决方案。

注意

虽然 Microsoft Entra ID 是 Azure Active Directory (Azure AD) 的新名称，但为了防止中断现有环境，Azure AD 仍保留在一些硬编码的元素中，例如 UI 字段、连接提供程序、错误代码和 cmdlet。在本文中，这两个名称可以互换。

Azure：身份验证库

此设置仅在 Azure Data Studio 1.41 到 1.45 版本中可用。它不再在 Azure Data Studio 1.46 及更高版本中可用。

此设置控制添加 Microsoft Entra 帐户时 Azure Data Studio 使用的身份验证库。 Microsoft 身份验证库 (MSAL) 使用 OAuth 2.0 和 OpenID Connect (OIDC) 1.0 的符合标准的实现提供身份验证和授权服务。详细了解 Microsoft 身份验证库 (MSAL)。在 Azure Data Studio 1.46 及更高版本中，MSAL 是唯一正在使用的库，因为 ADAL（Active Directory 身份验证库）已弃用。

Azure 身份验证方法

Azure Data Studio 支持使用以下模式Microsoft Entra 多重身份验证（MFA）：

使用代码授予身份验证（默认启用）
使用设备代码身份验证

“帐户”>“Azure”>“授权: 代码授予”

Settings.json

"accounts.azure.auth.codeGrant": true

Azure 身份验证代码授予选项的屏幕截图。

选中“代码授予方法”时，系统会提示用户使用基于浏览器的身份验证进行身份验证。默认情况下该选项处于启用状态。

“帐户”>“Azure”>“授权: 设备代码”

Settings.json

"accounts.azure.auth.deviceCode": true

Azure 身份验证设备代码选项的屏幕截图。

启用“设备代码方法”后，会向用户提供一个代码和一个要输入的 URL，用于在稍后登录时使用。

选中这两个选项后，在添加 Microsoft Entra 帐户时，系统会提示用户选择这两种身份验证模式之一。

Azure 云配置

Azure Data Studio 支持使用国家云Microsoft Entra 身份验证。 Azure 公有云默认启用，但用户可以根据需要启用其他国家云：

Settings.json

"accounts.azure.cloud.enableChinaCloud": false,
"accounts.azure.cloud.enablePublicCloud": true,
"accounts.azure.cloud.enableUsGovCloud": false

Azure 身份验证国家云的屏幕截图。

还可以定义自定义云终结点。请参阅配置自定义云终结点。

Azure 资源配置

这些设置对 Azure 资源和租户应用筛选器。

资源配置筛选器：将包含筛选器应用于应显示的资源。
租户配置筛选器：将排除筛选器应用于应忽略的租户。

Settings.json

"azure.resource.config.filter": [],
"azure.tenant.config.filter": [
    "313b5f9e-9b92-414c-8d87-a317e42d0222"
]

Azure 身份验证资源配置选项的屏幕截图。

Microsoft Entra 身份验证的代理设置

如果在代理后面使用 Azure Data Studio，用户必须指定 Azure Data Studio 的代理设置才能与外部终结点通信。可通过两种方法为 Azure Data Studio 提供代理设置才能使用：

在 Azure Data Studio 中设置代理配置（“设置”>“Http: 代理设置”）
设置代理配置的环境变量

Azure Data Studio 设置优先于环境变量。

Azure Data Studio 代理设置

Azure Data Studio 中提供了以下设置：

Settings.json

"http.proxy": "https://userName@fqdn:yourPassword@yourProxyURL.com:8080",
"http.proxyStrictSSL": true,
"http.proxyAuthorization": "",
"http.proxySupport" : "override"

Azure 身份验证代理设置的屏幕截图。

代理支持的环境变量

'HTTP_PROXY': 'http://userName@fqdn:yourPassword@yourProxyURL.com:8080'
'HTTPS_PROXY': 'https://userName@fqdn:yourPassword@yourProxyURL.com:8080'

允许列表 URL

在代理环境中，用户应用程序可能需要允许 Azure Data Studio 使用的特定域。可能需要或希望允许通信的主机名包括：

Azure 公用

https://management.azure.com
https://login.microsoftonline.com/

Azure（美国政府）

https://management.core.usgovcloudapi.net/
https://login.microsoftonline.us/

由世纪互联运营的 Azure

https://management.core.chinacloudapi.cn/
https://login.partner.microsoftonline.cn/

要允许的 URL 有时可能会因具体情况而异。若要验证没有阻止任何 URL 通过，请转到“帮助”>“切换开发人员工具”，并选择“网络”选项卡。其中会列出所有被阻止的 URL，你可能需要允许这些 URL 才能成功添加帐户。

配置自定义云终结点

Azure Data Studio 1.46 引入了对为非公有云添加自定义终结点的支持。

添加自定义云终结点

在 Azure Data Studio 中打开“设置”(Ctrl/Cmd + Shift + P)，然后输入“Azure: Custom Provider Settings”，然后选择“在 settings.json 中编辑”，从而自动打开 settings.json 文件并添加 azure.customProviderSettings：

添加到settings.json文件的 azure.customProviderSettings 的屏幕截图。

终结点需要以下条目才能正常工作：

host
clientId
scopes
sqlResource
microsoftResource
armResource
graphResource
azureStorageResource

提供了一个提供程序的示例 JSON 条目作为指南：

"azure.customProviderSettings": [
    {
        "name": "Azure Custom",
        "settings": {
            "metadata": {
                "displayName": "Azure Custom Cloud",
                "id": "azure_customCloud",
                "endpoints": {
                    "host": "https://hostendpoint.com/",
                    "clientId": "test",
                    "microsoftResource": "https://microsoftresource.com/",
                    "graphResource": "https://graphresource.com/",
                    "msGraphResource": "https://msgraphresource.com/",
                    "armResource": "https://armresource.com/",
                    "sqlResource": "https://sqlresource.net/",
                    "azureKeyVaultResource": "https://azurekeyvault.net/",
                    "azureLogAnalyticsResource": "https://azure.loganalytic.io/",
                    "azureStorageResource": {
                        "endpoint": "",
                        "endpointSuffix": ".azurestorage.net/"
                    },
                    "azureKustoResource": "https://kusto.net/",
                    "powerBiResource": "https://powerbi.net/",
                    "scopes": "https://management.net/scopes",
                    "portalEndpoint": "https://portal.azure.com"
                }
            }
        }
    }
]

添加终结点后，保存 settings.json 文件。 Azure Data Studio 会通知你重新加载应用程序。重新加载后，系统会通知你已加载自定义终结点：

重新加载 Azure Data Studio 后显示已加载自定义终结点的屏幕截图。

如果未显示此消息，检查终结点的所有条目是否都存在并且已填充。

添加自定义云后，打开“Azure 链接帐户”窗格，并显示自定义云 viewlet。选择“添加帐户”，并在出现提示时选择身份验证模式。转到主机终结点进行身份验证。

Azure 帐户窗格中自定义云提供商的屏幕截图。

多个自定义云提供商

可以使用同一格式将其他云提供商添加到 settings.json 文件中。

"azure.customProviderSettings": [
    {
        "name": "Azure Custom",
        "settings": {
            "metadata": {
                "displayName": "Azure Custom Cloud",
                "id": "azure_customCloud",
                "endpoints": {
                    "host": "https://hostendpoint.com/",
                    "clientId": "test",
                    "microsoftResource": "https://microsoftresource.com/",
                    "graphResource": "https://graphresource.com/",
                    "msGraphResource": "https://msgraphresource.com/",
                    "armResource": "https://armresource.com/",
                    "sqlResource": "https://sqlresource.net/",
                    "azureKeyVaultResource": "https://azurekeyvault.net/",
                    "azureLogAnalyticsResource": "https://azure.loganalytic.io/",
                    "azureStorageResource": {
                        "endpoint": "",
                        "endpointSuffix": ".azurestorage.net/"
                    },
                    "azureKustoResource": "https://kusto.net/",
                    "powerBiResource": "https://powerbi.net/",
                    "scopes": "https://management.net/scopes",
                    "portalEndpoint": "https://portal.azure.com"
                }
            }
        }
    },
    {
        "name": "Azure Custom 2",
        "settings": {
            "metadata": {
                "displayName": "Azure Custom Cloud 2",
                "id": "azure_customCloud2",
                "endpoints": {
                    "host": "https://hostendpoint.com/",
                    "clientId": "test",
                    "microsoftResource": "https://microsoftresource.com/",
                    "graphResource": "https://graphresource.com/",
                    "msGraphResource": "https://msgraphresource.com/",
                    "armResource": "https://armresource.com/",
                    "sqlResource": "https://sqlresource.net/",
                    "azureKeyVaultResource": "https://azurekeyvault.net/",
                    "azureLogAnalyticsResource": "https://azure.loganalytic.io/",
                    "azureStorageResource": {
                        "endpoint": "",
                        "endpointSuffix": ".azurestorage.net/"
                    },
                    "azureKustoResource": "https://kusto.net/",
                    "powerBiResource": "https://powerbi.net/",
                    "scopes": "https://management.net/scopes",
                    "portalEndpoint": "https://portal.azure.com"
                }
            }
        }
    }
]

身份验证常见问题

讨论了添加 Azure 帐户时可能出现的问题和解决方案。

问题：localhost 页上的 SSL 错误 (ERR_SSL_PROTOCOL_ERROR)

用户在登录其帐户时可能会遇到 SSL 错误。此流打开指向 localhost 的外部网页，通常用于提示用户通过标准 Microsoft 身份验证提示登录。此页面的 URL 类似于 http://localhost:50055/signin?nonce=...

某些浏览器可能设置为自动将所有 http 链接重定向到 https，这会中断此过程，因为为网页提供服务的本地服务器不支持 https。如果地址栏中的链接以 https 开头，则会遇到 SSL 错误，并且页面无法加载。在这种情况下，此处列出的解决方法可以解决此问题。

将 URL 更改为 http

首先，手动将 URL 从 https:// 更改为 http://。浏览器可能会将其更改回 https，此时需要尝试其他选项。

禁用 HSTS（HTTP 严格传输安全性）

对于 Edge/Chrome 浏览器，可以为 localhost 禁用 HSTS。

打开 Edge，在地址栏中键入 edge://net-internals/#hsts（或打开 Chorme，在地址栏中键入 chrome://net-internals/#hsts）。
滚动到页面底部，在 Delete domain security policies 部分中输入 localhost 并按 Delete。

完成后，你应该能够登录，并且浏览器不会自动将 localhost 链接重定向到 https。

问题：无法在使用代理时添加帐户

如果用户应用程序在使用代理的环境中运行，则用户身份验证可能无法完成，以下步骤可用于解决此问题。

在 Azure Data Studio 中重新检查环境变量和 http.proxy 设置。如果代理需要用户身份验证，请在 http.proxy URL 中提供用户名/密码可以解决身份验证问题;否则，Azure Data Studio 无法读取登录的用户凭据。或者，可以尝试以其他用户身份运行 Azure Data Studio，因为它可能有助于解决代理的身份验证问题。但是，后一种方法仅适用于某些情况。
要允许的 URL 可能会因具体情况而异。若要验证没有阻止任何 URL 通过，请转到“帮助”>“切换开发人员工具”，并选择“网络”选项卡。此处将显示所有被阻止的 URL，你可能需要允许这些 URL 才能成功添加帐户。
取消选中“Http: 代理严格 SSL”。代理证书可能无法针对受信任的 CA 列表进行验证。禁用严格 SSL 可以排除代理证书的问题。

总结：

作为跨平台应用程序，Azure Data Studio 代理解析从应用程序内的设置或通过环境变量提取代理。目的是避免与系统设置交互，这些设置在不同的操作系统中可能会有很大的差异。

问题：Azure Core 扩展已禁用

Azure Core 扩展是 Azure Data Studio 中的内置扩展。请确保它不会被意外禁用或卸载。此扩展需要对 Microsoft Entra 帐户进行身份验证，并使用 MFA 连接到资源。

内置 Azure Core 扩展的屏幕截图。

问题：系统 CA 证书已过期

Azure Data Studio 的默认行为包括在使用 HTTPS 协议进行 REST API 调用时验证系统的根 CA 证书。验证由默认启用的 http:systemCertificates 设置进行控制：

系统证书设置的屏幕截图。

"http.systemCertificates": true

如果系统的根 CA 证书已过期，则对 Microsoft Entra ID 的身份验证请求失败，并在 Azure 帐户日志中捕获错误：

error: certificate is expired

若要解决此错误，应移除任何过期的根 CA 证书，或禁用该设置以不验证系统证书。

捕获 Azure 身份验证的日志

默认情况下，Azure Data Studio 会捕获 Microsoft Entra 帐户活动的错误事件。若要启用更详细的跟踪，用户可以修改以下设置：

Azure: 日志记录级别

此设置配置可在 Azure Data Studio 中捕获的 Azure 核心中的信息的日志记录级别。将其更改为“详细”或“全部”以捕获可用于诊断身份验证失败的详细日志。有关详细信息，请参阅 Azure Data Studio 日志和位置，了解如何捕获日志记录信息。

Settings.json

"azure.loggingLevel": "Verbose"

Azure 身份验证日志记录级别配置的屏幕截图。

Azure: PII 日志记录

用户可以启用 PII（个人身份信息）日志记录以进行本地测试和调试。此设置可以更彻底地记录身份验证过程，但在使用 Microsoft Entra ID 进行身份验证时可能包含敏感信息，例如访问令牌或用户 ID。由于此日志记录捕获敏感信息，因此建议：

不与其他人共享这些日志，尤其是在将日志添加到 GitHub 问题时
收集必要信息后禁用此设置
禁用此设置后删除日志文件

Settings.json

"azure.piiLogging": true

Azure 身份验证 PII 日志记录选项的屏幕截图。

Azure: 无系统密钥链

此设置禁用系统密钥链集成，以防止 macOS 上重复出现密钥链访问提示。用户凭据也可以存储在用户主目录下的平面文件中。

Settings.json

"azure.noSystemKeychain": true

Azure 身份验证密钥链配置的屏幕截图。

清除Microsoft Entra 帐户令牌缓存

Azure Data Studio 维护访问令牌缓存，以防止限制对Microsoft Entra ID 的令牌请求。 Azure Data Studio 的令牌缓存可能已过时，因此需要从应用程序缓存中清理过期的访问令牌。

从 命令面板（Ctrl/CMD + Shift + P） 执行此命令，以清除链接Microsoft Entra 帐户的访问令牌：

Azure Accounts: Clear Azure Account Token Cache (accounts.clearTokenCache)

清除所有已保存Microsoft Entra 帐户

从 命令面板（Ctrl/CMD + Shift + P） 执行此命令，从 Azure Data Studio 中删除所有链接Microsoft Entra 帐户：

清除所有已保存的帐户 (clearSavedAccounts)

通过

Azure Data Studio - Azure 连接

Azure：身份验证库

Azure 身份验证方法

“帐户”>“Azure”>“授权: 代码授予”

“帐户”>“Azure”>“授权: 设备代码”

Azure 云配置

Azure 资源配置

Microsoft Entra 身份验证的代理设置

Azure Data Studio 代理设置

代理支持的环境变量

允许列表 URL

配置自定义云终结点

添加自定义云终结点

多个自定义云提供商

身份验证常见问题

问题：localhost 页上的 SSL 错误 (ERR_SSL_PROTOCOL_ERROR)

问题：无法在使用代理时添加帐户

问题：Azure Core 扩展已禁用

问题：系统 CA 证书已过期

捕获 Azure 身份验证的日志

Azure: 日志记录级别

Azure: PII 日志记录

Azure: 无系统密钥链

清除Microsoft Entra 帐户令牌缓存

清除所有已保存Microsoft Entra 帐户

反馈

其他资源