DS.Foundation.Authentication 8.4.2

DS.Foundation.Authentication

Emisión y validación de JWT firmados con HMAC-SHA256, el modelo de usuario autenticado (UserToken) y la validación de API keys, sin depender de ASP.NET Core.

Úselo en el servicio que emite tokens (por ejemplo DS.Security) y en cualquier proceso que deba validar un token fuera del pipeline HTTP. Para proteger endpoints de ASP.NET Core instale además DS.Foundation.Authentication.AspNetCore.

• Target framework: netstandard2.0.
• Dependencias: DS.Foundation, Microsoft.IdentityModel.JsonWebTokens, Microsoft.Extensions.Options.ConfigurationExtensions.

Instalación

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

Registro

using DS.Foundation.Authentication.Configuration;
using DS.Foundation.Services;
using DS.Foundation.Services.Extensions;

// Enlaza JwtAuthenticationOptions con la sección System:Authentication:Jwt.
builder.Services.AddJwtAuthentication(builder.Configuration);

// Registra JsonWebTokenService y OmniLayerCookieService como scoped.
builder.Services.AddFoundationServices(new IServiceRepository[]
{
    new DS.Foundation.Authentication.Services.ServiceRepository(),
});

AddJwtAuthentication solo enlaza las opciones: no valida la configuración al arrancar. La validación ocurre al emitir o validar el primer token.

Configuración

Sección System:Authentication:Jwt (JwtAuthenticationOptions.SectionName):

{
  "System": {
    "Authentication": {
      "Jwt": {
        "Issuer": "ds-security",
        "Audience": "mi-sistema",
        "SecretKey": "<se carga desde variables de entorno o un almacén de secretos>",
        "TokenLifetimeMinutes": 60,
        "ClockSkewSeconds": 30
      }
    }
  }
}

El emisor y todas las aplicaciones que validan sus tokens deben compartir Audience y SecretKey, y el iss de cada token debe ser uno de los emisores aceptados por la aplicación que lo valida.

Varios emisores: Issuer y ValidIssuers

Desde 8.4.1 una aplicación puede aceptar tokens de más de un emisor, por ejemplo durante el cambio de DS.Security a https://security.<dominio>.

• Emisores aceptados (JwtAuthenticationOptions.GetAcceptedIssuers()): Issuer, si tiene valor, más las entradas de ValidIssuers. Las dos claves valen lo mismo para validar. Los valores se recortan, los vacíos se ignoran y los repetidos se cuentan una vez.
• La comparación con el iss del token es exacta y distingue mayúsculas: https://Security.test no coincide con https://security.test, y https://security.test/ tampoco.
• Hace falta al menos una de las dos claves. Si no queda ningún emisor, Validate() lanza InvalidOperationException: System:Authentication:Jwt:Issuer or System:Authentication:Jwt:ValidIssuers is required.
• Emisor con el que se firma (JwtAuthenticationOptions.GetDefaultIssuer(), usado por CreateJwtFromToken(token)): Issuer si tiene valor; si no, la primera entrada válida de ValidIssuers, en el orden de la configuración. Para firmar con otro emisor aceptado use CreateJwtFromToken(token, issuer).
• Una aplicación configurada solo con Issuer funciona igual que antes, sin cambios.

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

Con variables de entorno (por ejemplo en Docker), cada entrada de la lista lleva su índice:

System__Authentication__Jwt__Issuer=DS.Security
System__Authentication__Jwt__ValidIssuers__0=https://security.example.com
System__Authentication__Jwt__ValidIssuers__1=https://security.otro-dominio.com

IConfiguration combina las listas por índice: ValidIssuers__0 en una variable de entorno reemplaza la entrada 0 de appsettings.json, y las demás entradas se conservan.

Importante: una aplicación configurada solo con ValidIssuers (sin Issuer) necesita 8.4.1 o posterior. Las versiones anteriores ignoran ValidIssuers, exigen Issuer y fallan al arrancar o al validar el primer token.

Cambiar el emisor de los tokens

1. En cada aplicación que valida tokens, actualice el paquete a 8.4.1 o posterior y agregue el emisor nuevo a ValidIssuers, manteniendo el actual en Issuer. Despliegue todas.
2. Recién cuando todas las aplicaciones aceptan el emisor nuevo, el emisor (DS.Security) empieza a firmar con él: con CreateJwtFromToken(token, "https://security.example.com") en los endpoints que lo necesiten, o cambiando su Issuer.
3. Cuando ya no queden tokens vigentes con el emisor anterior (pasado TokenLifetimeMinutes), puede quitarlo de la configuración de las aplicaciones.

Si se invierte el orden, las aplicaciones que todavía no aceptan el emisor nuevo rechazan esos tokens (401 en ASP.NET Core, false en TryValidateAndCreateUserToken).

API key (ApiKeyValidator):

Uso

Emitir un token

using DS.Foundation.Authentication;
using DS.Foundation.Authentication.Services;

var userToken = new UserToken
{
    UserId = 42,
    Username = "jperez",
    TenantCode = "ACME",
    Roles = new List<string> { "admin" },
    ApplicationRoles = new List<UserApplicationRole>
    {
        new UserApplicationRole { ApplicationCode = "CRM", Roles = new List<string> { "ventas" } },
    },
};

string jwt = jsonWebTokenService.CreateJwtFromToken(userToken);

// Con un emisor específico; debe ser uno de los emisores aceptados.
string jwtOauth = jsonWebTokenService.CreateJwtFromToken(userToken, "https://security.example.com");

CreateJwtFromToken(token) firma con GetDefaultIssuer() (ver Varios emisores). CreateJwtFromToken(token, issuer) lanza ArgumentException si issuer está vacío o no coincide exactamente (sin recortar y distinguiendo mayúsculas) con uno de GetAcceptedIssuers().

El token incluye estos claims:

• ClaimTypes.NameIdentifier (UserId), ClaimTypes.Name (Username) y ClaimTypes.GroupSid (TenantCode).
• Un ClaimTypes.Role por cada rol general (Roles). En el JWT, un rol queda como texto y varios como arreglo, por ejemplo ["admin","ventas"]. Así funcionan User.IsInRole("admin") y [Authorize(Roles = "admin")].
• ApplicationRoles, solo si hay roles de aplicación. Lleva un objeto JSON por aplicación, por ejemplo {"A":"CRM","R":["ventas"]}. Con una aplicación el valor es ese objeto; con varias, un arreglo de objetos. Estos roles no se agregan a ClaimTypes.Role.

Las fechas iat y exp se calculan en UTC.

Validar un token

if (jsonWebTokenService.TryValidateAndCreateUserToken(jwt, out UserToken token))
{
    // Firma, emisor (cualquiera de GetAcceptedIssuers()), audiencia y expiración válidos.
}

TryValidateAndCreateUserToken devuelve false si el token está vacío, mal formado, vencido, firmado con otra clave, con un emisor no aceptado o con un claim ApplicationRoles que no es JSON válido. Al reconstruir el token:

• UserCode toma el valor de UserId como texto.
• Roles acepta un claim por rol o el formato anterior a 8.4.0, un único claim con los roles separados por |. Los roles se recortan y no se repiten (sin distinguir mayúsculas), así que un rol no puede contener |.
• Las entradas de ApplicationRoles con el mismo ApplicationCode (sin distinguir mayúsculas) se unen en una sola, sin roles repetidos.

Roles por aplicación

List<string> rolesEnCrm = token.ApplicationRoles
    .Where(x => string.Equals(x.ApplicationCode, "CRM", StringComparison.OrdinalIgnoreCase))
    .SelectMany(x => x.Roles)
    .ToList();

Los tokens emitidos por versiones anteriores a 8.4.0 no traen el claim, y ApplicationRoles queda vacío.

Leer el usuario desde un ClaimsPrincipal

var helper = new UserHelper(principal);
int id = helper.UserId;                       // 0 si no hay claim
bool puede = helper.IsInRoles("admin", "ventas");
List<string> rolesEnCrm = helper.GetApplicationRoles("CRM"); // vacía si no hay claim ApplicationRoles

UserToken token = UserTokenMapper.FromClaimsPrincipal(principal); // null si no está autenticado

Replicar el JWT en una cookie (login MVC)

Las aplicaciones MVC que validan el JWT de DS.Security en el login y después trabajan con una cookie deben armar la identidad de la cookie con UserTokenMapper.ToClaims o UserTokenMapper.ToClaimsPrincipal. Es la forma recomendada: producen exactamente los mismos claims y en el mismo formato que CreateJwtFromToken, así que UserHelper (Roles, ApplicationRoles, GetApplicationRoles), UserTokenMapper.FromClaimsPrincipal y el menú de DS.Foundation.WebApp (MainMenuOptions.ApplicationCode) funcionan igual sobre la cookie que sobre el JWT.

using DS.Foundation.Authentication;
using DS.Foundation.Authentication.Services;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

public class AccountController : Controller
{
    private readonly JsonWebTokenService _jsonWebTokenService;

    public AccountController(JsonWebTokenService jsonWebTokenService) => _jsonWebTokenService = jsonWebTokenService;

    [AllowAnonymous]
    [HttpPost]
    public async Task<IActionResult> Login(string jwt, string returnUrl)
    {
        if (!_jsonWebTokenService.TryValidateAndCreateUserToken(jwt, out UserToken userToken))
        {
            return Unauthorized();
        }

        var principal = UserTokenMapper.ToClaimsPrincipal(userToken, CookieAuthenticationDefaults.AuthenticationScheme);
        await HttpContext.SignInAsync(CookieAuthenticationDefaults.AuthenticationScheme, principal);

        return LocalRedirect(string.IsNullOrEmpty(returnUrl) ? "/" : returnUrl);
    }
}

Si la aplicación agrega claims propios, parta de ToClaims:

var claims = new List<Claim>(UserTokenMapper.ToClaims(userToken))
{
    new Claim("Nickname", nickname),
};
var identity = new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme);
await HttpContext.SignInAsync(CookieAuthenticationDefaults.AuthenticationScheme, new ClaimsPrincipal(identity));

ToClaims devuelve, en orden:

• ClaimTypes.NameIdentifier (UserId), ClaimTypes.Name (Username) y ClaimTypes.GroupSid (TenantCode). Un valor null se escribe como texto vacío.
• Un ClaimTypes.Role por rol general, recortado, sin vacíos ni repetidos (sin distinguir mayúsculas). Un valor con | se separa en varios roles.
• Un claim UserTokenMapper.ApplicationRolesClaimType ("ApplicationRoles") por cada entrada de ApplicationRoles, con el JSON de UserApplicationRole ({"A":"COM","R":["COMPRADOR"]}) y tipo de valor JsonClaimValueTypes.Json. No se fusionan al escribir: las entradas repetidas con distinto casing se fusionan al leer.

UserCode no se escribe porque al leer se toma de UserId. ToClaims lanza ArgumentNullException si el token es null. ToClaimsPrincipal además lanza ArgumentException si authenticationType está vacío, porque una identidad sin tipo de autenticación no queda autenticada y FromClaimsPrincipal devolvería null.

Validar una API key

bool valida = apiKeyValidator.IsValid(apiKeyRecibida); // compara con System:ApiKey

Errores frecuentes

Qué no hacer

• No guardar SecretKey en appsettings.json versionado ni en el código: use variables de entorno o un almacén de secretos.
• No usar JsonWebTokenService.CreateTokenFromJwt: está obsoleto y lanza SecurityTokenValidationException en lugar de devolver false. Use TryValidateAndCreateUserToken.
• No usar OmniLayerCookieService.GetCurrentJwt(): devuelve siempre una cadena vacía.
• No leer los claims de un JWT sin validarlo antes.
• No armar a mano los claims de una cookie ni serializar ApplicationRoles por su cuenta, ni repetir el literal "ApplicationRoles": use UserTokenMapper.ToClaims o ToClaimsPrincipal y, si necesita el tipo de claim, UserTokenMapper.ApplicationRolesClaimType. Si el formato cambia en una versión futura, el código propio deja de funcionar sin ningún error visible.
• No empezar a emitir con un emisor nuevo antes de que todas las aplicaciones que validan los tokens lo acepten.

Cambios

Ver CHANGELOG.md.