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

Screenshot of Azure authentication Code Grant option.

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

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

Settings.json

"accounts.azure.auth.deviceCode": true

Screenshot of Azure authentication Device Code option.

启用“设备代码方法”后，会向用户提供一个代码和一个要输入的 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

Screenshot of Azure authentication National Clouds.

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

Azure 资源配置

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

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

Settings.json

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

Screenshot of Azure authentication resource configuration options.

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"

Screenshot of Azure authentication proxy settings.

代理支持的环境变量

'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：

Screenshot of azure.customProviderSettings added to settings.json file.

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

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 会通知你重新加载应用程序。重新加载后，系统会通知你已加载自定义终结点：

Screenshot after reloading Azure Data Studio indicating custom endpoints have been loaded.

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

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

Screenshot of a custom cloud provider in the Azure accounts pane.

多个自定义云提供商

可以使用同一格式将其他云提供商添加到 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 中的内置扩展。请确保它不会被意外禁用或卸载。此扩展需要使用 MFA 对 Microsoft Entra 帐户进行身份验证并连接到资源。

Screenshot of built-in Azure Core extension.

问题：系统 CA 证书已过期

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

Screenshot of system certificates setting.

"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"

Screenshot of Azure authentication logging Level configuration.

Azure: PII 日志记录

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

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

Settings.json

"azure.piiLogging": true

Screenshot of Azure authentication PII logging option.

Azure: 无系统密钥链

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

Settings.json

"azure.noSystemKeychain": true

Screenshot of Azure authentication keychain configuration.

清除 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 帐户

反馈

反馈

其他资源