Bot do Copilot Studio não autentica conector do SharePoint: correção

Quando o bot do Copilot Studio não consegue autenticar o conector do SharePoint, ele não consegue ler ou gravar dados de listas, bibliotecas ou sites do SharePoint. Isso geralmente acontece porque a configuração de autenticação do bot não corresponde às permissões exigidas pelo recurso do SharePoint. Neste artigo, você aprenderá por que a autenticação falha e como corrigi-la ajustando as configurações do conector, verificando o registro do aplicativo no Microsoft Entra ID e atribuindo as permissões de API corretas.

Por que a autenticação do conector do SharePoint falha no Copilot Studio

O conector do SharePoint no Copilot Studio exige um token OAuth 2.0 válido que comprove que o bot tem permissão para acessar o site, lista ou biblioteca do SharePoint de destino. A falha de autenticação ocorre quando o registro do aplicativo no Microsoft Entra ID para o bot não possui as permissões delegadas corretas para o SharePoint. Outra causa comum é que o bot não foi publicado no site do SharePoint onde o conector está configurado, então a solicitação de token é rejeitada porque a declaração de público no token não corresponde à URL do recurso.

O conector usa a API do Microsoft Graph ou a API REST do SharePoint para ler e gravar dados. Ambas as APIs exigem escopos de permissão específicos. Se o registro do aplicativo tiver apenas permissões de Aplicativo, mas o conector usar autenticação delegada, o token será inválido. Da mesma forma, se o administrador não tiver concedido consentimento para as permissões, a solicitação de token retornará um erro de não autorizado.

O papel da URL do site do SharePoint na autenticação

O conector do SharePoint no Copilot Studio exige a URL exata do site onde os dados residem. Se a URL estiver errada — por exemplo, usando a URL do site raiz em vez de um sub-site — o token será emitido para o recurso errado e a autenticação falhará. O bot deve ser publicado no mesmo site do SharePoint ou pelo menos em um site que esteja no mesmo locatário e tenha acesso aos dados de destino.

Etapas para corrigir a autenticação do conector do SharePoint

Siga estas etapas em ordem. Após cada etapa, teste o conector enviando uma mensagem que acione uma chamada de dados para o SharePoint.

1. Abra as configurações de autenticação do conector no Copilot Studio
   Faça login no Copilot Studio. Vá para Tópicos e selecione o tópico que usa o conector do SharePoint. Clique em Conectores e selecione o conector do SharePoint. Clique em Editar autenticação. Verifique se o tipo de autenticação está definido como OAuth 2.0 com Microsoft Entra ID. Se estiver definido como Nenhum ou Básico, altere para OAuth 2.0.
2. Verifique a URL do site do SharePoint no conector
   Nas mesmas configurações do conector, verifique o campo URL do site. Ele deve corresponder exatamente à URL do site do SharePoint que contém a lista ou biblioteca que você deseja acessar. Por exemplo: https://contoso.sharepoint.com/sites/ProjectAlpha. Se você precisar acessar dados de um sub-site, use a URL do sub-site, não a URL do site raiz.
3. Verifique o registro do aplicativo no Microsoft Entra ID para o bot
   Vá para o centro de administração do Microsoft Entra. Em Identidade > Aplicativos > Registros de aplicativo, encontre o registro do aplicativo associado ao seu bot do Copilot Studio. O nome do aplicativo geralmente é o mesmo que o nome do bot. Clique no nome do aplicativo para abrir suas configurações.
4. Adicione permissões delegadas do SharePoint ao registro do aplicativo
   No registro do aplicativo, vá para Permissões de API. Clique em Adicionar permissão. Selecione SharePoint. Escolha Permissões delegadas. Selecione pelo menos Sites.Read.All para acesso de leitura ou Sites.ReadWrite.All para acesso de leitura e gravação. Clique em Adicionar permissões. Em seguida, clique em Conceder consentimento do administrador para o locatário. Uma marca de verificação verde deve aparecer ao lado de cada permissão.
5. Publique o bot no site do SharePoint
   No Copilot Studio, vá para Publicar > Canais. Selecione SharePoint. Escolha o site específico do SharePoint onde o conector é executado. Clique em Publicar. Aguarde a conclusão da publicação. Esta etapa garante que o bot possa autenticar nesse site.
6. Teste o conector com uma consulta de dados simples
   No Copilot Studio, abra o tópico que usa o conector do SharePoint. Envie uma mensagem de teste como “Mostre-me os itens mais recentes da lista Projetos.” Se o bot retornar dados, a autenticação foi corrigida. Se você ainda vir um erro, prossiga para a próxima seção.

Se o bot do Copilot Studio ainda não autenticar após a correção principal

O conector retorna um erro 401 Não Autorizado

Um erro 401 significa que o token está ausente ou é inválido. Abra o registro do aplicativo no Microsoft Entra e vá para Certificados e segredos. Certifique-se de que existe um segredo de cliente válido e que não expirou. Se o segredo expirou, crie um novo e atualize a autenticação do conector no Copilot Studio com o novo segredo. Além disso, confirme se o URI de redirecionamento no registro do aplicativo corresponde à URL de retorno de chamada do conector do Copilot Studio. A URL de retorno de chamada está visível nas configurações de autenticação do conector em URI de redirecionamento.

O conector retorna um erro 403 Proibido

Um erro 403 significa que o token é válido, mas o usuário ou bot não tem permissão para acessar o item específico do SharePoint. Vá para o site do SharePoint e verifique se a conta de serviço do bot — geralmente a mesma conta que criou o bot — tem pelo menos acesso de Leitura à lista ou biblioteca de destino. Se o conector usar autenticação delegada, o token é emitido para o usuário conectado. Esse usuário deve ter permissão para os dados do SharePoint. Se o conector usar autenticação de aplicativo, o próprio aplicativo deve ter permissões em nível de site concedidas por meio de uma política de permissão de aplicativo no SharePoint.

O conector funciona no teste, mas falha em produção

Isso acontece quando o bot é publicado em um site do SharePoint diferente daquele usado durante o teste. Vá para Publicar > Canais > SharePoint e confirme se a URL do site corresponde à URL do site nas configurações do conector. Se o bot estiver incorporado em um aplicativo do Teams, o manifesto do aplicativo do Teams também deve incluir o domínio correto do site do SharePoint na matriz validDomains.

Conector do SharePoint no Copilot Studio: tipos de autenticação comparados

Item	OAuth 2.0 com Microsoft Entra ID	Autenticação Básica
Descrição	Usa autenticação baseada em token com permissões delegadas ou de aplicativo	Usa nome de usuário e senha diretamente no conector
Segurança	Alta — os tokens expiram e podem ser revogados individualmente	Baixa — as credenciais são armazenadas em texto simples e não podem ser escopadas
Compatível com SharePoint Online	Sim	Não — a Microsoft desativou a autenticação básica para SharePoint Online em 2022
Configuração necessária	Registro de aplicativo no Microsoft Entra com permissões delegadas e consentimento do administrador	Nenhuma — mas falha para locatários do SharePoint Online

Sempre use OAuth 2.0 com Microsoft Entra ID para conectores do SharePoint no Copilot Studio. A autenticação básica não funciona mais com o SharePoint Online e causará falhas de autenticação.

Agora você pode corrigir erros de autenticação do conector do SharePoint ajustando as configurações de OAuth no Copilot Studio, adicionando as permissões delegadas corretas no Microsoft Entra ID e publicando o bot no site do SharePoint de destino. Em seguida, considere habilitar o log de auditoria no SharePoint para rastrear todas as solicitações de acesso a dados do bot. Como dica avançada, use permissões de aplicativo em vez de permissões delegadas se o bot precisar ser executado sem um usuário conectado — isso requer adicionar o aplicativo às Permissões do site do SharePoint por meio do centro de administração do SharePoint.