Agregar autenticación de usuario final a un bot de Power Virtual Agents
Seleccione la versión de Power Virtual Agents que está usando aquí:
Puede habilitar la autenticación de usuario directamente dentro de una conversación de bot de Power Virtual Agents. La autenticación de usuario significa que puede obtener las propiedades básicas de un usuario, como el nombre y la identificación, en las variables del bot, pero también solicitar al usuario que inicie sesión utilizando un nodo de autenticación, recuperar un token de usuario para ese usuario y luego usar ese token para recuperar la información del usuario desde un sistema back-end.
También puede configurar el inicio de sesión único (SSO) para que sus usuarios no tengan que iniciar sesión manualmente.
Importante
Antes de usar esta función, debe seguir las instrucciones de configuración de autenticación de usuario final.
Requisitos previos
Variables de autenticación
Si su bot está configurado con las opciones de autenticación "Solo para Teams" o "Manual", tendrá un conjunto de variables de autenticación disponibles en sus temas. Compruebe la documentación de configuración de autenticación para obtener más información sobre cómo configurar la autenticación en su bot.
La siguiente tabla compara la disponibilidad de la variable de autenticación por opción de configuración de autenticación:
| Variable de autenticación | Sin autenticación | Solo para Teams | Manual |
|---|---|---|---|
UserDisplayName |
❌ | ✔️ | ✔️ |
UserID |
❌ | ✔️ | ✔️ |
IsLoggedIn |
❌ | ❌ | ✔️ |
AuthToken |
❌ | ❌ | ✔️ |
Variable UserDisplayName
La variable UserDisplayName contiene el nombre del usuario almacenado en el proveedor de identidad. Puede usar esta variable para saludar o referirse al usuario final sin que tenga que decírselo explícitamente al bot, lo que lo hace más personalizado.
Este valor de campo se obtiene de la notificación name de Azure Active Directory (Azure AD). Para los proveedores de OAuth, este es el valor almacenado en la notificación name. Power Virtual Agents extrae automáticamente este campo en la variable, así que asegúrese de tener profile como parte de su configuración del ámbito de la autenticación.
Variable UserID
La variable UserID contiene el identificador del usuario almacenado en el proveedor de identidad. Este valor lo pueden utilizar los flujos de Power Automate para llamar a las API que toman el UserID como valor.
Este valor de campo se obtiene de la notificación sub de Azure AD. Para los proveedores de OAuth, este es el valor almacenado en la notificación sub. Power Virtual Agents extrae automáticamente este campo en la variable.
Advertencia
Las variables UserDisplayName y UserID no se garantiza que se completen y pueden ser cadenas vacías según la configuración del usuario en el proveedor de identidad. Pruebe con un usuario de su proveedor de identificación para asegurarse de que sus temas funcionen correctamente, incluso si estas variables están vacías.
Variable IsLoggedIn
La variable IsLoggedIn indica si el usuario ha iniciado sesión (ya sea como resultado de iniciar sesión o de haberlo hecho ya, lo que se conoce como ruta de inicio de sesión válida) o no ha iniciado sesión (lo que daría como resultado la ruta de inicio de sesión fallida).
IsLoggedIn es una variable de tipo booleano que contiene el estado de inicio de sesión del usuario. Puede usar esta variable para crear una lógica de bifurcación en sus temas que verifique un inicio de sesión correcto (por ejemplo, en la plantilla ya proporcionada como parte de agregar el nodo Autenticar), o para obtener información de usuario de manera oportunista solo si el usuario ha iniciado sesión.
Variable AuthToken
La variable AuthToken contiene el token del usuario, obtenido después de que el usuario haya iniciado sesión. Puede pasar esta variable a flujos de Power Automate para que puedan conectarse a las API de back-end y recuperar la información del usuario, o para tomar medidas en nombre del usuario.
Advertencia
Asegúrese de pasar la variable AuthToken solo a fuentes confiables. Contiene información de autenticación del usuario que, si se ve comprometida, podría dañar al usuario.
No use AuthToken dentro de los nodos Mensaje o en flujos en los que no confía.
Prueba de variables de autenticación
Por defecto, el panel Bot de prueba utilizará la cuenta del usuario que ha iniciado sesión actualmente para completar las variables UserDisplayName y UserID. Sin embargo, al probar temas que utilizan autenticación, es posible que desee utilizar otros valores para estas variables (o incluso un valor en blanco).
Por ejemplo, es posible que desee probar cómo se utilizan los caracteres especiales o qué sucede si la variable está vacía.
Esto solo se aplica al panel Probar bot; no puede usar los comandos descritos en esta sección en un bot publicado implementado en un canal.
La siguiente tabla enumera los comandos que completarán estas variables. Ingrese el comando en el panel Probar bot tal como lo haría si estuviera normalmente charlando con el bot. Recibirá un mensaje de confirmación del bot si tiene éxito. Si su bot no usa la autenticación, recibirá un error.
Si reinicia el panel Probar bot (o realiza cambios en un tema que hacen que Probar bot se restablezca automáticamente), deberá enviar los comandos nuevamente.
| Variables | Comando valor personalizado | Comando de valor vacío (en blanco) |
|---|---|---|
UserDisplayName |
/debug set bot.UserDisplayName "Value" |
/debug set bot.UserDisplayName "" |
UserID |
No disponible | /debug set bot.UserID "" |
Importante
No puede poblar la variable UserID con un valor personalizado (que no sea un valor vacío o en blanco) debido a razones de seguridad.
Autenticación cuando se usa la configuración "Solo para equipos"
Si su opción de autenticación está configurada en Solo para equipos, no necesita agregar autenticación explícitamente a sus temas. En esta configuración, cualquier usuario en Microsoft Teams inicia sesión automáticamente a través de sus credenciales de Teams y no es necesario que inicien sesión explícitamente con una tarjeta de autenticación. Si su opción de autenticación está configurada en Manual, deberá agregar el nodo de autenticación (incluso para el canal Teams).
Nota
Si su opción de autenticación está configurada en "Solo para Teams", no tiene la opción de agregar autenticación explícitamente a sus temas.
Agregar autenticación de usuario a un tema
Inserte la plantilla del nodo de autenticación:
Vaya a la página de temas del bot que quiera editar.
Abra el Lienzo de creación del tema al que desea agregar la plantilla de autenticación.
Seleccione el icono de más (+) para agregar un nodo de mensaje. Introduzca lo que debe decir el bot para indicar que una experiencia de inicio de sesión está a punto de ocurrir.
Debajo del nodo del mensaje, seleccione el icono de signo más (+), luego Llamar a una acción y, finalmente, Autenticar.
Una vez seleccionado, se agregarán automáticamente varios nodos nuevos. Estos nodos incluyen un nodo principal Autenticar, seguido de nodos tanto para una ruta correcta como para una ruta errónea.
Nota
El nodo Autenticar solo está disponible en el selector de acciones situado al final de un árbol de diálogo (como un nodo hoja). No se puede agregar en medio de un diálogo. Una vez agregado, se pueden agregar otros nodos debajo de él.
Autenticar nodo
El nodo Autenticar es donde el usuario, si aún no ha iniciado sesión, recibirá una tarjeta de inicio de sesión.
Una vez que el usuario introduce su nombre de usuario y contraseña en el mensaje (hospedado por el proveedor de identidades), se le puede solicitar que introduzca un código de validación, dependiendo del canal. Algunos canales, como Microsoft Teams, no requieren que el usuario introduzca un código de validación.
Tenga en cuenta que si su bot tiene SSO configurado, no se le pedirá al usuario que inicie sesión.
A los usuarios solo se les pide que inicien sesión una vez durante una conversación, incluso si encuentran otra tarjeta de inicio de sesión.
Uso de AuthToken sin un nodo de autenticación
Las variables IsLoggedIn y AuthToken están disponibles incluso si no utiliza la plantilla proporcionada por la entrada de menú Llamar una acción. Si pasa la variable AuthToken sin que primero el usuario haya pasado por el nodo Autenticar, se le pedirá al usuario que inicie sesión en ese paso.
Pasar la variable AuthToken puede ser útil si siempre espera que el usuario tenga sesión iniciada o si su usuario está siendo redirigido desde un tema diferente. Sugerimos que utilice la plantilla proporcionada por la entrada Llamar una acción para tratar casos en los que el usuario no puede iniciar sesión.
Nota
Si el usuario cierra sesión en medio de una conversación, se le pedirá que inicie sesión nuevamente si el tema llega a un nodo que utiliza la variable AuthToken.
Ruta de éxito
La ruta de éxito equivale a IsLoggedIn = True y representa el momento en que el usuario ha iniciado sesión correctamente (o ya había iniciado sesión).
Si tiene lógica que usa la variable AuthToken (por ejemplo, para conectarse a un sistema de back-end utilizando un flujo para recuperar la información de un usuario), debe ir con esta ruta.
Ruta de fallo
La ruta de fallo equivale a cualquier otra condición que no sea IsLoggedIn = True. En la mayoría de los casos, la ruta fallida se produce porque el usuario no pudo iniciar sesión, utilizó una contraseña incorrecta o canceló la experiencia de inicio de sesión.
Agregue cualquier lógica que desee para tratar este caso. Como ejemplo, hemos proporcionado opciones para volver a intentar o escalar a un agente por chat. Personalice las acciones de la ruta fallida para su escenario y uso particulares.
Prueba de su tema
Asegúrese de probar su tema utilizando un usuario real configurado en su proveedor de identidades. Asegúrese de que se sigan las rutas de éxito y fallo de inicio de sesión, de modo que no haya sorpresas si su usuario no puede iniciar sesión o si hay un error con la experiencia de inicio de sesión del proveedor de identidades.