Início Rápido: Conectar usuários e chamar a API do Microsoft Graph de um aplicativo web do ASP.NET

  • Artigo

Neste início rápido, você baixará e executará um exemplo de código que demonstra um aplicativo web ASP.NET que pode conectar usuários com contas do Microsoft Entra.

Confira Como o exemplo funciona para ver uma ilustração.

Pré-requisitos

Registrar e baixar o aplicativo

Dica

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

Você tem duas opções para começar a criar o seu aplicativo: configuração automática ou manual.

Configuração automática

Se você quiser configurar automaticamente o seu aplicativo e baixar o exemplo de código, siga estas etapas:

  1. Entre na experiência de início rápido do centro de administração do Microsoft Entra como, pelo menos, um Administrador de Aplicativo de Nuvem.
  2. Insira um nome para seu aplicativo e selecione Registrar.
  3. Siga as instruções para baixar e configurar automaticamente o novo aplicativo com apenas um clique.

Configuração manual

Se você quiser configurar manualmente o seu aplicativo e o exemplo de código, use os procedimentos a seguir.

Etapa 1: Registre seu aplicativo

  1. Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
  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 de aplicativos e selecione Novo registro.
  4. Em Nome, insira um nome para o seu aplicativo. Por exemplo, insira ASPNET-Quickstart. Os usuários do seu aplicativo verão esse nome e você pode alterá-lo mais tarde.
  5. Defina o tipo de URI de Redirecionamento como Web e valor como https://localhost:44368/.
  6. Selecione Registrar.
  7. Em Gerenciar, selecione Autenticação.
  8. Na seção Concessão implícita e fluxos híbridos, selecione Tokens de ID.
  9. Clique em Salvar.

Etapa 2: Baixe o projeto

Baixar o exemplo de código do ASP.NET

Dica

Para evitar erros causados por limitações de comprimento do caminho no Windows, é recomendável extrair os arquivos em um diretório próximo à raiz da unidade.

Etapa 3: Executar o projeto

  1. Extraia o arquivo. zip em uma pasta local próxima à pasta raiz. Por exemplo, extraia em C:\Azure-Samples.

    É recomendável extrair os arquivos em um diretório próximo à raiz da unidade para evitar erros causados por limitações de comprimento do caminho no Windows.

  2. Abra a solução no Visual Studio (AppModelv2-WebApp-OpenIDConnect-DotNet.sln).

  3. Dependendo da versão do Visual Studio, pode ser necessário clicar com o botão direito do mouse no projeto AppModelv2-WebApp-OpenIDConnect-DotNet e selecionar Restaurar os pacotes do NuGet.

  4. Abra o Console do Gerenciador de Pacotes selecionando Exibir>Outras Janelas>Console do Gerenciador de Pacotes. Em seguida, execute Update-Package Microsoft.CodeDom.Providers.DotNetCompilerPlatform -r.

  5. Edite appsettings.json e substitua os parâmetros ClientId, Tenant e redirectUri por:

    "ClientId" :"Enter_the_Application_Id_here" />
"TenantId": "Enter_the_Tenant_Info_Here" />
"RedirectUri" :"https://localhost:44368/" />

    Neste código:

    • Enter_the_Application_Id_here é a ID do aplicativo (cliente) do registro do aplicativo que você criou anteriormente. Localize a ID do aplicativo (cliente) na página Visão Geral do aplicativo em Registros de aplicativo no centro de administração do Microsoft Entra.
    • Enter_the_Tenant_Info_Here é uma das seguintes opções:
      • Se o seu aplicativo dá suporte a Somente minha organização, substitua esse valor pela ID do diretório (locatário) ou pelo nome do locatário (por exemplo, contoso.onmicrosoft.com). Localize a ID do diretório (locatário) na página Visão Geral do aplicativo em Registros de aplicativo no centro de administração do Microsoft Entra.
      • Se o aplicativo der suporte para Contas em qualquer diretório organizacional, substitua esse valor por organizations.
      • Se o aplicativo der suporte a Todos os usuários de contas Microsoft, substitua esse valor por common.
    • redirectUri é o URI de redirecionamento que você inseriu anteriormente em Registros de aplicativo no centro de administração do Microsoft Entra.

Mais informações

Esta seção apresenta uma visão geral do código necessário para a entrada de usuários. Essa visão geral pode ser útil para entender como o código funciona, quais são os argumentos principais e como adicionar credenciais a um aplicativo ASP.NET existente.

Como o exemplo funciona

O diagrama da interação entre o navegador da Web, o aplicativo Web e a plataforma de identidade da Microsoft no aplicativo de exemplo.

Pacotes do NuGet de middleware OWIN

Você pode configurar o pipeline de autenticação com a autenticação baseada em cookies usando o OpenID Connect no ASP.NET com pacotes de middleware OWIN. Você pode instalar esses pacotes executando os seguintes comandos no Console do Gerenciador de Pacotes no Visual Studio:

Install-Package Microsoft.Identity.Web.Owin
Install-Package Microsoft.Identity.Web.GraphServiceClient
Install-Package Microsoft.Owin.Security.Cookies

Classe de inicialização do OWIN

O middleware OWIN usa uma classe de inicialização que é executada quando o processo de hospedagem é iniciado. Neste guia de início rápido, o arquivo startup.cs está na pasta raiz. O seguinte código mostra os parâmetros usados neste guia de início rápido:

    public void Configuration(IAppBuilder app)
    {
        app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

        app.UseCookieAuthentication(new CookieAuthenticationOptions());
        OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

        app.AddMicrosoftIdentityWebApp(factory);
        factory.Services
            .Configure<ConfidentialClientApplicationOptions>(options => { options.RedirectUri = "https://localhost:44368/"; })
            .AddMicrosoftGraph()
            .AddInMemoryTokenCaches();
        factory.Build();
    }
Where Descrição
ClientId A ID do aplicativo registrado no portal do Azure.
Authority O ponto de extremidade do STS (serviço de token de segurança) para o usuário se autenticar. Geralmente, ele é https://login.microsoftonline.com/{tenant}/v2.0 para a nuvem pública. Nessa URL, {tenant} é o nome do seu locatário, da ID do locatário ou de common para uma referência ao ponto de extremidade comum. (O ponto de extremidade comum é usado para aplicativos multilocatários.)
RedirectUri A URL para a qual os usuários são enviados após a autenticação na plataforma de identidade da Microsoft.
PostLogoutRedirectUri A URL para a qual os usuários são enviados após saírem.
Scope A lista de escopos que estão sendo solicitados, separados por espaços.
ResponseType A solicitação da resposta da autenticação contém um código de autorização e um token de ID.
TokenValidationParameters Uma lista de parâmetros para validação de token. Nesse caso, ValidateIssuer é definido como false para indicar que ele pode aceitar entradas de todos os tipos de conta corporativa ou de estudante ou pessoal.
Notifications Uma lista de delegados que podem ser executados em mensagens OpenIdConnect.

Desafio de autenticação

Você pode forçar um usuário a entrar solicitando um desafio de autenticação em seu controlador:

public void SignIn()
{
    if (!Request.IsAuthenticated)
    {
        HttpContext.GetOwinContext().Authentication.Challenge(
            new AuthenticationProperties{ RedirectUri = "/" },
            OpenIdConnectAuthenticationDefaults.AuthenticationType);
    }
}

Dica

Solicitar um desafio de autenticação usando esse método é opcional. Normalmente, você o usaria quando quisesse que uma exibição fosse acessível de usuários autenticados e não autenticados. Como alternativa, você pode proteger os controladores usando o método descrito na próxima seção.

Atributo para proteger um controlador ou ações do controlador

Você pode proteger um controlador ou ações do controlador usando o atributo [Authorize]. Esse atributo restringe o acesso ao controlador ou às ações permitindo que apenas usuários autenticados acessem as ações no controlador. Um desafio de autenticação ocorrerá automaticamente quando um usuário não autenticado tentar acessar uma das ações ou controladores decorados pelo atributo [Authorize].

Chamar o Microsoft Graph pelo controlador

Você pode chamar o Microsoft Graph pelo controlador obtendo a instância do GraphServiceClient usando o método de extensão GetGraphServiceClient no controlador, como no código a seguir:

    try
    { 
        var me = await this.GetGraphServiceClient().Me.GetAsync();
        ViewBag.Username = me.DisplayName;
    }
    catch (ServiceException graphEx) when (graphEx.InnerException is MicrosoftIdentityWebChallengeUserException)
    {
        HttpContext.GetOwinContext().Authentication.Challenge(OpenIdConnectAuthenticationDefaults.AuthenticationType);
        return View();
    }

Ajuda e suporte

Se precisar de ajuda, quiser relatar um problema ou desejar saber mais sobre as opções de suporte, confira Ajuda e suporte para desenvolvedores.

Próximas etapas

Para obter um guia passo a passo completo sobre a criação de aplicativos e novos recursos, incluindo uma explicação completa deste guia de início rápido, experimente o tutorial do ASP.NET.

Adicionar a entrada a um aplicativo Web ASP.NET