Compartir a través de

Editar Microsoft Entra manifiesto

Microsoft 365 Agents Toolkit (anteriormente conocido como Kit de herramientas de Teams) ahora administra Microsoft Entra aplicación con el archivo de manifiesto de la aplicación como el origen de la verdad durante el ciclo de vida de desarrollo de aplicaciones de Microsoft Teams.

Personalización de Microsoft Entra plantilla de manifiesto

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

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

    Captura de pantalla que muestra la plantilla.

  2. Actualice la plantilla directamente o haga referencia a los valores de otro archivo. A continuación se muestran los escenarios de personalización:

    Agregar un permiso de aplicación

    Si la aplicación teams requiere más permisos para llamar a una API con permisos adicionales, debe actualizar requiredResourceAccess la propiedad en la plantilla de manifiesto de Microsoft Entra. Puede ver el ejemplo siguiente para 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 distintas API. Para Microsoft Graph y Office 365 SharePoint Online, escriba el nombre directamente en lugar de UUID y, para otras API, use UUID.

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

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

    Autenticación previa de una aplicación cliente

    Puede usar preAuthorizedApplications la propiedad para autorizar a 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 ejemplo siguiente para esta propiedad:

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

    preAuthorizedApplications.appId se usa 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 la 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 identificador de la aplicación en la página de información general.

    Actualización de la dirección URL de redireccionamiento para la respuesta de autenticación

    Las direcciones URL de redireccionamiento se usan al devolver respuestas de autenticación como tokens después de la autenticación correcta. Puede personalizar las direcciones URL de redireccionamiento mediante la propiedad redirectUris dentro de web, spa. publicClient Por ejemplo, para agregar https://www.examples.com/auth-end.html como dirección URL de redireccionamiento, puede agregarla como el 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 Microsoft Entra los cambios de la aplicación para el entorno local o remoto.

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

      Captura de pantalla que muestra la vista previa.

    2. Seleccione entorno local o de desarrollo .

      Captura de pantalla que muestra la lista de entornos.

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

      Captura de pantalla que muestra la opción de implementación resaltada.

    4. Se implementan los cambios de Microsoft Entra aplicación que se usa en el entorno local o de desarrollo.

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

Me encontré con un problema

Microsoft Entra marcadores de posición de plantilla de manifiesto

El archivo de manifiesto Microsoft Entra contiene argumentos de marcador de posición con {{...}} instrucciones, 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 Microsoft Entra plantilla de manifiesto

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

Edición y vista previa Microsoft Entra manifiesto con CodeLens

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

Microsoft Entra archivo de plantilla de manifiesto

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 según el entorno.

Captura de pantalla que muestra la vista previa de agregar codelens.

CodeLens, argumento de marcador de posición

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

Captura de pantalla que muestra los argumentos de adición.

CodeLens de acceso a recursos necesario

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

Captura de pantalla que muestra el agregar recurso al acceso a recursos necesario.

CodeLens de aplicaciones preautorizadas

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

Ver Microsoft Entra aplicación en el Azure Portal

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

    Captura de pantalla que muestra el identificador de cliente.

    Nota:

    xxx en el identificador de cliente indica el nombre del entorno donde 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 Microsoft Entra mediante el identificador de cliente que copió antes.

    Captura de pantalla que muestra el identificador de cliente en la pestaña Todas las aplicaciones.

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

  5. En Microsoft Entra página de información de la aplicación, 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 obtener más información sobre el manifiesto, consulte Microsoft Entra manifiesto de aplicación.

    Captura de pantalla que muestra la pantalla Manifiesto.

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

Me encontré con un problema

Uso de una aplicación Microsoft Entra existente

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

Microsoft Entra aplicación en el ciclo de vida de desarrollo de aplicaciones de Teams

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

  1. Para crear un proyecto

    Puede crear un proyecto con Agents Toolkit que incluye 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 Creación de una nueva aplicación de Teams mediante Agents Toolkit. Se crea automáticamente un archivo de manifiesto Microsoft Entra en aad.template.json. Agents Toolkit 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 inicio de sesión único al bot o a la pestaña

    Después de crear una aplicación de Teams sin sso integrado, Agents Toolkit 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.json.

    Agents Toolkit 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

    Agents Toolkit realiza las siguientes funciones durante el desarrollo local:

    • Lea el .env.local archivo para buscar una aplicación Microsoft Entra existente. Si ya existe una aplicación Microsoft Entra, Agents Toolkit reutiliza la aplicación Microsoft Entra existente. De lo contrario, debe crear una nueva aplicación mediante 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 Microsoft Entra con el archivo de manifiesto.

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

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

  4. Para aprovisionar recursos en la nube

    Debe aprovisionar recursos en la nube e implementar la aplicación mientras mueve la aplicación a la nube. En fases, como la depuración local, Agents Toolkit:

    • Lee el .env.{env} archivo para buscar una aplicación Microsoft Entra existente. Si ya existe una aplicación Microsoft Entra, Agents Toolkit reutiliza la aplicación Microsoft Entra existente. De lo contrario, debe crear una nueva aplicación mediante el aad.template.json archivo .

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

    • Completa el aprovisionamiento de otros recursos, Microsoft Entra de la identifierUrisaplicación y redirectUris se actualizan según los puntos de conexión correctos.

  5. Para compilar la aplicación

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

    • Agents Toolkit 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 Microsoft Entra esquema de manifiesto.

    En la tabla siguiente se enumeran las propiedades que no se admiten en la extensión Agents Toolkit:

    Propiedades no admitidas Motivo
    passwordCredentials No permitido 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 las cadenas de nombre de aplicación de recursos legibles del usuario o nombre de permiso solo para Microsoft Graph las API y Office 365 SharePoint Online . Debe usar UUID para otras API. Siga estos pasos para recuperar los identificadores de Azure Portal:

    1. Registre una nueva aplicación 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 el permiso que necesita.
    4. Seleccione Manifest en la requiredResourceAccess propiedad , donde puede encontrar los identificadores de API y los permisos.

Vea también

  • Last updated on