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.
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 se crea un agente, Copilot Studio se agrega automáticamente un tema del sistema llamado iniciar sesión. Para usarlo, debes configurar la autenticación de tu agente en manual y requerir que los usuarios inicien sesión. Cuando un cliente inicia una conversación con agente, se activa el inicio de sesión tema y se solicita al usuario que inicie sesión. Puede personalizar el inicio de sesión tema según sea apropiado para su agente.
Importante
Se recomienda que el tema Iniciar 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.
Abra su agente en Copilot Studio, Seleccionar Configuración en la parte superior de la página y luego Seleccionar Seguridad.
Seleccione Autenticación.
Seleccione Autenticar manualmente y luego seleccione Requerir que los usuarios inicien sesión.
Configurar todos los campos de autenticación manual, según sea necesario.
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 solicitar, incluso si llegan a otro nodo de Autenticar .
Seleccione Configuración en la parte superior de la página y, a continuación, seleccione Seguridad.
Seleccione el icono Autenticación.
Nota
Debe seleccionar Autenticar manualmente para agregar autenticación de usuario a un tema personalizado.
Despeje la casilla de verificación Requerir que los usuarios inicien sesión.
Configurar todos los campos de autenticación manual, según sea necesario.
Seleccione Guardar.
Seleccione Temas en la parte superior de la página.
Seleccione Agregar nodo ( 
) >Avanzado>Autenticar.
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 configura la autenticación de usuario para su agente, puede usar 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 sobre las variables, vea Trabajar con 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 sin que tenga que dar explícitamente su nombre al agente, haciendo la conversación 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. La opción requerir que los usuarios inicien sesión debe estar activada.
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.
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 su 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. Puedes usar esta variable para saludar o referirse al usuario final sin que éste tenga que decírselo explícitamente a agente, haciéndolo 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 Usuario.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 puedes usarlos en un agente publicado e implementado en un canal.
Ingrese el comando deseado en el panel Probar bot tal como lo haría si estuviera chateando normalmente con agente. Recibirás un mensaje de confirmación de agente si tienes éxito. Si su agente no utiliza 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 utilizar “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 inicia sesión, no se le vuelve a solicitar, incluso si llega a otro nodo de Autenticar .
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 tenga configurado el SSO , no se le solicitará al usuario que inicie sesión.
Para agregar un nodo Autenticar a su tema:
Vaya a la página Temas correspondiente al agente que desea editar.
Abra el tema al que desea agregar la plantilla de autenticación.
Nota
Si su agente está conectado a Dynamics 365 servicio al cliente,, el nodo de autenticación no puede ser parte de la ruta de conversación que sigue agente cuando saluda inicialmente a los usuarios; de lo contrario, el inicio de sesión tarjeta se mostrará dos veces. En su lugar, debe agregar el nodo Autenticar a otro tema que se desencadena por una respuesta del usuario.
Seleccione Agregar nodo (+) para agregar un nodo de mensaje. Ingrese lo que debe decir agente para indicar que está a punto de ocurrir una experiencia de inicio de sesión.
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.