Skip to content
← Tous les articles
· Delta1 Labs LicensingKeyright

Appliquer les droits de licence dans les services gRPC

Un service gRPC n'a ni pipeline de filtres MVC ni attribut [Authorize] auquel accrocher une vérification de licence : le seul point qui voit chaque appel est l'Interceptor du serveur. Cet article écrit un LicensingInterceptor qui valide une licence Keyright une seule fois, mappe chaque méthode gRPC vers un droit requis et échoue fermé avec le bon statut : FailedPrecondition en l'absence de licence valide, PermissionDenied quand la licence n'a pas le droit, ResourceExhausted quand une limite numérique est épuisée. Plus un chemin chaud en cache qui ne fait jamais d'aller-retour vers le service émetteur, l'enregistrement par DI via AddGrpc et les variantes de streaming.

Une Web API ASP.NET Core vous offre un point net pour les vérifications de licence : une politique d’autorisation, un attribut [Authorize(Policy = "ent:export")], et la requête est rejetée avant que votre action ne s’exécute. Un service gRPC n’a rien de tout cela. Pas de contrôleur, pas de pipeline de filtres d’action, pas d’attribut que le framework évalue par appel. Si vous essayez de disperser if (license.HasEntitlement("export")) dans vos méthodes de service, vous revenez à ce que le pipeline d’autorisation HTTP a été conçu pour remplacer : une vérification que vous devez penser à écrire dans chaque méthode, où en oublier une expédie une fonctionnalité sans licence.

gRPC possède pourtant un point qui voit chaque appel, et c’est le bon endroit pour cela : l’Interceptor côté serveur. Cet article écrit un LicensingInterceptor qui valide une licence Keyright une seule fois, mappe chaque méthode gRPC vers un droit requis et échoue fermé avec le bon statut gRPC.

Pourquoi gRPC a besoin de son propre point d’application

Un interceptor est à gRPC ce que le middleware et les filtres sont à MVC, mais la forme diffère. Vous ne décorez pas des méthodes en laissant un pipeline les découvrir ; vous dérivez Grpc.Core.Interceptors.Interceptor et surchargez le handler de chaque type d’appel — UnaryServerHandler, ServerStreamingServerHandler, ClientStreamingServerHandler, DuplexStreamingServerHandler. Chaque surcharge reçoit la requête, un ServerCallContext et un délégué continuation qui invoque la vraie méthode de service. Ce que vous faites avant d’appeler la continuation se produit avant l’exécution du corps de la méthode ; si vous levez une exception au lieu de l’appeler, la méthode ne s’exécute jamais.

C’est précisément le point de contrôle d’admission que veut une barrière de licence. Une classe, enregistrée une fois, protège chaque RPC — et comme le nom de la méthode est sur le ServerCallContext, la même classe peut exiger un droit différent par méthode.

L’interceptor est le seul point qui voit chaque appel

Voici le flux d’un appel unaire. L’interceptor valide la licence en cache, cherche le droit requis par cette méthode, puis appelle la continuation ou lève une RpcException avec un statut d’échec fermé.

RPC unaire/Reports/ExportLicensingInterceptorvalide licence en cachemappe méthode → droitla méthode s'exécutecontinuation(request, ctx)FailedPreconditionpas de licence validePermissionDenieddroit manquantKeyright SDK — validation en cache et hors ligne ; aucun aller-retour par RPC vers le service émetteurvalide + habilitépas de licencedroit manquant

Gardez le chemin chaud bon marché : validez une fois, mettez l’instantané en cache

Un serveur RPC peut traiter des milliers d’appels par seconde, donc la barrière doit être quasi gratuite. Le SDK Keyright met déjà en cache le bail activé — il ne recontacte pas le service émetteur à chaque validation — mais ValidateAsync vérifie quand même la signature et analyse la licence à chaque exécution. Faites ce travail une fois et conservez l’instantané immuable LicenseInfo, en le rafraîchissant à intervalle court pour qu’un bail renouvelé ou révoqué soit pris en compte sans épuiser le CPU à chaque 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}."));
    }
}

Deux propriétés du SDK rendent cela sûr. ValidateAsync ne lève jamais face à une licence invalide — une licence absente, expirée ou révoquée se résout au niveau Community Edition avec un statut, donc license.IsValid vaut simplement false et la barrière lève sa propre RpcException propre au lieu de laisser une exception s’échapper du pipeline. Et HasEntitlement échoue fermé : un droit inconnu ou absent se lit comme false. Refuser est le comportement par défaut, ce qui est exactement ce que vous voulez dans une vérification d’admission.

Mapper les méthodes vers les droits

ServerCallContext.Method est le chemin de méthode pleinement qualifié — "/acme.Reports/Export". Un dictionnaire indexé sur cette chaîne est le mapping le plus simple, et il garde la politique en un seul endroit lisible. Les méthodes qui ne sont pas dans le mapping n’exigent qu’une licence valide, pas un droit spécifique — ainsi vos RPC de base fonctionnent sur toute édition et seules les méthodes premium nomment un droit.

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 vous préférez garder l’exigence à côté de la méthode, marquez l’implémentation du service et construisez le mapping par réflexion au démarrage :

[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")]

Parcourez les méthodes du type de service une fois, lisez l’attribut et traduisez chaque nom de méthode CLR en son chemin gRPC ("/" + ServiceName + "/" + MethodName) pour peupler le même dictionnaire. Dans les deux cas l’interceptor reste identique — il consomme seulement le mapping fini.

Le LicensingInterceptor lui-même

L’interceptor est mince : il délègue à la barrière, puis appelle la continuation. Toute la politique vit dans la barrière ; l’interceptor ne fait que câbler la barrière dans chaque type d’appel.

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 lève une exception, continuation n’est jamais invoquée et gRPC renvoie la RpcException au client sous forme du statut et du détail que vous avez choisis — pas de méthode exécutée à moitié, pas de réponse divulguée.

Les appels en streaming ont besoin de la même barrière — une fois

Les RPC en streaming ont leurs propres handlers, mais la décision de licence est la même et se prend une fois, en haut : la licence et ses droits ne changent pas en cours d’appel, donc revérifier par message n’apporte rien. Appliquez la barrière avant la continuation, exactement comme pour l’unaire.

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 et DuplexStreamingServerHandler suivent le même motif — barrière d’abord, puis await continuation(...). Si vous exécutez un flux de longue durée et voulez qu’il se coupe quand une licence expire en cours de session, relisez l’instantané en cache sur un minuteur dans votre boucle de flux et terminez le flux ; mais la vérification d’admission va en haut, où elle refuse avant qu’aucune donnée ne circule.

Choisir le bon statut gRPC

Le choix du statut n’est pas cosmétique — les clients gRPC se ramifient selon le StatusCode, donc le code que vous renvoyez indique à l’appelant s’il faut réessayer et quand. Un échec de licence se mappe sur trois codes distincts :

  • FailedPrecondition — il n’y a pas de licence valide. Le service n’est pas dans un état où l’appel peut aboutir, et le client ne doit pas réessayer aveuglément : un humain doit d’abord installer ou renouveler une licence. C’est le défaut correct pour « pas de licence, expirée, révoquée ».
  • PermissionDenied — la licence est valide mais ne porte pas le droit que cette méthode exige. L’appelant est connu et l’appel est bien formé ; il n’est simplement pas licencié pour cette capacité, et réessayer sans changement n’aidera pas.
  • ResourceExhausted — une limite numérique est épuisée : un plafond de sièges, un quota quotidien d’appels. Celui-ci est réessayable plus tard, une fois l’usage libéré, ce qui est déjà la façon dont les clients traitent ResourceExhausted du contrôle de flux. Lisez le nombre sur la même licence et levez-le là où un plafond est atteint :
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}."));

Résistez à Unauthenticated pour aucun de ceux-ci — ce code concerne qui est l’appelant, pas pour quoi il est licencié, et confondre identité et droit rend les deux plus difficiles à raisonner.

Enregistrer l’interceptor

Enregistrez le client Keyright en singleton (il charge la clé publique une fois et est thread-safe), ajoutez la barrière et le mapping, et attachez l’interceptor au 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>());

Cette unique ligne Interceptors.Add<LicensingInterceptor>() est tout l’enregistrement : chaque méthode unaire et en streaming de chaque service gRPC de l’application passe désormais par la barrière avant que son corps ne s’exécute. Ajouter une méthode nouvellement protégée, c’est une entrée dans le mapping (ou un attribut) — pas une ligne de code d’application dans la méthode elle-même.

Pourquoi c’est le bon point

L’intérêt de pousser la vérification dans l’interceptor est le même que de la pousser dans l’autorisation ASP.NET Core : cela change le défaut. Avec des vérifications if éparpillées dans les méthodes de service, en oublier une signifie qu’une capacité est expédiée sans licence — le défaut est autoriser. Avec l’interceptor, le défaut est refuser : une méthode premium non mappée exige quand même une licence valide, et une méthode protégée exige son droit, avant que la continuation ne s’exécute. La décision reste hors ligne et en échec fermé exactement comme partout ailleurs dans Keyright, le chemin chaud est une lecture de champ en cache plutôt qu’un appel réseau, et le client reçoit un statut gRPC précis sur lequel agir au lieu d’un RPC exécuté à moitié.

Voyez droits et feature flags pour le modèle de capacités dont s’inspire le mapping, vérification en cache sur le chemin chaud pour le motif d’instantané, et les droits comme politiques d’autorisation ASP.NET Core pour le frère HTTP de ce point.

Essayez Nebula.NET

Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.