Editar manifesto do Microsoft Entra

O Microsoft 365 Agents Toolkit (anteriormente conhecido como Teams Toolkit) agora gerencia o aplicativo Microsoft Entra com o arquivo de manifesto do aplicativo como a fonte da verdade durante o ciclo de vida de desenvolvimento do aplicativo Microsoft Teams.

Personalizar o modelo de manifesto do Microsoft Entra

Você pode personalizar o modelo de manifesto do Microsoft Entra para atualizar o aplicativo do Microsoft Entra.

  1. Abra aad.template.json no seu projeto.

    A captura de tela mostra o modelo.

  2. Atualize o modelo diretamente ou faça referência a valores de outro arquivo. A seguir estão os cenários de personalização:

    Adicionar uma permissão de aplicativo

    Se o aplicativo Teams exigir mais permissões para chamar uma API com permissões adicionais, você precisará atualizar requiredResourceAccess a propriedade no modelo de manifesto do Microsoft Entra. Você pode ver o seguinte exemplo para esta propriedade:

    "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"
            }
        ]
    }
]

    A lista a seguir fornece diferentes IDs de propriedade e seu uso:

    • A resourceAppId propriedade é usada para diferentes APIs. Para Microsoft Graph e Office 365 SharePoint Online, insira o nome diretamente em vez de UUID e, para outras APIs, use UUID.

    • A resourceAccess.id propriedade é usada para diferentes permissões. Para Microsoft Graph e Office 365 SharePoint Online, insira o nome da permissão diretamente em vez de UUID e, para outras APIs, use UUID.

    • A resourceAccess.type propriedade é usada para permissão delegada ou permissão de aplicativo. Scope significa permissão delegada e Role significa permissão do aplicativo.

    Pré-autorizar um aplicativo cliente

    Você pode usar preAuthorizedApplications a propriedade para autorizar um aplicativo cliente para indicar que a API confia no aplicativo. Os usuários não consentem quando o cliente chama a API exposta. Você pode ver o seguinte exemplo para esta propriedade:

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

    preAuthorizedApplications.appId é usada para o aplicativo que você deseja autorizar. Se você não souber a ID do aplicativo e souber apenas o nome do aplicativo, use as seguintes etapas para pesquisar a ID do aplicativo:

    1. Acesse o portal do Azure e abra Registros de Aplicativo.

    2. Selecione Todos os aplicativos e procure pelo nome do aplicativo.

    3. Selecione o nome do aplicativo e obtenha a ID do aplicativo na página de visão geral.

    Atualizar a URL de redirecionamento para resposta de autenticação

    As URLs de redirecionamento são usadas ao retornar respostas de autenticação, como tokens, após a autenticação bem-sucedida. Você pode personalizar URLs de redirecionamento usando a propriedade redirectUris dentro de web, spa, publicClient. Por exemplo, para adicionar https://www.examples.com/auth-end.html como URL de redirecionamento, você pode adicioná-la como o seguinte exemplo:

    "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. Atualizar as alterações do aplicativo Microsoft Entra para ambiente local ou remoto.

    1. Selecione Preview CodeLens em aad.template.json.

      A captura de tela mostra a visualização.

    2. Selecione o ambiente local ou de desenvolvimento .

      A captura de tela mostra a lista de ambientes.

    3. Selecione Deploy Azure AD Manifest CodeLens em aad.local.json ou aad.dev.json.

      A captura de tela mostra a opção de implantação realçada.

    4. As alterações para o aplicativo Microsoft Entra usado no ambiente local ou de desenvolvimento são implantadas.

    5. Além disso, você pode abrir a paleta de comandos e selecionar Teams: Atualizar o aplicativo Microsoft Entra para atualizar o aplicativo Microsoft Entra. A captura de tela mostra a opção Paleta de Comandos.

Tive um problema

Espaços reservados de modelo de manifesto do Microsoft Entra

O arquivo de manifesto do Microsoft Entra contém argumentos de espaço reservado com {{...}} da Microsoft, ela é substituída durante o build para ambientes diferentes. Você pode fazer referência a variáveis de ambiente com os argumentos de espaço reservado.

Variável de ambiente de referência no modelo de manifesto do Microsoft Entra

Você não precisa inserir valores permanentes no modelo de manifesto do Microsoft Entra e o arquivo de modelo de manifesto do Microsoft Entra dá suporte a valores de variáveis de ambiente de referência. Você pode usar a sintaxe ${{YOUR_ENV_VARIABLE_NAME}} na ferramenta como valores de parâmetro para resolver os valores da variável de ambiente.

Editar e visualizar o manifesto do Microsoft Entra com o CodeLens

O arquivo de modelo de manifesto do Microsoft Entra tem o CodeLens para revisar e editar o código.

Arquivo de modelo de manifesto do Microsoft Entra

Há uma visualização do CodeLens no início do arquivo de modelo de manifesto do Microsoft Entra. Selecione o CodeLens para gerar um manifesto do Microsoft Entra com base no seu ambiente.

A captura de tela mostra a versão prévia do add codelens.

Argumento de espaço reservado CodeLens

Argumento de espaço reservado O CodeLens ajuda você a ver os valores para depuração local e desenvolver seu ambiente. Se você passar o mouse sobre o argumento de espaço reservado, ele mostrará a caixa de dica de ferramenta para os valores de todos os ambientes.

A captura de tela mostra os argumentos adicionar.

Acesso necessário ao recurso CodeLens

O modelo de manifesto do Microsoft Entra no Kit de Ferramentas de Agentes também dá suporte a cadeias de caracteres legíveis do usuário para Microsoft Graph e Office 365 SharePoint Online permissões. O esquema de manifesto oficial do Microsoft Entra, que é a resourceAppId propriedade and resourceAccess inrequiredResourceAccess, suporta apenas o UUID. Se você inserir UUID, o CodeLens mostrará cadeias de caracteres legíveis pelo usuário, caso contrário, mostrará o UUID.

A captura de tela mostra adicionar recurso ao acesso necessário ao recurso.

Aplicativos pré-autorizados CodeLens

O CodeLens mostra o nome do aplicativo para a ID do aplicativo pré-autorizado para a propriedade dentro da preAuthorizedApplications propriedade da API.

Exibir o aplicativo Microsoft Entra no portal do Azure

  1. Copie a ID do cliente do aplicativo Microsoft Entra do .env.xxx arquivo () na AAD_APP_CLIENT_ID propriedade.

    A captura de tela mostra a ID do cliente.

    Observação

    xxx na ID do cliente indica o nome do ambiente em que você implantou o aplicativo Microsoft Entra.

  2. Acesse o portal do Azure e entre na conta do Microsoft 365.

    Observação

    Certifique-se de que as credenciais de logon do aplicativo Teams e da conta do M365 sejam as mesmas.

  3. Abra a página Registros de Aplicativo e pesquise o aplicativo Microsoft Entra usando a ID do cliente que você copiou antes.

    A captura de tela mostra a ID do cliente na guia Todos os aplicativos.

  4. Selecione o aplicativo Microsoft Entra no resultado da pesquisa para exibir as informações detalhadas.

  5. Na página de informações do aplicativo Microsoft Entra, selecione o menu Manifesto para exibir o manifesto deste aplicativo. O esquema do manifesto é o mesmo que o aad.template.json do arquivo. Para obter mais informações sobre o manifesto, confira Manifesto do aplicativo Microsoft Entra.

    A captura de tela mostra a tela Manifesto.

  6. Você pode selecionar Outro Menu para exibir ou configurar o aplicativo Microsoft Entra por meio de seu portal.

Tive um problema

Usar um aplicativo existente do Microsoft Entra

Você pode usar o aplicativo Microsoft Entra existente para o projeto do Teams. Para obter mais informações, consulte Usar um aplicativo do Microsoft Entra existente para seu aplicativo do Teams.

Aplicativo Microsoft Entra no ciclo de vida de desenvolvimento de aplicativos do Teams

Você precisa interagir com o aplicativo Microsoft Entra durante vários estágios do ciclo de vida de desenvolvimento do aplicativo Teams.

  1. Para criar um Projeto

    Você pode criar um projeto com o Agents Toolkit que vem com suporte a logon único (SSO) por padrão, como SSO-enabled tab. Para obter mais informações sobre como criar um novo aplicativo, consulte criar um novo aplicativo do Teams usando o Kit de Ferramentas de Agentes. Um arquivo de manifesto do Microsoft Entra é criado automaticamente no aad.template.jsonformato . O Agents Toolkit cria ou atualiza o aplicativo Microsoft Entra durante o desenvolvimento local ou enquanto você move o aplicativo para a nuvem.

  2. Para adicionar SSO ao seu bot ou guia

    Depois de criar um aplicativo do Teams sem o SSO interno, o Agents Toolkit ajuda você a adicionar o SSO progressivamente ao projeto. Como resultado, um arquivo de manifesto do Microsoft Entra é criado automaticamente no aad.template.jsonformato .

    O Agents Toolkit cria ou atualiza o aplicativo Microsoft Entra durante a próxima sessão de desenvolvimento local ou enquanto você move o aplicativo para a nuvem.

  3. Para compilar localmente

    O Agents Toolkit executa as seguintes funções durante o desenvolvimento local:

    • Leia o .env.local arquivo para encontrar um aplicativo do Microsoft Entra existente. Se já existir um aplicativo do Microsoft Entra, o Agents Toolkit reutiliza o aplicativo do Microsoft Entra existente. Caso contrário, você precisará criar um novo aplicativo usando o aad.template.json arquivo.

    • Inicialmente, ignora algumas propriedades no arquivo de manifesto que exigem mais contexto, como redirectUris a propriedade que requer um ponto de extremidade de desenvolvimento local durante a criação de um novo aplicativo Microsoft Entra com o arquivo de manifesto.

    • Depois que o ambiente de desenvolvimento local for iniciado com êxito, o , do identifierUrisredirectUrisaplicativo do Microsoft Entra e outras propriedades que não estiverem disponíveis durante o estágio de criação serão atualizados de acordo.

    • As alterações feitas no aplicativo do Microsoft Entra são carregadas durante a próxima sessão de desenvolvimento local. Você pode ver as alterações do aplicativo Microsoft Entra aplicadas manualmente.

  4. Para provisionar recursos de nuvem

    Você precisa provisionar recursos de nuvem e implantar seu aplicativo enquanto move seu aplicativo para a nuvem. Em estágios, como depuração local, Kit de Ferramentas de Agentes:

    • Lê o .env.{env} arquivo para encontrar um aplicativo do Microsoft Entra existente. Se já existir um aplicativo do Microsoft Entra, o Agents Toolkit reutiliza o aplicativo do Microsoft Entra existente. Caso contrário, você precisará criar um novo aplicativo usando o aad.template.json arquivo.

    • Ignora inicialmente algumas propriedades no arquivo de manifesto que exigem mais contexto, como redirectUris propriedade. Esta propriedade requer front-end ou ponto de extremidade de bot durante a criação de um novo aplicativo do Microsoft Entra com o arquivo de manifesto.

    • Conclui a provisão de outros recursos, o aplicativo identifierUrisdo Microsoft Entra e redirectUris são atualizados de acordo com os pontos de extremidade corretos.

  5. To build application

    • O comando cloud implanta seu aplicativo nos recursos provisionados. Isso não inclui implantar as alterações feitas no aplicativo do Microsoft Entra.

    • O Agents Toolkit atualiza o aplicativo do Microsoft Entra de acordo com o arquivo de modelo de manifesto do Microsoft Entra.

Limitações

  1. A extensão do Kit de Ferramentas de Agentes não dá suporte a todas as propriedades listadas no esquema de manifesto do Microsoft Entra.

    A tabela a seguir lista as propriedades que não têm suporte na extensão Kit de Ferramentas de Agentes:

    Propriedades não suportadas Motivo
    passwordCredentials Não permitido no manifesto
    createdDateTime Somente leitura e não pode ser alterado
    logoUrl Somente leitura e não pode ser alterado
    publisherDomain Somente leitura e não pode ser alterado

  2. A requiredResourceAccess propriedade é usada para o nome do aplicativo de recurso legível pelo usuário ou cadeias de caracteres de nome de permissão somente para Microsoft GraphOffice 365 SharePoint Online e APIs. Você precisa usar o UUID para outras APIs. Execute as seguintes etapas para recuperar IDs do portal do Azure:

    1. Registre um novo aplicativo do Microsoft Entra no portal do Azure.
    2. Selecione API permissions na página do aplicativo Microsoft Entra.
    3. Selecione add a permission para adicionar a permissão necessária.
    4. Selecione Manifest na requiredResourceAccess propriedade, onde você pode encontrar as IDs da API e as permissões.

Confira também

  • Last updated on