Inicio rápido: Protección de una API web de ASP.NET Core

En este inicio rápido, protegerá una API web de ASP.NET Core con Microsoft Entra ID mediante Microsoft. Identity.Web. Agregue middleware de autenticación que valide los tokens portador y restrinja el acceso a las llamadas autorizadas.

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

Prerrequisitos

Opción 1: Crear a partir de una plantilla (más rápida)

Utiliza la plantilla de ASP.NET Core con autenticación Microsoft Entra integrada para crear un proyecto de API protegido.

1. Creación del proyecto

Ejecute los siguientes comandos para crear un nuevo proyecto de API web con autenticación de una sola organización y vaya al directorio del proyecto:

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

2. Configurar el registro de aplicaciones

Reemplaza los valores de marcador de posición en appsettings.json con los detalles de registro de tu aplicación de Microsoft Entra:

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

3. Ejecución de la API

Inicie la aplicación:

dotnet run

La API ahora está protegida en https://localhost:5001.

¡Listo! Las solicitudes ahora requieren un token de acceso válido.

Opción 2: Agregar a la API web existente

Si ya tiene una API web de ASP.NET Core, agregue Microsoft Entra autenticación con los pasos siguientes.

1. Instalación del paquete NuGet

Agregue el paquete Microsoft.Identity.Web de NuGet a su proyecto.

dotnet add package Microsoft.Identity.Web

2. Configurar la autenticación en Program.cs

Registre los servicios de autenticación y autorización en la canalización de inicio de la aplicación. El siguiente código configura la autenticación del portador JWT con la validación de 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. Agregar configuración a appsettings.json

Agregue la sección de configuración de Microsoft Entra con los detalles de su inquilino y su aplicación. Establezca el nivel de registro de Microsoft.Identity.Web en Information para ayudar a solucionar problemas de validación 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. Protección de los puntos de conexión de API

Aplique el [Authorize] atributo a controladores o acciones que requieren un token de acceso válido.

Requerir autenticación para todos los puntos de conexión:

El controlador siguiente requiere un token de acceso válido para todas las acciones y muestra cómo acceder a las notificaciones de usuario:

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

Requerir ámbitos específicos:

Use el [RequiredScope] atributo para aplicar permisos específicos en acciones individuales:

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. Ejecutar y probar

Inicie la aplicación y compruebe que se rechazan las solicitudes no autenticadas:

dotnet run

Pruebe utilizando una herramienta como Postman o curl. Una solicitud no autenticada devuelve 401 Unauthorized:

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

¡Éxito! La API ahora valida los tokens de portador.

Configuración del registro de aplicaciones

Para que la API pueda validar tokens, necesita un registro de aplicación Microsoft Entra. Siga estos pasos en el portal de Azure.

1. Registrar la API

  1. Inicie sesión en el portal Azure
  2. Vaya a Microsoft Entra ID>Registros de aplicaciones>Nuevo registro
  3. Escriba un nombre (por ejemplo, "Mi API web")
  4. Seleccione Inquilino único (más común para las API)
  5. No se necesita ningún URI de redirección para las API
  6. Haga clic en Registrar.

Exponer un ámbito de API

Defina los permisos (ámbitos) que las aplicaciones cliente pueden solicitar al llamar a la API.

  1. En el registro de la aplicación de API, vaya a Exponer una API.
  2. Haga clic en Agregar un ámbito.
  3. Acepte el URI de identificador de aplicación predeterminado o personalícelo (por ejemplo, api://your-api-client-id)
  4. Agregue un ámbito:
    • Nombre del ámbito:access_as_user
    • Quién puede dar su consentimiento: Administradores y usuarios
    • Nombre para mostrar del consentimiento del administrador: "Access My Web API" (Acceso a Mi API web)
    • Descripción del consentimiento del administrador: "Permite que la aplicación acceda a la API web en nombre del usuario que ha iniciado sesión"
  5. Haga clic en Agregar ámbito.

3. Anote el identificador de la aplicación

Copie el identificador de aplicación (cliente) de la página de información general del registro de aplicaciones. Este valor es tu ClientId en appsettings.json.

Creación de un registro de aplicaciones cliente (para pruebas)

Para probar la API protegida, registre una aplicación cliente independiente que adquiera tokens y llame a la API.

1. Registrar una aplicación cliente

  1. En Microsoft Entra ID>Registros de aplicaciones, cree otro registro.
  2. Asígnelo el nombre (por ejemplo, "Mi cliente de API")
  3. Selección de tipos de cuenta
  4. Agregar URI de redirección: https://localhost:7000/signin-oidc (si se trata de una aplicación web)
  5. Haga clic en Registrar.

2. Concesión de permisos de API

Conceda permiso a la aplicación cliente para llamar a la API con los ámbitos definidos.

  1. En el registro de aplicaciones cliente, vaya a Permisos de API.
  2. Haga clic en Agregar un permiso>Mis API.
  3. Selección del registro de API
  4. Comprueba el access_as_user ámbito
  5. Haga clic en Agregar permisos.
  6. Haga clic en Conceder consentimiento del administrador (si es necesario)

3. Crear un secreto de cliente (para clientes confidenciales)

Si la aplicación cliente se ejecuta en un servidor (no en un explorador o dispositivo móvil), cree un secreto de cliente para la autenticación.

  1. Vaya a Certificados y secretos
  2. Haga clic en Nuevo secreto de cliente.
  3. Agregar una descripción y una expiración
  4. Haga clic en Agregar.
  5. Copie el valor secreto inmediatamente: usted no podrá verlo de nuevo.

Prueba de la API protegida

Compruebe que la API valida correctamente los tokens mediante el envío de solicitudes autenticadas.

Uso de Postman

Configure la autenticación de OAuth 2.0 en Postman para adquirir un token y llamar a la API.

  1. Creación de una nueva solicitud en Postman
  2. Configuración de la autenticación de OAuth 2.0:
    • Tipo de concesión: Código de autorización (para contexto de usuario) o Credenciales de cliente (para el contexto de la aplicación)
    • Dirección URL de autenticación:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
    • Dirección URL del token de acceso:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
    • Id. de cliente: Identificador de cliente de la aplicación cliente
    • Secreto de cliente: Secreto de la aplicación cliente
    • Alcance:api://your-api-client-id/access_as_user
  3. Haga clic en Obtener nuevo token de acceso.
  4. Uso del token para llamar a la API

Uso de código (ejemplo de C#)

En el ejemplo siguiente se usa MSAL.NET para adquirir un token con el flujo de credenciales de cliente y llamar a la 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");

Opciones de configuración comunes

Microsoft. Identity.Web admite varios patrones de configuración para distintos escenarios.

Requerir ámbitos específicos en la configuración

En lugar de usar el [RequiredScope] atributo , puede configurar los ámbitos necesarios globalmente en appsettings.json:

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

Aceptar tokens de varios inquilinos

Para aceptar tokens de cualquier inquilino de Microsoft Entra, establezca TenantId en common:

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

Configuración de la validación de tokens

Si la API llama a las API de bajada (por ejemplo, Microsoft Graph), habilite la adquisición de tokens y configure una caché de tokens:

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

Pasos siguientes

Ahora que tiene una API protegida, explore estos temas:

Solución de problemas

401 No autorizado

Problema: La API devuelve 401 incluso con un token.

Causas posibles:

  • La audiencia del token (aud reclamación) no coincide con la de su API. ClientId
  • El token ha expirado
  • El token es para el arrendatario incorrecto
  • Falta el ámbito requerido

Solución: Descodifique el token en jwt.ms y verifique las declaraciones. Consulte Registro y diagnóstico para obtener una solución de problemas detallada.

AADSTS50013: firma no válida

Problema: Se produce un error en la validación de la firma del token.

Solución: Asegúrese de que TenantId y ClientId son correctos. La autoridad esperada debe emitir el token. Habilite el registro detallado para ver los errores de validación.

Ámbitos no encontrados en el token

Problema:[RequiredScope] se produce un error en el atributo .

Solution:

  1. Verifica que la aplicación del cliente tenga permiso para el ámbito
  2. Asegúrese de que se concedió el consentimiento del administrador (si es necesario)
  3. Consulte la Guía de autorización para obtener patrones de validación de ámbito completo.
  4. Compruebe que el ámbito se solicita cuando se adquiera el token (por ejemplo, api://your-api/.default o ámbitos específicos).

Consulte más:Guía de solución de problemas de API web

Contenido relacionado

  • Last updated on