Configurar logon único com um provedor OAuth genérico

O Copilot Studio oferece suporte a logon único (SSO) com provedores de autenticação compatíveis com OAuth 2.0. O SSO permite que os agentes em seu site conectem clientes se eles fizerem logon na página ou no aplicativo em que o agente está implantado.

Pré-requisitos

Criar ou usar uma tela personalizada que ofereça suporte ao fluxo de SSO do provedor OAuth genérico

Quando o tópico de autenticação é disparado em agentes conectados a um provedor OAuth 2.0 genérico, o Copilot Studio envia uma mensagem contendo uma URL segura, que é usada para enviar o token de acesso do usuário.

A tela personalizada ou uma página em que a tela está inserida deve implementar o seguinte padrão:

  1. Obtenha um token de acesso para o usuário conectado do provedor de autenticação OAuth 2.0 usando o método preferido.

  2. Intercepte uma mensagem de entrada do Copilot Studio e extraia a URL segura.

  3. Publique o token de acesso na URL segura.

Extraia a URL segura e publique o token

A tela personalizada intercepta mensagens recebidas usando um conceito de middleware, que consiste em código executado no contexto do recebimento de mensagens do Copilot Studio.

Para responder a solicitações de entrada, a tela personalizada precisa interceptar mensagens com anexos que tenham o tipo de conteúdo application/vnd.microsoft.card.oauth. Os anexos OAuthCard contêm uma propriedade content.tokenPostResource.sasUrl da qual a URL segura pode ser extraída. Por fim, a tela personalizada deve publicar o token de acesso do usuário na URL segura.

O código JavaScript a seguir é um exemplo de código de middleware que extrai a URL segura e publica um token. Se a postagem for bem-sucedida, o middleware retornará false. Se a postagem não for bem-sucedida ou se a atividade não tiver a propriedade application/vnd.microsoft.card.oauth, ela retornará 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);
  }
};

Exemplo de código completo

A implementação de uma tela ou aplicativo personalizado que obtém um token de um usuário autenticado e envia esse token para o Copilot Studio varia conforme o seu provedor de autenticação. Para obter mais informações, consulte a documentação do seu provedor de autenticação para obter mais detalhes sobre fluxos de entrada e obtenção de tokens de acesso. Para obter um exemplo de referência usando OKTA, consulte SSO de terceiros com OKTA.

Usando o token no Copilot Studio

Os tokens que são enviados por meio da URL segura são armazenados na variável System.User.AccessToken no Copilot Studio. Os criadores de agentes podem utilizar essa variável de sistema para acessar APIs protegidas vinculadas ao provedor autenticado que gerou o token.

No exemplo a seguir, uma chamada HTTP é configurada com um cabeçalho Authorization que usa System.User.AccessToken.

Captura de tela ilustrando uma chamada HTTP que acessa uma API segura.

Canais compatíveis

O SSO com um provedor de autenticação OAuth genérico é um padrão personalizado, que pode ser implementado por uma tela personalizada ou por qualquer outro cliente que trabalhe com a API do Directline.

  • Last updated on