Agregue código para habilitar el SSO en la aplicación de bot

Antes de agregar código para habilitar el inicio de sesión único (SSO), asegúrese de configurar la aplicación y el recurso del bot en el Centro de administración de Microsoft Entra.

Debe configurar el código de la aplicación para obtener un token de acceso de Microsoft Entra ID. El token de acceso se emite en nombre de la aplicación bot.

Nota:

Si ha creado la aplicación de Teams con el Kit de herramientas de Microsoft Teams, puede habilitar el SSO para la aplicación siguiendo las instrucciones del módulo Herramientas y SDK. Para obtener más información, consulte Agregar inicio de sesión único a la aplicación Teams. El Kit de herramientas de Teams admite SSO para aplicaciones JavaScript, TypeScript y C# en Visual Studio Code.

En esta sección se describen estos temas:

  1. Actualizar variables de entorno de desarrollo
  2. Inicializar la aplicación con OAuth
  3. Controlar el inicio de sesión y la recepción de tokens
  4. Controlar errores de inicio de sesión
  5. Gestionar el cierre de sesión del usuario de la aplicación

Actualizar variables de entorno de desarrollo

Ha configurado el secreto de cliente y la configuración de conexión de OAuth para la aplicación en Microsoft Entra ID. Debe configurar el código con estos valores.

Para actualizar las variables de entorno de desarrollo:

  1. Abra el proyecto de la aplicación bot.

  2. Abra el archivo de entorno (.env) del proyecto.

  3. Actualiza las siguientes variables:

    • Para CLIENT_ID, actualice el ID de bot de Microsoft Entra ID.
    • Para CLIENT_SECRET, actualice el secreto de cliente.
    • Para CONNECTION_NAME, actualice el nombre de la conexión OAuth que configuró en Microsoft Entra ID.
    • Para TENANT_ID, actualice el identificador de inquilino.

    Nota:

    Puede personalizar la dirección URL de redireccionamiento de OAuth para el bot y el proveedor de identidades en función de los requisitos de residencia de datos, independientemente de si el bot está en la nube pública, en la nube de Microsoft Azure Government o en Microsoft Azure operado por 21Vianet. Para ver las direcciones URL de OAuth y la lista de residencia de datos, consulte Compatibilidad con direcciones URL de OAuth en Servicio de Bot de Azure AI.

  4. Guarde el archivo.

Ahora ha configurado las variables de entorno necesarias para la aplicación de bot y el SSO. A continuación, inicializa la aplicación con OAuth.

Inicializar la aplicación con OAuth

El SDK de Teams simplifica la inicialización de aplicaciones con una única App clase que controla el ciclo de vida del servidor, la autenticación y el intercambio de tokens internamente.

using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.OAuth;

var builder = WebApplication.CreateBuilder(args);

var connectionName = builder.Configuration["CONNECTION_NAME"]
    ?? throw new InvalidOperationException("Missing required configuration value: CONNECTION_NAME");

builder.Services.AddTeamsBotApplication(options =>
{
  options.AddOAuthFlow(connectionName);
});

var app = builder.Build();
var teams = app.UseTeamsBotApplication();

OAuthFlow auth = teams.GetOAuthFlow(connectionName);

Nota:

La App clase controla internamente toda la configuración del adaptador, el middleware, el control de errores y la configuración del servidor.

Controlar el inicio de sesión y la recepción de tokens

El SDK de Teams usa controladores sencillos controlados por eventos para la autenticación. Se usa IsSignedIn para comprobar el estado de autenticación, SignIn() para desencadenar el flujo de SSO y suscribirse al evento para controlar la signin autenticación correcta.

teams.OnMessage(async (context, cancellationToken) =>
{
  string? token = await auth.SignInAsync(context, cancellationToken);
  if (token is null)
    {
        return;
    }

  await context.SendAsync($"You are signed in. Token length: {token.Length}", cancellationToken);
});

auth.OnSignInComplete(async (context, tokenResponse, cancellationToken) =>
{
  await context.SendAsync("Successfully signed in! You can now use the bot.", cancellationToken);
});

Nota:

El SDK controla el intercambio de tokens y la validación internamente. Ya no necesita administrar OAuthPromptmanualmente , WaterfallDialogo MainDialog clases.

Controlar errores de inicio de sesión

Al usar SSO, si se produce un error en el intercambio de tokens, Teams envía una signin/failure actividad de invocación a la aplicación. El SDK incluye un controlador predeterminado integrado que registra una advertencia con instrucciones de solución de problemas accionables. Opcionalmente, puede registrar su propio controlador para personalizar el comportamiento:

auth.OnSignInFailure(async (context, failure, cancellationToken) =>
{
    Console.WriteLine($"Sign-in failed: {failure?.Code} - {failure?.Message}");
    await context.SendAsync("Sign-in failed. Please try again.", cancellationToken);
});

Gestionar el cierre de sesión del usuario de la aplicación

signout Llame al método para quitar el token de autenticación del usuario de la caché del servicio de token de usuario y cierre sesión de forma eficaz. El SDK de Teams reemplaza el patrón anterior de usar DialogContext, UserTokenClient, y CancelAllDialogsAsync con una llamada de método simple.

teams.OnMessage("/signout", async (context, cancellationToken) =>
{
  await auth.SignOutAsync(context, cancellationToken);
  await context.SendAsync("You have been signed out.", cancellationToken);
});

El usuario debe dar su consentimiento a los permisos solicitados por la aplicación bot para obtener el token de acceso. El cuadro de diálogo de consentimiento aparece en función del ámbito de la aplicación.

Chats uno a uno

Cuando el usuario de la aplicación usa la aplicación por primera vez y se requiere el consentimiento del usuario, aparece el siguiente cuadro de diálogo:

La infografía muestra la interacción de un bot con un usuario en el ámbito personal

Cuando el usuario selecciona Continuar, se produce uno de los siguientes eventos:

  • Si la interfaz de usuario del bot tiene un botón de inicio de sesión, se activa el flujo de inicio de sesión para los bots. Puede determinar los permisos que requieren el consentimiento del usuario de la aplicación. Use este enfoque si la aplicación requiere permisos de Graph distintos de openid.

  • Si el bot no tiene un botón de inicio de sesión en la tarjeta OAuth, se requiere el consentimiento del usuario de la aplicación para un conjunto mínimo de permisos. Este token es útil para la autenticación básica y para obtener la dirección de correo electrónico del usuario de la aplicación.

El cuadro de diálogo de consentimiento que aparece es para ámbitos de id. abierto definidos en Microsoft Entra ID. El usuario de la aplicación solo debe dar su consentimiento una vez. Después de dar su consentimiento, el usuario de la aplicación puede acceder y usar la aplicación bot para los permisos y ámbitos concedidos.

Chats de grupo

Estos son los dos escenarios para la autenticación en el ámbito de grupo:

Cuando se agrega un bot a un chat grupal por primera vez y se requiere el consentimiento para un usuario determinado, se mostrará un cuadro de diálogo de consentimiento solo para el usuario que @mentions creó el bot. El usuario debe dar su consentimiento único a los permisos solicitados por la aplicación bot para obtener el token de acceso.

El usuario @mentions el bot. Aparece una tarjeta adaptable para solicitar el consentimiento del usuario.

La imagen muestra un cuadro de diálogo de consentimiento para el escritorio

  • Si el usuario selecciona Agregar, aparecerá un cuadro de diálogo de permisos.

    La imagen muestra la ventana emergente de permisos solicitados en el escritorio

    El usuario debe seleccionar Aceptar para dar su consentimiento.

  • Si el usuario lo rechaza o se agota el tiempo de espera de la solicitud, el usuario debe @mention utilizar el bot de nuevo para conceder permiso para la adquisición de tokens. El grupo puede ver un mensaje de bot que indica que la autenticación no se realizó correctamente.

    La imagen muestra la interacción del bot cuando se deniega el consentimiento del usuario o se agota el tiempo de espera de la solicitud

Si los permisos de usuario se conceden de forma predeterminada o para aplicaciones de confianza, el usuario con el que @mentions trabaja el bot puede interactuar directamente con el bot sin necesidad de dar su consentimiento.

Nota:

Una vez que el usuario de la aplicación da su consentimiento, no es necesario que vuelva a dar su consentimiento para ningún otro permiso. Si se modifican los permisos definidos en el ámbito de Microsoft Entra, es posible que el usuario de la aplicación deba dar su consentimiento de nuevo. Sin embargo, si la solicitud de consentimiento no permite el acceso del usuario a la aplicación, la aplicación del bot vuelve a la tarjeta de inicio de sesión.

Importante

Escenarios en los que no se necesitan cuadros de diálogo de consentimiento:

  • Si el administrador otorga consentimiento en nombre del inquilino, no es necesario solicitar el consentimiento a los usuarios de la aplicación. Esto significa que los usuarios de la aplicación no ven los cuadros de diálogo de consentimiento y pueden acceder a la aplicación sin problemas.
  • Si la aplicación Microsoft Entra está registrada en el mismo inquilino desde el que solicita una autenticación en Teams, no se podrá pedir el consentimiento al usuario de la aplicación y se le concederá un token de acceso inmediatamente. Los usuarios de la aplicación aceptan estos permisos solo si la aplicación Microsoft Entra está registrada en un inquilino diferente.

Si encuentra algún error, consulte Solucionar problemas de autenticación SSO en Teams.

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js
Conversación del bot Inicio rápido de SSO Configure rápidamente el bot de Teams con SSO para una autenticación de usuario fluida para chats individuales y grupales. View View

Paso siguiente