EAC.Infrastructure.Security 0.1.0-rc.4

EAC.Infrastructure.Security

Desde 2026-10-09, Native AOT queda fuera del alcance por decisión del usuario. No se declara compatibilidad ni se exige su gate. Las referencias históricas no constituyen soporte vigente; build y tests ordinarios siguen siendo obligatorios.

Repositorio propietario del NuGet EAC.Infrastructure.Security.

Estado actual: alcance hasta RC completado con 0.1.0-rc.3 publicado en NuGet.org, incluida la corrección de composición de SEC-011. SEC-012 permanece pendiente antes de cualquier promoción estable.

Instalación y configuración

<PackageReference Include="EAC.Infrastructure.Security" Version="0.1.0-rc.3" />

El registro básico no exige configuración ambiental ni activa un handler de autenticación. Se mantiene para adaptadores no HTTP y pruebas:

services.AddEacSecurity(
    claims => claims.MapSubject("sub").MapClientId("client_id"),
    capabilities => capabilities.Add("sample.order.read"));

El overload declarativo con IConfiguration registra el handler JWT Bearer oficial y enlaza claims, catálogo, traducciones y políticas desde Eac:Security, sin callbacks específicos del servicio:

services.AddEacSecurity(builder.Configuration);

Configuración completa con valores seguros predeterminados:

{
  "Eac": {
    "Security": {
      "DefaultScheme": "Bearer",
      "Authority": "https://identity.example",
      "Audience": "orders-api",
      "Issuer": "https://identity.example",
      "ValidateIssuer": true,
      "ValidateAudience": true,
      "ValidateLifetime": true,
      "ValidateSignature": true,
      "RequireHttpsMetadata": true,
      "ValidTokenTypes": [ "at+jwt" ],
      "Capabilities": [ "sample.order.read" ],
      "ClaimMappings": {
        "SubjectClaimTypes": [ "sub" ],
        "ClientIdClaimTypes": [ "azp", "client_id" ],
        "ScopeClaimTypes": [ "scope" ],
        "JsonRoleMappings": [
          { "ClaimType": "resource_access", "Path": [ "orders-api", "roles" ] }
        ],
        "TrustedRoleSources": [
          { "ClientIds": [ "orders-client", "orders-batch" ] }
        ]
      },
      "RoleCapabilityMappings": [
        { "Value": "order-reader", "Capability": "sample.order.read" }
      ],
      "EndpointPolicies": [
        {
          "Name": "orders-read",
          "RoutePattern": "/orders/{id:guid}",
          "Methods": [ "GET" ],
          "Capabilities": [ "sample.order.read" ],
          "MatchMode": "AllOf"
        }
      ]
    }
  }
}

Equivalencia mediante variables de entorno:

Eac__Security__DefaultScheme=Bearer
Eac__Security__Authority=https://identity.example
Eac__Security__Audience=orders-api
Eac__Security__Issuer=https://identity.example
Eac__Security__ValidateIssuer=true
Eac__Security__ValidateAudience=true
Eac__Security__ValidateLifetime=true
Eac__Security__ValidateSignature=true
Eac__Security__RequireHttpsMetadata=true

Una sección incompleta o insegura impide el startup. Los cambios requieren reiniciar el proceso. Una configuración programática proporcionada al final del registro tiene precedencia sobre appsettings y variables de entorno:

services.AddEacSecurity(
    builder.Configuration,
    ConfigureClaims,
    ConfigureCapabilities,
    options => options.Audience = "orders-api-v2");

Authority, Audience e Issuer no son secretos. Tokens, claves privadas, client secrets y credenciales pertenecen al handler/proveedor oficial y deben obtenerse desde un almacén externo; este paquete nunca los recibe ni almacena. El overload con callbacks permanece para compatibilidad y para composición programática. En el overload declarativo, capabilities, claim types, rutas JSON, fuentes confiables y traducciones role/scope/permission se validan al inicio. Issuer y Audience de una fuente pueden omitirse para heredar los valores raíz; cada ClientId sigue siendo obligatorio y único.

Los roles de proveedor solo se traducen a capacidades cuando la fuente declara explícitamente claim type, issuer, audience y client/resource esperados:

services.AddEacSecurity(
    claims => claims
        .MapSubject("sub")
        .MapClientId("client_id", "azp")
        .MapRoles("roles")
        .MapJsonArrayRoles("resource_access", "orders-api", "roles")
        .AcceptRoleSource("https://identity.example", "orders-api", "orders-client")
        .FromRole("order-operator", "sample.order.read"),
    capabilities => capabilities.Add("sample.order.read"));

La ruta HTTP aplica la policy sin repetir capacidades en cada operación:

var orders = endpoints.MapGroup("/orders")
    .RequireConfiguredAuthorization(
        endpoints.ServiceProvider.GetRequiredService<EndpointAuthorizationMap>());

app.UseAuthentication();
app.UseEacExecutionIdentity();
app.UseAuthorization();
app.ValidateEacEndpointAuthorization();

MapJsonArrayRoles es un adaptador genérico por ruta JSON; el paquete no fija resource_access, un cliente ni nombres de roles. La fuente aceptada continúa exigiendo issuer, audience y client/resource exactos.

• Índice documental
• Guía de consumo y configuración
• Diseño
• Plan de implementación
• Arquitectura transversal