Compartir a través de

Edición del manifiesto de Microsoft Entra

  • Artículo

Microsoft Teams Toolkit ahora administra la aplicación Microsoft Entra 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 la plantilla de manifiesto de Microsoft Entra

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

  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 de Teams requiere más permisos para llamar a una API con permisos adicionales, debe actualizar requiredResourceAccess la propiedad en la plantilla de manifiesto 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:

    
      "preAuthorizedApplications": [
      {
          "appId": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
          "permissionIds": [
               "${{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 replyUrlsWithType. Por ejemplo, para agregar https://www.examples.com/auth-end.html como dirección URL de redireccionamiento, puede agregarla como el ejemplo siguiente:

        "replyUrlsWithType": [
       ...
     {
         "url": "https://www.examples.com/auth-end.html",
         "type": "Spa"
     }
]

  3. Actualice los cambios de la aplicación Microsoft Entra 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 la aplicación Microsoft Entra usada en el entorno local o de desarrollo.

    5. Además, puede abrir la paleta de comandos y seleccionar Teams: Update Microsoft Entra App para actualizar la aplicación Microsoft Entra. Captura de pantalla que 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 {{...}} 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 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 de variables 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 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 versión preliminar de CodeLens al principio del archivo de plantilla de manifiesto de Microsoft Entra. Seleccione CodeLens para generar un manifiesto de Microsoft Entra según su 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

La plantilla de manifiesto de Microsoft Entra en teams Toolkit también admite cadenas legibles para el usuario y Microsoft GraphOffice 365 SharePoint Online permisos. El esquema de manifiesto oficial de Microsoft Entra, 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 para la preAuthorizedApplications propiedad .

Visualización de la aplicación Microsoft Entra en 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 La aplicación Microsoft Entra en el resultado de la búsqueda para ver la información detallada.

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

    Captura de pantalla que muestra la pantalla Manifiesto.

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

Uso de una aplicación de Microsoft Entra existente

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

Ciclo de vida de desarrollo de aplicaciones de Microsoft Entra en Teams

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

  1. Para crear un proyecto

    Puede crear un proyecto con El kit de herramientas de Teams 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 el kit de herramientas de Teams. Se crea automáticamente un archivo de manifiesto de Microsoft Entra en aad.template.json. Teams 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, Teams 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.

    Teams 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

    Teams 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, Teams 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 replyUrls 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, las propiedades , replyUrlsy otras propiedades de la aplicación identifierUrisMicrosoft Entra 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 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 mueve la aplicación a la nube. En fases, como la depuración local, Teams Toolkit:

    • Lee el .env.{env} archivo para buscar una aplicación Microsoft Entra existente. Si ya existe una aplicación Microsoft Entra, Teams 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 replyUrls 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, a continuación, la identifierUrisaplicación Microsoft Entra y replyUrls se actualiza 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 de los cambios de aplicación de Microsoft Entra que ha realizado.

    • Teams Toolkit actualiza la aplicación Microsoft Entra según el archivo de plantilla de manifiesto de Microsoft Entra.

Limitaciones

  1. La extensión kit de herramientas de Teams no admite todas las propiedades enumeradas en el esquema de manifiesto de Microsoft Entra.

    En la tabla siguiente se enumeran las propiedades que no se admiten en la extensión del kit de herramientas de Teams:

    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
    oauth2RequirePostResponse No existe en Graph API
    oauth2AllowUrlPathMatching No existe en Graph API
    samlMetadataUrl No existe en Graph API
    orgRestrictions No existe en Graph API
    certification No existe en Graph API

  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