Configurar conectores externos para tarefas de enriquecimento

Os provedores de autenticação de terceiros permitem conectar com segurança as tarefas de enriquecimento do Knowledge Studio a plataformas externas, como GitHub, Microsoft SharePoint e Atlassian Confluence. Conclua as etapas de geração de credenciais e configuração do provedor de autenticação neste documento como parte da configuração de pré-requisitos.

Antes de começar

Antes de configurar conectores externos, verifique se você concluiu os seguintes pré-requisitos:

  • Confira o fluxo de trabalho geral de configuração de enriquecimento em Configurar pré-requisitos para tarefas de enriquecimento.
  • Verifique se você tem as permissões de administrador ou desenvolvedor necessárias nas plataformas de terceiros de destino (GitHub, Microsoft SharePoint ou Atlassian Confluence) para gerar tokens de acesso ou registrar aplicativos.
  • Para armazenar credenciais com segurança e anexá-las a tarefas, verifique se você configurou corretamente o serviço de identidade do agente. Para mais informações, consulte Configurar permissões do IAM para provedores de autenticação.

Ao conectar o agente de enriquecimento a fontes de conhecimento de terceiros, use o serviço de identidade do agente do Google Cloud . A Identidade do Agente atua como um gerenciador de autenticação que armazena com segurança suas credenciais de terceiros e provisiona tokens de acesso de curta duração para o agente de enriquecimento, de modo que os operadores humanos nunca precisem gerenciar diretamente as chaves secretas do cliente brutas durante a execução da tarefa.

Configurar o GitHub

Para conectar o Knowledge Studio aos repositórios do GitHub, crie um token de acesso pessoal (PAT, na sigla em inglês) detalhado no GitHub e armazene-o em um provedor de autenticação de chave de API.

  1. Faça login no GitHub, clique na foto do perfil e em Configurações.
  2. Acesse Configurações do desenvolvedor > Tokens de acesso pessoal > Tokens refinados.
  3. Clique em Gerar novo token.
  4. Configure as propriedades do token:
    • Nome do token: insira um nome descritivo (por exemplo, enrichment-agent).
    • Expiração: defina uma data de validade adequada.
    • Proprietário do recurso: selecione a organização ou a conta de usuário proprietária dos repositórios de destino.
    • Acesso ao repositório: selecione Somente repositórios selecionados e escolha os repositórios que você quer enriquecer.
    • Permissões: conceda acesso específico de Leitura ou Leitura e Gravação para os escopos necessários (como Problemas, Solicitações de pull e Conteúdo).
  5. Clique em Gerar token e copie o token com segurança.
  6. Registre um provedor de autenticação de chave de API em Google Cloud e forneça o PAT como a chave de API. Consulte Autenticar usando uma chave de API com o gerenciador de autenticação.

Para mais informações sobre como criar um PAT, consulte Como gerenciar seus tokens de acesso pessoal na documentação do GitHub.

Configurar o Microsoft SharePoint

Se você estiver se conectando ao Microsoft SharePoint, use um fluxo OAuth de duas etapas para receber as credenciais do Microsoft Entra ID (antigo Azure Active Directory).

  1. Registre um novo aplicativo no centro de administração do Microsoft Entra.
  2. Conceda permissões da API Microsoft Graph:
    1. Acesse Permissões da API > Adicionar uma permissão > Microsoft Graph > Permissões do aplicativo (não selecione Permissões delegadas).
    2. Adicione os escopos Sites.Read.All e Files.Read.All.
    3. Clique em Conceder consentimento de administrador para seu locatário, de modo que as duas permissões de aplicativo apareçam como "Concedidas".

  3. Crie uma nova chave secreta do cliente. Registre o valor imediatamente, porque ele é mostrado apenas uma vez. Para mais informações, consulte Criar uma nova chave secreta do cliente.

  4. Copie os valores de configuração do aplicativo. Após o registro, colete os seguintes valores para a configuração do provedor de autenticação:

    • ID do cliente: o ID do aplicativo (cliente) da visão geral do app.
    • URL do token: na página Visão geral, clique na guia Endpoints. Copie o URL rotulado como Endpoint do token OAuth 2.0 (v2).

  5. Registre um provedor de autenticação OAuth de duas etapas no Google Cloud usando esses secrets. Ao criar o provedor, forneça o escopo padrão para o parâmetro --allowed-scopes:

    --allowed-scopes="https://graph.microsoft.com/.default"

    Para mais informações, consulte Registrar um aplicativo com a plataforma de identidade da Microsoft na documentação do Microsoft Entra.

Configurar o Atlassian Confluence

Como o Confluence não é compatível com o OAuth de duas etapas para agentes de servidor para servidor, você precisa criar uma conta de serviço dedicada (ou uma conta de usuário fictícia) na Atlassian, conceder as permissões necessárias e gerar um PAT.

  1. Faça login na conta de serviço específica no Confluence.
  2. Clique na sua foto do perfil no canto superior direito da tela.
  3. Selecione Configurações (ou Configurações da conta) no menu.
  4. Na guia "Segurança", acesse a seção "Tokens de API".
  5. Clique no botão Criar token de API com escopos. Não use um token sem escopo, porque ele não vai buscar todas as ferramentas necessárias.
  6. Insira um nome descritivo (por exemplo, enrichment-agent), configure a data de validade e clique em Próxima.
  7. Na lista Selecionar o app, selecione a opção Atlassian MCP e clique em Próxima.
  8. Selecione todos os seguintes escopos de leitura e pesquisa do Confluence:
    • read:page:confluence
    • read:space:confluence
    • search:confluence
    • read:confluence-content.all
    • read:confluence-content.summary
    • read:confluence-space.summary
    • search:rovo:mcp
    • read:jira-work
  9. Clique em Próxima e em Criar.
  10. Copie o token gerado.
  11. Formate a string de credencial para o provedor de autenticação Google Cloud como <ATLASSIAN_EMAIL>:<API_TOKEN>. A Atlassian exige a codificação de autenticação básica HTTP (email:api_token) para usar os tokens de API pessoais de maneira programática.
  12. Registre um provedor de autenticação de chave de API em Google Cloud e forneça a string <ATLASSIAN_EMAIL>:<API_TOKEN> como a chave de API. Consulte Autenticar usando uma chave de API com o gerenciador de autenticação.

Para mais informações sobre como criar um PAT, consulte Gerenciar tokens de API para sua conta da Atlassian na documentação da Atlassian.

A seguir