Incompatibilidade do Verificador de Código PKCE no Copilot: Etapas de Diagnóstico

Quando o Copilot falha na autenticação, você pode ver um erro referente a uma incompatibilidade do verificador de código PKCE. Isso ocorre quando o desafio criptográfico enviado pelo seu aplicativo cliente não corresponde ao verificador esperado pela plataforma de identidade da Microsoft. A incompatibilidade bloqueia a troca de tokens e impede o Copilot de acessar os dados do Microsoft 365. Este artigo explica a causa raiz da incompatibilidade do verificador de código PKCE e fornece etapas de diagnóstico para identificar e resolver o problema.

Por que a Incompatibilidade do Verificador de Código PKCE Ocorre

Proof Key for Code Exchange (PKCE) é uma extensão do OAuth 2.0 que previne ataques de interceptação de código de autorização. Durante o fluxo de autorização, seu aplicativo cliente gera uma string aleatória de verificador de código. Em seguida, ele envia um hash SHA-256 desse verificador, chamado de desafio de código, para o endpoint de autorização. Quando o cliente troca o código de autorização por tokens, ele deve enviar o verificador de código original. A plataforma de identidade da Microsoft aplica hash ao verificador e o compara ao desafio de código armazenado. Se os dois não corresponderem, a troca de tokens falha com um erro de incompatibilidade do verificador de código PKCE.

Causas Comuns da Incompatibilidade

A incompatibilidade geralmente decorre de um de três problemas:

• Geração incorreta do verificador de código: O cliente gera um verificador que não corresponde ao desafio enviado anteriormente. Isso pode acontecer se o verificador for regenerado entre a solicitação de autorização e a troca de tokens.
• Diferenças na codificação de URL: O verificador de código deve ser enviado codificado por URL na solicitação de token. Se o método de codificação diferir entre os endpoints de autorização e token, o hash não corresponderá.
• Interferência de proxy ou middleware: Um serviço intermediário modifica o verificador de código ou os parâmetros de desafio, quebrando o vínculo criptográfico.

Etapas de Diagnóstico para Identificar a Incompatibilidade

Siga estas etapas para localizar a origem da incompatibilidade do verificador de código PKCE. Execute cada etapa em ordem.

1. Capture a solicitação de autorização e a troca de tokens com as ferramentas de desenvolvedor do navegador
   Abra as ferramentas de desenvolvedor do seu navegador (F12) e vá para a guia Rede. Reproduza a falha de autenticação do Copilot. Filtre as solicitações para login.microsoftonline.com. Localize a solicitação de autorização (HTTP 302 ou 200) e a solicitação de troca de tokens (POST para /oauth2/v2.0/token).
2. Extraia o code_challenge da solicitação de autorização
   Na URL da solicitação de autorização, encontre o parâmetro code_challenge. Copie o valor completo. Deve ser um hash SHA-256 codificado em base64url sem caracteres de preenchimento.
3. Extraia o code_verifier da solicitação de token
   No corpo POST da solicitação de token, encontre o parâmetro code_verifier. Copie o valor completo. Esta é a string de texto simples que seu cliente enviou.
4. Recalcule o hash SHA-256 do code_verifier
   Use uma ferramenta de linha de comando ou um gerador SHA-256 online para aplicar hash ao verificador de código. Em seguida, codifique o resultado em base64url sem preenchimento. Compare este valor com o code_challenge que você capturou. Se forem diferentes, o problema está na geração ou codificação do verificador pelo cliente.
5. Verifique a consistência da codificação de URL
   Confira se o code_verifier na solicitação de token está codificado por URL exatamente como o cliente o gerou. Incompatibilidades comuns de codificação incluem tratar + como espaço ou não codificar caracteres =.
6. Inspecione o URI de redirecionamento para correspondência exata
   No registro do seu aplicativo no Azure AD, vá para Autenticação > URIs de redirecionamento. Confirme se o URI corresponde exatamente ao da solicitação de autorização, incluindo barras finais e protocolo.

Se o Copilot Ainda Tiver Problemas de Autenticação Após o Diagnóstico

A solicitação de token retorna 400 Bad Request com erro invalid_grant

Se o hash calculado corresponder, mas a troca de tokens ainda falhar, o problema pode ser um código de autorização expirado. Os códigos de autorização expiram após 10 minutos. Se o seu cliente atrasar a troca de tokens além desse prazo, o servidor rejeita a solicitação. Regere o código de autorização e tente a troca novamente dentro do limite de tempo.

Os logs do cliente mostram parâmetro code_verifier ausente

Algumas bibliotecas de cliente omitem o code_verifier na solicitação de token se o PKCE não estiver explicitamente habilitado. Verifique se sua biblioteca OAuth suporta PKCE e se você definiu a opção usePKCE como true. Para a Microsoft Authentication Library (MSAL), isso é habilitado por padrão para aplicativos de página única.

O erro aparece apenas em ambientes de rede específicos

Proxies corporativos ou VPNs podem remover ou alterar o parâmetro code_verifier. Trabalhe com sua equipe de rede para incluir os endpoints da plataforma de identidade da Microsoft na lista de permissões e desativar a inspeção SSL para login.microsoftonline.com e todos os subdomínios.

Incompatibilidade do Verificador de Código PKCE vs Outros Erros OAuth: Principais Diferenças

Item	Incompatibilidade do Verificador de Código PKCE	Outros Erros OAuth
Mensagem de erro	invalid_grant com descrição referente ao verificador de código	invalid_request, unauthorized_client ou access_denied
Causa raiz	Incompatibilidade de hash criptográfico entre desafio e verificador	Código de autorização expirado, URI de redirecionamento incorreto ou ID do cliente inválido
Foco do diagnóstico	Inspecionar valores de code_challenge e code_verifier	Verificar expiração do token, URI de redirecionamento e permissões do aplicativo
Abordagem de correção	Corrigir geração ou codificação do verificador	Atualizar configurações do registro do aplicativo ou regerar código de autorização

Seguindo as etapas de diagnóstico neste artigo, você pode identificar a causa exata de uma incompatibilidade do verificador de código PKCE na autenticação do Copilot. Comece capturando o tráfego de rede e comparando os valores criptográficos. Se o hash corresponder, investigue a expiração do código de autorização ou interferência de rede. Para problemas persistentes, habilite o log detalhado no MSAL para capturar os parâmetros brutos enviados ao endpoint de token.