Configurar el inicio de sesión único con un proveedor OAuth genérico

Copilot Studio admite el inicio de sesión único (SSO) con proveedores de autenticación compatibles con OAuth 2.0. SSO permite a los agentes de su sitio web iniciar sesión de los clientes si iniciaron sesión en la página o aplicación donde se implementa el agente.

Requisitos previos

Cree o utilice un lienzo personalizado que admita el flujo SSO genérico del proveedor OAuth

Cuando se activa el tema de autenticación en agentes conectados con un proveedor genérico de OAuth 2.0, Copilot Studio envía un mensaje que contiene una URL segura, la cual se utiliza para publicar el token de acceso del usuario.

El lienzo personalizado o una página donde esté incrustado el lienzo debe implementar el siguiente patrón:

  1. Obtenga un token de acceso para el usuario que inició sesión de su proveedor de autenticación OAuth 2.0, utilizando su método preferido.

  2. Interceptar un mensaje entrante de Copilot Studio y extraer la URL segura.

  3. Publique el token de acceso en la URL segura.

Extraiga la URL segura y publique el token

El lienzo personalizado intercepta los mensajes entrantes utilizando el concepto de middleware, que es código que se ejecuta en el contexto de la recepción de mensajes de Copilot Studio.

Para responder a las solicitudes de inicio de sesión, el lienzo personalizado debe interceptar mensajes con archivos adjuntos que tengan el código tipo de contenido application/vnd.microsoft.card.oauth. Los archivos adjuntos OAuthCard contienen una propiedad content.tokenPostResource.sasUrl, de la cual se puede extraer la URL segura. Finalmente, el lienzo personalizado debe publicar el token de acceso del usuario en la URL segura.

El siguiente código JavaScript es un ejemplo de código middleware que extrae la URL segura y publica un token. Si la publicación tiene éxito, el middleware devuelve false. Si la publicación no tiene éxito, o si la actividad no tiene la propiedad application/vnd.microsoft.card.oauth, devuelve 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);
  }
};

Ejemplo completo de código

La forma de implementar un lienzo personalizado o una aplicación que obtiene un token para un usuario autenticado y envía el token a Copilot Studio varía según el proveedor de autenticación. Para obtener más información, consulte la documentación de su proveedor de autenticación para obtener más detalles sobre los flujos de inicio de sesión y la obtención de tokens de acceso. Para obtener un ejemplo de referencia utilizando OKTA, consulte SSO de terceros con OKTA.

Uso del token en Copilot Studio

Los tokens que se envían mediante la URL segura se almacenan en la variable System.User.AccessToken de Copilot Studio. Los creadores de agentes pueden usar esta variable del sistema para acceder a las API protegidas que están conectadas al proveedor autenticado que generó el token.

En el siguiente ejemplo, una llamada HTTP se configura con un encabezado de autorización que utiliza System.User.AccessToken.

Captura de pantalla que ilustra una llamada HTTP que accede a una API segura.

Canales admitidos

SSO con un proveedor de autenticación OAuth genérico es un patrón personalizado, que puede implementarse mediante un lienzo personalizado o cualquier otro cliente que trabaje con la API de Directline.

  • Last updated on