Quickstart: Autenticar Utilizadores numa Aplicação de Internet ASP.NET Core

Neste guia inicial, irá criar uma aplicação web ASP.NET Core que permite aos utilizadores iniciar sessão com Microsoft Entra ID usando a Microsoft.Identity.Web. Podes ou estruturar um novo projeto a partir de um template ou adicionar autenticação a uma aplicação existente.

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

Pré-requisitos

• .NET 9 SDK
• Um inquilino Microsoft Entra ID
• Um registo de aplicação no seu locatário Microsoft Entra. Se precisar de criar uma, consulte Registar a sua candidatura.

Crie um projeto a partir do modelo

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

Execute os seguintes comandos para criar uma nova aplicação web com autenticação de uma única organização e navegue para o diretório do projeto:

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

O modelo gera um projeto com a Microsoft. Identity.Web já configurado. Só precisa de fornecer os detalhes de registo da sua aplicação.

Abra appsettings.json e substitua os valores provisórios pelo ID da Aplicação (cliente) e ID do Diretório (inquilino) do registo da sua aplicação:

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

Inicie a aplicação para verificar se o login funciona:

dotnet run

Navegue até https://localhost:5001 e selecione Iniciar sessão. Se aparecer um prompt para iniciar sessão da Microsoft, a configuração está correta.

Adicionar autenticação a uma aplicação web existente

Se tem uma aplicação ASP.NET Core existente, siga estes passos para adicionar login no Microsoft Entra.

Instalar pacotes NuGet

Adicionar as bibliotecas Microsoft.Identity.Web. O pacote Microsoft.Identity.Web trata da autenticação, e o Microsoft.Identity.Web.UI fornece componentes pré-construídos para iniciar e sair de sessão:

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 seguinte código regista a autenticação OpenID Connect com a Microsoft Entra, permite a aquisição de tokens para chamadas API a jusante e adiciona a interface de log-in/log-out:

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

Abre appsettings.json e adiciona a AzureAd secção. Substitua os valores provisórios pelo ID de Aplicação (cliente) do registo da sua aplicação. Defina TenantId para o público apropriado para a sua aplicação:

{
  "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 que contas podem iniciar sessão:

Proteja as suas páginas

Adicione o [Authorize] atributo a páginas ou controladores que exijam iniciar sessão.

Para as Razor Pages, o [Authorize] atributo redireciona os utilizadores não autenticados para a página de iniciação de sessão. Após iniciar sessão, as reivindicações do utilizador como Name e preferred_username estão disponíveis através do User objeto:

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 aplica-se ao nível do controlador ou 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 para iniciar sessão e sair

Adicione links de navegação ao seu layout para que os utilizadores possam iniciar e desconectar. As rotas da área MicrosoftIdentity são fornecidas pelo pacote Microsoft.Identity.Web.UI. A seguinte marcação Razor apresenta condicionalmente Logout ou Login com base no estado de autenticação do utilizador:

<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 a aplicação para verificar se a autenticação funciona:

dotnet run

Navegue até https://localhost:5001. Deverá ver um link Iniciar sessão. Selecione-o para confirmar que o fluxo de início de sessão da Microsoft foi concluído com sucesso.

Registe a aplicação

Se ainda não tem um registo de aplicação, siga estes passos para criar um no portal do Azure.

1. Inicie sessão no portal do Azure.
2. Navegue atéMicrosoft Entra ID>Registos de aplicações>Novo registo.
3. Insira um nome de exibição (por exemplo, "A Minha Aplicação Web").
4. Selecione os tipos de conta suportados:
   • Inquilino único — Apenas utilizadores na sua organização
   • Multi-inquilino — Utilizadores em qualquer organização
   • Multi-locatário + pessoal — Todas as contas Microsoft
5. Em Redirecionar URI, defina a plataforma para Web e introduza https://localhost:5001/signin-oidc.
6. Selecione Register.
7. Na página de visão geral, copie o ID da Aplicação (cliente) e o ID do Diretório (inquilino). Precisas destes valores para os campos ClientId e TenantId em appsettings.json.

Configurar definições opcionais

O seu cenário pode exigir estas definições adicionais.

Permitir a emissão de ID token — Alguns cenários de autenticação híbrida exigem que os ID tokens sejam emitidos diretamente a partir do endpoint de autorização. O fluxo de código de autorização (utilizado pela Microsoft. Identity.Web) é a abordagem recomendada. Ative esta definição apenas se o seu cenário a exigir especificamente.

1. No registo da sua aplicação, vá a Autenticação.
2. Em Concessão implícita e fluxos híbridos, selecione tokens ID.
3. Selecione Guardar.

Configurar o URL de logout da interface principal — Garante que os utilizadores ficam desconectados da sua aplicação quando saem da Microsoft Entra:

1. No registo da sua aplicação, vá a Autenticação.
2. Em URL de logout do canal dianteiro, introduza https://localhost:5001/signout-oidc.
3. Selecione Guardar.

Solucionar erros comuns

Caso encontre problemas durante o login, verifique estes erros comuns.

Conteúdo relacionado

• Chamar APIs a jusante a partir de aplicações web
• Authorization
• Visão geral da cache de tokens
• Quickstart: Web API