Configurar início de sessão único com um fornecedor genérico de OAuth

O Copilot Studio suporta início de sessão único (SSO) com fornecedores de autenticação compatíveis com OAuth 2.0. O SSO permite que os agentes no seu site iniciem sessão dos clientes se estes já tiverem iniciado sessão na página ou aplicação onde o agente está implementado.

Pré-requisitos

Crie ou utilize uma tela personalizada que suporte o fluxo SSO do fornecedor OAuth genérico

Quando o tópico de autenticação é acionado em agentes ligados a um fornecedor OAuth 2.0 genérico, o Copilot Studio envia uma mensagem contendo um URL seguro, que é usado para enviar o token de acesso do utilizador.

A tela personalizada ou uma página onde a tela está incorporada deve implementar o seguinte padrão:

  1. Obtenha um token de acesso para o utilizador com sessão iniciada a partir do seu fornecedor de autenticação OAuth 2.0, utilizando o método que preferir.

  2. Intercete uma mensagem a receber do Copilot Studio e extraia o URL seguro.

  3. Publique o token de acesso no URL seguro.

Extrair o URL seguro e publicar o token

A tela personalizada intercepta mensagens a receber utilizando um conceito de middleware, que é código executado no contexto da receção de mensagens do Copilot Studio.

Para responder a pedidos de informações de início de sessão, a tela personalizada precisa de intercetar mensagens com anexos que tenham o tipo de conteúdo application/vnd.microsoft.card.oauth. Os anexos OAuthCard contêm a propriedade content.tokenPostResource.sasUrl, de onde se pode extrair o URL seguro. Por fim, a tela personalizada deve enviar o token de acesso do utilizador para o URL seguro.

O código JavaScript seguinte é um exemplo de código middleware que extrai o URL seguro e publica um token. Se a publicação for bem-sucedida, o middleware devolve false. Se a publicação não for bem-sucedida, ou se a atividade não tiver a propriedade application/vnd.microsoft.card.oauth, devolve next(…args).

const activityMiddleware = () => next => (...args) => {
  if (args[0].activity.attachments?.[0]?.contentType === 'application/vnd.microsoft.card.oauth') {
    var postEndpoint = args[0].activity.attachments?.[0].content.tokenPostResource.sasUrl;

    // Perform an HTTP POST to the secure URL with the body of:
    // {
    //     "token": <user_token> 
    // } 

    if(success)
       return false;
    else
       return next(...args);
  } else {
    return next(...args);
  }
};

Código de exemplo completo

A implementação de uma tela ou aplicação personalizada que obtém um token para um utilizador com sessão iniciada e publica o token no Copilot Studio, varia de acordo com o seu fornecedor de autenticação. Para obter mais informações, consulte a documentação do seu fornecedor de autenticação para obter mais detalhes sobre fluxos de início de sessão e obtenção de tokens de acesso. Para um exemplo de integração usando OKTA, consulte SSO de terceiros com OKTA.

Utilização do token no Copilot Studio

Os tokens que são publicados usando o URL seguro são preenchidos na variável System.User.AccessToken no Copilot Studio. Os criadores de agentes podem usar esta variável do sistema para aceder a APIs protegidas que estão ligadas ao fornecedor autenticado que gerou o token.

No exemplo seguinte, uma chamada HTTP é configurada com um cabeçalho de autorização que utiliza System.User.AccessToken.

Captura de ecrã que ilustra uma chamada HTTP que acede a uma API segura.

Canais suportados

O SSO com um fornecedor de autenticação OAuth genérico é um padrão personalizado, que pode ser implementado através de uma tela personalizada ou de qualquer outro cliente que trabalhe com a API DirectLine.

  • Last updated on