Configurar o logon único com um provedor OAuth genérico

O Copilot Studio suporta logon único (SSO) com provedores de autenticação compatíveis com OAuth 2.0. O SSO permite que os agentes no seu site conectem os clientes, caso eles tenham feito login na página ou aplicação onde o agente está implementado.

Pré-requisitos

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

Quando o tópico de autenticação é acionado em agentes 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 onde a tela está incorporada deve implementar o seguinte padrão:

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

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

  3. Poste o token de acesso na URL segura.

Extraia o URL seguro e publique o token

A tela personalizada interceta mensagens recebidas usando um conceito de middleware, que é um código executado no contexto do recebimento 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 uma content.tokenPostResource.sasUrl propriedade, da qual a URL segura pode ser extraída. Finalmente, o canvas personalizado deve enviar o token de acesso do utilizador para o URL seguro.

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 application/vnd.microsoft.card.oauth propriedade, 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);
  }
};

Código de exemplo completo

A implementação de uma tela ou aplicativo personalizado que obtém um token para um usuário conectado e publica o token no 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 um exemplo de referência utilizando OKTA, consulte SSO de terceiros com OKTA.

Usando o token no Copilot Studio

Os tokens que são postados usando a URL segura são preenchidos na System.User.AccessToken variável no Copilot Studio. Os criadores de agentes podem usar essa variável de sistema para acessar APIs protegidas que estão 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 ecrã que ilustra uma chamada HTTP que acede a uma API segura.

Canais suportados

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

  • Last updated on