Editar manifiesto de Microsoft Entra

Kit de herramientas para agentes de Microsoft 365 (anteriormente conocido como Kit de herramientas de Teams) ahora administra la aplicación Microsoft Entra con el archivo de manifiesto de la aplicación como fuente de confianza durante el ciclo de vida de desarrollo de aplicaciones de Microsoft Teams.

Personalizar plantilla de manifiesto de Microsoft Entra

Puede personalizar la plantilla de manifiesto de Microsoft Entra para actualizar la aplicación de Microsoft Entra.

  1. Abrir aad.template.json en el proyecto.

    Captura de pantalla que muestra la plantilla.

  2. Actualice la plantilla directamente o haga referencia a valores de otro archivo. Estos son los escenarios de personalización:

    Agregar un permiso de aplicación

    Si la aplicación de Teams requiere más permisos para llamar a una API con permisos adicionales, deberá actualizar requiredResourceAccess la propiedad en la plantilla de manifiesto de Microsoft Entra. Puede ver el siguiente ejemplo de esta propiedad:

    "requiredResourceAccess": [
        {
            "resourceAppId": "Microsoft Graph",
            "resourceAccess": [
                {
                    "id": "User.Read", // For Microsoft Graph API, you can also use uuid for permission id
                    "type": "Scope" // Scope is for delegated permission
                },
                {
                    "id": "User.Export.All",
                    "type": "Role" // Role is for application permission
                }
            ]
        },
        {
            "resourceAppId": "Office 365 SharePoint Online",
            "resourceAccess": [
                {
                        "id": "AllSites.Read",
                "type": "Scope"
                }
            ]
        }
    ]
    
    

    En la lista siguiente se proporcionan diferentes identificadores de propiedad y su uso:

    • La resourceAppId propiedad se usa para diferentes API. Para Microsoft Graph y Office 365 SharePoint Online, escriba el nombre directamente en lugar del UUID, y para otras API use UUID.

    • La resourceAccess.id propiedad se usa para diferentes permisos. Para Microsoft Graph y Office 365 SharePoint Online, escriba el nombre del permiso directamente en lugar del UUID, y para otras API use UUID.

    • La resourceAccess.type propiedad se usa para permisos delegados o permisos de aplicación. Scope significa permiso delegado y Role significa permiso de aplicación.

    Autorización previa de una aplicación cliente

    Puede utilizar preAuthorizedApplications una propiedad para autorizar una aplicación cliente para indicar que la API confía en la aplicación. Los usuarios no dan su consentimiento cuando el cliente llama a la API expuesta. Puede ver el siguiente ejemplo de esta propiedad:

    "api": {
       ...
       "preAuthorizedApplications": [
           {
               "appId": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
               "delegatedPermissionIds": [
                   "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
               ]
           }
       ]
       ...
    }
    
    

    preAuthorizedApplications.appId propiedad que se utiliza para la aplicación que desea autorizar. Si no conoce el identificador de la aplicación y solo conoce el nombre de la aplicación, siga estos pasos para buscar el identificador de aplicación:

    1. Vaya a Azure Portal y abra Registros de aplicaciones.

    2. Seleccione Todas las aplicaciones y busque el nombre de la aplicación.

    3. Seleccione el nombre de la aplicación y obtenga el id. de la aplicación en la página de información general.

    Actualizar la dirección URL de redirección para la respuesta de autenticación

    Las direcciones URL de redireccionamiento se usan cuando devuelven respuestas de autenticación, como tokens después de una autenticación correcta. Puedes personalizar las URL de redireccionamiento mediante la propiedad redirectUris dentro webde , spa, publicClient. Por ejemplo, para agregarla https://www.examples.com/auth-end.html como dirección URL de redireccionamiento, puede agregarla como ejemplo siguiente:

    "publicClient": {
      "redirectUris": [
          "https://www.examples.com/auth-end.html"
      ]
    },
    "web": {
      "redirectUris": [
          "https://www.examples.com/auth-end.html"
      ],
      "implicitGrantSettings": {}
    },
    "spa": {
      "redirectUris": [
          "https://www.examples.com/auth-end.html",
      ]
    }
    
  3. Actualice los cambios de aplicación de Microsoft Entra para el entorno local o remoto.

    1. Selecciona Preview CodeLens en aad.template.json.

      La captura de pantalla muestra la vista previa.

    2. Seleccione el entorno local o de desarrollo .

      La captura de pantalla muestra la lista de entornos.

    3. Selecciona Deploy Azure AD Manifest CodeLens en aad.local.json o aad.dev.json.

      La captura de pantalla muestra la opción de implementación resaltada.

    4. Se implementan los cambios para la aplicación Microsoft Entra utilizada en el entorno local o de desarrollo.

    5. Además, puede abrir la paleta de comandos y seleccionar Teams: Actualizar aplicación Microsoft Entra para actualizar la aplicación Microsoft Entra. La captura de pantalla muestra la opción Paleta de comandos.

Marcadores de posición de plantilla de manifiesto de Microsoft Entra

El archivo de manifiesto de Microsoft Entra contiene argumentos de marcador de posición con {{...}} se reemplaza durante la compilación para diferentes entornos. Puede hacer referencia a variables de entorno con los argumentos de marcador de posición.

Variable de entorno de referencia en la plantilla de manifiesto de Microsoft Entra

No es necesario escribir valores permanentes en la plantilla de manifiesto de Microsoft Entra y el archivo de plantilla de manifiesto de Microsoft Entra admite valores variables de entorno de referencia. Puede utilizar la sintaxis ${{YOUR_ENV_VARIABLE_NAME}} de la herramienta como valores de parámetro para resolver los valores de variables de entorno.

Editar y obtener una vista previa del manifiesto de Microsoft Entra con CodeLens

El archivo de plantilla de manifiesto de Microsoft Entra tiene CodeLens para revisar y editar el código.

Archivo de plantilla de manifiesto de Microsoft Entra

Hay una vista previa de CodeLens al principio del archivo de plantilla de manifiesto de Microsoft Entra. Seleccione CodeLens para generar un manifiesto de Microsoft Entra basado en su entorno.

La captura de pantalla muestra la vista previa de agregar codelens.

Argumento de marcador de posición CodeLens

Argumento de marcador de posición CodeLens le ayuda a ver los valores de la depuración local y a desarrollar su entorno. Si mueve el mouse sobre el argumento de marcador de posición, se muestra el cuadro de información sobre herramientas para los valores de todos los entornos.

La captura de pantalla muestra los argumentos de agregar.

Acceso necesario a recursos CodeLens

La plantilla de manifiesto de Microsoft Entra en Agents Toolkit también admite cadenas legibles por el usuario para Microsoft Graph permisos y Office 365 SharePoint Online permisos. El esquema de manifiesto oficial de Microsoft Entra, que es la resourceAppId propiedad and resourceAccess inrequiredResourceAccess, solo admite el UUID. Si introduces el UUID, CodeLens muestra cadenas legibles por el usuario; de lo contrario, muestra el UUID.

La captura de pantalla muestra la opción Agregar recurso al acceso necesario al recurso.

Aplicaciones autorizadas previamente CodeLens

CodeLens muestra el nombre de la aplicación para el id. de aplicación preautorizado para la propiedad dentro de la preAuthorizedApplications propiedad api.

Ver la aplicación Microsoft Entra en el Azure Portal

  1. Copie el identificador de cliente de la aplicación Microsoft Entra desde .env.xxx el archivo () de la AAD_APP_CLIENT_ID propiedad.

    La captura de pantalla muestra el id. de cliente.

    Nota:

    xxx en el id. de cliente indica el nombre del entorno en el que ha implementado la aplicación Microsoft Entra.

  2. Vaya a Azure Portal e inicie sesión en la cuenta de Microsoft 365.

    Nota:

    Asegúrese de que las credenciales de inicio de sesión de la aplicación Teams y la cuenta de M365 sean las mismas.

  3. Abra la página Registros de aplicaciones y busque la aplicación de Microsoft Entra con el id. de cliente que copió anteriormente.

    La captura de pantalla muestra el id. de cliente en la pestaña Todas las aplicaciones.

  4. Seleccione la aplicación Microsoft Entra en el resultado de la búsqueda para ver la información detallada.

  5. En la página de información de la aplicación Microsoft Entra, seleccione el menú Manifiesto para ver el manifiesto de esta aplicación. El esquema del manifiesto es el mismo que el del aad.template.json archivo. Para más información sobre el manifiesto, consulte Manifiesto de la aplicación Microsoft Entra.

    La captura de pantalla muestra la pantalla Manifiesto.

  6. Puede seleccionar Otro menú para ver o configurar la aplicación Microsoft Entra a través de su portal.

Utilizar una aplicación de Microsoft Entra existente

Puede utilizar la aplicación de Microsoft Entra existente para el proyecto de Teams. Para obtener más información, consulte usar una aplicación de Microsoft Entra existente para su aplicación de Teams.

Aplicación de Microsoft Entra en Teams ciclo de vida de desarrollo de aplicaciones

Debe interactuar con la aplicación Microsoft Entra durante varias etapas del ciclo de vida de desarrollo de aplicaciones de Teams.

  1. Para crear un proyecto

    Puedes crear un proyecto con Agents Toolkit que incluya la compatibilidad con el inicio de sesión único (SSO) de forma predeterminada, como SSO-enabled tab. Para obtener más información sobre cómo crear una nueva aplicación, consulte Crear una nueva aplicación de Teams con el Kit de herramientas de agentes. Se crea automáticamente un archivo de manifiesto de Microsoft Entra en aad.template.json. Kit de herramientas de agentes crea o actualiza la aplicación Microsoft Entra durante el desarrollo local o mientras mueve la aplicación a la nube.

  2. Para agregar el SSO al bot o a la pestaña

    Después de crear una aplicación de Teams sin SSO integrado, Kit de herramientas de agentes le ayuda progresivamente a agregar SSO para el proyecto. Como resultado, se crea automáticamente un archivo de manifiesto de Microsoft Entra en aad.template.jsonformato

    Kit de herramientas de agentes crea o actualiza la aplicación Microsoft Entra durante la siguiente sesión de desarrollo local o mientras mueve la aplicación a la nube.

  3. Para compilar localmente

    El Kit de herramientas de agentes realiza las siguientes funciones durante el desarrollo local:

    • Lea el .env.local archivo para buscar una aplicación de Microsoft Entra existente. Si ya existe una aplicación de Microsoft Entra, Kit de herramientas de agentes reutiliza la aplicación de Microsoft Entra existente. En caso contrario, deberá crear una nueva aplicación con el aad.template.json archivo.

    • Inicialmente omite algunas propiedades del archivo de manifiesto que requieren más contexto, como redirectUris la propiedad que requiere un punto de conexión de desarrollo local durante la creación de una nueva aplicación de Microsoft Entra con el archivo de manifiesto.

    • Una vez que el entorno de desarrollo local se inicia correctamente, el , y otras propiedades de la aplicación Microsoft Entra y otras propiedades que no están disponibles durante la fase de identifierUrisredirectUriscreación se actualizan en consecuencia.

    • Los cambios realizados en la aplicación de Microsoft Entra se cargarán durante la siguiente sesión de desarrollo local. Puede ver los cambios de la aplicación Microsoft Entra aplicados manualmente.

  4. Para aprovisionar recursos en la nube

    Debe aprovisionar recursos en la nube e implementar la aplicación mientras la mueve a la nube. En fases, como la depuración local, Kit de herramientas de agentes:

    • Lee el .env.{env} archivo para buscar una aplicación de Microsoft Entra existente. Si ya existe una aplicación de Microsoft Entra, Kit de herramientas de agentes reutiliza la aplicación de Microsoft Entra existente. En caso contrario, deberá crear una nueva aplicación con el aad.template.json archivo.

    • Inicialmente omite algunas propiedades del archivo de manifiesto que requieren más contexto, como redirectUris propiedad. Esta propiedad requiere un punto de conexión de front-end o bot durante la creación de una nueva aplicación Microsoft Entra con el archivo de manifiesto.

    • Completa el aprovisionamiento de otros recursos, y, a continuación, la aplicación de Microsoft Entra y redirectUris se actualizan según los puntos de identifierUrisconexión correctos.

  5. Para crear una aplicación

    • El comando en la nube implementa la aplicación en los recursos aprovisionados. No incluye la implementación de los cambios de aplicación de Microsoft Entra que ha realizado.

    • Kit de herramientas de agentes actualiza la aplicación Microsoft Entra según el archivo de plantilla de manifiesto de Microsoft Entra.

Limitaciones

  1. La extensión Agents Toolkit no admite todas las propiedades enumeradas en el esquema de manifiesto de Microsoft Entra.

    En la tabla siguiente se enumeran las propiedades que no son compatibles con la extensión Agents Toolkit:

    Propiedades no admitidas Motivo
    passwordCredentials No se permiten en el manifiesto
    createdDateTime Solo lectura y no se puede cambiar
    logoUrl Solo lectura y no se puede cambiar
    publisherDomain Solo lectura y no se puede cambiar
  2. La requiredResourceAccess propiedad se usa para cadenas de nombre de aplicación o nombre de permiso de recurso legible por el usuario solo para Microsoft Graph y Office 365 SharePoint Online API. Debe usar UUID para otras API. Realice los pasos siguientes para recuperar identificadores de Azure Portal:

    1. Registro de una nueva aplicación de Microsoft Entra en Azure Portal.
    2. Seleccione API permissions en la página de la aplicación Microsoft Entra.
    3. Seleccione add a permission esta opción para agregar los permisos que necesite.
    4. Seleccione Manifest en la requiredResourceAccess propiedad, donde puede encontrar los identificadores de API y los permisos.

Vea también