Configurar seu aplicativo de guia no Microsoft Entra ID

Microsoft Entra ID fornece acesso ao aplicativo de guia com base na identidade do teams do usuário do aplicativo. Registre seu aplicativo de guia com Microsoft Entra ID para que o usuário do aplicativo que entrou no Teams possa ter acesso ao aplicativo de guias.

Habilitar o SSO em Microsoft Entra ID

Registrar seu aplicativo de guia no Microsoft Entra ID e habilitá-lo para SSO requer a criação de configurações de aplicativo, como gerar ID do aplicativo, definir escopo de API e pré-autenticar IDs do cliente para aplicativos confiáveis.

Crie um novo registro de aplicativo no Microsoft Entra ID e exponha sua API (Web) usando escopos (permissões). Configure uma relação de confiança entre a API exposta em Microsoft Entra ID e seu aplicativo. Ele permite que o Cliente do Teams obtenha um token de acesso em nome do seu aplicativo e do usuário conectado. Você pode adicionar IDs de cliente para aplicativos móveis, desktop e Web confiáveis que você deseja pré-autenticar.

Você também pode precisar configurar outros detalhes, como autenticar usuários de aplicativo na plataforma ou dispositivo em que deseja direcionar seu aplicativo de guia.

Há suporte apenas para API do Graph no nível do usuário, ou seja, email, perfil, offline_access, OpenId. Se você precisar de acesso a outros escopos do Graph, como User.Read ou Mail.Read, consulte obter um token de acesso com permissões do Graph.

Microsoft Entra configuração habilita o SSO para seu aplicativo de guia no Teams. Ele responde com um token de acesso para validar o usuário do aplicativo.

Antes de configurar seu aplicativo

É útil se você aprender sobre a configuração para registrar seu aplicativo em Microsoft Entra ID de antemão. Verifique se você se preparou para configurar os seguintes detalhes antes de registrar seu aplicativo:

• Opções únicas ou multilocatários: seu aplicativo será usado apenas no locatário do Microsoft 365 em que está registrado ou muitos locatários do Microsoft 365 o usarão? Os aplicativos gravados para uma empresa normalmente são de locatário único. Os aplicativos escritos por um fornecedor de software independente e usados por muitos clientes precisam ser multilocatários para que o locatário de cada cliente possa acessar o aplicativo.
• URI de ID de aplicativo: é um URI globalmente exclusivo que identifica a API Web que você expõe para o acesso do seu aplicativo por meio de escopos. Ele também é conhecido como URI de identificador. O URI da ID do aplicativo inclui a ID do aplicativo e o subdomínio em que seu aplicativo está hospedado. O nome de domínio do seu aplicativo e o nome de domínio que você registra para seu aplicativo Microsoft Entra devem ser os mesmos. Atualmente, não há suporte para vários domínios por aplicativo.
• Escopo: é a permissão que um usuário de aplicativo autorizado ou seu aplicativo pode receber para acessar um recurso exposto pela API.

Observação

• Aplicativos personalizados criados para sua organização (aplicativos LOB): aplicativos personalizados criados para sua organização (aplicativos LOB) são internos ou específicos em sua organização ou empresa. Sua organização pode disponibilizar esses aplicativos por meio da Microsoft Store.
• Aplicativos de propriedade do cliente: o SSO também tem suporte para aplicativos de propriedade do cliente dentro dos locatários do Azure AD B2C.

Para criar e configurar seu aplicativo no Microsoft Entra ID para habilitar o SSO:

• Configure o escopo para o token de acesso.
• Configure a versão do token de acesso.

Configurar seu aplicativo no Microsoft Entra ID

Você pode configurar seu aplicativo de guia no Microsoft Entra ID para configurar o escopo e as permissões para tokens de acesso.

Registre seu aplicativo no Microsoft Entra ID e configure o locatário e a plataforma do aplicativo, antes de habilitá-lo para SSO. Microsoft Entra ID gera uma nova ID do aplicativo que você deve observar. Você precisa atualizá-lo mais tarde no manifesto do aplicativo (anteriormente chamado de manifesto do aplicativo teams).

Observação

O Microsoft Teams Toolkit registra o aplicativo Microsoft Entra em um projeto SSO. Você pode ignorar esta seção se tiver usado o Teams Toolkit para criar seu aplicativo. No entanto, você precisaria configurar permissões e escopo e confiar em aplicativos cliente.

Saiba como registrar seu aplicativo no Microsoft Entra ID

Para registrar um novo aplicativo no Microsoft Entra ID

1. No navegador da Web, vá para o Portal do Azure.

2. Selecione o ícone Registros de aplicativo.

   

   A página Registros de aplicativo é exibida.

3. Selecione o ícone + Novo registro.

   

   A página Registrar um aplicativo é exibida.

4. Insira o nome do aplicativo que você deseja exibir para o usuário do aplicativo. Você pode alterar o nome em um estágio posterior, se quiser.

   

5. Selecione o tipo de conta de usuário que pode acessar seu aplicativo. Você pode selecionar entre opções únicas ou multilocatários em diretórios organizacionais ou restringir o acesso apenas a contas pessoais da Microsoft.

   Opções para tipos de conta com suporte

   Opção	Selecione essa opção para...
   Somente contas neste diretório organizacional (somente Microsoft – locatário único)	Crie um aplicativo para uso somente por usuários (ou convidados) em seu locatário. Geralmente chamado de aplicativo personalizado criado para seu aplicativo LOB (organização), este aplicativo é um aplicativo de locatário único no plataforma de identidade da Microsoft.
   Contas em qualquer diretório organizacional (qualquer locatário de ID Microsoft Entra – Multilocatário)	Permitir que os usuários em qualquer locatário Microsoft Entra usem seu aplicativo. Essa opção será apropriada se, por exemplo, você estiver criando um aplicativo SaaS e pretende disponibilizá-lo para várias organizações. Esse tipo de aplicativo é conhecido como um aplicativo multilocatário no plataforma de identidade da Microsoft.
   Contas em qualquer diretório organizacional (qualquer locatário de ID Microsoft Entra – Multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox)	Destina-se ao conjunto mais amplo de clientes. Ao selecionar essa opção, você está registrando um aplicativo multilocatário que pode dar suporte a usuários de aplicativo que também têm contas pessoais da Microsoft.
   Contas pessoais da Microsoft	Crie um aplicativo somente para usuários que têm contas pessoais da Microsoft.

   Observação

   Você não precisa inserir o URI de redirecionamento para habilitar o SSO para um aplicativo de guias.

6. Selecione Registrar. Uma mensagem é exibida no navegador informando que o aplicativo foi criado.

   

   A página com a ID do aplicativo e outras configurações é exibida.

   

7. Observe e salve a ID do aplicativo da ID do aplicativo (cliente) para atualizar o manifesto do aplicativo posteriormente.

   Seu aplicativo está registrado em Microsoft Entra ID. Agora você tem a ID do aplicativo de guia.

Configurar o escopo para o token de acesso

Depois de criar um novo registro de aplicativo, configure as opções de escopo (permissão) para enviar o token de acesso ao Cliente do Teams e autorizar aplicativos cliente confiáveis para habilitar o SSO.

Para configurar o escopo e autorizar aplicativos cliente confiáveis, você precisa:

• Para expor uma API: configurar opções de escopo (permissão) para seu aplicativo. Exponha uma API Web e configure o URI da ID do aplicativo.
• Para configurar o escopo da API: defina o escopo para a API e os usuários que podem consentir um escopo. Você pode permitir que somente administradores forneçam consentimento para permissões com privilégios mais altos.
• Para configurar o aplicativo cliente autorizado: crie IDs de cliente autorizadas para aplicativos que você deseja pré-autenticar. Isso permite que o usuário do aplicativo acesse os escopos do aplicativo (permissões) que você configurou, sem a necessidade de qualquer consentimento adicional. Preautorize apenas os aplicativos cliente em que você confia, pois os usuários do aplicativo não terão a oportunidade de recusar o consentimento.

Para expor uma API

1. Selecione Gerenciar>Expor uma API no painel esquerdo.

   

   A página Expor uma API é exibida.

2. Selecione Adicionar para gerar o URI de ID do aplicativo na forma de api://{AppID}.

   

   A seção para definir o URI da ID do aplicativo é exibida.

3. Insira o URI da ID do aplicativo no formato explicado aqui.

   

   • O URI da ID do Aplicativo está pré-preenchido com a ID do aplicativo (GUID) no formato api://{AppID}.
   • O formato URI da ID do aplicativo deve ser: api://fully-qualified-domain-name.com/{AppID}.
   • Insira fully-qualified-domain-name.com entre api:// e {AppID} (ou seja, a GUID). Por exemplo, api://example.com/{AppID}.

   Em que:

   • fully-qualified-domain-name.com é o nome de domínio legível por humanos a partir do qual o aplicativo de guia é atendido. O nome de domínio do seu aplicativo e o nome de domínio que você registra para seu aplicativo Microsoft Entra devem ser os mesmos.

     Se você estiver usando um serviço de túnel, como ngrok, deverá atualizar esse valor sempre que o subdomínio ngrok mudar.

   • AppID é a ID do aplicativo (GUID) que foi gerada quando você registrou seu aplicativo. Você pode exibi-lo na seção Visão geral.

   Importante

   • Informações confidenciais: o URI da ID do aplicativo é registrado como parte do processo de autenticação e não deve conter informações confidenciais.

   • URI da ID do aplicativo para aplicativo com vários recursos: se você estiver criando um aplicativo com um bot, uma extensão de mensagens e uma guia, insira o URI da ID do aplicativo como api://fully-qualified-domain-name.com/botid-{YourClientId}, em que {YourClientId} é sua ID do aplicativo bot.

   • Formatar para nome de domínio: use letras minúsculas para o nome de domínio. Não use maiúsculas.

     Por exemplo, para criar um serviço de aplicativo ou aplicativo Web com o nome do recurso, demoapplication:

     Se o nome do recurso base usado for	A URL será...	Há suporte para o formato em...
     demoapplication	https://demoapplication.example.net	Todas as plataformas.
     DemoApplication	https://DemoApplication.example.net	Somente área de trabalho, Web e iOS. Não há suporte para ele no Android.

     Use a opção minúscula demoapplication como o nome do recurso base.

4. Selecione Salvar.

   Uma mensagem é exibida no navegador informando que o URI da ID do aplicativo foi atualizado.

   

   O URI da ID do aplicativo é exibido na página.

   

5. Observe e salve o URI da ID do Aplicativo para atualizar o manifesto do aplicativo posteriormente.

Para configurar o escopo da API

1. Selecione + Adicionar um escopo nos Escopos definidos por esta seção de API.

   

   A página Adicionar um escopo é exibida.

2. Insira os detalhes para configurar o escopo.

   

   1. Insira o nome do escopo. Esse campo é obrigatório.
   2. Selecione o usuário que pode dar consentimento para este escopo. A opção padrão é Somente administradores.
   3. Insira o Nome de exibição de consentimento do administrador. Esse campo é obrigatório.
   4. Insira a descrição do consentimento do administrador. Esse campo é obrigatório.
   5. Insira o Nome de exibição do consentimento do usuário.
   6. Insira a descrição para o consentimento do usuário.
   7. Selecione a opção Habilitado para o estado.
   8. Selecione Adicionar escopo.

   Uma mensagem é exibida no navegador informando que o escopo foi adicionado.

   

   O novo escopo que você definiu é exibido na página.

   

Para configurar o aplicativo cliente autorizado

1. Percorra a página Expor uma API até a seção Aplicativo cliente autorizado e selecione + Adicionar um aplicativo cliente.

   

   A página Adicionar um aplicativo cliente será exibida.

2. Insira a ID de cliente apropriada do Microsoft 365 para os aplicativos que você deseja autorizar para o aplicativo Web do seu aplicativo.

   

   Observação

   • As IDs de cliente do Microsoft 365 para aplicativos móveis, desktop e Web para o Teams, o aplicativo Microsoft 365 e o Outlook são as IDs reais que você deve adicionar.
   • Para um aplicativo de guia do Teams, você precisa de Web ou SPA, pois não é possível ter um aplicativo cliente móvel ou de área de trabalho no Teams.

   1. Selecione uma das seguintes IDs do cliente:

      Usar a ID do cliente	Para autorizar...
      1fec8e78-bce4-4aaf-ab1b-5451cc387264	Aplicativo da área de trabalho ou móvel do Teams.
      5e3ce6c0-2b1f-4285-8d4b-75ee78787346	Aplicativo Web do Teams.
      4765445b-32c6-49b0-83e6-1d93765276ca	Aplicativo Web do Microsoft 365
      0ec893e0-5785-4de6-99da-4ed124e5296c	Aplicativo de área de trabalho do Microsoft 365
      d3590ed6-52b3-4102-aeff-aad2292ab01c	Aplicativo móvel do Microsoft 365
      d3590ed6-52b3-4102-aeff-aad2292ab01c	Aplicativo da área de trabalho do Outlook
      bc59ab01-8403-45c6-8796-ac3ef710b3e3	Aplicativo Web do Outlook
      27922004-5251-4030-b22d-91ecd9a37ea4	Aplicativo móvel do Outlook

   2. Selecione o URI da ID do aplicativo que você criou para seu aplicativo em Escopos autorizados para adicionar o escopo à API Web que você expôs.

   3. Selecione Adicionar aplicativo.

      Uma mensagem é exibida no navegador informando que o aplicativo cliente autorizado foi adicionado.

      

      A ID do cliente do aplicativo autorizado é exibida na página.

      

Observação

Você pode autorizar mais de um aplicativo cliente. Repita as etapas deste procedimento para configurar outro aplicativo cliente autorizado.

Você configurou com êxito o escopo do aplicativo, as permissões e os aplicativos cliente. Verifique se você observa e salva o URI da ID do aplicativo. Em seguida, você configurará a versão do token de acesso.

Configurar a versão do token de acesso

Você deve definir a versão do token de acesso para seu aplicativo. Essa configuração é feita no manifesto do aplicativo Microsoft Entra.

Para definir a versão do token de acesso

1. Selecione Gerenciar>Manifesto no painel esquerdo.

   

   O manifesto do aplicativo Microsoft Entra é exibido.

2. Insira 2 como o valor da propriedade accessTokenAcceptedVersion.

   Observação

   Se você tiver selecionado somente contas pessoais da Microsoft ou Contas em qualquer diretório organizacional (Qualquer diretório Microsoft Entra – Multilocatário) e contas pessoais da Microsoft (por exemplo, Skype e Xbox) durante o registro do aplicativo, atualize o valor da accessTokenAcceptedVersion propriedade como 2.

   

3. Selecione Salvar

   Uma mensagem aparece no navegador informando que o manifesto do aplicativo foi atualizado com êxito.

   

Parabéns! Você concluiu a configuração do aplicativo em Microsoft Entra ID necessária para habilitar o SSO para seu aplicativo de guias.

Próxima etapa

Configurar código para habilitar o SSO

Confira também

• Locação em Microsoft Entra ID
• Estender o aplicativo de guia com permissões e escopo do Microsoft Graph
• Início rápido: registrar um aplicativo na plataforma de identidade da Microsoft
• Início rápido: configurar um aplicativo para expor uma API Web
• Fluxo de código de autorização do OAuth 2.0