Tutorial: Criar um daemon multilocatário que usa a plataforma de identidade da Microsoft

  • Artigo

Neste tutorial, você baixa e executa um aplicativo Web ASP.NET daemon que demonstra o uso da concessão de credenciais de cliente OAuth 2.0 para obter um token de acesso para chamar a API do Microsoft Graph.

Neste tutorial:

  • Integrar um aplicativo daemon com a plataforma de identidade da Microsoft
  • Conceder permissões de aplicativo diretamente ao aplicativo por um administrador
  • Obter um token de acesso para chamar a API do Microsoft Graph
  • Chame a API do Microsoft Graph.

Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

  • Visual Studio 2017 ou 2019.
  • Um locatário do Microsoft Entra. Para obter mais informações, consulte Como obter um locatário do Microsoft Entra.
  • Uma ou mais contas de utilizador no seu inquilino. Este exemplo não funcionará com uma conta da Microsoft. Se você entrou com uma conta da Microsoft e nunca criou uma conta de usuário em seu diretório, faça isso agora.

Cenário

O aplicativo é criado como um aplicativo MVC ASP.NET. Ele usa o middleware OWIN OpenID Connect para entrar nos usuários.

O componente "daemon" neste exemplo é um controlador de API, SyncController.cs. Quando o controlador é chamado, ele recebe uma lista de usuários no locatário do Microsoft Entra do cliente do Microsoft Graph. SyncController.cs é acionado por uma chamada AJAX no aplicativo Web. Ele usa a Microsoft Authentication Library (MSAL) para .NET para adquirir um token de acesso para o Microsoft Graph.

Como o aplicativo é um aplicativo multilocatário para clientes empresariais da Microsoft, ele deve fornecer uma maneira para os clientes "se inscreverem" ou "conectarem" o aplicativo aos dados da empresa. Durante o fluxo de conexão, um Administrador Global primeiro concede permissões de aplicativo diretamente ao aplicativo para que ele possa acessar os dados da empresa de forma não interativa, sem a presença de um usuário conectado. A maioria da lógica neste exemplo mostra como obter esse fluxo de conexão usando o ponto de extremidade de consentimento de administrador da plataforma de identidade.

Diagram shows UserSync App with three local items connecting to Azure, with Start dot Auth acquiring a token interactively to connect to Microsoft Entra ID, AccountController getting admin consent to connect to Microsoft Entra ID, and SyncController reading user to connect to Microsoft Graph.

Para obter mais informações sobre os conceitos usados neste exemplo, leia a documentação do protocolo de credenciais do cliente para a plataforma de identidade.

Clone ou faça o download deste repositório

No shell ou na linha de comando, digite este comando:

git clone https://github.com/Azure-Samples/active-directory-dotnet-daemon-v2.git

Ou baixe o exemplo em um arquivo zip.

Registar a aplicação

Este exemplo tem um projeto. Para registrar o aplicativo com seu locatário do Microsoft Entra, você pode:

Se você quiser usar a automação:

  1. No Windows, execute o PowerShell e vá para a raiz do diretório clonado.

  2. Execute este comando:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. Execute o script para criar seu aplicativo Microsoft Entra e configure o código do aplicativo de exemplo de acordo:

    .\AppCreationScripts\Configure.ps1

    Outras maneiras de executar scripts são descritas em Scripts de criação de aplicativos.

  4. Abra a solução Visual Studio e selecione Iniciar para executar o código.

Se você não quiser usar a automação, use as etapas nas seções a seguir.

Escolha o inquilino

Gorjeta

As etapas neste artigo podem variar ligeiramente com base no portal a partir do qual você começou.

  1. Entre no centro de administração do Microsoft Entra como pelo menos um desenvolvedor de aplicativos.

  2. Se você tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas.

  3. Navegue até Registros do aplicativo Identity>Applications>.

  4. Selecione Novo registo.

  5. Introduza um Nome para a sua aplicação, por exemplo dotnet-web-daemon-v2. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.

  6. Na seção Tipos de conta suportados, selecione Contas em qualquer diretório organizacional.

  7. Na seção Redirecionar URI (opcional), selecione Web na caixa de combinação e digite https://localhost:44316/ e https://localhost:44316/Account/GrantPermissions como Redirecionar URIs.

    Se houver mais de dois URIs de redirecionamento, você precisará adicioná-los na guia Autenticação mais tarde, depois que o aplicativo for criado com êxito.

  8. Selecione Registar para criar a aplicação.

  9. Na página Visão geral do aplicativo, localize o valor da ID do aplicativo (cliente) e registre-o para uso posterior. Você precisará dele para configurar o arquivo de configuração do Visual Studio para este projeto.

  10. Em Gerir, selecione Autenticação.

  11. Defina URL de logout do canal frontal como https://localhost:44316/Account/EndSession.

  12. Na seção Concessão implícita e fluxos híbridos, selecione Tokens de acesso e Tokens de ID. Este exemplo requer que o fluxo de concessão implícito seja habilitado para entrar no usuário e chamar uma API.

  13. Selecione Guardar.

  14. Em Gerenciar, selecione Certificados & segredos.

  15. Na seção Segredos do cliente, selecione Novo segredo do cliente.

  16. Insira uma descrição de chave (por exemplo, segredo do aplicativo).

  17. Selecione uma duração de chave em 1 ano, em 2 anos ou Nunca expira.

  18. Selecione Adicionar. Registre o valor da chave em um local seguro. Você precisará dessa chave posteriormente para configurar o projeto no Visual Studio.

  19. Em Gerenciar, selecione Permissões>de API Adicionar uma permissão.

  20. Na seção APIs da Microsoft comumente usadas, selecione Microsoft Graph.

  21. Na seção Permissões do aplicativo, verifique se as permissões corretas estão selecionadas: User.Read.All.

  22. Selecione Adicionar permissões.

Configurar o exemplo para usar seu locatário

Nas etapas a seguir, ClientID é o mesmo que "application ID" ou AppId.

Abra a solução no Visual Studio para configurar os projetos.

Configurar o projeto cliente

Se você usou os scripts de instalação, as seguintes alterações terão sido aplicadas para você.

  1. Abra o arquivo UserSync\Web.Config .
  2. Encontre a chave do aplicativo ida:ClientId. Substitua o valor existente pelo ID do aplicativo dotnet-web-daemon-v2 que foi gravado anteriormente.
  3. Encontre a chave do aplicativo ida:ClientSecret. Substitua o valor existente pela chave que você salvou durante a criação do aplicativo dotnet-web-daemon-v2 .

Executar o exemplo

Limpe a solução, reconstrua a solução, execute o aplicativo UserSync e entre como administrador no locatário do Microsoft Entra. Se você não tiver um locatário do Microsoft Entra para teste, siga estas instruções para obter um.

Quando inicia sessão, a aplicação pede-lhe primeiro permissão para iniciar sessão e ler o seu perfil de utilizador. Esse consentimento permite que o aplicativo garanta que você é um usuário comercial.

User consent

Em seguida, o aplicativo tenta sincronizar uma lista de usuários do seu locatário do Microsoft Entra, via Microsoft Graph. Se não for possível, ele pede que você (o administrador do locatário) conecte seu locatário ao aplicativo.

Em seguida, o aplicativo pede permissão para ler a lista de usuários em seu locatário.

Admin consent

Depois de conceder permissão, você será desconectado do aplicativo. Essa saída garante que todos os tokens de acesso existentes para o Microsoft Graph sejam removidos do cache de tokens. Quando você entrar novamente, o token novo obtido terá as permissões necessárias para fazer chamadas para o Microsoft Graph.

Quando você concede a permissão, o aplicativo pode consultar usuários a qualquer momento. Você pode verificar isso selecionando o botão Sincronizar usuários e atualizando a lista de usuários . Tente adicionar ou remover um usuário e ressincronizar a lista. (Mas note que o aplicativo sincroniza apenas a primeira página dos usuários.)

Sobre o código

O código relevante para este exemplo está nos seguintes arquivos:

  • App_Start\Startup.Auth.cs, Controllers\AccountController.cs: Entrada inicial. Em particular, as ações no controlador têm um atributo Authorization , que força o usuário a entrar. O aplicativo usa o fluxo de código de autorização para entrar no usuário.
  • Controllers\SyncController.cs: Sincronizando a lista de usuários com o armazenamento local na memória.
  • Controllers\UserController.cs: Exibindo a lista de usuários do armazenamento local na memória.
  • Controllers\AccountController.cs: Adquirindo permissões do administrador do locatário usando o ponto de extremidade de consentimento do administrador.

Recriar o aplicativo de exemplo

  1. No Visual Studio, crie um novo projeto Visual C#ASP.NET Web Application (.NET Framework ).
  2. Na próxima tela, escolha o modelo de projeto MVC . Adicione também referências de pasta e núcleo para API da Web, porque você adicionará um controlador de API da Web mais tarde. Deixe o modo de autenticação escolhido pelo projeto como padrão: Sem autenticação.
  3. Selecione o projeto na janela Gerenciador de Soluções e selecione a tecla F4.
  4. Nas propriedades do projeto, defina SSL Enabled como True. Observe as informações em URL SSL. Você precisará dele ao configurar o registro deste aplicativo no portal do Azure.
  5. Adicione o seguinte ASP.NET pacotes NuGet de middleware OWIN:
    • Microsoft.Owin.Security.ActiveDirectory
    • Microsoft.Owin.Security.Cookies
    • Microsoft.Owin.Host.SystemWeb
    • Microsoft.IdentityModel.Protocol.Extensions
    • Microsoft.Owin.Security.OpenIdConnect
    • Microsoft.Identity.Client
  6. Na pasta App_Start:
    1. Crie uma classe chamada Startup.Auth.cs.
    2. Remover . App_Start a partir do nome do namespace.
    3. Substitua o código da classe Startup pelo código do mesmo arquivo do aplicativo de exemplo. Certifique-se de tomar toda a definição de classe. A definição muda de Startup de classe pública para Startup de classe parcial pública.
  7. Em Startup.Auth.cs, resolva referências ausentes adicionando instruções usando como sugerido pelo Visual Studio IntelliSense.
  8. Clique com o botão direito do mouse no projeto, selecione Adicionar e, em seguida, selecione Classe.
  9. Na caixa de pesquisa, digite OWIN. A classe OWIN Startup aparece como uma seleção. Selecione-o e nomeie a classe Startup.cs.
  10. Em Startup.cs, substitua o código da classe Startup pelo código do mesmo arquivo do aplicativo de exemplo. Novamente, observe que a definição muda de Startup de classe pública para Startup de classe parcial pública.
  11. Na pasta Models, adicione uma nova classe chamada MsGraphUser.cs. Substitua a implementação pelo conteúdo do arquivo de mesmo nome do exemplo.
  12. Adicione um novo MVC 5 Controller - Instância vazia chamada AccountController. Substitua a implementação pelo conteúdo do arquivo de mesmo nome do exemplo.
  13. Adicione um novo MVC 5 Controller - instância vazia chamada UserController. Substitua a implementação pelo conteúdo do arquivo de mesmo nome do exemplo.
  14. Adicione um novo Web API 2 Controller - instância vazia chamada SyncController. Substitua a implementação pelo conteúdo do arquivo de mesmo nome do exemplo.
  15. Para a interface do usuário, na pasta Views\Account , adicione três instâncias Empty (sem modelo) Views chamadas GrantPermissions, Index e UserMismatch. Adicione e um índice chamado napasta Views\User . Substitua a implementação pelo conteúdo do arquivo de mesmo nome do exemplo.
  16. Atualize Shared_Layout.cshtml e Home\Index.cshtml para vincular corretamente os vários modos de exibição.

Implantar o exemplo no Azure

Este projeto tem projetos de aplicação web e API web. Para implantá-los em sites do Azure, execute as seguintes etapas para cada um:

  1. Crie um site do Azure.
  2. Publique o aplicativo Web e as APIs da Web no site.
  3. Atualize os clientes para chamar o site em vez do IIS Express.

Criar e publicar dotnet-web-daemon-v2 em um site do Azure

  1. Inicie sessão no portal do Azure.
  2. Selecione Criar um recurso no canto superior esquerdo.
  3. Selecione Web>App e, em seguida, dê um nome ao seu site. Por exemplo, nomeie-o dotnet-web-daemon-v2-contoso.azurewebsites.net.
  4. Selecione as informações para Assinatura, Grupo de recursos e Plano e local do serviço de aplicativo. OS é Windows, e Publish é Código.
  5. Selecione Criar e aguarde até que o serviço de aplicativo seja criado.
  6. Quando você receber a notificação Implantação bem-sucedida, selecione Ir para o recurso para ir para o serviço de aplicativo recém-criado.
  7. Depois que o site for criado, encontre-o no Painel e selecione-o para abrir a tela Visão geral do serviço de aplicativo.
  8. Na guia Visão geral do serviço de aplicativo, baixe o perfil de publicação selecionando o link Obter perfil de publicação e salve-o. Você pode usar outros mecanismos de implantação, como a implantação a partir do controle do código-fonte.
  9. Alterne para o Visual Studio e, em seguida:
    1. Vá para o projeto dotnet-web-daemon-v2 .
    2. Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Publicar.
    3. Selecione Importar perfil na barra inferior e importe o perfil de publicação que você baixou anteriormente.
  10. Selecione Configurar.
  11. Na guia Conexão, atualize a URL de destino para que ela use "https". Por exemplo, use https://dotnet-web-daemon-v2-contoso.azurewebsites.net. Selecione Seguinte.
  12. Na guia Configurações, verifique se Habilitar Autenticação Organizacional está desmarcado.
  13. Selecione Guardar. Selecione Publicar na tela principal.

O Visual Studio publicará o projeto e abrirá automaticamente um navegador para a URL do projeto. Se você vir a página da Web padrão do projeto, a publicação foi bem-sucedida.

Atualizar o registro do aplicativo de locatário do Microsoft Entra para dotnet-web-daemon-v2

  1. Volte para o centro de administração do Microsoft Entra e selecione o aplicativo dotnet-web-daemon-v2 em Registros de aplicativos.
  2. Na página Autenticação do seu aplicativo, atualize os campos URL de logout do canal frontal com o endereço do seu serviço. Por exemplo, use https://dotnet-web-daemon-v2-contoso.azurewebsites.net/Account/EndSession.
  3. No menu Marca, atualize o URL da página inicial para o endereço do seu serviço. Por exemplo, use https://dotnet-web-daemon-v2-contoso.azurewebsites.net.
  4. Guardar a configuração.
  5. Adicione a mesma URL na lista de valores do menu URIs de redirecionamento de autenticação>. Se você tiver várias URLs de redirecionamento, verifique se há uma nova entrada que usa o URI do serviço de aplicativo para cada URL de redirecionamento.

Clean up resources (Limpar recursos)

Quando não for mais necessário, exclua o objeto de aplicativo que você criou na etapa Registrar seu aplicativo . Para remover o aplicativo, siga as instruções em Remover um aplicativo criado por você ou sua organização.

Obter ajuda

Use as Perguntas e Respostas da Microsoft para obter suporte da comunidade. Faça as suas perguntas sobre as Perguntas e Respostas da Microsoft primeiro e procure os problemas existentes para ver se alguém já fez a sua pergunta antes. Certifique-se de que suas perguntas ou comentários estejam marcados com azure-ad-adal-deprecation, azure-ad-msale dotnet-standard."

Se você encontrar um bug no exemplo, levante a questão em Problemas do GitHub.

Se você encontrar um bug no MSAL.NET, levante a questão em MSAL.NET problemas do GitHub.

Para fornecer uma recomendação, vá para a página User Voice.

Próximos passos

Saiba mais sobre como criar aplicativos daemon que usam a plataforma de identidade da Microsoft para acessar APIs da Web protegidas:

Cenário: aplicativo Daemon que chama APIs da Web