Utilizar a aplicação Entra existente no TeamsFx

Esta secção explica como ligar Microsoft Entra ID ao seu projeto TeamsFx, quer através de um registo de aplicações Entra existente, quer através da criação de um novo. Siga os passos para definir as definições de autenticação necessárias e os valores do TeamsFx antes de executar ou implementar o seu agente ou aplicação.

Criar uma aplicação Microsoft Entra

1. Aceda à portal do Azure e selecione Microsoft Entra ID.

2. Selecione Registos de Aplicações>Novo registo para criar uma nova aplicação Microsoft Entra. Adicione os seguintes detalhes:

   1. Nome: o nome da sua aplicação de configuração.
   2. Tipos de conta suportados: selecione Conta apenas neste diretório organizacional.
   3. Deixe o campo URL de Redirecionamento em branco por enquanto.
   4. Selecione Registrar.

3. Depois de a aplicação ser registada, será reenen consolidou com a respetiva página Descrição geral . Copie o ID da Aplicação (cliente), o ID do Objeto e o ID do Diretório (inquilino) para utilização posterior. Verifique se os Tipos de conta suportados estão definidos como Apenas a minha organização.

Criar segredo do cliente para Microsoft Entra aplicação (opcional)

1. Aceda à página Certificados & segredos da aplicação, selecione Segredo do Cliente e selecione Novo segredo do cliente. Selecione os seguintes detalhes:

   1. Descrição: a descrição do segredo do cliente.
   2. Expira: a hora de expiração do segredo do cliente.
   3. Selecione Adicionar.

2. Quando o segredo do cliente for adicionado, prima o botão copiar na coluna Valor para copiar o Segredo do Cliente.

Criar acesso como âmbito de utilizador para Microsoft Entra aplicação (opcional)

1. Aceda à página Expor uma API da aplicação, selecione Adicionar um âmbito em Âmbitos definidos por esta API e siga os passos indicados:

   1. Selecione Salvar e continuar.
   2. Nome do âmbito: preencha access_as_user.
   3. Quem pode consentir?: Selecione Administradores e utilizadores.
   4. Administração o nome a apresentar do consentimento: o Teams pode aceder às APIs Web da aplicação.
   5. Administração descrição do consentimento: Preencher permite que o Teams chame as APIs Web da aplicação como o utilizador atual.
   6. Nome a apresentar do consentimento do utilizador: o Teams pode aceder às APIs Web da aplicação e fazer pedidos em seu nome.
   7. Descrição do consentimento do utilizador: preencha Ativar o Teams para chamar as APIs Web desta aplicação com os mesmos direitos que tem.
   8. Estado: selecione Ativado.
   9. Selecione Adicionar escopo.

2. Na mesma página, selecione Adicionar uma aplicação cliente em Aplicações cliente autorizadas e adicione os seguintes detalhes:

   1. ID de Cliente: preencha 1fec8e78-bce4-4aaf-ab1b-5451cc387264 , que é o ID de Cliente do Microsoft Teams em dispositivos móveis e cliente.
   2. Âmbitos autorizados: selecione o âmbito de access_as_user existente.
   3. Selecione Adicionar aplicativo.

3. Selecione Adicionar uma aplicação cliente e adicione os detalhes:

   1. ID de Cliente: preencha 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 , que é o ID de Cliente do Teams na Web.
   2. Âmbitos autorizados: selecione o âmbito de access_as_user existente.
   3. Selecione Adicionar aplicativo.

4. Aceda à página Manifesto da aplicação, copie o ID em oauth2Permissions como ID de Âmbito de Utilizador do Access As.

Obter informações da aplicação Microsoft Entra existente

Se já tiver uma aplicação Azure registada, pode reutilizá-la no seu projeto TeamsFx em vez de criar um novo registo. Antes de começar, capture os valores de configuração necessários do registo de aplicações existente para que possa adicioná-los ao seu projeto TeamsFx.

1. Aceda à portal do Azure e selecione Microsoft Entra ID.

2. Selecione Registos de Aplicações e localize a sua aplicação Microsoft Entra existente.

3. Aceda à página Descrição Geral da aplicação, copie o ID da Aplicação (cliente), o ID do Objeto e o ID do Diretório (inquilino) da aplicação; é necessário mais tarde.

4. Verifique se os Tipos de conta suportados estão definidos como Apenas a minha organização.

5. Aceda à página Descrição Geral da aplicação, copie o ID da Aplicação (cliente), o ID do Objeto e o ID do Diretório (inquilino) para utilização posterior. Verifique se os Tipos de conta suportados estão definidos como Apenas a minha organização.

6. Aceda à página Certificados & segredos da aplicação, prima o botão copiar na coluna Valor para copiar o Segredo do Cliente.

   Observação

   Se não conseguir copiar o segredo, siga as instruções para criar um novo segredo do cliente.

7. Aceda à página Expor uma API da aplicação . Se o âmbito de access_as_user já estiver definido e os dois IDs de cliente do Teams estiverem pré-autorizados, abra o Manifesto e copie o valor do ID em oauth2Permissions e introduza-o como o ID de Âmbito do Acesso Como Utilizador.

Definir informações da aplicação Entraa no projeto TeamsFx

Adicione as informações que guardou a partir da aplicação Microsoft Entra ao projeto TeamsFx.

1. Abra m365agents.yml e localize a ação aadApp/create .

2. Localize os nomes das variáveis de ambiente que armazenam informações para Microsoft Entra aplicação na writeToEnvironmentFile propriedade . Seguem-se as definições predefinidas writeToenvironmentFile se criar projetos com o Toolkit de Agentes do Microsoft 365 (anteriormente conhecido como Toolkit do Teams):

    writeToEnvironmentFile:
      clientId: AAD_APP_CLIENT_ID
      clientSecret: SECRET_AAD_APP_CLIENT_SECRET
      objectId: AAD_APP_OBJECT_ID
      tenantId: AAD_APP_TENANT_ID
      authority: AAD_APP_OAUTH_AUTHORITY
      authorityHost: AAD_APP_OAUTH_AUTHORITY_HOST
   

3. Adicione valores para cada variável de ambiente do passo 2.

   1. Adicione as seguintes variáveis de ambiente e os respetivos valores ao env\.env.{env} ficheiro.

      AAD_APP_CLIENT_ID=<value of Microsoft Entra application's client id (application id)> # example: 00000000-0000-0000-0000-000000000000
      AAD_APP_OBJECT_ID=<value of Microsoft Entra application's object id> # example: 00000000-0000-0000-0000-000000000000
      AAD_APP_TENANT_ID=<value of Microsoft Entra's (tenant) id> # example: 00000000-0000-0000-0000-000000000000
      AAD_APP_OAUTH_AUTHORITY=<value of Microsoft Entra's authority> # example: https://login.microsoftonline.com/<Directory (tenant) ID>
      AAD_APP_OAUTH_AUTHORITY_HOST=<host of Microsoft Entra's authority> # example: https://login.microsoftonline.com
      AAD_APP_ACCESS_AS_USER_PERMISSION_ID=<id of access_as_user permission> # example: 00000000-0000-0000-0000-000000000000
      

      AAD_APP_OAUTH_AUTHORITY_HOSTé o Microsoft Entra anfitrião de autoridade (por exemplo, https://login.microsoftonline.com) que o agente ou bot utiliza como o ponto final de início de sessão OAuth 2.0. Para pontos finais específicos do ambiente, veja Microsoft Entra pontos finais de autenticação.

   2. Se o agente ou a aplicação precisar de um segredo do cliente da aplicação Microsoft Entra, adicione a seguinte variável de ambiente e o respetivo valor ao env\.env.{env}.user ficheiro.

      SECRET_AAD_APP_CLIENT_SECRET=<value of Microsoft Entra application's client secret>
      

      Observação

      Lembre-se de atualizar os nomes das variáveis de ambiente indicados nos exemplos se utilizar nomes diferentes no writeToEnvironmentFile.

4. Abra a extensão Do Toolkit de Agentes e selecione Aprovisionar na cloud. Aguarde até que o projeto seja aprovisionado com êxito.

Carregar Microsoft Entra manifesto da aplicação para portal do Azure

Se o Toolkit de Agentes não atualizar a aplicação Microsoft Entra, é apresentada uma mensagem de erro:

Insufficient privileges to complete the operation.

Se vir esta mensagem, atualize Microsoft Entra permissão da aplicação e siga as instruções para atualizar a permissão.

1. Localize o manifesto da aplicação Microsoft Entra em build/aad.manifest.{env}.json.

2. Copie o conteúdo do ficheiro de manifesto.

3. Aceda à portal do Azure e selecione Microsoft Entra ID.

4. Selecione Registos de Aplicações e localize a sua aplicação Microsoft Entra existente.

5. Aceda à página Manifesto da aplicação, cole o conteúdo do manifesto no editor e selecione Guardar para guardar as alterações.

Confira também

• Criar o seu primeiro agente
• Criar um novo aplicativo do Teams