Quickstart: Proteger uma Web API ASP.NET Core

Neste início rápido, protege uma API web ASP.NET Core com o Microsoft Entra ID usando o Microsoft.Identity.Web. Adiciona-se middleware de autenticação que valida os tokens portadores e restringe o acesso a chamadores autorizados.

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

Pré-requisitos

Opção 1: Criar a partir do modelo (mais rápido)

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

1. Crie o projeto

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

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

2. Configurar o registo da aplicação

Substitua os valores provisórios em appsettings.json pelos detalhes de registo da sua Microsoft Entra app:

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

3. Executar a API

Inicie a candidatura:

dotnet run

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

Feito! Os pedidos agora requerem um token de acesso válido.

Opção 2: Adicionar à Web API existente

Se já tem uma API web ASP.NET Core, adicione autenticação Microsoft Entra com os seguintes passos.

1. Instalar o pacote NuGet

Adicione o pacote Microsoft.Identity.Web NuGet ao seu projeto.

dotnet add package Microsoft.Identity.Web

2. Configurar autenticação em Program.cs

Registe os serviços de autenticação e autorização no pipeline de arranque da sua aplicação. O seguinte código configura a autenticação do 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 secção de configuração do Microsoft Entra com os detalhes do seu tenant e da aplicação. Defina o nível de registo para Microsoft.Identity.Web para Information para ajudar a resolver problemas de validação de tokens:

{
  "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 os seus endpoints 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 endpoints:

O controlador seguinte requer um token de acesso válido para todas as ações e mostra como aceder às reivindicações dos utilizadores:

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"
        });
    }
}

Requerer escopos específicos:

Use o [RequiredScope] atributo para impor permissões detalhadas 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 a candidatura e verifique se os pedidos não autenticados são rejeitados:

dotnet run

Teste com uma ferramenta como o Postman ou curl. Um pedido não autenticado devolve 401 Unauthorized:

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

Sucesso! A sua API agora valida tokens portadores.

Configuração do registo de aplicações

Antes de a sua API validar tokens, precisa de um registo na aplicação Microsoft Entra. Siga estes passos no portal Azure.

1. Registe a sua API

  1. Iniciar sessão no portal Azure
  2. Navegue até Microsoft Entra ID>Registos de aplicações>Novo registo
  3. Insira um nome (por exemplo, "A Minha Web API")
  4. Selecionar Inquilino único (mais comum para APIs)
  5. Não é necessário URI de redirecionamento para APIs
  6. Clique em Registar

2. Expor um âmbito de API

Defina as permissões (scopes) que as aplicações clientes podem solicitar ao chamar a sua API.

  1. No registo da sua aplicação API, vá a Expose uma API
  2. Clique em Adicionar um âmbito
  3. Aceite o URI padrão do ID da aplicação ou personalize-o (por exemplo, api://your-api-client-id)
  4. Adicione um escopo:
    • Nome do âmbito:access_as_user
    • Quem pode consentir: Administradores e utilizadores
    • Nome de visualização do consentimento do administrador: "Aceder à minha API Web"
    • Descrição do consentimento do administrador: "Permite à aplicação aceder à API web em nome do utilizador iniciado sessão"
  5. Clique em Adicionar âmbito

3. Note o ID da aplicação

Copie o ID da Aplicação (cliente) da página de visão geral do registo da aplicação. Este valor é o seu ClientId em appsettings.json.

Criar um registo de aplicação cliente (para testes)

Para testar a sua API protegida, registe uma aplicação cliente separada que adquira tokens e chame a API.

1. Registar uma aplicação cliente

  1. Em Microsoft Entra ID>Registos de aplicações, crie outro registro
  2. Nomeia-o (por exemplo, "O Meu Cliente API")
  3. Selecionar tipos de contas
  4. Adicionar URI de redirecionamento: https://localhost:7000/signin-oidc (se for uma aplicação web)
  5. Clique em Registar

2. Conceder permissões de API

Conceda à aplicação cliente permissão para chamar a sua API com os escopos que definiu.

  1. No registo da aplicação cliente, vá a permissões API
  2. Clique em Adicionar uma permissão>As Minhas APIs
  3. Selecione o registo da sua API
  4. Verifica o access_as_user alcance
  5. Clique em Adicionar permissões
  6. Clique em Conceder consentimento de administrador (se necessário)

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

Se a sua aplicação cliente correr num servidor (não num navegador ou dispositivo móvel), crie um segredo cliente para autenticação.

  1. Ir para Certificados & segredos
  2. Clique em Novo segredo de cliente
  3. Adicionar uma descrição e uma expiração
  4. Clique em Adicionar
  5. Copie imediatamente o valor secreto – não poderá voltar a vê-lo

Teste a sua API protegida

Verifique se a sua API valida corretamente os tokens enviando pedidos autenticados.

Usando o Postman

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

  1. Criar um novo pedido no Postman
  2. Configurar autenticação OAuth 2.0:
    • Tipo de Subsídio: Código de Autorização (para contexto do utilizador) ou Credenciais do Cliente (para contexto da aplicação)
    • 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 de cliente da sua aplicação cliente
    • Segredo do Cliente: O segredo da sua aplicação cliente
    • Âmbito:api://your-api-client-id/access_as_user
  3. Clique em Obter Novo Token de Acesso
  4. Use o token para chamar a sua API

Usar código (exemplo C#)

O exemplo seguinte utiliza o 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 de configuração comuns

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

Exigir escopos específicos na configuração

Em vez de usar o [RequiredScope] atributo, 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 múltiplos locatários

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

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

Configurar a validação do token

Se a sua API chamar APIs a jusante (como a Microsoft Graph), ative a aquisição de tokens e configure uma cache de tokens:

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

Passos seguintes

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

Troubleshooting

401 Não autorizado

Problema: A API devolve 401 mesmo com um token.

Causas possíveis:

  • A destinatário do token (aud declaração) não corresponde ao da sua API ClientId
  • O token está expirado
  • Token está associado ao tenant errado
  • Falta o âmbito exigido

Solução: Decifra o token no jwt.ms e verifica as reivindicações. Consulte Registo e Diagnóstico para resolução de problemas detalhada.

AADSTS50013: Assinatura inválida

Problema: A validação da assinatura do token falha.

Solução: Certifique-se de que o TenantId e o ClientId estão corretos. O token deve ser emitido pela autoridade esperada. Ative o registo detalhado para ver erros de validação.

Osciloscópios não encontrados em token

Problema:[RequiredScope] O atributo falha.

Solution:

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

Ver mais:Guia de Resolução de Problemas da Web API

Conteúdo relacionado

  • Last updated on