Configurar seu aplicativo no Microsoft Entra ID

  • Artigo

Microsoft Entra ID fornece aos usuários do aplicativo acesso ao seu aplicativo de extensão de bot ou mensagem. O usuário do aplicativo que entrou no Teams pode ter acesso ao seu aplicativo.

Configuração do SSO no centro de administração do Microsoft Entra

Os aplicativos de extensão de bot e mensagem usam o Bot Framework para se comunicar com usuários do aplicativo e implementar a autenticação.

Para configurar o SSO para seu aplicativo de extensão de bot ou mensagem, você precisará:

  • Configurar o recurso de bot no Microsoft Entra ID
  • Configurar aplicativo no Microsoft Entra ID

Observação

Verifique se você criou um aplicativo e um recurso de bot no Microsoft Entra ID.

Você pode configurar o recurso de bot e o aplicativo em Microsoft Entra ID para seu aplicativo de extensão de bot ou mensagem de uma das duas seguintes maneiras:

  • Configure o SSO usando o recurso de bot e configure Microsoft Entra aplicativo: você pode começar configurando o SSO para o recurso de bot e habilitar o SSO para seu aplicativo Microsoft Entra. Você configurará:

    • Para o recurso bot: ponto de extremidade de mensagens e conexão OAuth.

      Observação

      Ao criar o recurso de bot no Microsoft Entra ID, você pode selecionar a opção para criar uma nova ID do aplicativo ou usar uma ID de aplicativo existente se já tiver registrado seu aplicativo em Microsoft Entra ID.

    • Para Microsoft Entra aplicativo: URI de ID do aplicativo, escopo e permissões, IDs confiáveis do cliente, versão do token de acesso, segredo do cliente e URL de redirecionamento.

  • Configure o SSO usando Microsoft Entra aplicativo e, em seguida, configure o recurso de bot: você pode começar configurando seu aplicativo Microsoft Entra e, em seguida, usar essa ID do aplicativo no recurso bot quando habilitar o SSO para ele. Você configurará:

    • Para Microsoft Entra aplicativo: URI de ID do aplicativo, token de acesso, IDs confiáveis do cliente, versão do token de acesso, segredo do cliente e URL de redirecionamento.

    • Para o recurso bot: ponto de extremidade de mensagens e conexão OAuth.

      Observação

      Configure o recurso de bot usando a ID do aplicativo gerada por Microsoft Entra ID quando você registrou seu aplicativo.

Habilitar o SSO em Microsoft Entra ID

Ao final deste tutorial, você aprenderá a configurar:

  • ID do Aplicativo
  • ID do Bot
  • Token de acesso
    • URI da ID do Aplicativo
    • Escopo, permissões e IDs de cliente autorizadas
    • Segredo do cliente
    • URL de redirecionamento
  • Ponto de extremidade de mensagens e conexão OAuth

Selecione uma das duas seguintes maneiras de configurar o SSO para o recurso do bot:

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

Importante

Verifique se, ao criar o recurso do bot, selecione a opção para criar uma nova ID do aplicativo. Você também pode usar uma ID de aplicativo existente, se já tiver registrado um aplicativo no centro de administração Microsoft Entra.

Configurar ponto de extremidade de mensagens

O ponto de extremidade de mensagens é onde as mensagens são enviadas para o bot. Ele habilita a comunicação com o bot.

Para configurar o ponto de extremidade de mensagens para o recurso do bot

  1. No navegador da Web, vá para o Portal do Azure. A página do Microsoft Azure Bot é aberta.

  2. Insira o nome do recurso do bot na caixa Pesquisar e selecione Inserir para abri-lo.

  3. Selecione Configuração de Configurações>.

    A captura de tela mostra o menu Configuração do bot.

    A página Configuração é exibida.

  4. Insira a URL do ponto de extremidade de mensagens em que o bot recebe mensagens do usuário do aplicativo.

    A captura de tela mostra a opção ponto de extremidade mensagens para adicionar a URL em que o bot interage com o usuário.

  5. Selecione Aplicar.

    O ponto de extremidade de mensagens está configurado.

Você configurou o ponto de extremidade de mensagens para o recurso do bot. Em seguida, você deve habilitar o SSO para o aplicativo Microsoft Entra.

Configurar o SSO para Microsoft Entra aplicativo

Você deve configurar permissões e escopos, autorizar aplicativos cliente, atualizar manifesto de aplicativo (anteriormente chamado de manifesto do aplicativo teams) e criar segredo do cliente para seu aplicativo Microsoft Entra. Essas configurações ajudam a invocar o SSO para seu aplicativo bot.

Configurar o escopo para o token de acesso

Configure opções de escopo (permissão) para enviar token de acesso ao cliente do Teams e autorizar aplicativos cliente confiáveis para habilitar o SSO.

Você precisa:

  • Para configurar o URI da ID do aplicativo: configurar opções de escopo (permissão) para seu aplicativo. Você exporá uma API Web e configurará 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 do cliente autorizadas para aplicativos que você deseja pré-autorizar. 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. Autorize 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 configurar o URI da ID do aplicativo

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

    A página do Microsoft Azure Bot é aberta.

  2. Insira o nome do recurso do bot na caixa Pesquisar e selecione Inserir para abri-lo.

  3. Selecione Configuração de Configurações>.

    A captura de tela mostra o menu Configuração do bot em Configurações.

    A página Configuração é exibida.

  4. Selecione Gerenciar.

    A captura de tela mostra a configuração do recurso bot.

    A página Microsoft Entra aplicativo é exibida.

    A nova ID do aplicativo (ID do cliente) para o aplicativo é exibida nesta página. Observe e salve esta ID do aplicativo. Você precisará atualizá-lo no manifesto do aplicativo mais tarde. Se você usou a ID de um aplicativo existente quando criou o recurso de bot, a ID desse aplicativo será exibida nesta página.

    A captura de tela mostra a página do aplicativo Bot com a ID do cliente do aplicativo realçada.

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

    A página Expor uma API é exibida.

  6. Selecione Adicionar para gerar o URI da ID do aplicativo.

    A captura de tela mostra a opção Definir do URI da ID do Aplicativo.

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

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

    A captura de tela mostra o URI da ID do Aplicativo adicionado.

    • O URI da ID do Aplicativo está pré-preenchido com a ID do aplicativo (GUID) no formato api://{AppID}.

    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.

    • Bot autônomo: se você estiver criando um bot autônomo, insira o URI da ID do aplicativo como api://botid-{YourBotId}. Aqui, {YourBotId} é sua ID do aplicativo Microsoft Entra.

    • 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}, onde {YourClientId} está sua ID do aplicativo bot.

    • Formato para nome de domínio: use letras minúsculas para o nome do 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 lowercase demoapplication como nome de recurso base.

  8. Selecione Salvar.

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

    A captura de tela mostra a mensagem atualizada do URI da ID do Aplicativo.

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

    A captura de tela mostra o URI de ID do Aplicativo atualizado.

  9. Observe e salve o URI da ID do aplicativo. Você precisará dele para atualizar o manifesto do aplicativo mais tarde.

O URI da ID do aplicativo está configurado. Agora você pode definir escopo e permissões para seu aplicativo.

Para configurar o escopo da API

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

    A captura de tela mostra a opção Adicionar um escopo realçada.

    A página Adicionar um escopo é exibida.

  2. Insira os detalhes para configurar o escopo.

    A captura de tela mostra como adicionar detalhes de escopo no Azure.

    1. Insira o nome do escopo.

    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.

    4. Insira a descrição do consentimento do administrador.

    5. Insira o Nome de exibição do consentimento do usuário.

    6. Insira a descrição do consentimento do usuário.

    7. Selecione a opção Habilitado para o estado.

    8. Selecione Adicionar escopo.

      Observação

      Para este tutorial, você pode usar o perfil User.Read User.ReadBasic.All openid como escopo. Esse escopo é adequado para usar o exemplo de código. Você também pode adicionar mais escopos e permissões do Graph. Para obter mais informações, consulte Estender seu aplicativo com permissões e escopos do Microsoft Graph.

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

    A captura de tela mostra a mensagem adicionada de Escopo.

    Observação

    O novo escopo que você definiu é exibido na página. Verifique se você observa e salva o escopo que você configurou. Você precisará dele para atualizar a conexão OAuth mais tarde.

O escopo e as permissões agora estão configurados. Em seguida, você deve configurar os aplicativos cliente autorizados para seu aplicativo Microsoft Entra.

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 captura de tela mostra a opção Adicionar um aplicativo cliente realçada em Aplicativos cliente autorizados.

    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.

    A captura de tela mostra a ID do cliente adicionada.

    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.
    • Se seu aplicativo tiver um aplicativo de guia, você precisará da Web ou do SPA, pois não é possível ter um aplicativo cliente móvel ou de área de trabalho no Teams.

  3. 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 Outlook
    bc59ab01-8403-45c6-8796-ac3ef710b3e3 Aplicativo Web do Outlook
    27922004-5251-4030-b22d-91ecd9a37ea4 Aplicativo móvel do Outlook

  4. 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.

  5. Selecione Adicionar aplicativo.

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

    A captura de tela mostra a mensagem adicionada à ID do cliente.

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

    A captura de tela mostra a ID do cliente recém-adicionada na tela Aplicativos cliente autorizados.

    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 no manifesto do aplicativo Microsoft Entra.

Para definir a versão do token de acesso

  1. Selecione Gerenciar>Manifesto no painel esquerdo.

    A captura de tela mostra o manifesto do centro de administração Microsoft Entra.

    O manifesto do aplicativo Microsoft Entra é exibido.

  2. Insira 2 como o valor da propriedade accessTokenAcceptedVersion.

    A captura de tela mostra a versão do token value for accepted access.

  3. Selecione Salvar.

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

    A captura de tela mostra a mensagem atualizada do Manifesto.

Você atualizou a versão do token de acesso. Em seguida, você criará um segredo do cliente para seu aplicativo.

Criar segredo do cliente

Um segredo do cliente é uma cadeia de caracteres que o aplicativo usa para provar sua identidade ao solicitar um token.

Para criar um segredo do cliente para seu aplicativo

  1. Selecione Gerenciar>Certificados & segredos.

    A captura de tela mostra a opção menu Certificados e segredos.

    A página Certificados & segredos é exibida.

  2. Selecione + Novo segredo do cliente.

    A captura de tela mostra a opção Novo segredo do cliente realçada para adicionar um novo segredo do cliente.

    A página Adicionar um segredo do cliente é exibida.

    A captura de tela mostra a página Adicionar um segredo do cliente para fornecer os detalhes necessários.

    1. Insira a descrição.
    2. Selecione a duração da validade do segredo.

  3. Selecione Adicionar.

    Uma mensagem é exibida no navegador informando que o segredo do cliente foi atualizado e o segredo do cliente é exibido na página.

    A captura de tela mostra a mensagem adicionada ao segredo do cliente.

  4. Selecione o botão copiar ao lado do segredo valor do cliente.

  5. Salve o valor copiado. Você precisará dele mais tarde para atualizar o código.

    Importante

    Verifique se você copia o valor do segredo do cliente logo após criá-lo. O valor fica visível somente no momento em que o segredo do cliente é criado e não pode ser exibido depois disso.

Você configurou o segredo do cliente. Em seguida, você deve configurar a URL de redirecionamento.

Configurar a URL de redirecionamento

A configuração para autenticação depende da plataforma ou dispositivo em que você deseja direcionar seu aplicativo. Talvez seja necessário configurar URIs de redirecionamento, configurações de autenticação ou detalhes específicos da plataforma.

Observação

  • Se o seu aplicativo bot não tiver recebido o consentimento do administrador de TI, os usuários do aplicativo terão que fornecer consentimento na primeira vez que usarem seu aplicativo em uma plataforma diferente.
  • A concessão implícita não será necessária se o SSO estiver habilitado em um aplicativo bot.

Você pode configurar a autenticação para várias plataformas, desde que o URL seja exclusivo.

Para configurar a URL de redirecionamento

  1. Abra o aplicativo que você registrou no portal do Azure.

  2. Selecione Gerenciar>Autenticação no painel esquerdo.

    A captura de tela mostra a opção Autenticação em Gerenciar.

    A página Configurações da plataforma é exibida.

  3. Selecione Adicionar uma plataforma.

    A captura de tela mostra a opção Adicionar uma plataforma em Autenticação.

    A página Configurar plataformas é exibida.

  4. Selecione a plataforma que você deseja configurar para seu aplicativo. Você pode selecionar o tipo de plataforma na Web ou SPA.

    A captura de tela mostra a seleção da plataforma Web.

    A página Configurar Web é exibida.

    Observação

    As configurações serão diferentes com base na plataforma que você selecionou.

  5. Insira os detalhes da configuração para a plataforma.

    A captura de tela mostra a página Configurar a Web para fornecer entradas.

    1. Insira o URI de redirecionamento. A URI deve ser exclusiva.

      Observação

      A URL mencionada nas URIs de Redirecionamento é um exemplo.

    2. Insira a URL de logoff do canal frontal.

    3. Selecione os tokens que você deseja Microsoft Entra ID para enviar para seu aplicativo.

  6. Selecione Configurar.

    A plataforma é configurada e exibida na página Configurações da plataforma.

A configuração do aplicativo Microsoft Entra está concluída e agora você deve habilitar o suporte ao SSO para o recurso de bot configurando a conexão OAuth.

Configurar a conexão OAuth

Para um bot dar suporte ao SSO, você deve atualizar suas configurações de conexão OAuth. Esse processo associa o bot aos detalhes do aplicativo que você configurou para seu aplicativo Microsoft Entra:

  • Microsoft Entra ID do aplicativo, que é a ID do cliente
  • ID do locatário
  • Escopo e permissões

Com a ID do aplicativo (cliente) e o segredo do cliente fornecidos, a Loja de Tokens do Bot Framework troca o token por um token de grafo com permissões definidas.

Para atualizar a conexão OAuth

  1. No navegador da Web, vá para o Portal do Azure. A página do Microsoft Azure Bot é aberta.

  2. Insira o nome do aplicativo Microsoft Entra na caixa Pesquisar e abra seu aplicativo.

  3. Selecione Configuração de Configurações>.

    A captura de tela mostra as configurações de OAUth configuradas para seu aplicativo bot.

    A página Configuração é exibida.

  4. Passe pela página Configuração e selecione Adicionar Configurações de Conexão OAuth.

    A captura de tela mostra a opção Adicionar Configurações de Conexão OAuth realçada.

    A página Nova Configuração de Conexão é exibida.

  5. Insira as configurações do OAuth para o bot do Azure.

    A captura de tela mostra a Nova Configuração de Conexão para fornecer os detalhes.

    1. Insira um nome para a configuração.

    2. Selecione o provedor de serviços.

      Os detalhes restantes da configuração são exibidos.

      A captura de tela mostra os campos adicionais para Nova Configuração de Conexão.

    3. Insira a ID do aplicativo (cliente) para o aplicativo Microsoft Entra.

    4. Insira o segredo do cliente que você criou para o bot.

    5. Insira o URI de ID do aplicativo do bot na URL do Token Exchange.

    6. Insira a ID do locatário.

    7. Insira o escopo que você definiu quando configurou o escopo e as permissões.

  6. Selecione Salvar.

  7. Selecione Aplicar.

    Depois de configurar a conexão OAuth, você pode selecionar Testar conexão para marcar se a conexão OAuth for bem-sucedida.

    A captura de tela mostra a conexão OAuth de teste para a opção de recurso do bot.

    Se a conexão não for bem-sucedida, Microsoft Entra ID exibirá um erro. Você pode verificar todas as configurações e testar novamente.

Parabéns! Você concluiu as seguintes configurações de aplicativo no Microsoft Entra ID necessária para habilitar o SSO para seu aplicativo bot:

  • ID do Aplicativo
  • ID do Bot
  • Token de acesso
    • URI da ID do Aplicativo
    • Escopo, permissões e IDs de cliente autorizadas
    • Segredo do cliente
    • URL de redirecionamento
  • Ponto de extremidade de mensagens e conexão OAuth

Práticas recomendadas

  • Mantenha o registro do aplicativo Microsoft Entra restrito à sua finalidade original de serviço ao aplicativo de serviço.
  • Para obter um melhor controle sobre como desabilitar conexões de autenticação, rolar segredos ou reutilização do aplicativo Microsoft Entra com outros aplicativos, crie um aplicativo de Microsoft Entra adicional para qualquer usuário fazer o serviço de autenticação.

Se você usar o aplicativo de registro Microsoft Entra para autenticação, poderá encontrar os seguintes problemas:

  • Se você renovar o certificado anexado ao registro do aplicativo Microsoft Entra, ele afetará os usuários que se autenticaram com outros serviços Microsoft Entra usando o certificado.
  • Ele cria um único ponto de falha e controle para todas as atividades relacionadas à autenticação com o bot.

Próxima etapa

Adicionar código para habilitar o logon único