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 em seu site façam login nos clientes se eles entrarem na página ou aplicativo em que o agente está implantado.

Pré-requisitos

• Configure a autenticação do usuário com um provedor OAuth 2.0 genérico.
• Adicione autenticação de usuário a tópicos.
• Personalize a aparência de um agente.

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 solicitações de entrada, a tela personalizada precisa intercetar mensagens com anexos que tenham o tipo application/vnd.microsoft.card.oauthde conteúdo . Os anexos OAuthCard contêm uma content.tokenPostResource.sasUrl propriedade, da qual a URL segura pode ser extraída. Finalmente, a tela personalizada deve postar 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 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 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 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.

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.