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

  • Artigo

Neste tutorial, você baixará e executará um aplicativo Web do daemon ASP.NET que demonstra como usar a concessão de credenciais de cliente do OAuth 2.0 para obter um token de acesso para chamar a API do Microsoft Graph.

Neste tutorial:

  • Integrar um aplicativo daemon à 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 você não tiver uma assinatura 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, confira Como obter um locatário do Microsoft Entra.
  • Uma ou mais contas de usuário no seu locatário. Este exemplo não funcionará com uma conta Microsoft. Caso você tenha se conectado com uma conta Microsoft e nunca tenha criado uma conta de usuário no 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 conectar usuários.

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

Já que o aplicativo é um aplicativo multilocatário para clientes empresariais da Microsoft, ele deve fornecer uma maneira para que os clientes "inscrevam" ou "conectem" 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 maneira não interativa, sem a presença de um usuário conectado. A maior parte da lógica neste exemplo mostra como alcançar esse fluxo de conexão usando a plataforma de identidade de ponto de extremidade de consentimento do administrador.

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 da plataforma de identidade.

Clonar ou baixar este 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.

Registre seu aplicativo

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

Se você quiser usar a automação:

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

  2. Execute este comando:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. Executar o script para criar o aplicativo do Microsoft Entra e configurar 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 aplicativo.

  4. Abra a solução do 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.

Escolher o locatário

Dica

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

  1. Faça login 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 de 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é Identidade>Aplicativos>Registros do aplicativo.

  4. Selecione Novo registro.

  5. Insira um Nome para seu aplicativo, 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 com suporte, escolha Contas em qualquer diretório organizacional.

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

    Se houver mais de dois URIs de redirecionamento, você precisará adicioná-los por meio da guia Autenticação posteriormente, depois que o aplicativo tiver sido criado com êxito.

  8. Selecione Registrar para criar o aplicativo.

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

  10. Em Gerenciar, selecione Autenticação.

  11. Defina URL de logoff de front-channel para 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ícita seja habilitado para conectar o usuário e chamar uma API.

  13. Selecione Salvar.

  14. Em Gerenciar, selecione Certificados e segredos.

  15. Na seção Segredos do Cliente, escolha Novo Segredo do Cliente.

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

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

  18. Selecione Adicionar. Registre o valor da chave em uma localização segura. 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 frequentemente utilizadas, selecione Microsoft Graph.

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

  22. Escolha Adicionar permissões.

Configurar a amostra para usar seu locatário

Nas etapas seguintes, ClientID é o mesmo que "ID do aplicativo" ou AppId.

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

Configurar o projeto do cliente

Se você tiver usado os scripts de instalação, as alterações a seguir terão sido aplicadas para você.

  1. Abra o arquivo UserSync\Web.Config.
  2. Localize a chave do aplicativo ida:ClientId. Substitua o valor existente pela ID do aplicativo dotnet-web-daemon-v2 já registrado.
  3. Localize 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.

Execute o exemplo

Limpar e recompilar a solução, executar o aplicativo UserSync e entrar como administrador no seu locatário do Microsoft Entra. Caso você não tenha um locatário do Microsoft Entra para teste, siga estas instruções para obter um.

Quando você entrar, o aplicativo primeiro solicitará permissão para realizar esse processo e para ler seu perfil do usuário. Esse consentimento permite ao aplicativo ter a certeza de que você é um usuário empresarial.

User consent

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

O aplicativo pedirá então permissão para ler a lista de usuários em seu locatário.

Admin consent

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

Quando você concede a permissão, o aplicativo pode consultar os usuários em 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 observe que o aplicativo sincroniza apenas a primeira página de usuários).

Observações sobre o código

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

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

Recriar o aplicativo de exemplo

  1. No Visual Studio, crie um projeto em Visual C#aplicativo Web ASP .NET (.NET Framework).
  2. Na próxima tela, escolha o modelo de projeto MVC. Além disso, adicione referências de pasta e núcleo para a API Web, pois você adicionará um controlador de API Web mais tarde. Deixe o modo de autenticação escolhido do projeto como o padrão: Sem autenticação.
  3. Selecione o projeto na janela do Gerenciador de Soluções e selecione a tecla F4.
  4. Nas propriedades do projeto, defina Habilitado para SSL como True. Observe as informações em URL de SSL. Você precisará dessas informações ao configurar o registro do aplicativo no portal do Azure.
  5. Adicione os seguintes pacotes NuGet do middleware ASP.NET OWIN:
    • Microsoft.Owin.Security.ActiveDirectory
    • Microsoft.Owin.Security
    • 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. Remova .App_Start do nome do namespace.
    3. Substitua o código da classe Startup pelo código do mesmo arquivo do aplicativo de exemplo. Verifique se você obteve toda a definição de classe. A definição muda de Inicialização de classe pública para Inicialização de classe parcial pública.
  7. Em Startup.Auth.cs, resolva as referências ausentes adicionando instruções using conforme sugerido pelo IntelliSense do Visual Studio.
  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 de inicialização OWIN aparece como uma seleção. Selecione-a 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 Inicialização de classe pública para Inicialização de classe parcial pública.
  11. Na pasta Modelos, adicione uma nova classe chamada MsGraphUser.cs. Substitua a implementação pelo conteúdo do arquivo com o mesmo nome do exemplo.
  12. Adicione uma nova instância da MVC 5 Controller – Vazia chamada AccountController. Substitua a implementação pelo conteúdo do arquivo com o mesmo nome do exemplo.
  13. Adicione uma nova instância da MVC 5 Controller – Vazia chamada UserController. Substitua a implementação pelo conteúdo do arquivo com o mesmo nome do exemplo.
  14. Adicione uma nova instância da API Web 2 Controller – Vazia chamada SyncController. Substitua a implementação pelo conteúdo do arquivo com o mesmo nome do exemplo.
  15. Para a interface do usuário, na pasta Views\Account, adicione três instâncias de Exibições vazias (sem modelo) chamadas GrantPermissions, Index e UserMismatch. Adicione a chamada Index na pasta Views\User. Substitua a implementação pelo conteúdo do arquivo com o mesmo nome do exemplo.
  16. Atualize Shared_Layout.cshtml e Home\Index.cshtml para vincular corretamente várias exibições juntas.

Implantar o exemplo no Azure

Este projeto tem projetos de API Web e aplicativo 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 Web no site.
  3. Atualize os clientes para chamarem o site em vez de IIS Express.

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

  1. Entre no portal do Azure.
  2. No canto superior esquerdo, selecione Criar um recurso.
  3. Selecione Web>Aplicativo Web e 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 do serviço de aplicativo e local. O SO é Windows e a Publicação é Código.
  5. Clique em Criar e aguarde até que o serviço de aplicativo seja criado.
  6. Quando você obtiver a notificação de Implantação bem-sucedida, selecione Ir para o recurso para acessar o serviço de aplicativo recém-criado.
  7. Depois que o site for criado, localize-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 por meio de controle do código-fonte.
  9. Alterne para o Visual Studio e, em seguida:
    1. Acesse 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 Avançar.
  12. Na guia Configurações, verifique se Habilitar Autenticação Organizacional está desmarcada.
  13. Clique em Salvar. Selecione Publicar na tela principal.

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

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

  1. Volte ao centro de administração do Microsoft Entra e selecione o aplicativo dotnet-web-daemon-v2 em Registros de aplicativo.
  2. Na página Autenticação do seu aplicativo, atualize os campos de URL de logoff de front-channel com o endereço do seu serviço. Por exemplo, use https://dotnet-web-daemon-v2-contoso.azurewebsites.net/Account/EndSession.
  3. No menu de Identidade Visual, atualize a URL da página inicial para o endereço do serviço. Por exemplo, use https://dotnet-web-daemon-v2-contoso.azurewebsites.net.
  4. Salve a configuração.
  5. Adicione a mesma URL na lista de valores do menu Autenticação>URIs de Redirecionamento. 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.

Limpar os recursos

Quando não for mais necessário, exclua o objeto de aplicativo criado 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 o Microsoft Q&A para obter suporte da comunidade. Faça suas perguntas primeiro no Microsoft Q&A e navegue pelos problemas existentes para ver se alguém já fez sua pergunta antes. Verifique se as perguntas ou os comentários estão marcados com azure-ad-adal-deprecation, azure-ad-msal e dotnet-standard.

Se você encontrar um bug no exemplo, crie um registro do problema em Problemas do GitHub.

Se você encontrar um bug no MSAL.NET, crie um registro do problema em Problemas do GitHub no MSAL.NET.

Para fornecer uma recomendação, acesse a página Voz do Usuário.

Próximas etapas

Saiba mais sobre a criação de aplicativos daemon que usam a plataforma de identidade da Microsoft para acessar APIs Web protegidas:

Cenário: Aplicativo daemon que chama APIs Web