Agregar autenticación de usuario a temas

Puede habilitar la autenticación de usuarios directamente dentro de la conversación de un agente. Puede asignar las propiedades básicas de un usuario, como el nombre y la identificación, en las variables. También puede solicitar a un usuario que inicie sesión usando un nodo de autenticación en un tema, que recupera un token de usuario y luego usar ese token para recuperar la información del usuario de un sistema de back-end.

Nota

Agentes creados en Copilot Studio y en Microsoft Teams se configuran automáticamente para la autenticación de Microsoft Entra ID.

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

Requisitos previos

• Información general de las variables
• Configurar la autenticación de usuarios en Copilot Studio

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.

Siga las instrucciones en Configurar la autenticación de usuario con Microsoft Entra ID.

Agregar autenticación de usuario con el tema del sistema Iniciar sesión

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

Importante

Se recomienda que el tema de Inicio de sesión solo se utilice para proporcionar el método de autenticación proporcionado por Copilot Studio. No debe modificarse para llamar a otras acciones o flujos, ni a otros métodos de autenticación.

1. Abra su agente en Copilot Studio, seleccione Configuración en la parte superior de la página y luego seleccione Seguridad.

2. Seleccione Autenticación.

3. Seleccione Autenticar manualmente y luego seleccione Requerir que los usuarios inicien sesión.

4. Configurar todos los campos de autenticación manual, según sea necesario.

5. Seleccione Guardar.

Agregar autenticación de usuario con un tema personalizado

El tema Iniciar sesión autentica al usuario al inicio 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, es posible que se les solicite que ontroduzcan un código de validación. Después de iniciar sesión, no se les vuelve a preguntar, incluso si llegan a otro nodo de autenticación.

1. Seleccione Configuración en la parte superior de la página y, a continuación, seleccione Seguridad.

2. Seleccione el icono Autenticación.

   Nota

   Debe seleccionar Autenticar manualmente para agregar autenticación de usuario a un tema personalizado.

3. Despeje la casilla de verificación Requerir que los usuarios inicien sesión.

4. Configurar todos los campos de autenticación manual, según sea necesario.

5. Seleccione Guardar.

6. Seleccione Temas en la parte superior de la página.

7. Seleccione Agregar nodo ( ) >Avanzado>Autenticar.

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

Al configurar la autenticación de usuario para su agente, puede 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ó.

Para obtener más información acerca de las variables, consulte Información general sobre las variables.

Variable de autenticación	Sin autenticación	Autenticar con Microsoft	Autenticar manualmente
User.DisplayName	No disponible	Disponibles	Disponibles
User.FirstName	No disponible	Disponibles	Disponibles
User.LastName	No disponible	Disponibles	Disponibles
User.PrincipalName	No disponible	Disponibles	Disponibles
User.Email	No disponible	Disponibles	Disponibles
User.Id	No disponible	Disponibles	Disponibles
User.IsLoggedIn	No disponible	Disponibles	Disponibles
User.AccessToken	No disponible	No disponible	Disponibles
SignInReason	No disponible	Disponibles	Disponibles

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 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 agente, lo que lo hace que la conversación sea más personalizada.

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 identificador del usuario 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.

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 booleana 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 cuando un usuario no ha iniciado sesión y llega a un momento de la conversación que usa variables de autenticación, se le pide que inicie sesión.

Clásico

Variables de autenticación

Si su agente está configurado con las opciones de autenticación Autenticar con Microsoft o Manual, tendrá un conjunto de variables de autenticación disponibles en sus temas. Para obtener más información sobre cómo configurar la autenticación en el agente, consulte Configurar la autenticación de usuario en Copilot Studio.

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	Autenticar con Microsoft	Manual
User.DisplayName	❌	✔️	✔️
User.Id	❌	✔️	✔️
User.IsLoggedIn	❌	❌	✔️
User.AccessToken	❌	❌	✔️

Variable UserDisplayName

La variable User.DisplayName contiene el nombre del usuario almacenado en el proveedor de identidad. Puede usar esta variable para saludar o referirse al cliente sin que tenga que decírselo explícitamente al agente, 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. 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 User.Id 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. Copilot Studio extrae automáticamente este campo en la variable.

Advertencia

Las variables User.DisplayName y User.Id 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 User.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).

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

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.

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.

No use User.AccessToken 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 User.DisplayName y User.Id. 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.

La siguiente tabla enumera los comandos que completarán estas variables. Estos comandos solo se aplican al panel Probar bot; no puede usarlos en un agente publicado implementado en un canal.

Introduzca el comando en el panel Probar bot tal como lo haría si estuviera charlando normalmente con el agente. Recibirá un mensaje de confirmación del agente si tiene éxito. Si su agente 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)
User.DisplayName	/debug set bot.UserDisplayName "Value"	/debug set bot.UserDisplayName ""
User.Id	No disponible	/debug set bot.UserID ""

Importante

Por motivos de seguridad, no puede poblar la variable User.Id con un valor personalizado (que no sea un valor vacío o en blanco).

Autenticación al usar "Autenticar con Microsoft"

Si su opción de autenticación está configurada en Autenticar con Microsoft, 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 Autenticar con Microsoft, 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 solicita a un usuario que inicie sesión con una tarjeta de acceso. Una vez que un usuario ha iniciado sesión, no se le vuelve a preguntar, 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 agente tiene SSO configurado, no se le pedirá al usuario que inicie sesión.

Para agregar un nodo Autenticar a su tema:

1. Vaya a la pestaña Temas para el agente que desea editar.

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

   Nota

   Si el agente está conectado a Dynamics 365 Customer Service, el nodo Autenticación no puede formar parte de la ruta de conversación que sigue el agente al saludar inicialmente 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 agente para indicar que una experiencia de inicio de sesión está a punto de producirse.

   

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.

   Nuevos nodos aparecen automáticamente: un nodo principal Autenticar, seguido de nodos para una ruta correcta y una ruta errónea.

Uso de User.AccessToken sin un nodo de autenticación

Las variables User.IsLoggedIn y User.AccessToken están disponibles incluso si no utiliza la plantilla proporcionada por la entrada de menú Llamar una acción. Si pasa la variable User.AccessToken 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 User.AccessToken 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 User.AccessToken.

Ruta de éxito

La ruta de éxito equivale a User.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 User.AccessToken (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.

Contenido relacionado

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