Agregar autenticación de usuario final a un copiloto

Importante

Las capacidades y características de Power Virtual Agents son ahora parte de Microsoft Copilot Studio tras importantes inversiones en IA generativa e integraciones mejoradas en Microsoft Copilot.

Algunos artículos y capturas de pantalla pueden hacer referencia a Power Virtual Agents mientras actualizamos la documentación y el contenido de capacitación.

Puede habilitar la autenticación de usuario directamente dentro de una conversación de copiloto. 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, 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.

Nota

Los copilotos creados en la aplicación web y en Microsoft Teams vienen con la autenticación preconfigurada para usar la autenticación Solo para Teams y Power Apps.

También puede configurar el inicio de sesión único (SSO) para que sus usuarios no tengan que iniciar sesión manualmente. Para obtener más información, consulte Configurar SSO para Web.

Requisitos previos

• Utilizar variables
• Configuración de la autenticación de usuario final.

Aplicación web

Agruegue la autenticación de usuario a un tema para permitir que sus clientes inicien sesión directamente en la conversación. Después puede personalizar la conversación con variables de usuario o acceder a los sistemas de back-end en nombre del usuario.

Configurar la autenticación manual con Microsoft Entra ID

Debe configurar la autenticación de usuario con Microsoft Entra ID antes de poder usar la autenticación en sus temas.

1. Siga las instrucciones en Configurar la autenticación de usuario con Microsoft Entra ID.
2. Vuelva a este artículo.

Agregar autenticación de usuario con el tema del sistema Signin

Cuando crea un copiloto, Microsoft Copilot Studio agrega automáticamente un tema de sistema llamado Signin. Para usarlo, debe configurar la autenticación de su copiloto en manual y solicitar a los usuarios que inicien sesión. Cuando un cliente inicia una conversación con el copiloto, el tema Signin se activa y solicita al usuario que inicie sesión. Puede personalizar el tema Signin según corresponda para su copiloto.

1. En el menú de navegación, en Configuración, seleccione Seguridad.

2. Seleccione el icono Autenticación.

3. Seleccione Manual (para sitio web personalizado) y luego seleccione Requerir que los usuarios inicien sesión.

   

   

Agregar autenticación de usuario con un tema personalizado

El tema de inicio de sesión autentica al usuario al comienzo de la conversación. Para permitir que el usuario inicie sesión más tarde, puede agregar un nodo Authenticate a cualquier tema personalizado.

Cuando los clientes introducen su nombre de usuario y contraseña, se le puede solicitar que introduzca un código de validación. Después de que hayan iniciado sesión, no se le volverá a solicitar, incluso si llega a otro nodo de autenticación.

1. En el menú de navegación, en Configuración, seleccione Seguridad.

2. Seleccione el icono Autenticación.

3. Desactive Requerir que los usuarios inicien sesión.

4. En el menú de navegación superior, seleccione Temnas y abra el tema al que desea añadir autenticación.

5. Seleccione Agregar nodo (+), seleccione Llamar una acción y luego Autenticar.

6. Pruebe el tema con un usuario configurado con su proveedor de identidades.

Propina

Es importante que cree rutas tanto para el éxito como para el fracaso del inicio de sesión. Un inicio des esión puede fallar por muchas razones, incluidos errores con la experiencia de inicio de sesión del proveedor de identidad.

Variables de autenticación

Cuando haya configurado la autenticación de usuario para su copiloto, podrá utilizar variables de autenticación en sus temas. La siguiente tabla compara la disponibilidad de estas variables según la opción de autenticación que eligió.

Variable de autenticación	Sin autenticación	Solo para Teams y Power Apps	Manual
User.DisplayName	no disponible	disponible	disponible
User.FirstName	no disponible	disponible	disponible
User.LastName	no disponible	disponible	disponible
User.PrincipalName	no disponible	disponible	disponible
User.Email	no disponible	disponible	disponible
User.Id	no disponible	disponible	disponible
User.IsLoggedIn	no disponible	disponible	disponible
User.AccessToken	no disponible	no disponible	disponible
SignInReason	no disponible	disponible	disponible

User.DisplayName

Advertencia

No se garantiza que esta variable contenga un valor. Pruebe con un usuario de su proveedor de identidades para asegurarse de que su tema funcione correctamente.

La variable User.DisplayName contiene el nombre del usuario que se ha almacenado en el proveedor de identidad. Utilice esta variable para saludar o referirse al usuario final sin que tenga que dar su nombre explícitamente al copiloto, lo que lo hace que la conversación sea más personalizada.

Microsoft Copilot Studio establece automáticamente el valor de User.DisplayName de la notificación name proporcionada por el proveedor de identidad, siempre que el ámbito profile se haya definido cuando se configuró la autenticación manual. Para obtener más información sobre el ámbito, consulte Configurar la autenticación de usuario con Microsoft Entra ID.

User.Id

Advertencia

No se garantiza que esta variable contenga un valor. Pruebe con un usuario de su proveedor de identidades para asegurarse de que su tema funcione correctamente.

La variable User.Id contiene el userID almacenado en el proveedor de identidad. Use esta variable en flujos de Power Automate para llamar a las API que toman el UserID como valor.

Microsoft Copilot Studio establece automáticamente el valor de User.DisplayName basado en el reclamo de sub del proveedor de identidad.

User.IsLoggedIn

User.IsLoggedIn es una variable de tipo booleano que almacena el estado de inicio de sesión del usuario. Un valor de true indica que el usuario ha iniciado sesión. Puede usar esta variable para crear una lógica de bifurcación en sus temas que verifique un inicio de sesión correcto, o para obtener información de usuario solo si el usuario ha iniciado sesión.

User.AccessToken

Advertencia

Asegúrese de pasar la variable User.AccessToken solo a fuentes confiables. Contiene información de autenticación del usuario que, si se ve comprometida, podría dañar al usuario.

La variable User.AccessToken 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.

No use User.AccessToken en los nodos Mensaje o en flujos en los que no confía.

SignInReason

SignInReason es una variable de tipo elección que indica cuándo debe iniciar sesión el usuario. Tiene dos valores posibles:

• SignInRequired indica que el usuario debe iniciar sesión al comienzo de la conversación usando el tema del sistema Iniciar sesión. Requerir a los usuarios iniciar sesión debe estar activado.

• Initializer indica que si el usuario aún no ha iniciado sesión y llega a un punto de la conversación que usa variables de autenticación, se le pedirá que inicie sesión.

Clásico

Variables de autenticación

Si su bot está configurado con las opciones de autenticación Solo para Teams y Power Apps 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 y Power Apps	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 Microsoft Entra ID. Para los proveedores de OAuth, este es el valor almacenado en la notificación name. Microsoft Copilot Studio 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 Microsoft Entra ID. Para los proveedores de OAuth, este es el valor almacenado en la notificación sub. Microsoft Copilot Studio 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 Teams y Power Apps"

Si su opción de autenticación está configurada en Solo para Teams y Power Apps 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 y Power Apps, no tiene la opción de agregar autenticación explícitamente a sus temas.

Agregar autenticación de usuario a un tema

El nodo Autenticar solicitará al usuario que inicie sesión con una tarjeta de inicio de sesión. Si un usuario ya inició sesión, no se le volverá a solicitar, incluso si llega a otro nodo de autenticació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.

Cuando su bot tenga SSO configurado, no se le pedirá al usuario que inicie sesión.

Para agregar un nodo Autenticar a su tema:

1. Vaya a la página de temas del bot que quiera editar.

2. Abra el Lienzo de creación del tema al que desea agregar la plantilla de autenticación.

   Nota

   Si su bot está conectado a Dynamics 365 Customer Service, el nodo de autenticación no puede ser parte de la ruta de conversación que sigue el bot cuando inicialmente saluda a los usuarios; de lo contrario, la tarjeta de inicio de sesión se mostrará dos veces. En su lugar, debe agregar el nodo Autenticar a otro tema que se desencadena por una respuesta del usuario.

3. Seleccione Agregar nodo (+) 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.

   

4. Debajo del nodo del mensaje, seleccione Agregar nodo (+), luego Llamar a una acción y, finalmente, Autenticar.

   

   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.

5. 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.

   

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.

Temas relacionados

También puede configurar el inicio de sesión único (SSO) para que sus usuarios no tengan que iniciar sesión manualmente. Para obtener más información, consulte Configurar SSO para Web.