Solucionar problemas do Power Apps CLI relacionados ao Zscaler

Este artigo fornece etapas de solução de problemas para casos em que o comando Power Apps CLI pa app add data-source falha repetidamente atrás do Zscaler ou de um proxy semelhante que inspeciona SSL.

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.

Lista de verificação de pré-requisitos

Antes de começar, verifique o seguinte:

1. A CLI de Power Apps mais recente está instalada.
2. Você está conectado com a conta correta. Execute pa auth status para verificar a conta ativa.
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 de solução de problemas

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

Etapa 1: Validar a linha de base

Para eliminar problemas de autenticação, execute:

pa auth status

Confirme se a conta ativa tem acesso ao ambiente configurado em power.config.json.

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.

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 formato 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.

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

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). Para obter mais informações, consulte o Provedor de Certificados do PowerShell e o RFC de Formato PEM.

comando 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. Para obter mais informações, 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.

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 a correção de confiança do certificado Zscaler

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.

pa app add data-source --connector <connector-id> --connection-id <connection-id> [--table <table-name>] [--dataset <dataset-or-site-url>]

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

Evite a solução alternativa insegura para validação do TLS

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.

$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"

Para desconsiderar após o teste:

Remove-Item Env:\NODE_TLS_REJECT_UNAUTHORIZED

Validar a recuperação de conectores pela CLI do Power Apps

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

Solucionar os problemas restantes do proxy do Zscaler

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

fetch failed persiste

Confirme novamente se NODE_EXTRA_CA_CERTS continua definido após reiniciar o shell; verifique se o PEM não tem zero bytes. Execute os comandos em Validar a correção de confiança do certificado Zscaler para validar se o arquivo existe e a variável de ambiente está definida 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 com 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 Power Apps para *.powerplatform.com, *.dynamics.com e *.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 permitidos de pontos de extremidade.

SELF_SIGNED CERT IN CHAIN

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

Notes

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 alternar os 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 desenvolvimento dedicado se a política restringir a exportação de certificados.

Escalonar dados

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

• Versão da CLI do Power Apps: pa --version
• Node.js versão: node --version
• SO e shell (por exemplo, Windows PowerShell 7 ou Windows CMD)
• Comando completo executado (limpo)
• Bloco de erro sanitizado (primeira ocorrência)
• Valor de NODE_EXTRA_CA_CERTS (PowerShell: [System.Environment]::GetEnvironmentVariable('NODE_EXTRA_CA_CERTS','User'))
• Presença e 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