Solucionar problemas relacionados ao Zscaler (versão prévia)

Este artigo oferece etapas da solução de problemas para quando a CLI do PAC (Interface de Linha de Comando do Power Apps) pac code add-data-source falha repetidamente atrás de um Zscaler ou de proxies de inspeção SSL semelhantes.

O Zscaler é uma plataforma de segurança baseada em nuvem que executa a inspeção SSL/TLS (Secure Socket Layer Security) descriptografando e criptografando novamente o tráfego HTTPS. Ele funciona intencionalmente como um intermediário para inspecionar o conteúdo em busca de ameaças. Confira a visão geral da inspeção do SSL do Zscaler

Sintomas

A tabela a seguir lista os sintomas que podem indicar problemas relacionados ao Zscaler.

Sintoma	Exemplo de mensagem/padrão
Falha na busca	TypeError: fetch failed / [AddDataSource.ServiceCall.GetConnector.Failure] ... fetch failed
Falha na solicitação vazia	Error: Request failed: {} (sem corpo)
Erros de handshake/certificado do TLS	UNABLE_TO_VERIFY_LEAF_SIGNATURE / SELF_SIGNED CERT IN CHAIN (se a depuração estiver habilitada)
Funciona fora da rede corporativa	O comando é bem-sucedido quando desconectado do Zscaler

Lista de verificação de pré-requisitos

Antes de começar, verifique o seguinte:

1. A CLI mais recente do Power Platform está instalada. Atualize-o se você não tiver certeza.
2. Você está autenticado no ambiente correto. Use comandos pac auth create e pac auth list.
3. A versão Node.js instalada é maior ou igual à v22. As versões mais antigas têm comportamentos de confiança diferentes que são mais estritos.
4. Você pode ler o repositório de certificados do usuário. Não há restrições de perfil rígidas.
5. A política corporativa permite adicionar o certificado raiz da Zscaler na lista de confiança do usuário para ferramentas de desenvolvedor.

Etapas para solucionar problemas

Use as informações nas seções a seguir para solucionar problemas.

Etapa 1: Validar a linha de base

Para eliminar causas não relacionadas a um proxy, execute o pac env who comando.

Se esse comando for bem-sucedido, a conectividade geral está funcionando corretamente; as falhas são isoladas em chamadas para fontes de dados.

Etapa 2: confirmar se o Zscaler está instalado

Execute este comando para garantir que o certificado Zscaler exista no repositório.

Get-ChildItem Cert:\CurrentUser\Root |
    Where-Object { $_.Subject -like "*Zscaler*" } |
    Select-Object Subject, Thumbprint

Se o Zscaler injetar seu certificado, você verá um emissor Zscaler em vez da Microsoft.

Observação

Quando um proxy como o Zscaler intercepta o tráfego HTTPS, ele substitui o certificado do servidor original por seu próprio certificado assinado por uma AC raiz corporativa. Isso permite que o proxy descriptografe, inspecione e criptografe novamente o tráfego. Os navegadores confiam porque a AC raiz corporativa está instalada no repositório de confiança do sistema. Veja como funciona a interceptação HTTPS

Etapa 3: Exportar o Certificado de Autoridade Raiz do Zscaler para PEM

Execute este comando para exportar a AC (Autoridade de Certificação Raiz) do Zscaler para o PEM (Privacy Enhanced Mail)

$cert = Get-ChildItem Cert:\CurrentUser\Root |
    Where-Object { $_.Subject -like "*Zscaler*" } |
    Select-Object -First 1

$pem = @(
    '-----BEGIN CERTIFICATE-----'
    [System.Convert]::ToBase64String(
        $cert.RawData,
        [System.Base64FormattingOptions]::InsertLineBreaks
    )
    '-----END CERTIFICATE-----'
) -join "`n"

Set-Content -Path "$env:USERPROFILE\.zscaler-root-ca.pem" -Value $pem

Resultado: ~\.zscaler-root-ca.pem criado.

Cuidado

Proteja o arquivo PEM: Verifique as permissões de arquivo adequadas no certificado exportado. Se um ator mal-intencionado puder substituir esse arquivo, ele poderá interceptar o tráfego HTTPS de processos Node.js. Fortalecimento recomendado (remove a herança, depois conceder permissão de leitura):

icacls "$env:USERPROFILE\.zscaler-root-ca.pem" /inheritance:r /grant:r "$env:USERNAME:(R)"

Se a remoção da herança entrar em conflito com a política corporativa ou acionar os controles de proteção de endpoint, ignore /inheritance:r e conceda apenas permissão de leitura explícita.

icacls "$env:USERPROFILE\.zscaler-root-ca.pem" /grant:r "$env:USERNAME:(R)"

Formato PEM e repositório de certificados do Windows

O Get-ChildItem Cert:\CurrentUser\Root comando acessa o Repositório de Certificados do Windows por meio do provedor de certificados do PowerShell. O PEM é um formato codificado em Base64 para certificados. A conversão é necessária porque Node.js requer formato PEM enquanto o Windows armazena certificados no formato DER (Regras de Codificação Diferenciadas). Consulte o Provedor de Certificados do PowerShell e o RFC de Formato PEM

Comando do Windows icacls

icacls (Lista de Controle de Acesso de Integridade) é um utilitário de linha de comando do Windows para gerenciar permissões de arquivo. Os parâmetros usados: /inheritance:r remove as permissões herdadas, /grant:r substitui as permissões existentes pelo acesso somente leitura para o usuário especificado. Consulte a documentação do icacls

Etapa 4: Instruir Node.js a confiar no certificado

Execute o script a seguir para instruir Node.js confiar no certificado.

[System.Environment]::SetEnvironmentVariable('NODE_EXTRA_CA_CERTS', "$env:USERPROFILE\.zscaler-root-ca.pem", 'User')

Feche e reinicie o terminal / VS Code para propagar.

Cuidado

Impacto no escopo: Essa variável de ambiente NODE_EXTRA_CA_CERTS afeta TODOS os processos de Node.js executados por sua conta de usuário. Se o arquivo PEM for adulterado, cada aplicativo Node.js confiará na autoridade de certificação modificada, não apenas na CLI do PAC. Verifique o hash do arquivo periodicamente e mantenha-o protegido.

variável de ambiente NODE_EXTRA_CA_CERTS

Essa variável de ambiente Node.js especifica um arquivo que contém autoridades de certificação mais confiáveis além da lista interna do Node.js(pacote de AC do Mozilla). Quando definido, Node.js confia em certificados assinados por CAs na lista interna e no arquivo especificado. Consulte variáveis de ambiente da CLI do Node.js

Validar correção

Siga estas etapas para validar se a correção foi aplicada corretamente nas Etapas 3-4 antes de passar para a Etapa 5.

1. Confirme se o arquivo PEM foi criado e existe no local esperado

    Test-Path "$env:USERPROFILE\.zscaler-root-ca.pem" # Expect True
   

2. Verifique se a variável de ambiente foi definida corretamente e retorna o caminho para o arquivo PEM

   [System.Environment]::GetEnvironmentVariable(
       'NODE_EXTRA_CA_CERTS',
       'User'
   )
   

3. Verifique se o arquivo PEM tem conteúdo válido em vez de estar vazio ou corrompido

   Get-Content "$env:USERPROFILE\.zscaler-root-ca.pem" -TotalCount 2
   # First line should be: -----BEGIN CERTIFICATE-----
   

Etapa 5: executar novamente o comando

Tente executar o comando novamente.

pac code add-data-source -a <apiId> -c <connectionId> [-t <tableName>] [-d <dataset|siteUrl>]

Espere êxito na recuperação do conector, em vez de uma falha de busca.

(Evite) Solução alternativa insegura

Um teste final e definitivo que deve ser evitado é desabilitar temporariamente a validação do TLS.

Essa solução alternativa força Node.js aceitar qualquer certificado apresentado, incluindo certificados autoassinados ou falsificados. Isso remove todas as garantias de autenticidade e integridade do HTTPS. Isso expõe as sessões a ataques MITM (homem-no-meio), captura de credenciais e modificação de conteúdo. Nunca use fora de uma sessão de diagnóstico de curta duração.

Aviso

Risco de segurança: Isso desabilita completamente a validação do certificado SSL para todas as conexões HTTPS Node.js na sessão atual. Qualquer invasor com acesso à rede pode executar ataques MITM. SÓ use essa solução alternativa no diagnóstico único para provar que a confiança do certificado é a causa raiz. Nunca confirme scripts; nunca use em ambientes de produção; desvincule imediatamente após o teste.

$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"

Para desconsiderar após o teste:

Remove-Item Env:\NODE_TLS_REJECT_UNAUTHORIZED

Validation

Depois de aplicar a solução, repita o comando. Procure uma recuperação bem-sucedida do conector:

[AddDataSource.ServiceCall.GetConnector.Start] { apiId: 'shared_office365users' }
[AddDataSource.ServiceCall.GetConnector.Success] { apiId: 'shared_office365users' }

Em vez de:

[AddDataSource.ServiceCall.GetConnector.Failure] { apiId: 'shared_office365users', error: 'fetch failed' }

Matriz da solução de problemas

Se você ainda tiver problemas após concluir as etapas de solução de problemas, investigue os seguintes problemas.

fetch failed persiste

Reconfirme NODE_EXTRA_CA_CERTS ajustado após reiniciar o shell; verifique se o PEM não possui zero byte. Execute os comandos em Validar correções para validar se o arquivo existe e a variável de ambiente está configurada corretamente.

Vários certificados do Zscaler

Se Get-ChildItem Cert:\CurrentUser\Root | Where-Object { $_.Subject -like "*Zscaler*" } retornar vários certificados, identifique a Autoridade Certificadora raiz (normalmente denominada Zscaler Root CA). Modifique a Etapa 3 para selecionar a correta por nome do emissor ou impressão digital.

Produto proxy diferente

A solução funciona para qualquer proxy corporativo que executa a inspeção SSL (Blue Coat, Forcepoint, Netskope etc.), mas a Etapa 3 procura *Zscaler* no assunto do certificado. Adapte o filtro para corresponder ao proxy:

# For Blue Coat:
$cert = Get-ChildItem Cert:\CurrentUser\Root |
    Where-Object { $_.Subject -like "*Blue Coat*" } |
    Select-Object -First 1

# For Forcepoint:
$cert = Get-ChildItem Cert:\CurrentUser\Root |
    Where-Object { $_.Subject -like "*Forcepoint*" } |
    Select-Object -First 1

Em seguida, conclua as Etapas 3-4 com o certificado correspondente.

Funciona somente fora da VPN

Quando o comando funciona apenas usando uma VPN externa, ele indica o bloqueio no nível da rede, não problemas de confiança de certificado. As configurações de VPN de túnel dividido corporativo podem rotear o tráfego da API do Power Platform por meio de firewalls locais que bloqueiam ferramentas de Node.js/CLI ou aplicam políticas restritivas ao tráfego que não é do navegador.

A correção NODE_EXTRA_CA_CERTS não resolve o problema aqui. Envolva sua equipe de rede/segurança para:

• Permitir o tráfego da CLI do PAC para *.powerplatform.com, *.dynamics.com, *.azure.net
• Permitir HTTPS direto (porta 443) de estações de trabalho de desenvolvedor para serviços de nuvem da Microsoft
• Configurar regras de túnel dividido para omitir a inspeção/filtragem para pontos de extremidade confiáveis da Microsoft

Diretrizes de túnel dividido e lista de autorização

Algumas VPNs empresariais roteiam apenas um subconjunto de tráfego diretamente, enquanto forçam o tráfego restante por meio dos gateways de inspeção. Os pontos de extremidade do Power Platform devem ser acessíveis sem conflitos de bloqueio ou interceptação SSL. Consulte os requisitos de conectividade da Microsoft para orientação para a lista de permissões de endpoints.

SELF_SIGNED CERT IN CHAIN

A cadeia de certificados está incompleta. Exporte a cadeia completa de certificados (raiz + intermediários) ou solicite à sua equipe de rede que forneça o conjunto completo de CA raiz. Alguns proxies exigem que as ACs raiz e intermediárias sejam confiáveis.

Anotações

Tenha estas anotações em mente para manter uma configuração segura e confiável ao trabalhar por trás de proxies de inspeção de SSL, como o Zscaler:

• Repita a exportação se o Zscaler fizer o rodízio de certificados.
• As alterações afetam apenas o escopo do usuário atual. Não há risco em todo o sistema.
• Seguro: adiciona confiança; não desabilitar a validação.
• Use um computador de devoção dedicado se a política restringir a exportação de certificados.

Dados de escalonamento

Se nenhuma das etapas deste artigo ajudar, antes de entrar em contato com o suporte técnico, colete as seguintes informações e forneça-as:

• Versão da CLI do PAC: pac --version
• Node.js versão: node --version
• SO + shell (por exemplo, Windows PowerShell 7/Windows CMD)
• Comando completo executado (sanitizado)
• Bloco de erro sanitizado (primeira ocorrência)
• Valor de NODE_EXTRA_CA_CERTS (PowerShell: [System.Environment]::GetEnvironmentVariable('NODE_EXTRA_CA_CERTS','User'))
• Presença &hash do arquivo PEM (por exemplo, Get-FileHash $env:USERPROFILE\.zscaler-root-ca.pem)

Artigos relacionados

Requisitos de conectividade do Power Platform
documentação do Node.js NODE_EXTRA_CA_CERTS