Compartilhar via

Configurar segurança do canal da Web e do Direct Line

Quando você cria um agente do Copilot Studio, ele é disponibilizado imediatamente no Site de demonstração e em canais do Site personalizado para qualquer pessoa que conheça a ID do agente. Esses canais estão disponíveis por padrão e nenhuma configuração é necessária.

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

Observação

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 no Copilot Studio ou podem recebê-la de alguém. Porém, dependendo da capacidade e sensibilidade do agente, isso pode não ser desejável.

Com a segurança baseada no Direct Line, é possível habilitar o acesso somente em locais controlados por você ativando o 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.

Observação

O Copilot Studio usa o canal do Direct Line do Bot Framework para conectar a 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.

Após habilitar essa opção, os canais precisarão que o cliente autentique as solicitações, seja ao usar um segredo ou ao usar um token gerado usando o segredo, obtido no 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, em seguida, selecione segurança de canal da Web.

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

  1. Habilitar Exigir acesso protegido.

Aviso

Depois de habilitar ou desabilitar "Exigir acesso seguro", o sistema poderá levar até duas horas para 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 o agente acidentalmente.

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

Captura de tela de uma mensagem de confirmação ao desabilitar o acesso seguro, que diz que essa ação renderiza o site de Demonstração e qualquer canal do Direct Line que não esteja usando um segredo ou token disponível. 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 gravando um aplicativo no qual o cliente executa um navegador da Web ou aplicativo móvel, ou se os clientes puderem visualizar o código, será necessário trocar o segredo por um token. Caso não use um token, o segredo poderá ficar comprometido. Quando estiver criando a solicitação para adquirir o token no 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 recomendamos expor o segredo em um código executado no navegador, seja ele codificado ou transferido por uma chamada de rede.

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

Obter os segredos

Você precisará do segredo para 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 para copiá-lo para a área de transferência. Selecione o ícone de visibilidade para revelar o segredo. Um aviso aparece antes que ele seja revelado.

Trocar segredos

Se você precisar alterar o segredo que está sendo usado pelo agente, faça-o sem qualquer interrupção ou tempo de inatividade.

O Copilot Studio fornece dois segredos que funcionam simultaneamente. Você pode trocar o segredo que está sendo usado pelo outro. Depois de trocar os segredos e os usuários se conectarem usando o novo, você pode regenerar o segredo com segurança.

Regenerar um segredo

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

Aviso

Qualquer perfil de usuário conectado usando o segredo original ou um token obtido desse segredo é desconectado.

Gerar um token

É possível gerar um token que pode ser usado ao iniciar uma única conversa de agente. Para obter mais informações, consulte a seção Obter token do Direct Line no tópico Publicar um agente aos aplicativos móveis ou personalizados.

  1. Obter os segredos.

  2. Emita a seguinte solicitação no código do serviço 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 da 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 o token permanecer útil, é necessário atualizar o token antes que ele expire.

Atualizar um token

Um token pode ser atualizado um número ilimitado de vezes, desde que não tenha expirado.

Não é possível atualizar um token expirado.

Para atualizar um token, emita a seguinte solicitação e substitua <TOKEN TO BE REFRESHED> pelo token que 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 da resposta da 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 o novo token permanecer útil, é necessário atualizar o token novamente antes que ele expire.

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 em API do Direct Line – Autenticação.

Conteúdo relacionado

  • Last updated on