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 和更新版本已不再提供。

此設定可控制 Azure Data Studio 新增 Microsoft Entra 帳戶時所使用的驗證連結庫。 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 驗證的 Proxy 設定

如果使用 Proxy 後方的 Azure Data Studio，使用者就必須指定 Azure Data Studio 的 Proxy 設定，才能與外部端點通訊。有兩種方式可用來提供 Azure Data Studio 的 Proxy 設定：

在 Azure Data Studio 中設定 Proxy 組態（設定 > Http：Proxy 設定）
設定 Proxy 組態的環境變數

Azure Data Studio 設定的優先順序高於環境變數。

Azure Data Studio Proxy 設定

下列設定可在 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.

Proxy 支援的環境變數

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

允許清單 URL

在 Proxy 環境中，使用者應用程式可能需要允許 Azure Data Studio 所使用的特定網域。您可能需要或想要允許通訊的主機名稱如下：

Azure 公用

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

Azure (美國政府)

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

由 21Vianet 營運的 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：自定義提供者設定，然後選取 [在 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 鏈接帳戶 ] 窗格，並顯示自定義雲端檢視程式。選取 [ 新增帳戶 ]，並在出現提示時選擇驗證模式。系統會將您帶到主機端點進行驗證。

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 Strict Transport Security)

針對 Edge/Chrome 瀏覽器，您可以停用 localhost 的 HSTS。

開啟 Edge/Chrome，然後在網址列中鍵入 edge://net-internals/#hsts (或針對 Chrome 鍵入 chrome://net-internals/#hsts)。
捲動至頁面底部，然後在 Delete domain security policies 區段中輸入 localhost 並按 Delete。

完成後，您應該能夠登入，且瀏覽器不會自動將 localhost 連結重新導向至 https。

問題：無法在 Proxy 後方新增帳戶

如果使用者應用程式是在 Proxy 後方的環境中執行，則使用者驗證可能無法完成，而這些步驟可用來解決問題。

在 Azure Data Studio 中重新檢查環境變數和 HTTP.proxy 設定。如果 Proxy 需要使用者驗證，請在 HTTP.proxy URL 中提供使用者名稱/密碼可以解決驗證問題;否則，Azure Data Studio 無法讀取登入的用戶認證。或者，您可以嘗試以不同的使用者身分執行 Azure Data Studio，因為它有助於解決 Proxy 的驗證問題。不過，後者僅適用於某些案例。
允許的 URL 可能依大小寫而有所不同。若要確認您未封鎖任何 URL，請移至 [說明 > 切換開發人員工具]，然後選取 [網路] 索引標籤。您在此處可以看到已封鎖的任何 URL，您可能需要允許才能成功新增您的帳戶。
取消核取 [Http：Proxy Strict SSL]。 Proxy 憑證可能無法根據受信任的 CA 清單進行驗證。停用 Strict SSL 可以排除 Proxy 憑證的問題。

若要結束：

作為跨平臺應用程式，Azure Data Studio Proxy 解析會從應用程式內的設定或透過環境變數擷取 Proxy。目標是避免與系統設定互動，這在不同作業系統上可能會有顯著差異。

問題：已停用 Azure Core 擴充功能

Azure Core 擴充功能是 Azure Data Studio 中的內建擴充功能。請確定它不會意外停用或卸載。需要此延伸模組才能驗證 Microsoft Entra 帳戶，並使用 MFA 連線到資源。

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 進行驗證時包含敏感性資訊，例如存取令牌或使用者標識碼。由於此記錄會擷取敏感性資訊，因此建議您：

不要與其他人共用這些記錄，特別是在將記錄新增至 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 標識符的令牌要求進行節流。 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 驗證的 Proxy 設定

Azure Data Studio Proxy 設定

Proxy 支援的環境變數

允許清單 URL

設定自定義雲端端點

新增自定義雲端端點

多個自定義雲端提供者

一般驗證問題

問題：localhost 頁面上的 SSL 錯誤 (ERR_SSL_PROTOCOL_ERROR)

問題：無法在 Proxy 後方新增帳戶

問題：已停用 Azure Core 擴充功能

問題：系統 CA 憑證已過期

擷取 Azure 驗證的記錄

Azure：記錄層級

Azure：PII 記錄

Azure：沒有系統金鑰鏈

清除 Microsoft Entra 帳戶令牌快取

清除所有已儲存的 Microsoft Entra 帳戶

意見反應

意見反應

其他資源