Configurar a segurança dos canais Web e Direct Line

Quando você cria um agente Copilot Studio, qualquer pessoa que conheça a ID do agente poderá acessar imediatamente o agente por meio dos canais Demo e Custom. Esses canais estão disponíveis por padrão e nenhuma configuração é necessária.

Para o aplicativo Microsoft Teams, você pode configurar opções avançadas de segurança de canal da Web.

Note

Se você tem uma Licença apenas para o Teams, não pode gerar segredos para permitir o acesso seguro. Os tokens de acesso seguro são criados automaticamente para você e o acesso seguro é habilitado por padrão.

Os usuários podem encontrar a ID do agente diretamente de dentro do Copilot Studio ou recebendo-a de alguém. Mas, dependendo da capacidade e sensibilidade do agente, esse acesso pode não ser desejável.

Ao usar a segurança baseada em Direct Line, é possível permitir o acesso apenas a locais que você controla, garantindo acesso seguro com segredos ou tokens do Direct Line.

Também é possível trocar e regenerar segredos e atualizar tokens, e você poderá facilmente desabilitar o acesso seguro se não quiser mais usá-lo.

Note

Copilot Studio usa o canal Direct Line Bot Framework para conectar sua página da Web ou aplicativo ao agente.

Habilitar ou desabilitar a segurança do canal da Web

Você pode impor o uso de segredos e tokens para cada agente individual.

Quando você ativa essa opção, os canais precisam que o cliente autentique suas solicitações usando um segredo ou usando um token gerado usando o segredo, obtido em runtime.

As tentativas de acessar o agente que não fornecem essa medida de segurança não funcionam.

  1. Vá para a página Configurações do agente, selecione Segurança e selecione segurança de canal da Web.

Captura de tela com a segurança do canal web destacada no painel de configurações.

  1. Ative Exigir acesso protegido.

Aviso

Quando você ativa ou desativa a Necessidade de acesso seguro, pode levar até duas horas para o sistema propagar as configurações e entrar em vigor. Até lá, a configuração anterior está em vigor. Você não precisa publicar o agente para que essa alteração entre em vigor.

Planeje com antecedência para evitar expor seu agente sem querer.

Se você precisar desabilitar a opção de segurança do canal da Web, poderá fazer isso desmarcando a alternância Exigir acesso seguro . Desabilitar o acesso seguro pode levar até duas horas para se propagar.

Captura de tela de uma mensagem de confirmação ao desabilitar o acesso protegido, que diz que essa ação torna o site de demonstração e qualquer canal Direct Line que não esteja usando um segredo ou token, disponíveis. Essa ação pode levar até duas horas para entrar em vigor.

Usar segredos ou tokens

Se você estiver criando um aplicativo de serviço a serviço, especificar o segredo nas solicitações do cabeçalho de autorização pode ser a abordagem mais simples.

Se você estiver desenvolvendo um aplicativo no qual o cliente executa em um navegador da Web ou em um aplicativo móvel, ou se de outra forma o código puder ser visível para os clientes, você deve trocar seu segredo por um token. Caso não use um token, o segredo poderá ficar comprometido. Quando estiver fazendo a solicitação para adquirir o token no seu serviço, especifique o segredo no cabeçalho de autorização.

Os tokens funcionarão somente para uma única conversa e expirarão caso não sejam atualizados.

Escolha o modelo de segurança que melhor se adapte à sua situação.

Aviso

Não exponha o segredo em nenhum código executado no navegador, codificado ou transferido por meio de uma chamada de rede.

Adquirir o token usando o segredo em seu código de serviço é a maneira mais segura de proteger seu agente de Copilot Studio.

Obter os segredos

Você precisa do segredo para que possa especificá-lo nas solicitações do cabeçalho de autorização do aplicativo ou semelhantes.

  1. No menu de navegação, em Configurações, selecione Segurança. Em seguida, selecione o bloco Segurança de canal da Web.

  2. Selecione Copiar para Segredo 1 ou Segredo 2 e copie-o para a área de transferência. Selecione o ícone de visibilidade para revelar o segredo. Um aviso aparece antes de você poder revelá-lo.

Trocar segredos

Se você precisar alterar o segredo que seu agente usa, poderá alterá-lo sem nenhum tempo de inatividade ou interrupção.

Copilot Studio fornece dois segredos, que funcionam simultaneamente. Você pode trocar o segredo que seu agente usa com o outro. Depois que os segredos forem trocados e os usuários estiverem todos conectados usando o novo segredo, você poderá regenerar o segredo.

Regenerar um segredo

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

Aviso

O perfil de usuário que se conecta usando o segredo original ou um token obtido desse segredo é desconectado.

Gerar um token

Você pode gerar um token que utiliza ao iniciar uma conversa única com um agente. Para obter mais informações, consulte a seção Obtenha o token Direct Line em Publicar um agente em aplicativos móveis ou personalizados.

  1. Obter o segredo.

  2. Em seu código de serviço, envie a solicitação a seguir para trocar o segredo por um token. Substitua <SECRET> pelo valor do segredo obtido na Etapa 1.

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

Os trechos a seguir fornecem exemplos da solicitação de token gerada e a resposta.

Exemplo de solicitação de geração de token

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

Exemplo de resposta para a geração de token

HTTP/1.1 200 OK
[other headers]

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

Se a solicitação for bem-sucedida, a resposta conterá um token válido para uma conversa e um valor expires_in que indica o número de segundos restantes até o token expirar.

Para manter o token útil, você deve atualizar o token antes que ele expire.

Atualizar um token

Você pode atualizar um token um número ilimitado de vezes, desde que ele não tenha expirado.

Você não pode atualizar um token expirado.

Para atualizar um token, envie a solicitação a seguir e substitua <TOKEN TO BE REFRESHED> pelo token que você deseja atualizar.

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

Os trechos a seguir fornecem exemplos da solicitação de atualização do token e a resposta.

Exemplo da solicitação 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 a solicitação for bem-sucedida, a resposta conterá um novo token válido para a mesma conversa do token anterior e um valor expires_in que indica o número de segundos restantes até o novo token expirar.

Para manter o novo token útil, atualize o token novamente antes de expirar.

HTTP/1.1 200 OK
[other headers]

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

Para obter mais informações sobre como atualizar um token, consulte a seção Atualizar um token do Direct Line na seção Direct Line API - Autenticação.

Conteúdo relacionado

  • Last updated on