Editar manifesto do Microsoft Entra

Artigo
06/24/2024

O Microsoft Teams Toolkit gere agora a aplicação Microsoft Entra com o ficheiro de manifesto da aplicação como a fonte de verdade durante o ciclo de vida de desenvolvimento de aplicações do Microsoft Teams.

Personalizar o modelo de manifesto do Microsoft Entra

Pode personalizar o modelo de manifesto do Microsoft Entra para atualizar a aplicação Microsoft Entra.

Abra aad.template.json no seu projeto.
Atualize o modelo diretamente ou referencie valores de outro ficheiro. Seguem-se os cenários de personalização:
Adicionar uma permissão de aplicação

Se a aplicação Teams necessitar de mais permissões para chamar uma API com permissões adicionais, terá de atualizar requiredResourceAccess a propriedade no modelo de manifesto do Microsoft Entra. 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 seguinte fornece IDs de propriedade diferentes e a respetiva utilização:
- A resourceAppId propriedade é utilizada para APIs diferentes. Para Microsoft Graph e Office 365 SharePoint Online, introduza o nome diretamente em vez de UUID e, para outras APIs, utilize UUID.
- A resourceAccess.id propriedade é utilizada para permissões diferentes. Para Microsoft Graph e Office 365 SharePoint Online, introduza o nome da permissão diretamente em vez de UUID e, para outras APIs, utilize UUID.
- A resourceAccess.type propriedade é utilizada para permissão delegada ou permissão de aplicação. Scope significa permissão delegada e Role significa permissão de aplicação.
Pré-autenticar uma aplicação cliente

Pode utilizar preAuthorizedApplications a propriedade para autorizar uma aplicação cliente a indicar que a API confia na aplicação. Os utilizadores não consentem quando o cliente chama a API exposta. Pode ver o seguinte exemplo para esta propriedade:
```
      "preAuthorizedApplications": [
      {
          "appId": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
          "permissionIds": [
               "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
           ]
      }
      ...
  ]
```
preAuthorizedApplications.appId a propriedade é utilizada para a aplicação que pretende autorizar. Se não souber o ID da aplicação e souber apenas o nome da aplicação, utilize os seguintes passos para procurar o ID da aplicação:
1. Aceda ao portal do Azure e abra Registos de Aplicações.
2. Selecione Todas as aplicações e procure o nome da aplicação.
3. Selecione o nome da aplicação e obtenha o ID da aplicação na página de descrição geral.
Atualizar o URL de redirecionamento para a resposta de autenticação

Os URLs de redirecionamento são utilizados ao devolver respostas de autenticação, como tokens após a autenticação com êxito. Pode personalizar URLs de redirecionamento com a propriedade replyUrlsWithType. Por exemplo, para adicionar https://www.examples.com/auth-end.html como URL de redirecionamento, pode adicioná-lo como o seguinte exemplo:
```
    "replyUrlsWithType": [
       ...
     {
         "url": "https://www.examples.com/auth-end.html",
         "type": "Spa"
     }
]
```
Atualize as alterações da aplicação Microsoft Entra para o ambiente local ou remoto.
1. Selecione Preview CodeLens em aad.template.json.
2. Selecione ambiente local ou dev .
3. Selecione Deploy Azure AD Manifest CodeLens em aad.local.json ou aad.dev.json.
4. As alterações à aplicação Microsoft Entra utilizadas no ambiente local ou dev são implementadas.
5. Além disso, pode abrir a paleta de comandos e selecionar Teams: Atualizar a Aplicação Microsoft Entra para atualizar a aplicação Microsoft Entra.

Marcadores de posição do modelo de manifesto do Microsoft Entra

O ficheiro de manifesto do Microsoft Entra contém argumentos de marcador de posição com {{...}} as instruções são substituídas durante a compilação para diferentes ambientes. Pode fazer referência a variáveis de ambiente com os argumentos de marcador de posição.

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

Não precisa de introduzir valores permanentes no modelo de manifesto do Microsoft Entra e o ficheiro de modelo de manifesto do Microsoft Entra suporta valores variáveis de ambiente de referência. Pode utilizar a sintaxe ${{YOUR_ENV_VARIABLE_NAME}} na ferramenta como valores de parâmetros para resolver os valores das variáveis de ambiente.

Editar e pré-visualizar o manifesto do Microsoft Entra com o CodeLens

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

Ficheiro de modelo de manifesto do Microsoft Entra

Existe uma pré-visualização do CodeLens no início do ficheiro de modelo de manifesto do Microsoft Entra. Selecione o CodeLens para gerar um manifesto do Microsoft Entra com base no seu ambiente.

Captura de ecrã a mostrar a pré-visualização de adicionar codelens.

Argumento de marcador de posição CodeLens

O argumento de marcador de posição CodeLens ajuda-o a ver os valores da depuração local e a desenvolver o seu ambiente. Se pairar o rato sobre o argumento marcador de posição, este mostra a caixa de descrição para os valores de todos os ambientes.

Captura de ecrã a mostrar os argumentos de adição.

CodeLens de acesso a recursos necessário

O modelo de manifesto do Microsoft Entra no Teams Toolkit também suporta cadeias legíveis pelo utilizador para Microsoft Graph permissões e Office 365 SharePoint Online . O esquema de manifesto oficial do Microsoft Entra, que é o resourceAppId e resourceAccess na requiredResourceAccess propriedade suporta apenas o UUID. Se introduzir UUID, o CodeLens mostra cadeias legíveis pelo utilizador, caso contrário, mostra o UUID.

Captura de ecrã a mostrar a adição de recursos ao acesso necessário aos recursos.

CodeLens de aplicações pré-autenticadas

O CodeLens mostra o nome da aplicação para o ID da aplicação pré-autorizado da preAuthorizedApplications propriedade .

Ver a aplicação Microsoft Entra no portal do Azure

Copie o ID de cliente da aplicação Microsoft Entra do .env.xxx ficheiro () na AAD_APP_CLIENT_ID propriedade .

Observação

xxx no ID de cliente indica o nome do ambiente onde implementou a aplicação Microsoft Entra.
Aceda ao portal do Azure e inicie sessão na conta do Microsoft 365.

Observação

Certifique-se de que as credenciais de início de sessão da aplicação Teams e da conta M365 são as mesmas.
Abra a página Registos de Aplicações e pesquise na aplicação Microsoft Entra com o ID de cliente que copiou anteriormente.
Selecione a aplicação Microsoft Entra no resultado da pesquisa para ver as informações detalhadas.
Na página de informações da aplicação Microsoft Entra, selecione o menu Manifesto para ver o manifesto desta aplicação. O esquema do manifesto é igual ao aad.template.json do ficheiro. Para obter mais informações sobre o manifesto, veja Manifesto da aplicação Microsoft Entra.
Pode selecionar Outro Menu para ver ou configurar a aplicação Microsoft Entra através do respetivo portal.

Utilizar uma aplicação Microsoft Entra existente

Pode utilizar a aplicação Microsoft Entra existente para o projeto teams. Para obter mais informações, consulte Utilizar uma aplicação Microsoft Entra existente para a sua aplicação Teams.

Ciclo de vida de desenvolvimento de aplicações da aplicação Microsoft Entra no Teams

Tem de interagir com a aplicação Microsoft Entra durante várias fases do ciclo de vida de desenvolvimento de aplicações do Teams.

Para criar o Project

Pode criar um projeto com o Teams Toolkit que vem com suporte de início de sessão único (SSO) por predefinição, como SSO-enabled tab. Para obter mais informações sobre como criar uma nova aplicação, consulte Criar uma nova aplicação do Teams com o Teams Toolkit. É criado automaticamente um ficheiro de manifesto do Microsoft Entra no aad.template.json. O Teams Toolkit cria ou atualiza a aplicação Microsoft Entra durante o desenvolvimento local ou enquanto move a aplicação para a cloud.
Para adicionar o SSO ao bot ou separador

Depois de criar uma aplicação do Teams sem o SSO incorporado, o Teams Toolkit ajuda-o progressivamente a adicionar o SSO ao projeto. Como resultado, é criado automaticamente um ficheiro de manifesto do Microsoft Entra no aad.template.json.

O Teams Toolkit cria ou atualiza a aplicação Microsoft Entra durante a próxima sessão de desenvolvimento local ou enquanto move a aplicação para a cloud.
Para criar localmente

O Teams Toolkit executa as seguintes funções durante o desenvolvimento local:
- Leia o .env.local ficheiro para localizar uma aplicação Microsoft Entra existente. Se já existir uma aplicação Microsoft Entra, o Toolkit do Teams reutiliza a aplicação Microsoft Entra existente. Caso contrário, terá de criar uma nova aplicação com o aad.template.json ficheiro .
- Inicialmente, ignora algumas propriedades no ficheiro de manifesto que requerem mais contexto, como replyUrls a propriedade que requer um ponto final de desenvolvimento local durante a criação de uma nova aplicação Microsoft Entra com o ficheiro de manifesto.
- Depois de o ambiente de desenvolvimento local ser iniciado com êxito, as propriedades , replyUrlse outras propriedades da identifierUrisaplicação Microsoft Entra que não estão disponíveis durante a fase de criação são atualizadas em conformidade.
- As alterações que fez à sua aplicação Microsoft Entra são carregadas durante a próxima sessão de desenvolvimento local. Pode ver as alterações da aplicação Microsoft Entra aplicadas manualmente.
Para aprovisionar recursos na cloud

Tem de aprovisionar recursos na cloud e implementar a sua aplicação ao mover a sua aplicação para a cloud. Em fases, como a depuração local, o Teams Toolkit:
- Lê o .env.{env} ficheiro para encontrar uma aplicação Microsoft Entra existente. Se já existir uma aplicação Microsoft Entra, o Toolkit do Teams reutiliza a aplicação Microsoft Entra existente. Caso contrário, terá de criar uma nova aplicação com o aad.template.json ficheiro .
- Ignora algumas propriedades no ficheiro de manifesto inicialmente que requerem mais contexto, como replyUrls propriedade. Esta propriedade requer um ponto final de front-end ou bot durante a criação de uma nova aplicação Microsoft Entra com o ficheiro de manifesto.
- Conclui o aprovisionamento de outros recursos e, em seguida, o da identifierUrisaplicação Microsoft Entra e replyUrls é atualizado de acordo com os pontos finais corretos.
Para criar a aplicação
- O comando da cloud implementa a sua aplicação nos recursos aprovisionados. Não inclui a implementação de alterações à aplicação Microsoft Entra efetuadas.
- O Teams Toolkit atualiza a aplicação Microsoft Entra de acordo com o ficheiro de modelo de manifesto do Microsoft Entra.

Limitações

A extensão do Teams Toolkit não suporta todas as propriedades listadas no esquema de manifesto do Microsoft Entra.

A tabela seguinte lista as propriedades que não são suportadas na extensão do Teams Toolkit:

Propriedades não suportadas	Motivo
`passwordCredentials`	Não permitido no manifesto
`createdDateTime`	Só de leitura e não pode alterar
`logoUrl`	Só de leitura e não pode alterar
`publisherDomain`	Só de leitura e não pode alterar
`oauth2RequirePostResponse`	Não existe na Graph API
`oauth2AllowUrlPathMatching`	Não existe na Graph API
`samlMetadataUrl`	Não existe na Graph API
`orgRestrictions`	Não existe na Graph API
`certification`	Não existe na Graph API

A requiredResourceAccess propriedade é utilizada para o nome de aplicação de recurso legível pelo utilizador ou para cadeias de nome de permissão apenas para Microsoft Graph apIs e Office 365 SharePoint Online . Tem de utilizar o UUID para outras APIs. Execute os seguintes passos para obter IDs do portal do Azure:
1. Registe uma nova aplicação Microsoft Entra no portal do Azure.
2. Selecione API permissions a partir da página da aplicação Microsoft Entra.
3. Selecione add a permission para adicionar a permissão de que precisa.
4. Selecione Manifest a requiredResourceAccess partir da propriedade, onde pode encontrar os IDs da API e as permissões.

Partilhar via