Implementación de la autenticación con credenciales de identidad federada

SE APLICA A: SDK v4

Para obtener información general sobre cómo Bot Framework controla este tipo de autenticación, consulte Autenticación de usuario.

En este artículo se explica cómo:

• Cree un recurso de Azure Bot.
• Cree el proveedor de identidades de Microsoft Entra ID y use el flujo de credenciales federadas.
• Registre el proveedor de identidad de Microsoft Entra ID con el bot para la autenticación de usuarios mediante el flujo de credenciales federadas.
• Prepare el código del bot.

Una vez finalizado este artículo, tiene un bot que puede responder a algunas tareas sencillas.

Prerrequisitos

• Conocimientos sobre conceptos básicos de los bots, administración de estado, biblioteca de diálogos, implementación de flujos de conversación secuenciales y reutilización de diálogos.

• Conocimientos sobre el desarrollo de Azure y OAuth 2.0.

• Visual Studio 2017 o posterior para .NET.

• Node.js para JavaScript.

• Python 3.8+ para Python.

• Uno de los ejemplos enumerados.

  Ejemplo	Versión de BotBuilder	Demostraciones
  Autenticación en C#	v4	Compatibilidad con OAuthCard

  Para ejecutar los ejemplos a los que se hace referencia en este artículo, necesita:

  • Una aplicación de Microsoft Entra ID con la que se va a registrar un recurso de bot en Azure. Esta aplicación permite al bot acceder a un recurso protegido externo, como Microsoft Graph. También permite al usuario comunicarse con el bot a través de varios canales, como Chat en web.
  • Una aplicación independiente de Microsoft Entra ID para funcionar como proveedor de identidad. Esta aplicación proporciona las credenciales necesarias para establecer una conexión de OAuth entre el bot y el recurso protegido. Tenga en cuenta que en este artículo se usa Active Directory como proveedor de identidades. También se admiten muchos otros proveedores.

Creación del recurso de Azure Bot

Cree el recurso Azure Bot, que le permite registrar su bot con el servicio de bot Azure AI.

1. Vaya a Azure Portal.

2. En el panel derecho, seleccione Crear un recurso.

3. Escribe bot en el cuadro de búsqueda y, luego, presiona Entrar.

4. Seleccione la tarjeta Azure Bot.

   

5. Seleccione Crear.

6. Escriba los valores en los campos obligatorios y revise y actualice la configuración.

   1. Proporciona información en Detalles del proyecto. Seleccione si el bot tiene residencia de datos globales o locales. Actualmente, la función de residencia de datos local está disponible para los recursos de la región "Europa Occidental" y "India Central". Para obtener más información, consulta Regionalización en Servicio de Bot de Azure AI.

      

   2. Proporciona información en identificador de aplicación de Microsoft. Seleccione cómo se administra la identidad del bot en Azure y si desea crear una nueva identidad o usar una existente.

      

7. Seleccione Revisar + crear.

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

9. Una vez completada la implementación, seleccione Ir al recurso. Debería ver el bot y los recursos relacionados que aparecen en el grupo de recursos que seleccionó.

10. Si aún no tiene Bot Framework SDK, seleccione Descargar desde GitHub para obtener información sobre cómo consumir los paquetes para su idioma preferido.

    

Ya está listo para desarrollar su bot con el SDK de Bot Framework.

Creación de una identidad administrada asignada por el usuario

Cree el recurso Identidad administrada asignada por el usuario, que le permite configurar una identidad que se utiliza como mecanismo de confianza para obtener tokens de acceso desde la aplicación Microsoft Entra.

1. Vaya a Azure Portal.

2. En el panel derecho, seleccione Crear un recurso.

3. Escribe Managed Identities en el cuadro de búsqueda y, luego, presiona Entrar.

4. Seleccione la tarjeta Identidad administrada asignada por el usuario.

   

5. Seleccione Crear.

6. Escriba los valores en los campos obligatorios y revise y actualice la configuración.

   1. Proporciona información en Detalles del proyecto. Seleccione si su identidad tiene residencia de datos global o local.

      

7. Seleccione Revisar + crear.

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

9. Una vez completada la implementación, seleccione Ir al recurso. Deberías ver la identidad gestionada y los recursos relacionados listados en el grupo de recursos que seleccionaste.

Para crear una nueva credencial federada

El propietario del recurso de App Service del bot puede agregar una nueva confianza:

1. Ve a la hoja de recursos del bot de Azure para el bot.

2. Ve a la hoja Configuración del bot.

3. Selecciona Administrar, junto a identificador de aplicación de Microsoft, para ir a la hoja Certificados y secretos del servicio de aplicaciones.

4. En la hoja Certificados y secretos, seleccione la pestaña Credenciales federadas y Agregar credenciales (+).

   

5. En la página Añadir credenciales, seleccione el Escenario de credenciales federado a Claves administradas por el cliente

   

6. Escriba los valores en los campos necesarios y revise y actualice la configuración.

   1. Proporcione información en Seleccione una identidad administrada.
      1. En la hoja Seleccione una identidad administrada:
      2. Seleccione la suscripción.
      3. En Identidades administradas asignadas por el usuario, seleccione la identidad administrada creada anteriormente.
      4. Seleccione Seleccione para usar esta identidad para el bot.
   2. Proporcione información en Detalles de credenciales.

7. Seleccione Agregar para agregar la credencial.

Para actualizar el bot

1. Actualice la versión del SDK de Bot Framework a la versión 4.22.8 o posterior.

2. Para habilitar la credencial federada para el bot, agregue el código siguiente al archivo Startup.cs:

   services.AddSingleton<ServiceClientCredentialsFactory>(new FederatedServiceClientCredentialsFactory(
       Configuration["MicrosoftAppId"],
       Configuration["MicrosoftAppClientId"],
       Configuration["MicrosoftAppTenantId"]));
   

3. Siga estos pasos para incluir información de identidad en el archivo de configuración del bot. El archivo y los pasos específicos pueden variar en función del lenguaje de programación que use para crear el bot.

   Importante

   La versión Java del SDK de Bot Framework solo admite bots multi-tenant. Las versiones de C#, JavaScript y Python admiten los tres tipos de aplicación para administrar la identidad del bot.

   Idioma	Nombre de archivo	Notas
   C#	appsettings.json	Admite los tres tipos de aplicación para administrar la identidad del bot.
   JavaScript	.env	Admite los tres tipos de aplicación para administrar la identidad del bot.
   Java	application.properties	Solo admite bots multitenant.
   Pitón	config.py	Admite los tres tipos de aplicación para administrar la identidad del bot.

La información de identidad que necesita agregar depende del tipo de aplicación del bot. Proporcione los siguientes valores en el archivo de configuración.

Para obtener la aplicación o el identificador de inquilino

Para obtener la aplicación o el identificador de inquilino del bot:

1. Ve a la hoja de recursos del bot de Azure para el bot.
2. Ve a la hoja Configuración del bot. En esta hoja, puedes copiar el identificador de aplicación de Microsoft del bot o el identificador de inquilino de la aplicación.

Para actualizar el servicio de aplicaciones

Si tu bot utiliza un recurso de App Service existente (aplicación web) y es una aplicación de uno o varios inquilinos, es posible que tengas que actualizar su servicio de aplicación.

1. Ve a la hoja de App Service de la aplicación web del bot.
2. En Configuración, seleccione Identidad.
3. En la hoja Identidad, selecciona Asignación de usuario yAgregar (+).
4. En la hoja identidad administrada asignada por el usuario:

   1. Seleccione la suscripción.

   2. En Identidades administradas asignadas por el usuario, seleccione la identidad administrada creada anteriormente.

   3. Seleccione Agregar para usar esta identidad para el bot.

      

Servicio de identidad de Microsoft Entra

Microsoft Entra ID es un servicio de identidad en la nube que permite crear aplicaciones que inician sesión de forma segura a los usuarios mediante protocolos estándar del sector como OAuth 2.0.

1. Plataforma de identidad de Microsoft (v2.0). También conocido como punto de conexión Microsoft Entra ID, que es una evolución de la plataforma Azure AD (v1.0), permite crear aplicaciones que inician sesión en todos los proveedores de identidad de Microsoft y obtienen tokens para llamar a las API de Microsoft, como Microsoft Graph, o a otras API creadas por desarrolladores. Para obtener más información, consulte la descripción general de la plataforma de identidad de Microsoft (v2.0) .

Para obtener información sobre las diferencias entre los puntos de conexión v1 y v2, consulte ¿Por qué actualizar a la plataforma de identidad de Microsoft (v2.0)?. Para obtener información completa, consulte plataforma de identidad de Microsoft (anteriormente Microsoft Entra ID para desarrolladores).

Creación del proveedor de identidades de Microsoft Entra ID

En esta sección se muestra cómo crear un proveedor de identidades de Id. de Entra de Microsoft que usa OAuth 2.0 para autenticar el bot. Puede usar los puntos de conexión de Microsoft Entra ID.

1. Abra el panel Microsoft Entra ID en el portal de Azure. Si no está en el inquilino correcto, seleccione Cambiar directorio para cambiar el inquilino. (Para obtener información sobre cómo crear un inquilino, consulte Acceso al portal y creación de un inquilino).

2. Abra el panel Registros de aplicaciones.

3. En el panel Registros de aplicaciones, seleccione Nuevo registro.

4. Rellene los campos obligatorios y cree el registro de la aplicación.

   1. Asigne un nombre a la aplicación.

   2. Seleccione los tipos de cuenta admitidos para la aplicación. (Cualquiera de estas opciones funciona con este ejemplo).

   3. En URI de redirección, seleccione Web y establezca la dirección URL en una de las direcciones URL de redirección de OAuth admitidas.

   4. Seleccione Registrar.

      • Una vez creada, Azure muestra la página Descripción general de la aplicación.
      • Registre el valor del identificador de aplicación (cliente). Este valor se utiliza posteriormente como ID de cliente cuando se crea la cadena de conexión y se registra el proveedor de ID de Microsoft Entra con el registro del bot.
      • Registre el valor del identificador de directorio (inquilino). Usarás este valor para registrar esta aplicación de proveedor con tu bot.

5. En el panel de navegación, seleccione Certificados & secretos para crear un secreto para su aplicación.

   1. En Credenciales federadas, seleccione Agregar credenciales.

      

   2. En la página Agregar credenciales, elija el Escenario de credenciales federadas a Otro emisor

      

   3. Escriba los valores en los campos necesarios y revise y actualice la configuración.

      1. Proporcione información en Conecte su cuenta.

         

         1. Emisor : https://login.microsoftonline.com/{customer-tenant-ID}/v2.0

         2. Identificador del sujeto : /eid1/c/pub/t/{base64 encoded customer tenant ID}/a/{base64 encoded first-party app client ID}/{unique-identifier-for-projected-identity}

            • La siguiente tabla contiene la representación de matrices de bytes con codificación Base64url de los ID de aplicaciones de origen admitidos. Utiliza este valor que representa nuestra aplicación de primera parte.

              Valor codificado	Descripción
              9ExAW52n_ky4ZiS_jhpJIQ	Codificación Base64url de Bot Service Token Store
              ND1y8_Vv60yhSNmdzSUR_A	Codificación Base64url del portal de desarrollo de Bot Framework

            • El siguiente código de ejemplo le ayuda a convertir el identificador de inquilino en una representación de matriz de bytes codificada en Base64url. Utilice el valor que corresponde al cliente de su aplicación.

         3. Audiencia : api://AzureADTokenExchange (usar valores específicos de la nube)

         4. identificador-único-para-identidad-proyectada : El token tiene el mismo valor especificado que el identificador único en la configuración de conexión de OAuth.

      2. Proporcione información en Detalles de credenciales.

         

      3. Seleccione Agregar para agregar la credencial.

6. En el panel de navegación, seleccione permisos de API para abrir el panel de permisos de API . Se recomienda establecer explícitamente los permisos de API para la aplicación.

   1. Seleccione Agregar un permiso para mostrar el panel Solicitar permisos de API.

   2. Para este ejemplo, seleccione Microsoft APIs y Microsoft Graph.

   3. Elija Permisos delegados y asegúrese de que se seleccionan los permisos que necesita. Este ejemplo requiere estos permisos.

      Nota

      Los permisos marcados como SE NECESITA EL CONSENTIMIENTO DEL ADMINISTRADOR requerirán un usuario y un administrador de inquilinos para iniciar sesión, por lo que evite usarlos para el bot.

      • openid
      • perfil
      • Mail.Read
      • Mail.Send
      • User.Read
      • User.ReadBasic.All

   4. Seleccione Agregar permisos. (La primera vez que un usuario accede a esta aplicación a través del bot, debe conceder consentimiento).

Ahora tiene una aplicación de Microsoft Entra ID configurada.

Registro del proveedor de identidades de Microsoft Entra ID con el bot

El siguiente paso es registrar el proveedor de identidades con el bot.

1. Abra la página de recursos Azure Bot de su bot en Azure Portal.

2. Haga clic en Configuración.

3. En Configuración de conexión de OAuth, cerca de la parte inferior de la página, seleccione Agregar configuración.

4. Rellene el formulario de la manera siguiente:

   1. Nombre. Escriba un nombre para la conexión. Lo usas en tu código del bot.

   2. Proveedor de servicios. Seleccione AAD v2 con credenciales federadas para mostrar campos específicos del proveedor de servicios.

   3. ID de cliente. Introduzca el ID de la aplicación (cliente) que registró para su proveedor de identidad Microsoft Entra ID (solo se admite un único inquilino).

   4. Identificador único. Ingrese el identificador único que registró para su proveedor de identidad Microsoft Entra ID al crear credenciales federadas.

   5. Dirección URL de intercambio de tokens. Déjalo en blanco porque se usa únicamente para SSO en Microsoft Entra ID.

   6. Identificador de inquilino. Escriba el identificador de directorio (inquilino) que registró anteriormente para la aplicación de Microsoft Entra ID o common (común) según los tipos de cuenta admitidos seleccionados al crear la aplicación de Azure DD. Para decidir qué valor asignar, siga estos criterios:

      • Al crear la aplicación de Microsoft Entra ID, si seleccionó solo las cuentas de este directorio organizativo (solo Microsoft: un solo inquilino), especifique el valor de identificador del inquilino que anotó anteriormente para la aplicación de Microsoft Entra ID.
      • Sin embargo, si seleccionó Cuentas en cualquier directorio organizativo (cualquier directorio de Microsoft Entra ID: multiinquilino y cuentas personales de Microsoft, como Xbox o Outlook.com) o Cuentas en cualquier directorio organizativo (directorio de Microsoft Entra ID: multiinquilino), escriba common en lugar de un identificador de inquilino. De lo contrario, la aplicación Microsoft Entra ID verifica a través del inquilino cuya ID fue seleccionada y excluye las cuentas personales de Microsoft.

      Este es el inquilino asociado a los usuarios que se pueden autenticar. Para más información, consulte Inquilinos en Microsoft Entra ID.

   7. En Ámbitos, escriba los nombres de los permisos que eligió en el registro de la aplicación. Con fines de prueba, puede escribir openid profile.

      Nota

      Para Microsoft Entra ID, el campo Ámbitos toma una lista de valores que distingue mayúsculas de minúsculas, separados por espacios.

5. Seleccione Guardar.

Prueba de la conexión

1. Seleccione en la entrada de conexión para abrir la conexión que creó.
2. Seleccione Probar conexión en la parte superior del panel Configuración de conexión del proveedor de servicios.
3. La primera vez, debe abrir una nueva pestaña del explorador en la que se enumeran los permisos que solicita la aplicación y solicitarle que acepte.
4. Seleccione Aceptar.
5. Esto debería redirigirle a la página Test Connection to <your-connection-name> Succeeded (Resultado satisfactorio de la prueba de conexión a "nombreDeLaConexión>").

Ahora puede usar este nombre de conexión en el código del bot para recuperar tokens de usuario.

Preparación del código del bot

Necesita el identificador y la contraseña de la aplicación del bot para completar este proceso.

Información adicional

Cuando un usuario pide al bot que haga algo que requiera que el bot haya iniciado sesión, el bot puede usar un OAuthPrompt para iniciar la recuperación de un token para una conexión determinada. El OAuthPrompt crea un flujo de recuperación de tokens que consta de:

1. Compruebe si Azure AI Bot Service ya tiene un token para el usuario y la conexión actuales. Si hay un token, se devuelve el token.
2. Si Azure AI Bot Service no tiene un token almacenado en caché, se crea un OAuthCard que es un botón de inicio de sesión en el que el usuario puede seleccionar.
3. Después de que el usuario seleccione en el botón de inicio de sesión de OAuthCard, Azure AI Bot Service enviará el token del usuario directamente o presentará al usuario un código de autenticación de seis dígitos para entrar en la ventana de chat.
4. Si el usuario se presenta con un código de autenticación, el bot intercambia este código de autenticación para el token del usuario.

En las secciones siguientes se describe cómo implementa el ejemplo algunas tareas comunes de autenticación.

Usar un mensaje de OAuth para iniciar la sesión del usuario y obtener un token

AddDialog(new OAuthPrompt(
    nameof(OAuthPrompt),
    new OAuthPromptSettings
    {
        ConnectionName = ConnectionName,
        Text = "Please Sign In",
        Title = "Sign In",
        Timeout = 300000, // User has 5 minutes to login (1000 * 60 * 5)
    }));

return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

// 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.
var tokenResponse = (TokenResponse)stepContext.Result;

Esperar a TokenResponseEvent

Al iniciar un aviso de OAuth, espera un evento de respuesta del token, del cual recupera el token del usuario.

    }
}

Cerrar sesión del usuario

Se recomienda permitir que los usuarios cierren sesión explícitamente, en lugar de depender de que la conexión expire.

private async Task<DialogTurnResult> InterruptAsync(DialogContext innerDc, CancellationToken cancellationToken = default(CancellationToken))
{
    if (innerDc.Context.Activity.Type == ActivityTypes.Message)
    {
        var text = innerDc.Context.Activity.Text.ToLowerInvariant();

        if (text == "logout")
        {
            // The UserTokenClient encapsulates the authentication processes.
            var userTokenClient = innerDc.Context.TurnState.Get<UserTokenClient>();
            await userTokenClient.SignOutUserAsync(innerDc.Context.Activity.From.Id, ConnectionName, innerDc.Context.Activity.ChannelId, cancellationToken).ConfigureAwait(false);

            await innerDc.Context.SendActivityAsync(MessageFactory.Text("You have been signed out."), cancellationToken);
            return await innerDc.CancelAllDialogsAsync(cancellationToken);
        }
    }

    return null;
}

Lectura adicional

• Bot Framework los otros recursos incluyen vínculos para obtener más soporte.
• El repositorio del SDK de Bot Framework tiene más información sobre repositorios, ejemplos, herramientas y especificaciones asociadas al SDK de Bot Builder.