Configurar segurança da Web e do canal Direct Line

Quando cria um agente do Copilot Studio, qualquer pessoa que saiba o ID do agente pode aceder imediatamente ao agente através dos canais Site de demonstração e Site personalizado. Estes canais estão disponíveis predefinidamente e não é necessária nenhuma configuração.

Para a aplicação Microsoft Teams, pode configurar opções de segurança avançadas para canais Web.

Nota

Se tiver uma licença exclusiva do Teams, não pode gerar segredos para ativar o acesso seguro. Os tokens de acesso seguro são criados automaticamente para si e o acesso seguro está ativado por predefinição.

Os utilizadores podem encontrar o ID do agente diretamente no Copilot Studio ou recebê-lo de alguém. Mas, dependendo da capacidade e da sensibilidade do agente, este acesso pode não ser desejável.

Ao utilizar a segurança baseada no Direct Line, pode ativar o acesso apenas a locais que controla, ativando o acesso seguro com segredos ou tokens do Direct Line.

Também pode trocar e regenerar segredos e atualizar tokens, e pode facilmente desativar o acesso seguro se já não quiser usá-lo.

Nota

O Copilot Studio utiliza o canal do Direct Line do Bot Framework para ligar a sua página Web ou aplicação ao agente.

Ativar ou desativar segurança de canal Web

Pode impor a utilização de segredos e tokens para cada agente individual.

Quando ativar esta opção, os canais precisarão que o cliente autentique os seus pedidos, quer utilizando um segredo, quer utilizando um token que é gerado através do segredo, obtido em runtime.

As tentativas de acesso ao agente que não forneçam esta medida de segurança falham.

  1. Vai para a página Definições do seu agente, selecione Segurança e, em seguida, selecione Segurança do canal Web.

Captura de ecrã da segurança do canal Web em destaque na lista de opções Definições.

  1. Ative Requerer acesso seguro.

Aviso

Ao ativar ou desativar Requerer acesso seguro, pode demorar até duas horas para que o sistema propague as definições e estas entrem em vigor. Até lá, a definição anterior está em vigor. Não precisa de publicar o agente para que esta alteração entre em vigor.

Planeie com antecedência para evitar expor o seu agente involuntariamente.

Se precisar de desativar a opção de segurança do canal Web, pode fazê-lo desmarcando a opção Requerer acesso seguro. Desativar o acesso seguro pode demorar até duas horas a propagar-se.

Captura de ecrã de uma mensagem de confirmação quando desativa o acesso seguro, que diz que esta ação torna o Site de demonstração e qualquer canal de Direct Line que não use um segredo ou token disponível. Esta ação pode levar até duas horas para entrar em vigor.

Use segredos ou tokens

Se estiver a criar uma aplicação de serviço para serviço, especificar o segredo nos pedidos de cabeçalho de autorização poderá ser a abordagem mais simples.

Se estiver a escrever uma aplicação onde o cliente é executado num browser Web ou numa aplicação móvel, ou caso contrário o código pode ser visível para os clientes, deve trocar o seu segredo por um token. Se não usar um token, o seu segredo pode ficar comprometido. Quando estiver a fazer o pedido para adquirir o token no seu serviço, especifique o segredo no cabeçalho de autorização.

Os tokens só funcionam para uma única conversa e expirarão a menos que sejam atualizados.

Escolha o modelo de segurança que funcione melhor para a sua situação.

Aviso

Não exponha o segredo em qualquer código que seja executado no browser, seja ele codificado no código ou transferido através de uma chamada de rede.

Adquirir o token utilizando o segredo no código do seu serviço é a forma mais segura de proteger o seu agente do Copilot Studio.

Obtenha os segredos

Vai precisar do segredo para que possa especificá-lo nos pedidos de cabeçalho de autorização da sua aplicação ou semelhantes.

  1. No menu de navegação, em Definições, selecione Segurança. Em seguida, selecione o mosaico Segurança do canal Web.

  2. Selecione Copiar para Segredo 1 ou Segredo 2 para copiá-lo para a área de transferência. Selecione o ícone de visibilidade para revelar o segredo. Aparece um aviso antes de poder revelá-lo.

Trocar segredos

Se precisar de alterar o segredo utilizado pelo seu agente, pode fazê-lo sem qualquer tempo de inatividade ou interrupção.

O Copilot Studio fornece-lhe dois segredos, que funcionam simultaneamente. Pode trocar o segredo que o seu agente utiliza pelo outro. Depois de os segredos serem trocados e os seus utilizadores estarem todos ligados utilizando o novo segredo, pode regenerar o segredo.

Regenerar um segredo

Para regenerar um segredo, selecione Regenerar ao lado do segredo.

Aviso

O perfil de utilizador que se liga utilizando o segredo original ou um token obtido a partir desse segredo é desligado.

Gerar um token

Pode gerar um token que utiliza ao iniciar uma única conversa de agente. Para mais informações, consulte a secção Obter token do Direct Line em Publicar um agente em aplicações móveis ou personalizadas.

  1. Obtenha o segredo.

  2. No código do seu serviço, envie o seguinte pedido para trocar o segredo por um token. Substitua <SECRET> pelo valor do segredo que obteve no Passo 1.

    POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer <SECRET>

Os seguintes fragmentos de código fornecem exemplos do pedido de token gerado e da sua resposta.

Exemplo de gerar pedido de token

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

Exemplo de resposta a gerar pedido de token

HTTP/1.1 200 OK
[other headers]

{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800
}

Se o pedido for bem sucedido, a resposta contém um token válido para uma conversa e um valor expires_in que indica o número de segundos até que o token expire.

Para que o token permaneça útil, deve atualizar o token antes que expire.

Atualizar um símbolo

Pode atualizar um token um número ilimitado de vezes, desde que não esteja expirado.

Não pode atualizar um token expirado.

Para atualizar um token, envie o seguinte pedido e substitua <TOKEN TO BE REFRESHED> pelo token que pretende atualizar.

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer <TOKEN TO BE REFRESHED>

Os seguintes fragmentos fornecem exemplos do pedido de atualizar token e a sua resposta.

Exemplo de pedido de atualização

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

Exemplo de resposta de atualização

Se o pedido for bem-sucedido, a resposta contém um novo token válido para a mesma conversa que o token anterior e um valor expires_in que indica o número de segundos até que o novo token expire.

Para que o token permaneça útil, volte a atualizá-lo antes que expire.

HTTP/1.1 200 OK
[other headers]

{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
  "expires_in": 1800
}

Para mais informações sobre a atualização de um token, consulte a secção Atualizar um token do Direct Line em Direct Line API - Autenticação.

Conteúdos relacionados

  • Last updated on