Compartilhar via

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

Quando você cria um agente do Copilot Studio, ele fica imediatamente disponível nos canais Demo e Custom 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 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 de dentro do Copilot Studio ou recebendo-a de alguém. Porém, dependendo da capacidade e sensibilidade do agente, isso pode não ser desejável.

Com a segurança baseada em Direct Line, você pode permitir o acesso apenas a locais que você controla, habilitando o acesso seguro com segredos do Direct Line ou tokens.

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

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.

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 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 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 em seu código de serviço é a maneira mais segura de proteger seu agente do 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 está sendo usado pelo agente, faça-o sem qualquer interrupção ou tempo de inatividade.

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 Direct Line em Publicar um agente em aplicativos móveis ou personalizados.

  1. Obter o segredo.

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

Conteúdo relacionado

  • Last updated on