Agregar autenticación al bot de Teams

Puede crear bots en Microsoft Teams que accedan a recursos en nombre del usuario, como un servicio de correo. Puede usar la autenticación del SDK de Azure Bot Service v4, basada en OAuth 2.0. Este método facilita el desarrollo de un bot que puede usar tokens de autenticación en función de las credenciales del usuario. La clave es el uso de proveedores de identidades.

OAuth 2.0 es un estándar abierto para la autenticación y autorización que usan Microsoft Entra id. y muchos otros proveedores de identidades. Tener conocimientos básicos del flujo de concesión implícito de OAuth 2.0 es un requisito previo para trabajar con la autenticación en pestañas de Microsoft Teams.

Consulte OAuth 2 Simplificado para obtener una descripción básica y OAuth 2.0 para obtener la especificación completa.

Para obtener más información sobre cómo el Azure Bot Service controla la autenticación, vea Autenticación de usuario dentro de una conversación.

En este artículo, aprenderá lo siguiente:

• Cómo crear un bot habilitado para autenticación. Usará cs-auth-sample para controlar las credenciales de inicio de sesión de usuario y la generación del token de autenticación.
• Cómo implementar el bot en Azure y asociarlo a un proveedor de identidades. El proveedor emite un token basado en las credenciales de inicio de sesión del usuario. El bot puede usar el token para acceder a recursos, como un servicio de correo, que requiere autenticación. Para obtener más información, consulte Flujo de autenticación de Microsoft Teams para bots.
• Cómo integrar el bot en Microsoft Teams. Una vez integrado el bot, puede iniciar sesión e intercambiar mensajes con él en un chat.

Requisitos previos

• Conocimientos sobre los conceptos básicos del bot, la administración del estado, la biblioteca de diálogos y cómo implementar el flujo de conversación secuencial.

• Conocimientos sobre el desarrollo de Azure y OAuth 2.0.

• Las versiones actuales de Microsoft Visual Studio y Git.

• Cuenta de Azure. Si es necesario, puede crear una cuenta gratuita de Azure.

• El ejemplo siguiente:

  Muestra	Versión de BotBuilder	Demuestra
  Autenticación de bot en cs-auth-sample	v4	Compatibilidad con OAuthCard
  Autenticación de bots en js-auth-sample	v4	Compatibilidad con OAuthCard
  Autenticación de bots en py-auth-sample	v4	Compatibilidad con OAuthCard

Creación del grupo de recursos

El grupo de recursos y el plan de servicio no son estrictamente necesarios, pero permiten liberar cómodamente los recursos que cree. Se recomienda mantener los recursos organizados y administrables.

Use un grupo de recursos para crear recursos individuales para el Bot Framework. Para mejorar el rendimiento, asegúrese de que estos recursos se encuentran en la misma región de Azure.

1. En el explorador, inicie sesión en el portal de Microsoft Azure.
2. En el panel de navegación izquierdo, seleccione Grupos de recursos.
3. En la parte superior izquierda de la ventana mostrada, seleccione la pestaña Agregar para crear un nuevo grupo de recursos. Proporcione los detalles siguientes:
   1. Suscripción. Use su suscripción existente.
   2. Grupo de recursos. Escriba el nombre del grupo de recursos. Un ejemplo podría ser TeamsResourceGroup. Recuerde que el nombre debe ser único.
   3. En el menú desplegable Región , seleccione Oeste de EE. UU. o una región cercana a las aplicaciones.
   4. Seleccione el botón Revisar y crear. Debería ver un banner que dice Validación superada.
   5. Seleccione el botón Crear. La creación del grupo de recursos puede tardar unos minutos.

Sugerencia

Al igual que con los recursos que creará más adelante en este tutorial, es una buena idea anclar este grupo de recursos al panel para facilitar el acceso. Si quiere hacerlo, seleccione el icono 📌 de anclaje en la esquina superior derecha del panel.

Creación del plan de servicio

1. En el Azure Portal, en el panel de navegación izquierdo, seleccione Crear un recurso.
2. En el cuadro de búsqueda, escriba Plan de servicio de la aplicación. Seleccione la tarjeta Plan de servicio de la aplicación en los resultados de la búsqueda.
3. Seleccione Crear.
4. Proporcione la siguiente información de envío:
   1. Suscripción. Puede usar una suscripción existente.
   2. Grupo de recursos. Seleccione el grupo que creó anteriormente.
   3. Nombre. Escriba el nombre del plan de servicio. Un ejemplo podría ser TeamsServicePlan. Recuerde que el nombre debe ser único dentro del grupo.
   4. Sistema operativo. Seleccione Windows o el sistema operativo aplicable.
   5. Región. Seleccione Oeste de EE. UU. o una región cercana a las aplicaciones.
   6. Plan de tarifa. Seleccione Estándar S1, que es el valor predeterminado.
   7. Seleccione el botón Revisar y crear. Debería ver un banner que dice Validación superada.
   8. Seleccione Crear. La creación del plan de servicio de la aplicación puede tardar unos minutos. El plan aparece en el grupo de recursos.

Creación del registro de recursos del bot de Azure

El registro de recursos de Bot de Azure registra el servicio web como bot con Bot Framework, que le proporciona un identificador de aplicación de Microsoft y una contraseña de aplicación (secreto de cliente).

Importante

Solo debe registrar el bot si no está hospedado en Azure. Si creó un bot a través de la Azure Portal, ya está registrado en el servicio. Si creó el bot a través de Bot Framework o el Portal para desarrolladores, el bot no está registrado en Azure.

1. Visite Azure Portal y busque Bot de Azure en la sección Crear un recurso.

2. Abra Bot de Azure y seleccione Crear.

3. Escriba el nombre del identificador del bot en el campo Identificador de bot.

4. Seleccione su Suscripción en la lista desplegable.

5. Seleccione el Grupo de recursos en la lista desplegable.

6. Seleccione Tipo de aplicación como Multiinquilino para el Identificador de aplicación de Microsoft.

   

7. Seleccione Revisar y crear.

   

8. Si se supera la validación, seleccione Crear.

   Azure aprovisiona el bot en unos instantes.

   

9. Seleccione Ir a recursos. El bot y los recursos relacionados aparecen en el grupo de recursos.

   

   Se crea el bot de Azure.

   

Para crear el secreto de cliente:

1. En Configuración, seleccione Configuración. Guarde el identificador de aplicación de Microsoft (id. de cliente) para futuras referencias.

   

2. Junto a Id. de aplicación de Microsoft, seleccione Administrar.

   

3. En la sección Secretos de cliente, seleccione Nuevo secreto de cliente. Aparece la ventana Agregar un secreto de cliente.

   

4. Escriba Descripción y seleccione Agregar.

   

5. En la columna Valor, seleccione Copiar en el Portapapeles y guarde el identificador de secreto de cliente para futuras referencias.

   

Para agregar el canal de Microsoft Teams:

1. Ve a Inicio.

   

2. Abra el bot en la sección Recursos recientes .

3. Seleccione Canales en el panel izquierdo y seleccione Microsoft Teams .

   

4. Active la casilla para aceptar los términos de servicio y seleccione Aceptar.
   

   

5. Seleccione Guardar.

   

Para obtener más información, vea Crear un bot para Teams.

Creación del proveedor de identidades

Necesita un proveedor de identidades para la autenticación. En este procedimiento, se usa un proveedor de Microsoft Entra. Como alternativa, también puede usar otros proveedores de identidades compatibles con el identificador de Microsoft Entra.

1. En el Azure Portal, en el panel de navegación izquierdo, seleccione Microsoft Entra id.

   Sugerencia

   Tendrá que crear y registrar este recurso de Microsoft Entra en un inquilino en el que pueda dar su consentimiento para delegar los permisos solicitados por una aplicación. Para obtener instrucciones sobre cómo crear un inquilino, consulte Acceso al portal y creación de un inquilino.

2. En el panel izquierdo, seleccione Registros de aplicaciones.

3. En el panel derecho, seleccione la pestaña Nuevo registro, en la esquina superior izquierda.

4. Proporcione la siguiente información de envío:

   1. Nombre. Escriba el nombre de la aplicación. Un ejemplo podría ser BotTeamsIdentity. Recuerde que el nombre debe ser único.
   2. Seleccione los tipos de cuenta admitidos para la aplicación. Seleccione Cuentas en cualquier directorio organizativo (cualquier inquilino de identificador de Microsoft Entra multiinquilino) y cuentas personales de Microsoft (por ejemplo, Skype, Xbox).
   3. Para el URI de redireccionamiento:
      ✓Seleccione Web.
      ✓ Establezca la dirección URL en https://token.botframework.com/.auth/web/redirect.
   4. Seleccione Registrar.

5. Una vez creada, Azure muestra la página Información general de la aplicación. Copie y guarde la siguiente información en un archivo:

   1. El valor de la Id. de aplicación (cliente). Usará este valor más adelante como Identificador de cliente al registrar esta aplicación de identidad de Azure con el bot.
   2. Valor del Identificador del directorio (inquilino). Usará este valor más adelante como identificador de inquilino para registrar esta aplicación de identidad de Azure con el bot.

6. En el panel izquierdo, seleccione Certificados y secretos para crear un secreto de cliente para la aplicación.

   1. En Secretos de cliente, seleccione ➕ Nuevo secreto de cliente.
   2. Agregue una descripción para identificar este secreto de otros usuarios que pueda necesitar crear para esta aplicación, como aplicación de identidad de bot en Teams.
   3. Establezca la Caducidad respecto a la selección.
   4. Seleccione Agregar.
   5. Antes de salir de esta página, registre el secreto. Usará este valor más adelante como secreto de cliente al registrar la aplicación Microsoft Entra con el bot.

Configuración de la conexión del proveedor de identidades y registro con el bot

Nota:

Aquí hay dos opciones para proveedores de servicios: Azure Active Directory v1 y Azure Active Directory v2. Las diferencias entre los dos proveedores se resumen aquí, pero, en general, v2 proporciona más flexibilidad con respecto al cambio de permisos de bot. Los permisos Graph API se muestran en el campo ámbitos y, a medida que se agregan nuevos, los bots permitirán a los usuarios dar su consentimiento a los nuevos permisos en el siguiente inicio de sesión. Para la versión v1, el usuario debe eliminar el consentimiento del bot para que se le soliciten nuevos permisos en el cuadro de diálogo de OAuth.

Microsoft Azure Active Directory (Azure AD) v1

1. En el Portal de Azure, seleccione el grupo de recursos en el panel.

2. Seleccione el vínculo de registro del bot.

3. Abra la página del recurso y seleccione Configuración en Configuración.

4. Seleccione el botón Agregar ajustes de conexión de OAuth en la pantalla Configuración. En la imagen siguiente se muestra la selección correspondiente en la página de recursos:

   

5. Complete el formulario de la siguiente manera:

   1. Nombre. Escriba un nombre para la conexión. Use este nombre en el bot en el appsettings.json archivo. Por ejemplo, BotTeamsAuthADv1.

   2. Proveedor de servicios Seleccione Azure Active Directory. Una vez seleccionada esta opción, se muestran los campos específicos de Azure Active Directory.

   3. Id. de cliente. Escriba el identificador de aplicación (cliente) que registró para la aplicación del proveedor de identidades de Azure.

   4. Secreto de cliente Escriba el secreto que registró para la aplicación del proveedor de identidades de Azure.

   5. Tipo de concesión. Escriba authorization_code.

   6. Dirección URL de inicio de sesión. Escriba https://login.microsoftonline.com.

   7. Id. de inquilino, escriba el identificador de directorio (inquilino) que registró anteriormente para la aplicación de identidad de Azure o común en función del tipo de cuenta compatible seleccionado al crear la aplicación del proveedor de identidades. Para decidir qué valor asignar, siga estos criterios:

      • Si seleccionó Solo cuentas en este directorio organizativo (solo Microsoft: inquilino único) o Cuentas en cualquier directorio organizativo (Cualquier inquilino de identificador de Microsoft Entra multiinquilino) , escriba el identificador de inquilino que registró anteriormente para la aplicación de Microsoft Entra. Este será el inquilino asociado a los usuarios que se pueden autenticar.

      • Si seleccionó Cuentas en cualquier directorio organizativo (Cualquier inquilino de identificador de Microsoft Entra multiinquilino) y cuentas personales de Microsoft (por ejemplo, Skype, Xbox) escriba la palabra común en lugar de un identificador de inquilino. De lo contrario, la aplicación Microsoft Entra comprueba a través del inquilino cuyo identificador se seleccionó y excluye las cuentas personales de Microsoft.

   h. En Dirección URL del recurso, escriba https://graph.microsoft.com/. Esta dirección URL no se usa en el ejemplo de código actual.
   i. Deje ámbitos en blanco. La siguiente imagen es un ejemplo:

   

6. Seleccione Guardar.

Microsoft Azure Active Directory (Azure AD) v2

1. En el Portal de Azure, seleccione el bot de Azure en el panel.

2. En la página del recurso, seleccione Configuración en Configuración.

3. Seleccione el botón Agregar ajustes de conexión de OAuth en la pantalla Configuración.
   En la imagen siguiente se muestra la selección correspondiente en la página de recursos:

   

4. Complete el formulario de la siguiente manera:

   1. Nombre. Escriba un nombre para la conexión. Usará este nombre en el bot en el archivo appsettings.json. Por ejemplo, BotTeamsAuthADv2.

   2. Proveedor de servicios Seleccione Azure Active Directory v2. Una vez seleccionada esta opción, se muestran los campos específicos de Azure AD v2.

   3. Id. de cliente. Escriba el identificador de aplicación (cliente) que registró para la aplicación del proveedor de identidades de Azure.

   4. Secreto de cliente Escriba el secreto que registró para la aplicación del proveedor de identidades de Azure.

   5. Dirección URL de intercambio de tokens. Déjelo en blanco.

   6. Id. de inquilino, escriba el identificador de directorio (inquilino) que registró anteriormente para la aplicación de identidad de Azure o común en función del tipo de cuenta compatible seleccionado al crear la aplicación del proveedor de identidades. Para decidir qué valor asignar, siga estos criterios:

      • Si seleccionó Solo cuentas en este directorio organizativo (solo Microsoft: inquilino único) o Cuentas en cualquier directorio organizativo (Cualquier inquilino de identificador de Microsoft Entra multiinquilino) , escriba el identificador de inquilino que registró anteriormente para la aplicación de Microsoft Entra. Este será el inquilino asociado a los usuarios que se pueden autenticar.

      • Si seleccionó Cuentas en cualquier directorio organizativo (Cualquier inquilino de identificador de Microsoft Entra multiinquilino) y cuentas personales de Microsoft (por ejemplo, Skype, Xbox) escriba la palabra común en lugar de un identificador de inquilino. De lo contrario, la aplicación Microsoft Entra comprueba a través del inquilino cuyo identificador se seleccionó y excluye las cuentas personales de Microsoft.

   7. En Ámbitos, escriba una lista delimitada por espacios de permisos de grafos que requiere esta aplicación, como User.Read, User.ReadBasic.All o Mail.Read.

5. Seleccione Guardar.

Pruebe la conexión

1. Seleccione la entrada de conexión para abrir la conexión que ha creado.

2. Seleccione Probar conexión en la parte superior del panel Configuración de conexión del proveedor de servicios.

3. Por primera vez, se abre una nueva ventana del explorador que le pide que seleccione una cuenta. Seleccione el que quiera usar.

4. A continuación, permita al proveedor de identidades usar los datos (credenciales). La siguiente imagen es un ejemplo:

   

5. Seleccione Aceptar.

6. Se abre una página Probar conexión al <nombre> de la conexión correcta . Actualice la página si recibe un error. La siguiente imagen es un ejemplo:

   

El código del bot usa el nombre de conexión para recuperar tokens de autenticación de usuario.

Preparación del código de ejemplo del bot

Una vez finalizada la configuración preliminar, vamos a centrarnos en la creación del bot que se va a usar en este artículo.

C#/.NET

1. Clone cs-auth-sample.

2. Abra Visual Studio.

3. En la barra de herramientas, seleccione Archivo > Abrir > proyecto o solución y abra el proyecto de bot.

4. En C#, actualice appsettings.json de la siguiente manera:

   • Establezca ConnectionName en el nombre de la conexión del proveedor de identidades que agregó al registro del bot. El nombre que usamos en este ejemplo es BotTeamsAuthADv1.
   • Establezca MicrosoftAppId en el identificador de aplicación del bot que guardó en el momento del registro del bot.
   • Establezca MicrosoftAppPassword en el secreto de cliente que guardó en el momento del registro del bot.

   En función de los caracteres del secreto del bot, es posible que deba aplicar un escape XML a la contraseña. Por ejemplo, cualquier y comercial (&) tendrá que codificarse como &.

   {
     "MicrosoftAppType": "",
     "MicrosoftAppId": "",
     "MicrosoftAppPassword": "",
     "ConnectionName": "",
   

5. En el Explorador de soluciones, vaya a la TeamsAppManifest carpeta, abra manifest.json y establezca id y botId en el identificador de aplicación del bot que guardó en el momento del registro del bot. Para obtener más información, vea manifiesto de aplicación.

JavaScript

1. Clone node-auth-sample.

2. En una consola, vaya al proyecto:
   
   cd samples/bot-teams-authentication/nodejs

3. Instalación de módulos
   
   npm install

4. Actualice la configuración .env de la siguiente manera:

   • Establezca MicrosoftAppId en el identificador de aplicación del bot que guardó en el momento del registro del bot.
   • Establezca MicrosoftAppPassword en el secreto de cliente que guardó en el momento del registro del bot.
   • Establezca el connectionName en el nombre de la conexión del proveedor de identidades. En función de los caracteres del secreto del bot, es posible que deba aplicar un escape XML a la contraseña. Por ejemplo, cualquier y comercial (&) tendrá que codificarse como &.

   MicrosoftAppId=
   MicrosoftAppPassword=
   connectionName=
   MicrosoftAppType= MultiTenant # Set this to SingleTenant if you are using a single tenant app registration
   MicrosoftAppTenantId= common # Set your tenantId here if you are using single tenant app registration.
   

5. En la teamsAppManifest carpeta, abra manifest.json y establezca id en el identificador de aplicación de Microsoft y botId en el id. de aplicación del bot que guardó en el momento del registro del bot.

Python

1. Clone py-auth-sample desde el repositorio de GitHub.

2. Actualice config.py:

   • Establezca ConnectionName en el nombre de la configuración de conexión de OAuth que agregó al bot.

   • Establezca MicrosoftAppId y MicrosoftAppPassword en el identificador de aplicación y el secreto de aplicación del bot.

     En función de los caracteres del secreto del bot, es posible que deba aplicar un escape XML a la contraseña. Por ejemplo, cualquier y comercial (&) tendrá que codificarse como &.

     APP_ID = os.environ.get("MicrosoftAppId", "")
     APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
     CONNECTION_NAME = os.environ.get("ConnectionName", "")
     

Implementar el bot en Azure

Para implementar el bot, siga los pasos descritos en How to Deploy your bot to Azure (Cómo implementar el bot en Azure).

Como alternativa, mientras esté en Visual Studio, puede seguir estos pasos:

1. En Visual Studio Explorador de soluciones, seleccione y mantenga presionado (o haga clic con el botón derecho) el nombre del proyecto.

2. En el menú desplegable, seleccione Publicar.

3. En la ventana mostrada, seleccione el vínculo Nuevo.

4. En la ventana de diálogo, seleccione App Service y Crear nuevo.

5. Seleccione el botón Publicar.

6. En la siguiente ventana de diálogo, escriba la información necesaria.

   

7. Seleccione Crear.

8. Si la implementación se completa correctamente, debería verla reflejada en Visual Studio. Se abre una página en el explorador predeterminado con el mensaje ¡El bot está listo!. La dirección URL es similar a https://botteamsauth.azurewebsites.net/. Guárdelo en un archivo.

9. En el explorador, vaya al Azure Portal.

10. Compruebe el grupo de recursos, el bot aparece junto con los demás recursos. La siguiente imagen es un ejemplo:

    

11. En el grupo de recursos, seleccione el nombre de registro del bot (vínculo).

12. En el panel izquierdo, seleccione Configuración.

13. En el cuadro Punto de conexión de mensajería , escriba la dirección URL que acaba de obtener seguida de api/messages. Por ejemplo, https://botteamsauth.azurewebsites.net/api/messages.

    Nota:

    Solo se permite un punto de conexión de mensajería para un bot.

14. Seleccione el botón Guardar en la esquina superior izquierda.

Prueba del bot mediante el emulador

Si aún no lo ha hecho, instale el Emulador de Microsoft Bot Framework. Consulte también Depurar con el emulador.

Para que el inicio de sesión de ejemplo del bot funcione, debe configurar el emulador.

Configuración del emulador para la autenticación

Si un bot requiere autenticación, debe configurar el emulador. Para configurar:

1. Inicie el emulador.
2. En el emulador, seleccione el icono ⚙ de engranaje en la parte inferior izquierda o la pestaña Configuración del emulador en la esquina superior derecha.
3. Active la casilla Use los tokens de autenticación de la versión 1.0.
4. Escriba la ruta de acceso local a la herramientangrok. Consulte la wiki de la integración de túnel del emulador de Bot Framework/ngrok. Para obtener más información sobre las herramientas, consulte ngrok.
5. Active la casilla Ejecutar ngrok cuando el emulador se inicie.
6. Seleccione el botón Guardar.

Cuando el bot muestra una tarjeta de inicio de sesión y el usuario selecciona el botón de inicio de sesión, el emulador abre una página que el usuario puede usar para iniciar sesión con el proveedor de autenticación. Una vez que el usuario lo hace, el proveedor genera un token de usuario y lo envía al bot. Después, el bot puede actuar en nombre del usuario.

Probar el bot localmente

Después de configurar el mecanismo de autenticación, puede realizar las pruebas reales del bot.

1. Ejecute el ejemplo de bot localmente en la máquina, a través de Visual Studio por ejemplo.

2. Inicie el emulador.

3. Seleccione el botón Abrir bot.

4. En la dirección URL del bot, escriba la dirección URL local del bot. Normalmente, http://localhost:3978/api/messages.

5. En Id . de aplicación de Microsoft, escriba el identificador de la aplicación del bot desde appsettings.json.

6. En Contraseña de la aplicación de Microsoft, escriba la contraseña de la aplicación del bot desde .appsettings.json

7. Seleccione Conectar.

8. Una vez que el bot esté en funcionamiento, escriba cualquier texto para mostrar la tarjeta de inicio de sesión.

9. Seleccione el botón Iniciar sesión.

10. Aparece un cuadro de diálogo emergente para confirmar la dirección URL abierta para autenticar al usuario del bot (usted).

11. Seleccione Confirmar.

12. Si se le pide, seleccione la cuenta del usuario aplicable.

13. Dependiendo de la configuración que haya usado para el emulador, obtendrá una de las siguientes opciones:

    1. Usar el código de verificación de inicio de sesión
       ✓ Se abre una ventana que muestra el código de validación.
       ✓ Copie y escriba el código de validación en el cuadro de chat para completar el inicio de sesión.
    2. Usar tokens de autenticación.
       ✓ Ha iniciado sesión en función de sus credenciales.

    La imagen siguiente es un ejemplo de la interfaz de usuario del bot después de haber iniciado sesión:

    

14. Si selecciona Sí cuando el bot le pregunta ¿Desea ver el token?, obtendrá la siguiente respuesta:

    

15. Escriba logout en el cuadro de chat de entrada para cerrar la sesión. Libera el token de usuario y el bot no podrá actuar en su nombre hasta que vuelva a iniciar sesión.

Nota:

La autenticación de bots requiere el uso del Conector de servicio del bot. El servicio accede a la información de registro de bots del bot.

Probar el bot implementado

1. En el explorador, vaya al Azure Portal.

2. Busque el grupo de recursos.

3. Seleccione el vínculo del recurso. Se muestra la página de recursos.

4. En la página de recursos, seleccione Probar en el chat de web. El bot se inicia y muestra los saludos predefinidos.

5. Escriba cualquier cosa en el cuadro de chat.

6. Seleccione el cuadro Iniciar sesión.

7. Aparece un cuadro de diálogo emergente para confirmar la dirección URL abierta para autenticar al usuario del bot (usted).

8. Seleccione Confirmar.

9. Si se le pide, seleccione la cuenta del usuario aplicable. La imagen siguiente es un ejemplo de la interfaz de usuario del bot después de haber iniciado sesión:

   

10. Seleccione el botón Sí para mostrar el token de autenticación. La siguiente imagen es un ejemplo:

    

11. Escriba logout en el cuadro de chat de entrada para cerrar la sesión.

    

Nota:

Si tiene problemas para iniciar sesión, intente probar de nuevo la conexión como se describe en los pasos anteriores. Esto podría volver a crear el token de autenticación. Con el cliente del chat de web de Bot Framework en Azure, es posible que tenga que iniciar sesión varias veces antes de que la autenticación se establezca correctamente.

Instalar y probar el bot en Teams

1. En el proyecto de bot, asegúrese de que la carpeta TeamsAppManifest contiene el manifest.json junto con un outline.png y archivos color.png.

2. En Explorador de soluciones, vaya a la TeamsAppManifest carpeta . Edite manifest.json asignando los siguientes valores:

   1. Asegúrese de que el identificador de la aplicación del bot que recibió en el momento del registro del bot esté asignado a id y botId.
   2. Asigne este valor: validDomains: [ "token.botframework.com" ].

3. Seleccione y comprima los archivos manifest.json, outline.pngy color.png.

4. Abra Microsoft Teams.

5. En el panel izquierdo, en la parte inferior, seleccione el icono Aplicaciones.

6. En el panel derecho, en la parte inferior, seleccione Cargar una aplicación personalizada.

7. Vaya a la TeamsAppManifest carpeta y cargue el manifiesto comprimido. Aparece la siguiente ventana:

   

8. Seleccione el botón Agregar a un equipo.

9. En la ventana siguiente, seleccione el equipo en el que desea usar el bot.

10. Seleccione el botón Configurar un bot.

11. Seleccione los tres puntos (●●●) en el panel izquierdo. A continuación, seleccione el icono Portal para desarrolladores .

12. Seleccione la pestaña Editor de manifiestos. Debería ver el icono del bot que cargó.

13. Además, debería poder ver que el bot aparece como un contacto en la lista de chats que puede usar para intercambiar mensajes con el bot.

Probando el bot localmente en Teams

Teams es un producto totalmente basado en la nube, requiere que todos los servicios a los que accede estén disponibles desde la nube mediante puntos de conexión HTTPS. Por lo tanto, para permitir que el bot (nuestro ejemplo) funcione en Teams, debe publicar el código en la nube que prefiera o hacer que una instancia de ejecución local sea accesible externamente a través de una herramienta de tunelización. Se recomienda ngrok, que crea una dirección URL direccionable externamente para un puerto que abra localmente en el equipo. Para configurar ngrok como preparación para ejecutar la aplicación de Teams localmente, siga estos pasos:

1. En una ventana de terminal, vaya al directorio donde ngrok.exe ha instalado. Se recomienda configurar la ruta de la variable de entorno para que apunte a ella.

2. Ejecute, por ejemplo, ngrok http 3978 --host-header=localhost:3978. Reemplace el número de puerto según sea necesario. Inicia ngrok para escuchar en el puerto especificado. A cambio, proporciona una dirección URL direccionable externamente, válida mientras se ejecute ngrok. La siguiente imagen es un ejemplo:

   

3. Copie la dirección HTTPS de reenvío similar a: https://dea822bf.ngrok.io/.

4. Anexe para obtener https://dea822bf.ngrok.io/api/messages, que es el punto de conexión de mensajes para el bot que se ejecuta localmente en el equipo y al que se puede acceder a través de la web en un chat en Teams./api/messages

5. Un último paso que se debe realizar es actualizar el punto de conexión de mensajes del bot implementado. En el ejemplo, se implementó el bot en Azure. Se van a realizar estos pasos:

   1. En el explorador, vaya al Azure Portal.
   2. Seleccione el registro del bot.
   3. En el panel izquierdo, seleccione Configuración.
   4. En el panel derecho, en el cuadro Punto de conexión de mensajería, escriba la dirección URL de ngrok, en el ejemplo, https://dea822bf.ngrok.io/api/messages.

6. Inicie el bot localmente, por ejemplo, en Visual Studio modo de depuración.

7. Pruebe el bot mientras se ejecuta localmente mediante el chat web de prueba del portal de Bot Framework. Al igual que el emulador, esta prueba no le permite acceder a la funcionalidad específica de Teams.

8. En la ventana de terminal donde se ejecuta ngrok puede ver el tráfico HTTP entre el bot y el cliente de chat en web. Si desea obtener una vista más detallada, en una ventana del explorador, escriba http://127.0.0.1:4040 obtuvo de la ventana de terminal anterior. La siguiente imagen es un ejemplo:

   

Nota:

Si detiene y reinicia ngrok, la dirección URL cambia. Para usar ngrok en el proyecto y, en función de las funcionalidades que use, debe actualizar todas las referencias de dirección URL.

Información adicional

TeamsAppManifest/manifest.json

Este manifiesto contiene la información necesaria por Teams para conectarse con el bot:

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "version": "1.0.0",
  "id": "",
  "developer": {
    "name": "TeamsBotAuth",
    "websiteUrl": "https://www.microsoft.com",
    "privacyUrl": "https://www.teams.com/privacy",
    "termsOfUseUrl": "https://www.teams.com/termsofuse"
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "name": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "description": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "",
      "scopes": [
        "groupchat",
        "team"
      ],
      "supportsFiles": false,
      "isNotificationOnly": false
    }
  ],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [ "token.botframework.com" ]
}

Con la autenticación, Teams se comporta ligeramente de forma ligeramente diferente que otros canales.

Controlar la actividad Invoke

Una actividad invoke se envía al bot en lugar de a la actividad de eventos usada por otros canales, que se realiza mediante la subclases ActivityHandler.

C#/.NET

Bots/DialogBot.cs

    public class DialogBot<T> : TeamsActivityHandler where T : Dialog
    {
        protected readonly BotState ConversationState;
        protected readonly Dialog Dialog;
        protected readonly ILogger Logger;
        protected readonly BotState UserState;

        public DialogBot(ConversationState conversationState, UserState userState, T dialog, ILogger<DialogBot<T>> logger)
        {
            ConversationState = conversationState;
            UserState = userState;
            Dialog = dialog;
            Logger = logger;
        }

        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))
        {
            await base.OnTurnAsync(turnContext, cancellationToken);

            // Save any state changes that might have occurred during the turn.
            await ConversationState.SaveChangesAsync(turnContext, false, cancellationToken);
            await UserState.SaveChangesAsync(turnContext, false, cancellationToken);
        }

        protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            Logger.LogInformation("Running dialog with Message Activity.");

            // Run the Dialog with the new message Activity.
            await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
        }
    }
}

Bots/TeamsBot.cs

La Actividad Invoke debe reenviarse al cuadro de diálogo si se usa OAuthPrompt.

protected override async Task OnTeamsSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with signin/verifystate from an Invoke Activity.");

    // The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.

    // Run the Dialog with the new Invoke Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

TeamsActivityHandler.cs

protected virtual Task OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    switch (turnContext.Activity.Name)
    {
        case "signin/verifyState":
            return OnSigninVerifyStateAsync(turnContext, cancellationToken);

        default:
            return Task.CompletedTask;
    }
}

protected virtual Task OnSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    return Task.CompletedTask;
}

JavaScript

bots/dialogBot.js

const { TeamsActivityHandler } = require('botbuilder');
class DialogBot extends TeamsActivityHandler {
    /**
     *
     * @param {ConversationState} conversationState
     * @param {UserState} userState
     * @param {Dialog} dialog
     */
    constructor(conversationState, userState, dialog) {
        super();
        if (!conversationState) {
            throw new Error('[DialogBot]: Missing parameter. conversationState is required');
        }
        if (!userState) {
            throw new Error('[DialogBot]: Missing parameter. userState is required');
        }
        if (!dialog) {
            throw new Error('[DialogBot]: Missing parameter. dialog is required');
        }

        this.conversationState = conversationState;
        this.userState = userState;
        this.dialog = dialog;
        this.dialogState = this.conversationState.createProperty('DialogState');

        this.onMessage(async (context, next) => {
            console.log('Running dialog with Message Activity.');

            // Run the Dialog with the new message Activity.
            await this.dialog.run(context, this.dialogState);

            await next();
        });
    }

    /**
     * Override the ActivityHandler.run() method to save state changes after the bot logic completes.
     */
    async run(context) {
        await super.run(context);

        // Save any state changes. The load happened during the execution of the Dialog.
        await this.conversationState.saveChanges(context, false);

bots/teamsBot.js

La Actividad Invoke debe reenviarse al cuadro de diálogo si se usa OAuthPrompt.

const { DialogBot } = require('./dialogBot');

class TeamsBot extends DialogBot {
    /**
     *
     * @param {ConversationState} conversationState
     * @param {UserState} userState
     * @param {Dialog} dialog
     */
    constructor(conversationState, userState, dialog) {
        super(conversationState, userState, dialog);

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded;
            for (let cnt = 0; cnt < membersAdded.length; cnt++) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity('Welcome to TeamsBot. Type anything to get logged in. Type \'logout\' to sign-out.');
                }
            }

            await next();
        });
    }
    
    async handleTeamsSigninVerifyState(context, query) {
        console.log('Running dialog with signin/verifystate from an Invoke Activity.');
        await this.dialog.run(context, this.dialogState);
    }

    async handleTeamsSigninTokenExchange(context, query) {

diálogos/mainDialog.js

En un paso del cuadro de diálogo, use beginDialog para iniciar el aviso de OAuth, que pide al usuario que inicie sesión.

• Si el usuario ya ha iniciado sesión, genera un evento de respuesta de token, sin preguntar al usuario.
• De lo contrario, solicita al usuario que inicie sesión. El servicio de bot de Azure envía el evento de respuesta del token después de que el usuario intente iniciar sesión.

async promptStep(stepContext) {
    try {

En el siguiente paso del cuadro de diálogo, compruebe la presencia de un token en el resultado del paso anterior. Si no es null, el usuario inició sesión correctamente.

async promptStep(stepContext) {
    try {
        return await stepContext.beginDialog(OAUTH_PROMPT);
    } catch (err) {
        console.error(err);
    }
}

async loginStep(stepContext) {
    // Get the token from the previous step. Note that we could also have gotten the
    // token directly from the prompt itself. There is an example of this in the next method.
    const tokenResponse = stepContext.result;
    if (!tokenResponse || !tokenResponse.token) {
        await stepContext.context.sendActivity('Login was not successful please try again.');

diálogos/logoutDialog.js

async interrupt(innerDc) {
    if (innerDc.context.activity.type === ActivityTypes.Message) {
        const text = innerDc.context.activity.text.toLowerCase();
        if (text === 'logout') {
            const userTokenClient = innerDc.context.turnState.get(innerDc.context.adapter.UserTokenClientKey);

            const { activity } = innerDc.context;
            await userTokenClient.signOutUser(activity.from.id, this.connectionName, activity.channelId);

            await innerDc.context.sendActivity('You have been signed out.');
            return await innerDc.cancelAllDialogs();
        }

Python

bots/dialog_bot.py

def __init__(
    self,
    conversation_state: ConversationState,
    user_state: UserState,
    dialog: Dialog,
):
    if conversation_state is None:
        raise Exception(
            "[DialogBot]: Missing parameter. conversation_state is required"
        )
    if user_state is None:
        raise Exception("[DialogBot]: Missing parameter. user_state is required")
    if dialog is None:
        raise Exception("[DialogBot]: Missing parameter. dialog is required")

    self.conversation_state = conversation_state
    self.user_state = user_state
    self.dialog = dialog

async def on_turn(self, turn_context: TurnContext):
    await super().on_turn(turn_context)

    # Save any state changes that might have occurred during the turn.
    await self.conversation_state.save_changes(turn_context, False)
    await self.user_state.save_changes(turn_context, False)

async def on_message_activity(self, turn_context: TurnContext):
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

bots/teams_bot.py

La Actividad Invoke debe reenviarse al cuadro de diálogo si se usa OAuthPrompt.

async def on_teams_signin_verify_state(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    # The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

dialogs/main_dialog.py

En un paso de diálogo, use begin_dialog para iniciar el aviso de OAuth, que pide al usuario que inicie sesión.

• Si el usuario ya ha iniciado sesión, genera un evento de respuesta de token, sin preguntar al usuario.
• De lo contrario, solicita al usuario que inicie sesión. El servicio de bot de Azure envía el evento de respuesta del token después de que el usuario intente iniciar sesión.

async def prompt_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    return await step_context.begin_dialog(OAuthPrompt.__name__)

En el siguiente paso del cuadro de diálogo, compruebe la presencia de un token en el resultado del paso anterior. Si no es null, el usuario inició sesión correctamente.

async def login_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    # Get the token from the previous step. Note that we could also have gotten the
    # token directly from the prompt itself. There is an example of this in the next method.
    if step_context.result:
        await step_context.context.send_activity("You are now logged in.")
        return await step_context.prompt(
            ConfirmPrompt.__name__,
            PromptOptions(
                prompt=MessageFactory.text("Would you like to view your token?")
            ),
        )

dialogs/logout_dialog.py

text = inner_dc.context.activity.text.lower()
if text == "logout":
    bot_adapter: BotFrameworkAdapter = inner_dc.context.adapter
    await bot_adapter.sign_out_user(inner_dc.context, self.connection_name)
    await inner_dc.context.send_activity("You have been signed out.")
    return await inner_dc.cancel_all_dialogs()

Ejemplo de código

En esta sección se proporciona un ejemplo del SDK de Bot Authentication v3.

Ejemplo de nombre	Descripción	.NET	Node.js	Python	Manifiesto
Autenticación del bot	En este ejemplo se muestra cómo empezar a usar la autenticación en un bot para Teams.	View	View	View	Ver
Inicio de sesión único de tab, bot y extensión de mensaje (ME)	En este ejemplo se muestra Microsoft Entra inicio de sesión único para Tab, Bot y ME: búsqueda, acción, desenlazamiento de vínculos.	View	View	ND	Ver

Consulte también

• Agregar autenticación a través del servicio de bot de Azure
• Obtener acceso en nombre de un usuario