Azure Data Studio - Azure 連線能力

發行項
10/16/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 驗證的 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"

Azure 驗證 Proxy 設定的螢幕擷取畫面。

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: Custom Provider Settings，然後選取 [在 settings.json 中編輯]，這將自動開啟 settings.json 檔案並新增 azure.customProviderSettings：

azure.customProviderSettings 新增至 settings.json 檔案的螢幕擷取畫面。

端點需要下列項目才能運作：

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 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 連線到資源。

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

不要與其他人共用這些記錄，特別是在將記錄新增至 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 驗證的 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 帳戶

意見反應

其他資源