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

  • Artigo

Quando você cria um copiloto do Microsoft Copilot Studio, ele é disponibilizado imediatamente nos canais Site de demonstração e Site personalizado para todos que conhecem a ID do copiloto. 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 copiloto diretamente no Microsoft Copilot Studio ou recebê-la de alguém. Mas, dependendo da capacidade e sensibilidade do copiloto, 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 Microsoft Copilot Studio usa o canal do Direct Line do Bot Framework para conectar a página da Web ou aplicativo ao copiloto.

Habilitar ou desabilitar a segurança do canal da Web

É possível impor o uso de segredos e tokens para cada copiloto 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.

Qualquer acesso ao copiloto que não forneça essa medida de segurança não funcionará.

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

    Captura de tela mostrando a segurança do canal da Web em destaque no submenu Configurações.

  2. Defina a opção Exigir acesso seguro como Habilitado.

    Captura de tela mostrando a página de segurança do canal da Web.

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é então, a configuração anterior estará em vigor. Você não precisa publicar o copiloto para que esta alteração entre em vigor.

Planeje com antecedência para evitar expor o copiloto acidentalmente.

Caso precise desabilitar a opção de segurança do canal da Web, defina Exigir acesso seguro como Desabilitado. Pode levar até duas horas para propagar o comando de desabilitar o acesso seguro.

Captura de tela mostrando uma mensagem de confirmação ao desabilitar o acesso seguro, informando que essa ação renderiza o site de demonstração e canais do Direct Line sem usar 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 copiloto do Microsoft 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 Í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 copiloto, faça-o sem qualquer interrupção ou tempo de inatividade.

O Microsoft 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

Todos os usuários conectados usando o segredo original ou um token obtido desse segredo serão desconectados.

Gerar um token

É possível gerar um token que pode ser usado ao iniciar uma única conversa do copiloto. Para obter mais informações, consulte a seção Obter token do Direct Line em Publicar um copiloto a 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

Não há limite de atualizações para o token, contanto que ele 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