Configurar logon único com um provedor OAuth genérico

Artigo
07/23/2024

Importante

As capacidades e os recursos do Power Virtual Agents agora fazem parte do Microsoft Copilot Studio após investimentos significativos em IA generativa e integrações aprimoradas no Microsoft Copilot.

Alguns artigos e capturas de tela podem fazer referência ao Power Virtual Agents enquanto atualizamos a documentação e o conteúdo do treinamento.

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 copilotos em seu site conectem clientes se eles fizerem logon na página ou no aplicativo em que o copiloto 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 é acionado em copilotos conectados a um provedor OAuth 2.0 genérico, o Copilot Studio envia uma mensagem contendo uma URL segura, que é usada para postar 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:

Obtenha um token de acesso para o usuário conectado do provedor de autenticação OAuth 2.0 usando o método preferido.
Intercepte uma mensagem de entrada do Copilot Studio e extraia a URL segura.
Publique o token de acesso na URL segura.

Extraia a URL segura e publique o token

A tela personalizada intercepta mensagens de entrada usando um conceito de middleware, que é um código executado no contexto de 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 para um usuário conectado e posta o token para o Copilot Studio varia de acordo com 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 publicados usando a URL segura são preenchidos na variável System.User.AccessToken no Copilot Studio. Os criadores do copiloto podem usar essa variável de sistema para acessar APIs protegidas conectadas 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 APU 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.

Compartilhar via