Aplicar los derechos de licencia en servicios gRPC
Un servicio gRPC no tiene el pipeline de filtros de MVC ni un atributo [Authorize] del que colgar la comprobación de licencia: el único punto que ve todas las llamadas es el Interceptor del servidor. Este artículo escribe un LicensingInterceptor que valida una licencia de Keyright una sola vez, mapea cada método gRPC a un derecho requerido y falla cerrado con el estado correcto: FailedPrecondition cuando no hay licencia válida, PermissionDenied cuando la licencia carece del derecho, ResourceExhausted cuando se agota un límite numérico. Además, una ruta caliente en caché que nunca viaja al servicio emisor, el registro por DI con AddGrpc y las variantes de streaming.
Una Web API de ASP.NET Core te da un punto ordenado para las comprobaciones de licencia: una política de autorización, un atributo [Authorize(Policy = "ent:export")], y la petición se rechaza antes de que se ejecute tu acción. Un servicio gRPC no tiene nada de eso. No hay controlador, ni pipeline de filtros de acción, ni atributo que el framework evalúe por llamada. Si intentas dispersar if (license.HasEntitlement("export")) por tus métodos de servicio, vuelves a aquello que el pipeline de autorización HTTP se construyó para reemplazar: una comprobación que tienes que acordarte de escribir en cada método, donde olvidar una envía una funcionalidad sin licenciar.
Sin embargo, gRPC sí tiene un punto que ve todas las llamadas, y es el lugar correcto para esto: el Interceptor del lado del servidor. Este artículo escribe un LicensingInterceptor que valida una licencia de Keyright una sola vez, mapea cada método gRPC a un derecho requerido y falla cerrado con el estado gRPC correcto.
Por qué gRPC necesita su propio punto de aplicación
Un interceptor es para gRPC lo que el middleware y los filtros son para MVC, pero la forma es distinta. No decoras métodos y dejas que un pipeline los descubra; subclaseas Grpc.Core.Interceptors.Interceptor y sobrescribes el handler de cada tipo de llamada — UnaryServerHandler, ServerStreamingServerHandler, ClientStreamingServerHandler, DuplexStreamingServerHandler. Cada sobrescritura recibe la petición, un ServerCallContext y un delegado continuation que invoca el método de servicio real. Lo que hagas antes de llamar a la continuation ocurre antes de que se ejecute el cuerpo del método; si lanzas en lugar de llamarla, el método nunca se ejecuta.
Ese es precisamente el punto de control de admisión que quiere una verja de licencia. Una clase, registrada una vez, protege cada RPC — y como el nombre del método está en el ServerCallContext, la misma clase puede exigir un derecho distinto por método.
El interceptor es el único punto que ve todas las llamadas
Este es el flujo de una llamada unaria. El interceptor valida la licencia en caché, busca el derecho que requiere este método, y o bien llama a la continuation o lanza una RpcException con un estado de fallo cerrado.
Mantén la ruta caliente barata: valida una vez, cachea la instantánea
Un servidor RPC puede atender miles de llamadas por segundo, así que la verja debe ser casi gratis. El SDK de Keyright ya cachea el lease activado — no vuelve a contactar con el servicio emisor en cada validación — pero ValidateAsync aún verifica la firma y analiza la licencia cada vez que se ejecuta. Haz ese trabajo una vez y mantén la instantánea inmutable LicenseInfo, refrescándola en un intervalo corto para que un lease renovado o revocado se recoja sin machacar la CPU en cada RPC.
using Grpc.Core;
using Keyright;
public sealed class LicenseGate
{
private readonly IKeyrightClient _client;
private readonly IReadOnlyDictionary<string, string> _methodEntitlements;
private static readonly TimeSpan RefreshWindow = TimeSpan.FromSeconds(5);
private volatile LicenseInfo? _snapshot; // signature-verified once per window
private long _nextRefreshTicks;
public LicenseGate(IKeyrightClient client, MethodEntitlementMap map)
{
_client = client;
_methodEntitlements = map.Entries;
}
private async ValueTask<LicenseInfo> CurrentAsync(CancellationToken ct)
{
LicenseInfo? snap = _snapshot;
if (snap is not null && DateTime.UtcNow.Ticks < Interlocked.Read(ref _nextRefreshTicks))
return snap; // hot path: field read, no verify
snap = await _client.ValidateAsync(ct); // offline: verify signature + parse, no network
_snapshot = snap;
Interlocked.Exchange(ref _nextRefreshTicks, (DateTime.UtcNow + RefreshWindow).Ticks);
return snap;
}
public async ValueTask EnforceAsync(string method, CancellationToken ct)
{
LicenseInfo license = await CurrentAsync(ct);
// 1. No valid license at all — the service cannot run this call.
if (!license.IsValid)
throw new RpcException(new Status(StatusCode.FailedPrecondition,
$"No valid Keyright license for '{_client.Product}'. " +
"Install or renew a license before calling this service."));
// 2. This method requires a specific entitlement the license does not carry.
if (_methodEntitlements.TryGetValue(method, out string? required)
&& !license.HasEntitlement(required))
throw new RpcException(new Status(StatusCode.PermissionDenied,
$"This license does not include the '{required}' entitlement required by {method}."));
}
}
Dos propiedades del SDK lo hacen seguro. ValidateAsync nunca lanza ante una licencia inválida — una licencia ausente, expirada o revocada se resuelve al nivel Community Edition con un estado, así que license.IsValid es simplemente false y la verja lanza su propia RpcException limpia en lugar de dejar que una excepción escape del pipeline. Y HasEntitlement falla cerrado: un derecho desconocido o ausente se lee como false. Denegar es lo predeterminado, que es exactamente lo que quieres en una comprobación de admisión.
Mapear métodos a derechos
ServerCallContext.Method es la ruta del método totalmente cualificada — "/acme.Reports/Export". Un diccionario con clave en esa cadena es el mapa más simple, y mantiene la política en un único lugar legible. Los métodos que no están en el mapa solo requieren una licencia válida, no un derecho específico — así tus RPC base funcionan en cualquier edición y solo los métodos premium nombran un derecho.
public sealed class MethodEntitlementMap
{
public IReadOnlyDictionary<string, string> Entries { get; } =
new Dictionary<string, string>(StringComparer.Ordinal)
{
["/acme.Reports/Export"] = "reports.export",
["/acme.Reports/StreamAudit"] = "audit.stream",
["/acme.Admin/RotateKeys"] = "admin.security",
};
}
Si prefieres mantener el requisito junto al método, marca la implementación del servicio y construye el mapa por reflexión al arrancar:
[AttributeUsage(AttributeTargets.Method)]
public sealed class RequiresEntitlementAttribute(string entitlement) : Attribute
{
public string Entitlement { get; } = entitlement;
}
// public override Task<ExportReply> Export(...) -> decorate with [RequiresEntitlement("reports.export")]
Recorre los métodos del tipo de servicio una vez, lee el atributo y traduce cada nombre de método CLR a su ruta gRPC ("/" + ServiceName + "/" + MethodName) para poblar el mismo diccionario. En ambos casos el interceptor permanece idéntico — solo consume el mapa terminado.
El propio LicensingInterceptor
El interceptor es delgado: delega en la verja y luego llama a la continuation. Toda la política vive en la verja; el interceptor solo cablea la verja en cada tipo de llamada.
using Grpc.Core;
using Grpc.Core.Interceptors;
public sealed class LicensingInterceptor : Interceptor
{
private readonly LicenseGate _gate;
public LicensingInterceptor(LicenseGate gate) => _gate = gate;
public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
TRequest request,
ServerCallContext context,
UnaryServerMethod<TRequest, TResponse> continuation)
{
await _gate.EnforceAsync(context.Method, context.CancellationToken);
return await continuation(request, context); // only reached if the gate allowed it
}
}
Si EnforceAsync lanza, continuation nunca se invoca y gRPC serializa la RpcException de vuelta al cliente como el estado y el detalle que elegiste — sin método ejecutado a medias, sin respuesta filtrada.
Las llamadas de streaming necesitan la misma verja — una vez
Las RPC de streaming tienen sus propios handlers, pero la decisión de licencia es la misma y se toma una vez, arriba: la licencia y sus derechos no cambian a mitad de llamada, así que no hay valor en recomprobar por mensaje. Aplica la verja antes de la continuation, exactamente igual que en la unaria.
public override async Task ServerStreamingServerHandler<TRequest, TResponse>(
TRequest request,
IServerStreamWriter<TResponse> responseStream,
ServerCallContext context,
ServerStreamingServerMethod<TRequest, TResponse> continuation)
{
await _gate.EnforceAsync(context.Method, context.CancellationToken);
await continuation(request, responseStream, context);
}
ClientStreamingServerHandler y DuplexStreamingServerHandler siguen el mismo patrón — verja primero, luego await continuation(...). Si ejecutas un stream de larga duración y quieres que se corte cuando una licencia caduca a mitad de sesión, relee la instantánea en caché con un temporizador dentro de tu bucle de stream y completa el stream; pero la comprobación de admisión va arriba, donde rechaza antes de que fluya ningún dato.
Elegir el estado gRPC correcto
La selección de estado no es cosmética — los clientes gRPC se ramifican según el StatusCode, así que el código que devuelves le dice al llamador si reintentar y cuándo. Un fallo de licencia se mapea sobre tres códigos distintos:
FailedPrecondition— no hay licencia válida. El servicio no está en un estado donde la llamada pueda tener éxito, y el cliente no debe reintentar a ciegas: un humano tiene que instalar o renovar una licencia primero. Este es el valor predeterminado correcto para “sin licencia, expirada, revocada”.PermissionDenied— la licencia es válida pero no lleva el derecho que este método requiere. El llamador es conocido y la llamada está bien formada; simplemente no está licenciado para esta capacidad, y reintentar sin cambios no ayudará.ResourceExhausted— un límite numérico está agotado: un tope de asientos, una cuota diaria de llamadas. Este sí es reintentable más tarde, cuando se libera uso, que es como los clientes ya tratanResourceExhausteddel control de flujo. Lee el número de la misma licencia y lánzalo donde se alcanza un tope:
long cap = license.GetLimit("rpc.daily", fallback: 0); // fail-closed fallback
if (usage.Today(context.Method) >= cap)
throw new RpcException(new Status(StatusCode.ResourceExhausted,
$"Daily call limit of {cap} reached for {context.Method}."));
Resiste a Unauthenticated para cualquiera de estos — ese código trata de quién es el llamador, no de para qué está licenciado, y confundir identidad con derecho hace ambos más difíciles de razonar.
Registrar el interceptor
Registra el cliente de Keyright como singleton (carga la clave pública una vez y es seguro entre hilos), añade la verja y el mapa, y adjunta el interceptor al pipeline gRPC:
builder.Services.AddSingleton<IKeyrightClient>(_ => KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-grpc",
PublicKeyBase64 = builder.Configuration["Keyright:PublicKey"], // not a secret; verify-only
ServiceUrl = builder.Configuration["Keyright:ServiceUrl"],
}));
builder.Services.AddSingleton<MethodEntitlementMap>();
builder.Services.AddSingleton<LicenseGate>();
builder.Services.AddGrpc(o => o.Interceptors.Add<LicensingInterceptor>());
Esa única línea Interceptors.Add<LicensingInterceptor>() es todo el registro: cada método unario y de streaming de cada servicio gRPC de la app pasa ahora por la verja antes de que se ejecute su cuerpo. Añadir un método recién protegido es una entrada en el mapa (o un atributo) — no una línea de código de aplicación en el método mismo.
Por qué este es el punto correcto
El sentido de empujar la comprobación al interceptor es el mismo que empujarla a la autorización de ASP.NET Core: cambia lo predeterminado. Con comprobaciones if salpicadas por los métodos de servicio, olvidar una significa que una capacidad se envía sin licenciar — lo predeterminado es permitir. Con el interceptor, lo predeterminado es denegar: un método premium sin mapear aún requiere una licencia válida, y uno protegido requiere su derecho, antes de que se ejecute la continuation. La decisión permanece sin conexión y fallando cerrado exactamente igual que en todas partes en Keyright, la ruta caliente es una lectura de campo en caché en vez de una llamada de red, y el cliente recibe un estado gRPC preciso sobre el que actuar en lugar de una RPC ejecutada a medias.
Consulta derechos y feature flags para el modelo de capacidades del que se nutre el mapa, verificación en caché en la ruta caliente para el patrón de instantánea, y derechos como políticas de autorización de ASP.NET Core para el hermano HTTP de este punto.
Prueba Nebula.NET
Endurece tu código .NET en minutos — empieza con la edición gratuita.