DS.Foundation.Authentication.AspNetCore 8.4.3

DS.Foundation.Authentication.AspNetCore

Protege APIs ASP.NET Core con JWT Bearer emitidos por DS.Foundation.Authentication (por ejemplo desde DS.Security) y con API keys en el encabezado X-Api-Key. Inyecta el usuario autenticado como UserToken.

• Target framework: net8.0.
• Dependencias: DS.Foundation.Authentication, Microsoft.AspNetCore.Authentication.JwtBearer 8.x y los paquetes Microsoft.IdentityModel.* / System.IdentityModel.Tokens.Jwt en 8.2.1.

Instalación

<PackageReference Include="DS.Foundation.Authentication.AspNetCore" Version="8.4.3" />

Trae DS.Foundation.Authentication como dependencia. Si la aplicación también lo referencia en forma directa, use la misma versión.

Todos los paquetes Microsoft.IdentityModel.* y System.IdentityModel.Tokens.Jwt deben quedar en la misma versión: Microsoft no soporta mezclarlas, y una mezcla falla recién en tiempo de ejecución (MissingMethodException, TypeLoadException o tokens rechazados con errores IDX...). Si la aplicación agrega otro paquete que trae alguno de ellos (por ejemplo, Microsoft.Identity.Web), referencie en forma directa la versión más alta para alinearlos todos.

Registro

using DS.Foundation.Authentication.ApiKeyAuthentication;
using DS.Foundation.Authentication.JwtBearerAuthentication;

builder.Services.AddJwtBearerAuthentication(builder.Configuration); // valida la configuración JWT al arrancar
builder.Services.AddJwtBearerAuthorization(builder.Configuration);  // política por defecto: usuario autenticado por JwtBearer
builder.Services.AddApiKeyAuthentication();                         // solo si usa [ApiKey]

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.MapControllers().RequireAuthorization();

AddJwtBearerAuthentication:

• Llama a AddJwtAuthentication, valida System:Authentication:Jwt y lanza una excepción en el arranque si falta algún dato.
• Registra el esquema JwtBearerDefaults.AuthenticationScheme con los parámetros de JwtTokenValidation.CreateValidationParameters: firma, emisor (cualquiera de Issuer y ValidIssuers), audiencia, expiración y algoritmo (solo HMAC-SHA256).
• Registra IHttpContextAccessor y un UserToken scoped construido desde HttpContext.User. Es null cuando el request no está autenticado.

UseJwtBearerAuthorization(IApplicationBuilder, IConfiguration) solo llama a UseAuthorization(); se mantiene por compatibilidad. UseAuthentication() siempre va antes de UseAuthorization().

Configuración

Usa la sección System:Authentication:Jwt descripta en el README de DS.Foundation.Authentication (Issuer, ValidIssuers, Audience, SecretKey de al menos 32 bytes, TokenLifetimeMinutes, ClockSkewSeconds).

Emisores aceptados

El pipeline acepta tokens cuyo iss sea Issuer o cualquier entrada de ValidIssuers, sin configuración extra. Hace falta al menos una de las dos claves; si no, AddJwtBearerAuthentication lanza InvalidOperationException: System:Authentication:Jwt:Issuer or System:Authentication:Jwt:ValidIssuers is required. al arrancar. La comparación es exacta y distingue mayúsculas; un emisor no aceptado recibe 401.

{
  "System": {
    "Authentication": {
      "Jwt": {
        "Issuer": "DS.Security",
        "ValidIssuers": [ "https://security.example.com" ],
        "Audience": "mi-sistema"
      }
    }
  }
}

System__Authentication__Jwt__Issuer=DS.Security
System__Authentication__Jwt__ValidIssuers__0=https://security.example.com

Una aplicación configurada solo con Issuer funciona igual que antes. Una configurada solo con ValidIssuers necesita 8.4.3 o posterior de este paquete (trae DS.Foundation.Authentication 8.4.1): las versiones anteriores exigen Issuer y fallan al arrancar.

Para cambiar el emisor de los tokens: primero actualice el paquete y agregue el emisor nuevo a ValidIssuers en todas las aplicaciones y despliéguelas; recién después DS.Security empieza a emitir con ese emisor. El procedimiento completo está en el README de DS.Foundation.Authentication ("Cambiar el emisor de los tokens").

Otras claves

Uso

Endpoint protegido con JWT

[ApiController]
[Route("api/pedidos")]
public class PedidosController : ControllerBase
{
    private readonly UserToken _usuario;

    public PedidosController(UserToken usuario) => _usuario = usuario;

    [HttpGet]
    public IActionResult Get() => Ok(new { _usuario.Username, _usuario.TenantCode });
}

El cliente envía Authorization: Bearer <jwt>.

Endpoint protegido con API key

[ApiKey]
[AllowAnonymous] // si la política por defecto exige JWT y este endpoint solo usa API key
[HttpPost("webhook")]
public IActionResult Webhook() => Ok();

El cliente envía X-Api-Key: <clave>. Si falta o no coincide con System:ApiKey, la respuesta es 401.

Errores frecuentes

Qué no hacer

• No usar UseJwtBearerAuthorization(WebApplication, IConfiguration): está obsoleto. Use UseAuthorization() y MapControllers().RequireAuthorization().
• No leer el encabezado Authorization a mano para obtener el usuario: inyecte UserToken o use HttpContext.User.
• No usar GetCurrentJwt(HttpRequest) de OmniLayerCookieService: devuelve siempre una cadena vacía.
• No guardar SecretKey ni System:ApiKey en appsettings.json versionado.

Cambios

Ver CHANGELOG.md.