Compartilhar via

Azure Data Studio – Conectividade do Azure

  • Artigo

O Azure Data Studio usa a MSAL (Biblioteca de Autenticação da Microsoft) por padrão para adquirir um token de acesso da ID do Microsoft Entra. As configurações que se aplicam à autenticação do Microsoft Entra são discutidas, juntamente com os problemas comumente observados e suas soluções.

Observação

Embora o Microsoft Entra ID seja o novo nome do Azure Active Directory (Azure AD), para evitar a interrupção de ambientes existentes, o Azure AD ainda permanecerá em alguns elementos codificados, como campos de interface do usuário, provedores de conexão, códigos de erro e cmdlets. Neste artigo, os dois nomes são intercambiáveis.

Azure: biblioteca de autenticação

Essa configuração só está disponível no Azure Data Studio 1.41 a 1.45. Ela não está mais disponível no Azure Data Studio 1.46 e versões posteriores.

Essa configuração controla a biblioteca de autenticação usada pelo Azure Data Studio ao adicionar uma conta do Microsoft Entra. A MSAL (Biblioteca de Autenticação da Microsoft) oferece serviços de autenticação e autorização que usam implementações em conformidade com padrões do OAuth 2.0 e OIDC (OpenID Connect) 1.0. Saiba mais sobre a MSAL (Biblioteca de Autenticação da Microsoft). No Azure Data Studio 1.46 e versões posteriores, a MSAL é a única biblioteca em uso, pois a ADAL (Biblioteca de Autenticação do Active Directory) está obsoleta.

Método de autenticação do Azure

O Azure Data Studio dá suporte à MFA (autenticação multifator) do Microsoft Entra usando os seguintes modos:

  • Usando a autenticação de concessão de código (habilitada por padrão)
  • Usando autenticação de código de dispositivo

Contas > Azure > Autenticação: concessão de Código

Settings.json

"accounts.azure.auth.codeGrant": true

Captura de tela da opção de concessão de código de autenticação do Azure.

Quando o método Code Grant é verificado, os usuários devem autenticar-se com a autenticação baseada no navegador. Por padrão, essa opção é ativada.

Contas> Azure > Autenticação: código do dispositivo

Settings.json

"accounts.azure.auth.deviceCode": true

Captura de tela da opção de código do dispositivo de autenticação do Azure.

Quando o método Device Code está habilitado, os usuários recebem um código e uma URL para inserir, que pode ser usada para entrar.

Quando ambas as opções estão marcadas, os usuários são solicitados a selecionar um dos dois modos de autenticação ao adicionar uma conta do Microsoft Entra.

Configuração de nuvem do Azure

O Azure Data Studio dá suporte à autenticação do Microsoft Entra com nuvens nacionais. A Nuvem Pública do Azure está habilitada por padrão, mas os usuários podem habilitar outras nuvens nacionais conforme necessário:

Settings.json

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

Captura de tela das Nuvens Nacionais de Autenticação do Azure.

Pontos de extremidade na nuvem personalizados também podem ser definidos. Consulte Configurando pontos de extremidade na nuvem personalizados.

Configuração de recurso do Azure

Essas configurações aplicam filtros em locatários e recursos do Azure.

  • Filtro de configuração de recurso: aplica o filtro de inclusão aos recursos que devem ser exibidos.
  • Filtro de configuração de locatário: aplica o filtro de exclusão aos locatários que devem ser ignorados.

Settings.json

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

Captura de tela das opções de configuração de recursos de autenticação do Azure.

Configuração de proxy para autenticação do Microsoft Entra

Se estiver usando o Azure Data Studio por trás de um proxy, os usuários deverão especificar configurações de proxy para que o Azure Data Studio se comunique com pontos de extremidade externos. Há duas maneiras de fornecer configurações de proxy para o Azure Data Studio usar:

  • Definindo a configuração de proxy no Azure Data Studio (Configurações > Http: Configurações de Proxy)
  • Definindo variáveis de ambiente para configuração de proxy

As configurações do Azure Data Studio prevalecem sobre variáveis de ambiente.

Configurações de proxy do Azure Data Studio

As configurações a seguir estão disponíveis no Azure Data Studio:

Settings.json

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

Captura de tela das configurações de proxy de autenticação do Azure.

Variáveis de ambiente com suporte para proxy

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

URLs da lista de permissões

Em um ambiente de proxy, os aplicativos de usuário talvez precisem permitir domínios específicos usados pelo Azure Data Studio. Os nomes de host por meio dos quais você pode precisar ou deseja permitir a comunicação são:

Público do Azure

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

Azure (US Government)

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

Azure operado pela 21Vianet

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

As URLs a serem permitidas às vezes podem variar conforme o caso. Para verificar se você não está bloqueando a passagem de URLs, acesse Ajuda > Alternar Ferramentas para Desenvolvedores e selecione a guia Rede. Todas as URLs bloqueadas estão listadas e talvez seja necessário permitir que essas URLs adicionem sua conta com êxito.

Configurando pontos de extremidade na nuvem personalizados

O Azure Data Studio 1.46 apresenta suporte para adicionar pontos de extremidade personalizados para nuvens não públicas.

Adição de pontos de extremidade de nuvem personalizados

Abra Configurações no Azure Data Studio (Ctrl/Cmd + Shift + P) e insira Azure: Configurações Personalizadas do Provedor, depois selecione Editar em settings.json, que abre o arquivo settings.json automaticamente e adiciona azure.customProviderSettings:

Captura de tela de azure.customProviderSettings adicionada a settings.json arquivo.

As entradas a seguir são necessárias para que o ponto de extremidade funcione:

  • host
  • clientId
  • scopes
  • sqlResource
  • microsoftResource
  • armResource
  • graphResource
  • azureStorageResource

Um exemplo de entrada JSON para um provedor é apresentado como um guia:

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

Depois de adicionar o ponto de extremidade, salve o arquivo settings.json. O Azure Data Studio notifica você para recarregar o aplicativo. Após o recarregamento, você será notificado de que os pontos de extremidade personalizados foram carregados:

Captura de tela após recarregar o Azure Data Studio indicando que os pontos de extremidade personalizados foram carregados.

Se essa mensagem não for exibida, verifique se todas as entradas do ponto de extremidade existem e estão preenchidas.

Depois de adicionar uma nuvem personalizada, abra o painel Contas vinculadas do Azure e o viewlet de nuvem personalizada será exibido. Selecione Adicionar uma conta e escolha o modo de autenticação, se solicitado. Você será levado ao ponto de extremidade do host para autenticação.

Captura de tela de um provedor de nuvem personalizado no painel de contas do Azure.

Vários provedores de nuvem personalizados

Outros provedores de nuvem podem ser adicionados ao arquivo settings.json usando o mesmo formato.

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

Problemas de autenticação comuns

Possíveis problemas e soluções ao adicionar uma conta do Azure são discutidos.

Problema: erro SSL na página localhost (ERR_SSL_PROTOCOL_ERROR)

Os usuários podem ver um erro SSL ao entrar na conta. Esse fluxo abre uma página da Web externa para localhost, normalmente solicitando que os usuários entrem por meio dos prompts de autenticação padrão da Microsoft. A URL desta página é semelhante a http://localhost:50055/signin?nonce=...

Alguns navegadores podem ser configurados para redirecionar automaticamente todos os links http para https, o que interrompe esse processo, pois o servidor local que atende a página da Web não dá suporte a https. Se o link na barra de endereços começar com https, você receberá um erro SSL e a página não poderá ser carregada. Nesse caso, as soluções alternativas listadas aqui podem resolver o problema.

Alterar URL para http

Primeiro, altere manualmente a URL de https:// para http://. O navegador pode alterá-la de volta para https. Nesse caso, é necessário tentar outra opção.

Desabilitar HSTS (Segurança de Transporte Estrito HTTP)

Para navegadores Edge/Chrome, você pode desabilitar o HSTS para localhost.

  1. Abra o Edge/Chrome e, na barra de endereços, digite edge://net-internals/#hsts (ou chrome://net-internals/#hsts para Chrome).
  2. Role até a parte inferior da página e, na Delete domain security policies seção, insira localhost e pressione Delete.

Depois que isso for concluído, você poderá entrar e não fazer com que o navegador redirecione seus links localhost automaticamente para https.

Problema: não é possível adicionar uma conta atrás de um proxy

Se o aplicativo de usuário estiver em execução em um ambiente atrás de um proxy, a autenticação do usuário poderá não ser concluída e essas etapas poderão ser usadas para resolver o problema.

  1. Verifique novamente as variáveis de ambiente e as configurações de http.proxy no Azure Data Studio. Se o proxy exigir autenticação de usuário, fornecer um nome de usuário/senha na URL http.proxy poderá resolver problemas de autenticação; caso contrário, o Azure Data Studio não poderá ler as credenciais de usuário conectadas. Como alternativa, você pode tentar executar o Azure Data Studio como um usuário diferente, pois isso pode ajudar a resolver problemas de autenticação com o proxy. No entanto, este último só funciona para alguns cenários.

  2. As URLs a serem permitidas podem variar caso a caso. Para verificar se você não está bloqueando a passagem de URLs, acesse Ajuda > Alternar Ferramentas para Desenvolvedores e selecione a guia Rede. Aqui você pode ver todas URLs que estão sendo bloqueadas e pode precisar permitir que essas URLs adicionem sua conta com êxito.

  3. Desmarque Http: SSL estrito do proxy. É possível que o certificado proxy não seja verificável na lista de ACs confiáveis. Desabilitar o SSL estrito pode excluir o certificado proxy como um problema.

Para concluir:

Como um aplicativo multiplataforma, a resolução de proxy do Azure Data Studio busca o proxy da configuração dentro do aplicativo ou por meio de variáveis de ambiente. O objetivo é evitar a interação com as configurações do sistema, que podem variar significativamente em diferentes sistemas operacionais.

Problema: a extensão do Azure Core está desabilitada

A extensão Azure Core é uma extensão incorporada no Azure Data Studio. Verifique se ela não foi desabilitada ou desinstalado acidentalmente. Essa extensão é necessária para autenticar contas do Microsoft Entra e se conectar a recursos usando MFA.

Captura de tela da extensão Azure Core interna.

Problema: os certificados de AC do sistema expiraram

O comportamento padrão do Azure Data Studio inclui a validação de certificados de AC raiz do sistema ao fazer chamadas à API REST usando o Protocolo HTTPS. A validação é controlada com a configuração http:systemCertificates, que é habilitada por padrão:

Captura de tela da configuração dos certificados do sistema. 

"http.systemCertificates": true

Se o certificado de autoridade de certificação raiz de um sistema expirar, as solicitações de autenticação para a ID do Microsoft Entra falharão e um erro será capturado nos logs da conta do Azure:

error: certificate is expired

Para atenuar esse erro, você deverá remover todos os certificados da autoridade de certificação raiz expirados ou desabilitar a configuração para não validar certificados do sistema.

Capturar logs para autenticação do Azure

O Azure Data Studio captura eventos de erro para a atividade da conta do Microsoft Entra por padrão. Para habilitar rastreamentos mais detalhados, os usuários podem modificar essas configurações:

Azure: nível de registros em log

Essa configuração configura o nível de log para obter informações do Azure Core que podem ser capturadas no Azure Data Studio. Altere-a para Detalhado ou Todos para capturar logs detalhados que podem ser úteis para diagnosticar falhas de autenticação. Para obter mais informações, confira Logs e localização do Azure Data Studio para saber como capturar informações de registro em log.

Settings.json

"azure.loggingLevel": "Verbose"

Captura de tela da configuração de nível de registros em log de autenticação do Azure.

Azure: registros em log de PII

Os usuários podem habilitar o registro em log de PII (Informações de Identificação Pessoal) para fins locais de teste e depuração. Essa configuração permite um registro mais completo do processo de autenticação, mas pode conter informações confidenciais, como tokens de acesso ou IDs de usuário ao autenticar com a ID do Microsoft Entra. Como esse log captura informações confidenciais, é recomendável:

  • Não compartilhar esses logs com mais ninguém, especialmente ao adicionar logs a problemas do GitHub
  • Desabilitar a configuração depois que as informações necessárias forem coletadas
  • Excluir os arquivos de log depois que a configuração tiver sido desabilitada

Settings.json

"azure.piiLogging": true

Captura de tela da opção de log de PII de autenticação do Azure.

Azure: nenhum conjunto de chaves do sistema

Essa configuração desabilita a integração do conjunto de chaves do sistema para evitar prompts repetidos de acesso ao conjunto de chaves no macOS. Como alternativa, as Credenciais do Usuário são armazenadas em um arquivo simples no diretório base do usuário.

Settings.json

"azure.noSystemKeychain": true

Captura de tela da configuração do conjunto de chaves de autenticação do Azure.

Limpe o cache do token da conta do Microsoft Entra

O Azure Data Studio mantém um cache de tokens de acesso para evitar a limitação de solicitações de token para a ID do Microsoft Entra. É possível que o cache de token do Azure Data Studio possa estar desatualizado, o que requer a limpeza de tokens de acesso expirados do cache do aplicativo.

Execute este comando na Paleta de Comandos (Ctrl/CMD + Shift + P) para limpar os tokens de acesso para contas vinculadas do Microsoft Entra:

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

Limpe todas as contas salvas do Microsoft Entra

Execute este comando na Paleta de Comandos (Ctrl/CMD + Shift + P) para remover todas as contas vinculadas do Microsoft Entra do Azure Data Studio:

Limpar todas as contas salvas (clearSavedAccounts)