Início Rápido: Conectar usuários em um aplicativo Web ASP.NET Core

Neste início rápido, você criará um aplicativo Web ASP.NET Core que conectará usuários com Microsoft Entra ID usando Microsoft. Identity.Web. Você pode estruturar um novo projeto de um modelo ou adicionar autenticação a um aplicativo existente.

Se você não tiver um tenant do Microsoft Entra, crie uma conta gratuita antes de começar.

Pré-requisitos

• .NET 9 SDK
• Um tenant Microsoft Entra ID
• Um registro de aplicativo em seu locatário do Microsoft Entra. Se você precisar criar um, consulte Registrar seu aplicativo.

Criar um projeto com base no modelo

A maneira mais rápida de começar é criar um novo projeto com a autenticação pré-configurada.

Execute os seguintes comandos para criar um novo aplicativo Web com autenticação de organização única e navegue até o diretório do projeto:

dotnet new webapp --auth SingleOrg --name MyWebApp
cd MyWebApp

O modelo gera um projeto com Microsoft. Identity.Web já configurado. Você só precisa fornecer os detalhes do registro do aplicativo.

Abra appsettings.json e substitua os valores do espaço reservado pelo ID do aplicativo (cliente) e pelo ID do diretório (locatário) do registro do aplicativo:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "CallbackPath": "/signin-oidc"
  }
}

Inicie o aplicativo para verificar se o login funciona:

dotnet run

Navegue até https://localhost:5001 e selecione Entrar. Se um prompt de entrada Microsoft for exibido, a configuração estará correta.

Adicionar autenticação a um aplicativo Web existente

Se você tiver um aplicativo ASP.NET Core existente, siga estas etapas para integrar o login do Microsoft Entra.

Instalar os pacotes NuGet

Adicione as bibliotecas Microsoft.Identity.Web. O pacote Microsoft.Identity.Web manipula a autenticação e Microsoft.Identity.Web.UI fornece componentes de interface do usuário de entrada e saída predefinidos:

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.UI

Configurar serviços de autenticação

Abra Program.cs e adicione os serviços de autenticação. O código a seguir registra a autenticação do OpenID Connect com Microsoft Entra, habilita a aquisição de token para chamadas à API downstream e adiciona a interface do usuário de entrada/saída:

using Microsoft.Identity.Web;
using Microsoft.Identity.Web.UI;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApp(builder.Configuration, "AzureAd")
                .EnableTokenAcquisitionToCallDownstreamApi() // Optional: if calling APIs
                .AddInMemoryTokenCaches(); // For production, use distributed cache

// Add Razor Pages or MVC
builder.Services.AddRazorPages()
    .AddMicrosoftIdentityUI(); // Adds sign-in/sign-out UI

var app = builder.Build();

// Configure middleware
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

app.UseAuthentication(); //  Add authentication middleware
app.UseAuthorization();

app.MapRazorPages();
app.MapControllers();

app.Run();

Adicionar configuração do Microsoft Entra

Abra appsettings.json e adicione a AzureAd seção. Substitua os valores de espaço reservado pela ID do Aplicativo (cliente) do registro do aplicativo. Defina TenantId para o público-alvo apropriado para seu aplicativo:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "ClientId": "your-client-id-from-app-registration",
    "CallbackPath": "/signin-oidc"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "Information"
    }
  }
}

O TenantId valor determina quais contas podem entrar:

Proteger suas páginas

Adicione o [Authorize] atributo a páginas ou controladores que exigem entrada.

Para o Razor Pages, o [Authorize] atributo redireciona usuários não autenticados para a página de entrada. Após o login, as declarações do usuário, como Name e preferred_username, estão disponíveis através do objeto User:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc.RazorPages;

[Authorize] //  Require authentication
public class IndexModel : PageModel
{
    public void OnGet()
    {
        var userName = User.Identity?.Name;
        var userEmail = User.FindFirst("preferred_username")?.Value;
    }
}

Para controladores MVC, o mesmo [Authorize] atributo se aplica no nível do controlador ou da ação:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize] //  Require authentication
public class HomeController : Controller
{
    public IActionResult Index()
    {
        var userName = User.Identity?.Name;
        return View();
    }
}

Adicionar links de entrada e de saída

Adicione links de navegação ao layout para que os usuários possam entrar e sair. As rotas de área MicrosoftIdentity são fornecidas pelo pacote Microsoft.Identity.Web.UI. A marcação razor a seguir renderiza condicionalmente Sair ou Entrar com base no estado de autenticação do usuário:

<ul class="navbar-nav">
    @if (User.Identity?.IsAuthenticated == true)
    {
        <li class="nav-item">
            <span class="nav-link">Hello @User.Identity.Name!</span>
        </li>
        <li class="nav-item">
            <a class="nav-link" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignOut">Sign out</a>
        </li>
    }
    else
    {
        <li class="nav-item">
            <a class="nav-link" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignIn">Sign in</a>
        </li>
    }
</ul>

Executar e testar

Inicie o aplicativo para verificar se a autenticação funciona:

dotnet run

Navegue até https://localhost:5001. Você deve ver um link Entrar. Selecione-o para confirmar se o fluxo de entrada do Microsoft foi concluído com êxito.

Registre seu aplicativo

Se você ainda não tiver um registro de aplicativo, siga estas etapas para criar um no portal do Azure.

1. Entre no portal do Azure.
2. Navegue até Microsoft Entra ID>registros de aplicativo>Nova inscrição.
3. Insira um nome de exibição (por exemplo, "Meu Aplicativo Web").
4. Selecione os tipos de conta com suporte:
   • Tenant único – Somente usuários na sua organização
   • Multi-tenant – Usuários em qualquer organização
   • Multi-tenant + personal — Todas as contas Microsoft
5. Em URI de Redirecionamento, defina a plataforma como Web e insira https://localhost:5001/signin-oidc.
6. Selecione Registrar.
7. Na página de visão geral, copie a ID do Aplicativo (cliente) e a ID do Diretório (inquilino). Você precisa desses valores para os campos ClientIdTenantId em appsettings.json.

Configurar definições opcionais

Seu cenário pode exigir essas configurações adicionais.

Habilitar a emissão de token de ID — alguns cenários de autenticação híbrida exigem que os tokens de ID sejam emitidos diretamente do ponto de extremidade de autorização. O fluxo de código de autorização (usado por Microsoft. Identity.Web) é a abordagem recomendada. Habilite essa configuração somente se o cenário exigir especificamente:

1. No registro do aplicativo, vá para Autenticação.
2. Em Concessão implícita e fluxos híbridos, selecione Tokens de ID.
3. Clique em Salvar.

Configurar URL de logoff de front-channel — garante que os usuários sejam desconectados de sua aplicação quando saírem do Microsoft Entra.

1. No registro do aplicativo, vá para Autenticação.
2. Na URL de logout do front-channel, insira https://localhost:5001/signout-oidc.
3. Clique em Salvar.

Solucionar erros comuns

Se você encontrar problemas durante a entrada, verifique esses erros comuns.

Conteúdo relacionado

• Chamando APIs downstream de aplicativos Web
• Autorização
• Visão geral do cache de token
• Início Rápido: API Web