Guia Rápido: Proteger uma API Web ASP.NET Core

Neste início rápido, você protege uma API Web ASP.NET Core com Microsoft Entra ID usando Microsoft. Identity.Web. Você adiciona middleware de autenticação que valida tokens de portador e restringe o acesso a chamadores autorizados.

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

Pré-requisitos

Opção 1: Criar com base no modelo (mais rápido)

Use o modelo de ASP.NET Core com autenticação Microsoft Entra interna para estruturar um projeto de API protegido.

1. Criar o projeto

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

dotnet new webapi --auth SingleOrg --name MyWebApi
cd MyWebApi

2. Configurar o registro do aplicativo

Substitua os valores de espaço reservado em appsettings.json pelos detalhes de registro do aplicativo Microsoft Entra:

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

3. Executar a API

Inicie o aplicativo:

dotnet run

Sua API agora está protegida em https://localhost:5001.

Concluído! As solicitações agora exigem um token de acesso válido.

Opção 2: Adicionar à API Web existente

Se você já tiver uma API Web ASP.NET Core, adicione Microsoft Entra autenticação com as etapas a seguir.

1. Instalar o pacote NuGet

Adicione o Microsoft. Pacote NuGet Identity.Web para seu projeto:

dotnet add package Microsoft.Identity.Web

2. Configurar a autenticação em Program.cs

Registre os serviços de autenticação e autorização no pipeline de inicialização do aplicativo. O código a seguir configura a autenticação de portador JWT com validação Microsoft Entra.

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(builder.Configuration, "AzureAd");

// Add authorization
builder.Services.AddAuthorization();

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

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

app.MapControllers();

app.Run();

3. Adicionar configuração a appsettings.json

Adicione a seção de configuração Microsoft Entra com os detalhes do locatário e do aplicativo. Defina o nível de log para Microsoft.Identity.Web como Information para ajudar a solucionar problemas de validação de token:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "Information"
    }
  }
}

4. Proteger seus pontos de extremidade de API

Aplique o [Authorize] atributo a controladores ou ações que exijam um token de acesso válido.

Exigir autenticação para todos os pontos de extremidade:

O controlador a seguir requer um token de acesso válido para todas as ações e mostra como acessar declarações de usuário:

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

[Authorize] //  Require valid access token
[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        // Access user information
        var userId = User.FindFirst("oid")?.Value;
        var userName = User.Identity?.Name;

        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = "Protected data"
        });
    }
}

Exigir escopos específicos:

Use o [RequiredScope] atributo para impor permissões refinadas em ações individuais:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Identity.Web;

[Authorize]
[ApiController]
[Route("api/[controller]")]
public class TodoController : ControllerBase
{
    [HttpGet]
    [RequiredScope("access_as_user")] //  Require specific scope
    public IActionResult GetAll()
    {
        return Ok(new[] { "Todo 1", "Todo 2" });
    }

    [HttpPost]
    [RequiredScope("write")] //  Different scope for write operations
    public IActionResult Create([FromBody] string item)
    {
        return Created("", item);
    }
}

5. Executar e testar

Inicie o aplicativo e verifique se as solicitações não autenticadas foram rejeitadas:

dotnet run

Teste utilizando uma ferramenta como Postman ou curl. Uma solicitação não autenticada retorna 401 Unauthorized:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://localhost:5001/api/weatherforecast

Êxito! Sua API agora valida tokens de portador.

Configuração de registro de aplicativo

Antes que sua API possa validar tokens, você precisa de um registro de aplicativo Microsoft Entra. Siga estes passos no portal do Azure.

Registre sua API

  1. Entre no portal Azure
  2. Navegue até Microsoft Entra ID>Registros de aplicativo>Novo registro
  3. Insira um nome (por exemplo, "Minha API Web")
  4. Selecionar locatário único (mais comum para APIs)
  5. Nenhum URI de redirecionamento necessário para APIs
  6. Clique em Registrar

2. Expor um escopo de API

Defina as permissões (escopos) que os aplicativos cliente podem solicitar ao chamar sua API.

  1. No registro do aplicativo de API, vá para Expor uma API
  2. Clique em Adicionar um escopo
  3. Aceite o URI da ID do Aplicativo padrão ou personalize-o (por exemplo, api://your-api-client-id)
  4. Adicione um escopo:
    • Nome do escopo:access_as_user
    • Quem pode consentir: Administradores e usuários
    • Nome de exibição de consentimento do administrador: "Acessar minha API Web"
    • Descrição do consentimento do administrador: "Permite que o aplicativo acesse a API Web em nome do usuário conectado"
  5. Clique em Adicionar escopo

3. Observe a ID do aplicativo

Copie a ID do aplicativo (cliente) da página de resumo do registro do aplicativo. Esse valor é seu ClientId em appsettings.json.

Criar um registro de aplicativo cliente (para teste)

Para testar sua API protegida, registre um aplicativo cliente separado que adquira tokens e chame a API.

1. Registrar um aplicativo cliente

  1. Em Microsoft Entra ID>Registros de aplicativo, crie outro registro
  2. Nomeie-o (por exemplo, "Meu cliente de API")
  3. Selecionar tipos de conta
  4. Adicionar URI de redirecionamento: https://localhost:7000/signin-oidc (se for um aplicativo Web)
  5. Clique em Registrar

2. Conceder permissões de API

Conceda ao aplicativo cliente permissão para chamar sua API com os escopos definidos.

  1. No registro do aplicativo cliente, acesse as permissões de API
  2. Clique em Adicionar uma permissão>Minhas APIs
  3. Selecione seu registro de API
  4. Verifique o escopo access_as_user
  5. Clique em Adicionar permissões
  6. Clique em Conceder consentimento do administrador (se necessário)

3. Criar um segredo do cliente (para clientes confidenciais)

Se o aplicativo cliente for executado em um servidor (não em um navegador ou dispositivo móvel), crie um segredo do cliente para autenticação.

  1. Vá para Certificados e segredos
  2. Clique em Novo segredo do cliente
  3. Adicionar uma descrição e data de expiração
  4. Clique em Adicionar
  5. Copie o valor do segredo imediatamente - você não poderá vê-lo novamente

Testar sua API protegida

Verifique se a API valida corretamente os tokens enviando solicitações autenticadas.

Usando o Postman

Configure a autenticação OAuth 2.0 no Postman para adquirir um token e chamar sua API.

  1. Criar uma nova solicitação no Postman
  2. Configurar a autenticação do OAuth 2.0:
    • Tipo de concessão: Código de autorização (para contexto do usuário) ou Credenciais do Cliente (para contexto de aplicativo)
    • URL de autenticação:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
    • URL do Token de Acesso:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
    • ID do cliente: ID do aplicativo cliente
    • Segredo do cliente: O segredo do aplicativo cliente
    • Âmbito:api://your-api-client-id/access_as_user
  3. Clique em Obter Novo Token de Acesso
  4. Use o token para chamar sua API

Usando código (exemplo de C#)

O exemplo a seguir usa MSAL.NET para adquirir um token com o fluxo de credenciais do cliente e chamar a API protegida:

// In a console app or client application
using Microsoft.Identity.Client;

var app = ConfidentialClientApplicationBuilder
    .Create("client-app-id")
    .WithClientSecret("client-secret")
    .WithAuthority("https://login.microsoftonline.com/{tenant-id}")
    .Build();

var result = await app.AcquireTokenForClient(
    new[] { "api://your-api-client-id/.default" }
).ExecuteAsync();

var accessToken = result.AccessToken;

// Use the token to call your API
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.GetAsync("https://localhost:5001/api/weatherforecast");

Opções comuns de configuração

Microsoft. O Identity.Web dá suporte a vários padrões de configuração para cenários diferentes.

Exigir escopos específicos na configuração

Em vez de usar o [RequiredScope] atributo, você pode configurar os escopos necessários globalmente em appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id",
    "Scopes": "access_as_user"
  }
}

Aceitar tokens de vários locatários

Para aceitar tokens de qualquer locatário Microsoft Entra, defina TenantId como common:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "ClientId": "your-api-client-id"
  }
}

Configurar a validação de token

Se a API chamar APIs downstream (como Microsoft Graph), habilite a aquisição de token e configure um cache de token:

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi() // If your API calls other APIs
    .AddInMemoryTokenCaches();

Próximas Etapas 

Agora que você tem uma API protegida, explore estes tópicos:

Solução de problemas

401 Não autorizado

Problema: A API retorna 401 mesmo com um token.

Causas possíveis::

  • O público-alvo do token (aud declaração) não corresponde à sua API ClientId
  • O token expirou
  • O token é para o locatário errado
  • O escopo necessário está ausente

Solução: Decodificar o token em jwt.ms e verificar as declarações. Consulte Registros & Diagnósticos para obter uma solução detalhada de problemas.

AADSTS50013: Assinatura inválida

Problema: Falha na validação da assinatura de token.

Solução: Verifique se o seu TenantId e ClientId estão corretos. O token deve ser emitido pela autoridade esperada. Habilite o log detalhado para ver erros de validação.

Escopos não encontrados no token

Problema:[RequiredScope] falha no atributo.

Solution:

  1. Verificar se o aplicativo cliente tem permissão para o escopo
  2. Verifique se o consentimento do administrador foi concedido (se necessário)
  3. Consulte o Guia de Autorização para obter padrões completos de validação de escopo
  4. Verifique se o escopo é solicitado ao adquirir o token (por exemplo, api://your-api/.default ou escopos específicos)

Veja mais:Guia de solução de problemas da API Web

Conteúdo relacionado

  • Last updated on