Agregar la autorización de usuario mediante la credencial de identidad federada

Servicio de Bot de Azure AI facilita el desarrollo de agentes que pueden acceder a recursos en línea que requieren autenticación de usuario. El agente no necesita administrar tokens de autenticación porque Azure lo hace por usted. Azure usa OAuth 2.0 para generar un token basado en las credenciales de cada usuario. El agente usa el token generado por Azure para tener acceso a esos recursos. De este modo, el usuario no tiene que proporcionar el identificador y la contraseña al agente para tener acceso a un recurso protegido, sino solo a un proveedor de identidades de confianza.

Para configurar OAuth en el agente, registre un bot de Azure si aún no lo ha hecho.

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.

Puede usar uno de estos tres servicios de identidad:

1. Plataforma de identidad de Microsoft (v2.0): también conocido como punto de conexión de Azure Active Directory v2, que es una evolución de la plataforma de Azure AD (v1.0).
2. Credenciales federadas: también conocida como AAD v2 con credenciales federadas.
3. Certificados: también conocido como AAD v2 con certificados.

Estos le permiten crear aplicaciones que inicien sesión en todos los proveedores de identidades de Microsoft y obtengan tokens para llamar a las API de Microsoft, como Microsoft Graph u otras API que los desarrolladores han creado.

Creación del proveedor de identidades de Microsoft Entra ID

En esta sección se muestra cómo crear un proveedor de identidades de Microsoft Entra ID que usa OAuth 2.0 para autenticar el agente para Graph.

1. Abra el panel de Microsoft Entra ID en Azure Portal. Si no está en el inquilino correcto, seleccione Cambiar directorio para cambiar al inquilino correcto. (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. Configuración de registro de aplicaciones

   1. Para SSO de Teams, abra el registro de aplicaciones existente para el agente o el bot de Azure.

      1. En el panel Autenticación si no ve una plataforma web, seleccione + Agregar una plataforma.

         1. Seleccione Web

         2. Escriba el URI de redirección de la tabla en el paso siguiente.

         3. Haga clic en Configurar

            

   2. Para otros canales u OAuth

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

      2. 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. Seleccione el inquilino único.

         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.

            Residencia de datos	Nube	URL de OAuth	Dirección URL de redireccionamiento de OAuth
            Sin ordenar	Público	https://token.botframework.com	https://token.botframework.com/.auth/web/redirect
            Europa	Público	https://europe.token.botframework.com	https://europe.token.botframework.com/.auth/web/redirect
            Estados Unidos	Público	https://unitedstates.token.botframework.com	https://unitedstates.token.botframework.com/.auth/web/redirect
            India	Público	https://india.token.botframework.com	https://india.token.botframework.com/.auth/web/redirect
            Sin ordenar	Azure Government (servicio de nube de Microsoft para el gobierno)	https://token.botframework.azure.us	https://token.botframework.azure.us/.auth/web/redirect
            Sin ordenar	Azure operado por 21Vianet	https://token.botframework.azure.cn	https://token.botframework.azure.cn/.auth/web/redirect

         4. Seleccione Registrar.

            1. Una vez creada, Azure muestra la página Descripción general de la aplicación.
            2. Registre el valor del identificador de aplicación (cliente). Este valor se usa más adelante como identificador de cliente al crear la cadena de conexión y registrar el proveedor de Microsoft Entra ID con el registro del agente.
            3. Registre el valor del identificador de directorio (inquilino). Usarás este valor para registrar esta aplicación de proveedor con tu bot.

4. En el panel de navegación, seleccione Certificados y secretos para agregar credenciales para la aplicación.

   1. En Credenciales federadas, seleccione Agregar credenciales.

      

   2. En la página Agregar credenciales, elija el escenario de credenciales federadas para 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.

         

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

      3. Identificador del asunto: /eid1/c/pub/t/{base64 encoded customer tenant ID}/a/{base64 encoded 1-P app client ID}/{unique-identifier-for-projected-identity}

         La tabla siguiente contiene la representación de matriz de bytes codificada en Base64url de identificadores de aplicación de primera entidad admitidos. Use este valor que representa nuestra aplicación de primera entidad.

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

         La tabla siguiente contiene la representación de matriz de bytes codificada en Base64url de identificadores de algunos inquilinos admitidos. Use el valor que representa el inquilino de la aplicación.

         Valor codificado	Description
         v4j5cvGGr0GRqy180BHbRw	Id. de inquilino de MSIT codificado en Base64url (aaaabbbb-0000-cccc-1111-dddd2222eeee)
         PwFflyR_6Een06vEdSvzRg	Id. de inquilino PME codificado en Base64url (bbbbcccc-1111-dddd-2222-eeee3333ffff)
         6q7FzcUVtk2wefyt0lBdwg	Id. de inquilino de Torus codificado en Base64url (ccccdddd-2222-eeee-3333-ffff4444aa)
         IRngM2RNjE-gVVva_9XjPQ	Id. de inquilino de AME codificado en Base64url (ddddeeee-3333-ffff-4444-aaaa5555bbbb)

         Los propietarios del servicio de identidad principal lo calculan una vez y los proporcionan a sus consumidores.

      4. Unique-identifier-for-projected-identity: un identificador único, que se usa en la configuración de conexión de OAuth en Azure Bot.

      5. Nombre: nombre de su elección, por ejemplo, agente oauth

      6. Audiencia: api://AzureADTokenExchange (Uso de valores específicos de la nube)

   4. Proporcione información en Detalles de credenciales.

      

   5. Seleccione Agregar para agregar la credencial.

5. Exposición del punto de conexión de API

   1. Haga clic en Exponer una API en el raíl izquierdo

      • Para un bot de Azure Bot Service: el valor predeterminado api://{appid} es adecuado.
      • Para un bot de Teams: este formato es OBLIGATORIO api://botid-{appid}

   2. Agregar un ámbito

      1. Seleccione + Agregar un ámbito en la sección Ámbitos definidos por esta API.

         

      2. Introduzca los detalles para configurar el ámbito.

         

      3. Introduzca el nombre del ámbito defaultScopes

      4. Seleccione el usuario que puede dar su consentimiento para este ámbito. La opción predeterminada es Solo administradores.

      5. Introduzca el nombre para mostrar del consentimiento del administrador.

      6. Introduzca la descripción para el consentimiento del administrador.

      7. Introduzca el nombre para mostrar del consentimiento del usuario.

      8. Escriba la descripción del consentimiento del usuario.

      9. Seleccione la opción Habilitado para el estado.

      10. Selecciona la opción Agregar un ámbito.

   3. Solo para Teams, configure una aplicación cliente autorizada

      1. Seleccione + Agregar una aplicación cliente.

         

      2. Escriba el identificador de cliente de Microsoft 365 adecuado para las aplicaciones que desea autorizar para la aplicación web de la aplicación.

         

      3. Seleccione uno de los siguientes Id. de cliente:

         Id. de cliente que se va a usar	Tipo de aplicación para autorizar
         1fec8e78-bce4-4aaf-ab1b-5451cc387264	Aplicación móvil o de escritorio de Teams
         5e3ce6c0-2b1f-4285-8d4b-75ee78787346	Aplicación web de Teams
         4765445b-32c6-49b0-83e6-1d93765276ca	Aplicación web de Microsoft 365
         0ec893e0-5785-4de6-99da-4ed124e5296c	Aplicación de escritorio de Microsoft 365
         d3590ed6-52b3-4102-aeff-aad2292ab01c	Aplicación móvil de Microsoft 365/Aplicación de escritorio de Outlook
         bc59ab01-8403-45c6-8796-ac3ef710b3e3	Aplicación web de Outlook
         27922004-5251-4030-b22d-91ecd9a37ea4	Aplicación móvil de Outlook

      4. Seleccione el URI de identificador de aplicación que creó para la aplicación en ámbitos autorizados para agregar el ámbito a la API web que ha expuesto.

      5. Seleccione Agregar una aplicación.

         

6. En el panel de navegación, seleccione Permisos de API para que se abra el panel Permisos de API. Es un procedimiento recomendado establecer explícitamente los permisos de API de la aplicación.

   1. Seleccione Agregar un permiso para que aparezca el panel Solicitud de 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: Cualquier permiso marcado como CONSENTIMIENTO DEL ADMINISTRADOR OBLIGATORIO requerirá que un usuario y un administrador de inquilinos inicien sesión, por lo que el agente tiende a permanecer alejado de estos.

      • User.Read

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

7. Ahora tiene configurada una aplicación de OAuth.

   Nota:

   Asignará el Id. de aplicación (cliente) al crear la cadena de conexión y registrará el proveedor de identidades con el registro del agente. Consulte la siguiente sección.

Creación de una conexión de OAuth en Azure Bot

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

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

2. Seleccione Configuración y, después, Configuración.

3. Seleccione el botón Configuración de conexión de OAuth cerca de la parte inferior de la página.

4. Rellene el formulario de la siguiente manera:

   1. Nombre. Escriba un nombre para la conexión. Se usa en el código del agente.

   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. En SSO de Teams, escriba el punto de conexión de API creado anteriormente: api://botid-{appId}. De lo contrario, déjelo en blanco.

   6. Id. de inquilino. Escriba el Id. de directorio (inquilino) que registró anteriormente para la aplicación de id. de Microsoft Entra o common en función de 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 obtener más información, consulte Inquilino 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 User.Read.

      1. Si necesita usar este token para OBO en otro servicio (un token intercambiable), use api://botid-{{appId}}/defaultScopes.

   Nota: Para Microsoft Entra ID, el campo Ámbitos toma una lista de valores con distinción entre mayúsculas y minúsculas y separada por espacios.

5. Seleccione Guardar.

Probar la conexión

1. Seleccione la entrada de la 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. 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. A continuación, se le redirigirá a la página Prueba de conexión del nombre de la conexión correcta, donde your-connection-succeeded es su nombre de conexión específico.
6. Solo para tokens intercambiables
   1. Copia del token JWT
   2. Descodificar el token mediante https://jwt.io/
   3. El aud valor de notificación debe comenzar por api://