Configurar a sua aplicação no Microsoft Entra ID

  • Artigo

O Microsoft Entra ID fornece aos utilizadores da aplicação acesso ao bot ou à aplicação de extensão de mensagens. O utilizador da aplicação que iniciou sessão no Teams pode ter acesso à sua aplicação.

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

As aplicações de extensão de bots e mensagens utilizam o Bot Framework para comunicar com os utilizadores da aplicação e implementar a autenticação.

Para configurar o SSO para a aplicação de extensão de bot ou mensagem, terá de:

  • Configurar o recurso do bot no Microsoft Entra ID
  • Configurar a aplicação no Microsoft Entra ID

Observação

Certifique-se de que criou uma aplicação e um recurso de bot no Microsoft Entra ID.

Pode configurar o recurso e a aplicação do bot no Microsoft Entra ID para o seu bot ou aplicação de extensão de mensagens de uma das duas formas seguintes:

  • Configurar o SSO com o recurso de bot e configurar a aplicação Microsoft Entra: pode começar por configurar o SSO para o recurso do bot e ativar o SSO para a sua aplicação Microsoft Entra. Irá configurar:

    • Para o recurso do bot: ponto final de mensagens e ligação OAuth.

      Observação

      Quando cria o recurso de bot no Microsoft Entra ID, pode selecionar a opção para criar um novo ID de aplicação ou pode utilizar um ID de aplicação existente se já tiver registado a sua aplicação no Microsoft Entra ID.

    • Para a aplicação Microsoft Entra: URI do ID da Aplicação, âmbito e permissões, IDs de cliente fidedignos, versão do token de acesso, segredo do cliente e URL de redirecionamento.

  • Configurar o SSO com a aplicação Microsoft Entra e, em seguida, configurar o recurso do bot: pode começar por configurar a sua aplicação Microsoft Entra e, em seguida, utilizar este ID de aplicação no recurso do bot quando ativar o SSO para o mesmo. Irá configurar:

    • Para a aplicação Microsoft Entra: URI do ID da Aplicação, token de acesso, IDs de cliente fidedignos, versão do token de acesso, segredo do cliente e URL de redirecionamento.

    • Para o recurso do bot: ponto final de mensagens e ligação OAuth.

      Observação

      Configure o recurso do bot com o ID da aplicação gerado pelo ID do Microsoft Entra quando registou a sua aplicação.

Ativar o SSO no Microsoft Entra ID

No final deste tutorial, irá aprender a configurar:

  • ID do Aplicativo
  • ID do Bot
  • Token de acesso
    • URI da ID do Aplicativo
    • Âmbito, permissões e IDs de cliente autorizados
    • Segredo do cliente
    • URL de redirecionamento
  • Ponto final de mensagens e ligação OAuth

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

Para ativar o SSO para a sua aplicação no Microsoft Entra ID:

Importante

Certifique-se de que, quando criar o recurso de bot, selecione a opção para criar um novo ID de aplicação. Também pode utilizar um ID de aplicação existente, se já tiver registado uma aplicação no centro de administração do Microsoft Entra.

Configurar o ponto final de mensagens

O ponto final de mensagens é onde as mensagens são enviadas para o bot. Permite a comunicação com o bot.

Para configurar o ponto final de mensagens para o recurso de bot

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

  2. Introduza o nome do recurso do bot na caixa Procurar e selecione Enter para o abrir.

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

    Captura de ecrã a mostrar o menu Configuração do bot.

    É apresentada a página Configuração .

  4. Introduza o URL do ponto final de mensagens onde o bot recebe as mensagens do utilizador da aplicação.

    Captura de ecrã a mostrar a opção Ponto final de Mensagens para adicionar o URL onde o bot interage com o utilizador.

  5. Selecione Aplicar.

    O ponto final de mensagens está configurado.

Configurou o ponto final de mensagens para o recurso do bot. Em seguida, tem de ativar o SSO para a aplicação Microsoft Entra.

Configurar o SSO para a aplicação Microsoft Entra

Tem de configurar permissões e âmbitos, autorizar aplicações cliente, atualizar o manifesto da aplicação (anteriormente denominado manifesto de aplicação do Teams) e criar o segredo do cliente para a sua aplicação Microsoft Entra. Estas configurações ajudam a invocar o SSO para a sua aplicação de bot.

Configurar o âmbito do token de acesso

Configure as opções de âmbito (permissão) para enviar o token de acesso para o cliente do Teams e autorizar aplicações cliente fidedignas para ativar o SSO.

Precisas:

  • Para configurar o URI do ID da aplicação: configure as opções de âmbito (permissão) para a sua aplicação. Vai expor uma API Web e configurar o URI do ID da aplicação.
  • 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. Pré-autorize apenas as aplicações cliente nas quais confia, uma vez que os utilizadores da sua aplicação não terão a oportunidade de recusar o consentimento.

Para configurar o URI do ID da aplicação

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

    É aberta a página Bot do Microsoft Azure.

  2. Introduza o nome do recurso do bot na caixa Procurar e, em seguida, selecione Enter para o abrir.

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

    Captura de ecrã a mostrar o menu Configuração do bot em Definições.

    É apresentada a página Configuração .

  4. Selecione Gerenciar.

    Captura de ecrã a mostrar a configuração do recurso do Bot.

    É apresentada a página da aplicação Microsoft Entra.

    O novo ID da aplicação (ID de cliente) da aplicação é apresentado nesta página. Anote e guarde este ID de aplicação. Terá de atualizá-lo no manifesto da aplicação mais tarde. Se utilizou o ID de uma aplicação existente quando criou o recurso de bot, o ID dessa aplicação será apresentado nesta página.

    Captura de ecrã a mostrar a página Aplicação bot com o ID de cliente da aplicação realçado.

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

    A página Expor uma API é exibida.

  6. Selecione Adicionar para gerar o URI do ID da aplicação.

    Captura de ecrã a mostrar a opção Definir do URI do ID da Aplicação.

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

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

    Captura de ecrã a mostrar o URI do ID da Aplicação adicionado.

    • O URI do ID da Aplicação está pré-preenchido com o ID da aplicação (GUID) no formato api://{AppID}.

    Importante

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

    • Bot autónomo: se estiver a criar um bot autónomo, introduza o URI do ID da aplicação como api://botid-{YourBotId}. Aqui, {YourBotId} é o seu ID de aplicação do Microsoft Entra.

    • URI do ID da Aplicação para a aplicação com múltiplas capacidades: se estiver a criar uma aplicação com um bot, uma extensão de mensagens e um separador, introduza o URI do ID da aplicação como api://fully-qualified-domain-name.com/botid-{YourClientId}, onde {YourClientId} está o ID da aplicação do bot.

    • Formato do nome de domínio: utilize 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.

      Utilize a opção em minúsculas demoapplication como nome de recurso base.

  8. Selecione Salvar.

    É apresentada uma mensagem no browser a indicar que o URI do ID da aplicação foi atualizado.

    Captura de ecrã a mostrar a mensagem do URI do ID da Aplicação atualizada.

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

    Captura de ecrã a mostrar o URI do ID da Aplicação atualizado.

  9. Anote e guarde o URI do ID da aplicação. Irá precisar dele para atualizar o manifesto da aplicação mais tarde.

O URI do ID da aplicação está configurado. Agora pode definir o âmbito e as permissões para a sua aplicação.

Para configurar o escopo da API

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

    Captura de ecrã a mostrar a opção Adicionar um âmbito realçada.

    A página Adicionar um escopo é exibida.

  2. Insira os detalhes para configurar o escopo.

    Captura de ecrã a mostrar como adicionar detalhes de âmbito 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. Introduza a descrição do consentimento do utilizador.

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

    8. Selecione Adicionar escopo.

      Observação

      Neste tutorial, pode utilizar o perfil User.Read User.ReadBasic.All openid como âmbito. Este âmbito é adequado para utilizar o exemplo de Código. Também pode adicionar mais âmbitos e permissões do Graph. Para obter mais informações, consulte Expandir a sua aplicação com permissões e âmbitos do Microsoft Graph.

    É apresentada uma mensagem no browser a indicar que o âmbito foi adicionado.

    Captura de ecrã a mostrar a mensagem Âmbito adicionado.

    Observação

    O novo escopo que você definiu é exibido na página. Certifique-se de que anota e guarda o âmbito que configurou. Precisará dela para atualizar a ligação OAuth mais tarde.

O âmbito e as permissões estão agora configurados. Em seguida, tem de configurar as aplicações cliente autorizadas para a sua aplicação 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.

    Captura de ecrã a mostrar a opção Adicionar uma aplicação cliente realçada em Aplicações cliente autorizadas.

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

  2. Introduza o ID de cliente do Microsoft 365 adequado para as aplicações que pretende autorizar para a aplicação Web da sua aplicação.

    Captura de ecrã a mostrar o ID de Cliente adicionado.

    Observação

    • Os IDs de cliente do Microsoft 365 para aplicações móveis, de ambiente de trabalho e Web para o Teams, a aplicação Microsoft 365 e o Outlook são os IDs reais que tem de adicionar.
    • Se a sua aplicação tiver uma aplicação de separador, precisará de web ou SPA, uma vez que não pode ter uma aplicação cliente móvel ou de ambiente de trabalho no Teams.

  3. Selecione um dos seguintes IDs de 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 Aplicação Web do Microsoft 365
    0ec893e0-5785-4de6-99da-4ed124e5296c Aplicação de ambiente de trabalho do Microsoft 365
    d3590ed6-52b3-4102-aeff-aad2292ab01c Aplicação microsoft 365 para dispositivos móveis Aplicação
    de ambiente de trabalho do Outlook
    bc59ab01-8403-45c6-8796-ac3ef710b3e3 Aplicação Web do Outlook
    27922004-5251-4030-b22d-91ecd9a37ea4 Aplicação outlook para dispositivos móveis

  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.

    É apresentada uma mensagem no browser a indicar que a aplicação cliente autorizada foi adicionada.

    Captura de ecrã a mostrar a mensagem ID de Cliente adicionado.

    O ID de cliente da aplicação autorizada é apresentado na página.

    Captura de ecrã a mostrar o ID de Cliente adicionado recentemente no ecrã Aplicações cliente autorizadas.

    Observação

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

Configurou com êxito o âmbito da aplicação, as permissões e as aplicações cliente. Certifique-se de que anota e guarda o URI do ID da aplicação. Em seguida, configure a versão do token de acesso.

Configurar a versão do token de acesso

Tem de definir a versão do token de acesso para a sua aplicação no manifesto da aplicação Microsoft Entra.

Para definir a versão do token de acesso

  1. Selecione Gerenciar>Manifesto no painel esquerdo.

    Captura de ecrã a mostrar o Manifesto do Centro de Administração do Microsoft Entra.

    É apresentado o manifesto da aplicação Microsoft Entra.

  2. Insira 2 como o valor da propriedade accessTokenAcceptedVersion.

    Captura de ecrã a mostrar o Valor da versão do token de acesso aceite.

  3. Selecione Salvar.

    É apresentada uma mensagem no browser a indicar que o manifesto da aplicação foi atualizado com êxito.

    Captura de ecrã a mostrar a mensagem Manifesto atualizado.

Atualizou a versão do token de acesso. Em seguida, irá criar um segredo do cliente para a sua aplicação.

Criar segredo do cliente

Um segredo do cliente é uma cadeia que a aplicação utiliza para provar a respetiva identidade ao pedir um token.

Para criar um segredo do cliente para a sua aplicação

  1. Selecione Gerir>Certificados & segredos.

    Captura de ecrã a mostrar a opção de menu Certificados e segredos.

    É apresentada a página Certificados & segredos .

  2. Selecione + Novo segredo do cliente.

    Captura de ecrã a mostrar a opção Novo segredo do cliente realçada para adicionar um novo segredo do cliente.

    É apresentada a página Adicionar um segredo do cliente .

    Captura de ecrã a mostrar a página Adicionar um segredo do cliente para fornecer os detalhes necessários.

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

  3. Selecione Adicionar.

    É apresentada uma mensagem no browser a indicar que o segredo do cliente foi atualizado e o segredo do cliente é apresentado na página.

    Captura de ecrã a mostrar a mensagem Segredo do cliente adicionado.

  4. Selecione o botão copiar junto ao Valor do segredo do cliente.

  5. Guarde o valor que copiou. Irá precisar dele mais tarde para atualizar o código.

    Importante

    Certifique-se de que copia o valor do segredo do cliente logo após criá-lo. O valor só é visível no momento em que o segredo do cliente é criado e não pode ser visualizado depois disso.

Configurou o segredo do cliente. Em seguida, tem de configurar o URL de redirecionamento.

Configurar o URL de redirecionamento

A configuração da autenticação depende da plataforma ou do dispositivo onde pretende direcionar a sua aplicação. Poderá ter de configurar URIs de redirecionamento, definições de autenticação ou detalhes específicos da plataforma.

Observação

  • Se não tiver sido concedido consentimento ao administrador de TI à aplicação bot, os utilizadores da aplicação terão de dar consentimento na primeira vez que utilizarem a sua aplicação numa plataforma diferente.
  • A concessão implícita não é necessária se o SSO estiver ativado numa aplicação de bot.

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

Para configurar o URL de redirecionamento

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

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

    Captura de ecrã a mostrar a opção Autenticação em Gerir.

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

  3. Selecione Adicionar uma plataforma.

    Captura de ecrã a mostrar a opção Adicionar uma plataforma em Autenticação.

    A página Configurar plataformas é exibida.

  4. Selecione a plataforma que pretende configurar para a sua aplicação. Pode selecionar o tipo de plataforma na Web ou spa.

    Captura de ecrã a mostrar a seleção da plataforma Web.

    É apresentada a página Configurar Web .

    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.

    Captura de ecrã a mostrar a página Configurar Web para fornecer entradas.

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

      Observação

      O URL mencionado em URIs de Redirecionamento é um exemplo.

    2. Insira a URL de logoff do canal frontal.

    3. Selecione os tokens que pretende que o ID do Microsoft Entra envie para a sua aplicação.

  6. Selecione Configurar.

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

A configuração da aplicação Microsoft Entra está concluída e agora tem de ativar o suporte de SSO para o recurso do bot ao configurar a ligação OAuth.

Configurar a ligação OAuth

Para um bot dar suporte ao SSO, você deve atualizar suas configurações de conexão OAuth. Este processo associa o bot aos detalhes da aplicação que configurou para a sua aplicação Microsoft Entra:

  • ID da aplicação Microsoft Entra, que é o ID de cliente
  • ID do locatário
  • Âmbito e permissões

Com o ID da aplicação (cliente) e o segredo do cliente fornecidos, o Arquivo de Tokens do Bot Framework troca o token por um token de grafo com permissões definidas.

Para atualizar a ligação OAuth

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

  2. Introduza o nome da sua aplicação Microsoft Entra na caixa Procurar e abra a sua aplicação.

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

    Captura de ecrã a mostrar as definições de configuração de OAUth para a sua aplicação de bot.

    É apresentada a página Configuração .

  4. Percorra a página Configuração e selecione Adicionar Definições de Ligação OAuth.

    Captura de ecrã a mostrar a opção Adicionar Definições de Ligação OAuth realçada.

    É apresentada a página Nova Definição de Ligação .

  5. Introduza as definições de configuração do OAuth para o bot do Azure.

    Captura de ecrã a mostrar a Nova Definição de Ligação para fornecer os detalhes.

    1. Introduza um nome para a definição de configuração.

    2. Selecione o fornecedor de serviços.

      Os restantes detalhes de configuração são apresentados.

      Captura de ecrã a mostrar os campos adicionais para Nova Definição de Ligação.

    3. Introduza o ID da aplicação (cliente) da aplicação Microsoft Entra.

    4. Introduza o segredo do cliente que criou para o bot.

    5. Introduza o URI do ID da aplicação do bot no URL do Exchange de Tokens.

    6. Introduza o ID do inquilino.

    7. Introduza o âmbito que definiu quando configurou o âmbito e as permissões.

  6. Selecione Salvar.

  7. Selecione Aplicar.

    Depois de configurar a ligação OAuth, pode selecionar Testar ligação para verificar se a ligação OAuth foi bem-sucedida.

    Captura de ecrã a mostrar a opção Testar ligação OAuth para o recurso do bot.

    Se a ligação não for bem-sucedida, o ID do Microsoft Entra apresenta um erro. Pode verificar todas as configurações e testar novamente.

Parabéns! Concluiu as seguintes configurações de aplicações no Microsoft Entra ID necessário para ativar o SSO para a sua aplicação bot:

  • ID do Aplicativo
  • ID do Bot
  • Token de acesso
    • URI da ID do Aplicativo
    • Âmbito, permissões e IDs de cliente autorizados
    • Segredo do cliente
    • URL de redirecionamento
  • Ponto final de mensagens e ligação OAuth

Práticas recomendadas

  • Mantenha o registo da aplicação Microsoft Entra restrito à sua finalidade original de aplicação serviço a serviço.
  • Para um melhor controlo sobre a desativação de ligações de autenticação, a implementação de segredos ou a reutilização da aplicação Microsoft Entra com outras aplicações, crie uma aplicação Microsoft Entra adicional para qualquer utilizador efetuar a autenticação.

Se utilizar a aplicação de registo do Microsoft Entra para autenticação, poderá deparar-se com os seguintes problemas:

  • Se renovar o certificado anexado ao registo da aplicação Microsoft Entra, este afetará os utilizadores que se autenticaram com outros serviços do Microsoft Entra através do certificado.
  • Cria um ponto único de falha e controlo para todas as atividades relacionadas com a autenticação com o bot.

Próxima etapa

Adicionar código para habilitar o logon único