Skip to content
← Alle Beiträge
· Delta1 Labs LicensingKeyright

Lizenzberechtigungen in gRPC-Diensten durchsetzen

Ein gRPC-Dienst hat weder eine MVC-Filter-Pipeline noch ein [Authorize]-Attribut, an das man eine Lizenzprüfung hängen könnte — der einzige Punkt, der jeden Aufruf sieht, ist der Server-Interceptor. Dieser Beitrag schreibt einen LicensingInterceptor, der eine Keyright-Lizenz einmal validiert, jede gRPC-Methode auf eine erforderliche Berechtigung abbildet und mit dem richtigen Status fail-closed scheitert: FailedPrecondition ohne gültige Lizenz, PermissionDenied wenn die Lizenz die Berechtigung nicht trägt, ResourceExhausted wenn ein numerisches Limit erschöpft ist. Dazu ein gecachter heißer Pfad, der nie zum Ausstellungsdienst zurückreist, die DI-Registrierung via AddGrpc und die Streaming-Varianten.

Eine ASP.NET-Core-Web-API gibt Ihnen einen sauberen Ansatzpunkt für Lizenzprüfungen: eine Autorisierungsrichtlinie, ein [Authorize(Policy = "ent:export")]-Attribut, und die Anfrage wird abgelehnt, bevor Ihre Aktion läuft. Ein gRPC-Dienst hat nichts davon. Kein Controller, keine Action-Filter-Pipeline, kein Attribut, das das Framework pro Aufruf auswertet. Wenn Sie versuchen, if (license.HasEntitlement("export")) über Ihre Dienstmethoden zu streuen, sind Sie zurück bei dem, was die HTTP-Autorisierungs-Pipeline ersetzen sollte: eine Prüfung, an die Sie in jeder Methode denken müssen und bei der das Vergessen einer einzigen ein Feature unlizenziert ausliefert.

gRPC hat jedoch einen Punkt, der jeden Aufruf sieht, und das ist der richtige Ort dafür: den serverseitigen Interceptor. Dieser Beitrag schreibt einen LicensingInterceptor, der eine Keyright-Lizenz einmal validiert, jede gRPC-Methode auf eine erforderliche Berechtigung abbildet und mit dem korrekten gRPC-Status fail-closed scheitert.

Warum gRPC seinen eigenen Durchsetzungspunkt braucht

Ein Interceptor ist für gRPC, was Middleware und Filter für MVC sind, aber die Form unterscheidet sich. Sie dekorieren keine Methoden und lassen eine Pipeline sie entdecken; Sie leiten Grpc.Core.Interceptors.Interceptor ab und überschreiben den Handler für jede Aufrufart — UnaryServerHandler, ServerStreamingServerHandler, ClientStreamingServerHandler, DuplexStreamingServerHandler. Jede Überschreibung erhält die Anfrage, einen ServerCallContext und ein continuation-Delegat, das die eigentliche Dienstmethode aufruft. Was Sie vor dem Aufruf der Continuation tun, geschieht vor dem Rumpf der Methode; werfen Sie stattdessen eine Ausnahme, läuft die Methode nie.

Genau das ist der Zulassungskontroll-Punkt, den eine Lizenzschranke will. Eine Klasse, einmal registriert, schützt jeden RPC — und da der Methodenname auf dem ServerCallContext liegt, kann dieselbe Klasse pro Methode eine andere Berechtigung verlangen.

Der Interceptor ist der einzige Punkt, der jeden Aufruf sieht

Hier der Ablauf eines unären Aufrufs. Der Interceptor validiert die gecachte Lizenz, schlägt die von dieser Methode erforderliche Berechtigung nach und ruft entweder die Continuation auf oder wirft eine RpcException mit einem fail-closed-Status.

Unärer RPC/Reports/ExportLicensingInterceptorgecachte Lizenz prüfenMethode → BerechtigungMethode läuftcontinuation(request, ctx)FailedPreconditionkeine gültige LizenzPermissionDeniedBerechtigung fehltKeyright SDK — gecachte, offline Validierung; kein Round-Trip pro RPC zum Ausstellungsdienstgültig + berechtigtkeine LizenzBerechtigung fehlt

Halten Sie den heißen Pfad billig: einmal validieren, Schnappschuss cachen

Ein RPC-Server kann Tausende Aufrufe pro Sekunde bedienen, also muss die Schranke nahezu kostenlos sein. Das Keyright-SDK cacht das aktivierte Lease bereits — es kontaktiert den Ausstellungsdienst nicht bei jeder Validierung erneut — aber ValidateAsync prüft dennoch bei jeder Ausführung die Signatur und parst die Lizenz. Erledigen Sie diese Arbeit einmal und halten Sie den unveränderlichen LicenseInfo-Schnappschuss, den Sie in kurzem Intervall auffrischen, damit ein erneuertes oder widerrufenes Lease erfasst wird, ohne bei jedem RPC die CPU zu belasten.

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}."));
    }
}

Zwei Eigenschaften des SDK machen das sicher. ValidateAsync wirft nie bei einer ungültigen Lizenz — eine fehlende, abgelaufene oder widerrufene Lizenz löst sich mit einem Status auf die Community-Edition-Stufe auf, sodass license.IsValid schlicht false ist und die Schranke ihre eigene saubere RpcException wirft, statt eine Ausnahme aus der Pipeline entkommen zu lassen. Und HasEntitlement scheitert fail-closed: eine unbekannte oder fehlende Berechtigung liest sich als false. Ablehnen ist das Standardverhalten — genau das, was man in einer Zulassungsprüfung will.

Methoden auf Berechtigungen abbilden

ServerCallContext.Method ist der vollständig qualifizierte Methodenpfad — "/acme.Reports/Export". Ein auf diese Zeichenkette indiziertes Dictionary ist die einfachste Abbildung und hält die Richtlinie an einem lesbaren Ort. Methoden, die nicht in der Abbildung stehen, verlangen nur eine gültige Lizenz, keine bestimmte Berechtigung — so laufen Ihre Basis-RPCs auf jeder Edition, und nur die Premium-Methoden nennen eine Berechtigung.

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",
        };
}

Wenn Sie die Anforderung lieber neben der Methode halten, markieren Sie die Dienstimplementierung und bauen die Abbildung beim Start per Reflexion:

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

Durchlaufen Sie die Methoden des Diensttyps einmal, lesen Sie das Attribut und übersetzen Sie jeden CLR-Methodennamen in seinen gRPC-Pfad ("/" + ServiceName + "/" + MethodName), um dasselbe Dictionary zu füllen. In beiden Fällen bleibt der Interceptor identisch — er konsumiert nur die fertige Abbildung.

Der LicensingInterceptor selbst

Der Interceptor ist schlank: Er delegiert an die Schranke und ruft dann die Continuation auf. Die gesamte Richtlinie lebt in der Schranke; der Interceptor verdrahtet die Schranke nur in jede Aufrufart.

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
    }
}

Wirft EnforceAsync, wird continuation nie aufgerufen, und gRPC schickt die RpcException als den von Ihnen gewählten Status und Detailtext an den Client zurück — keine halb ausgeführte Methode, keine durchgesickerte Antwort.

Streaming-Aufrufe brauchen dieselbe Schranke — einmal

Streaming-RPCs haben ihre eigenen Handler, aber die Lizenzentscheidung ist dieselbe und fällt einmal, oben: Lizenz und Berechtigungen ändern sich mitten im Aufruf nicht, also bringt eine Neuprüfung pro Nachricht nichts. Setzen Sie die Schranke vor der Continuation durch, genau wie beim unären Fall.

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 und DuplexStreamingServerHandler folgen demselben Muster — Schranke zuerst, dann await continuation(...). Wenn Sie einen langlebigen Stream betreiben und möchten, dass er abbricht, sobald eine Lizenz mitten in der Sitzung ausläuft, lesen Sie den gecachten Schnappschuss per Timer in Ihrer Stream-Schleife erneut und schließen den Stream ab; aber die Zulassungsprüfung gehört nach oben, wo sie ablehnt, bevor Daten fließen.

Den richtigen gRPC-Status wählen

Die Statuswahl ist nicht kosmetisch — gRPC-Clients verzweigen nach dem StatusCode, also sagt der Code, den Sie zurückgeben, dem Aufrufer, ob und wann er erneut versuchen soll. Ein Lizenzfehler bildet sich auf drei verschiedene Codes ab:

  • FailedPrecondition — es gibt keine gültige Lizenz. Der Dienst ist nicht in einem Zustand, in dem der Aufruf gelingen kann, und der Client darf nicht blind erneut versuchen: Ein Mensch muss zuerst eine Lizenz installieren oder erneuern. Das ist der korrekte Standard für „keine Lizenz, abgelaufen, widerrufen”.
  • PermissionDenied — die Lizenz ist gültig, trägt aber nicht die Berechtigung, die diese Methode verlangt. Der Aufrufer ist bekannt und der Aufruf wohlgeformt; er ist nur nicht für diese Fähigkeit lizenziert, und ein unveränderter Wiederholungsversuch hilft nicht.
  • ResourceExhausted — ein numerisches Limit ist erschöpft: ein Sitz-Limit, ein Tageskontingent an Aufrufen. Dieses ist später wiederholbar, sobald Nutzung frei wird — so behandeln Clients ResourceExhausted aus der Flusskontrolle bereits. Lesen Sie die Zahl aus derselben Lizenz und werfen Sie dort, wo ein Limit erreicht wird:
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}."));

Widerstehen Sie Unauthenticated für all dies — dieser Code betrifft, wer der Aufrufer ist, nicht, wofür er lizenziert ist, und Identität mit Berechtigung zu vermengen macht beides schwerer nachvollziehbar.

Den Interceptor registrieren

Registrieren Sie den Keyright-Client als Singleton (er lädt den öffentlichen Schlüssel einmal und ist thread-sicher), fügen Sie Schranke und Abbildung hinzu und hängen Sie den Interceptor an die gRPC-Pipeline:

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>());

Diese eine Zeile Interceptors.Add<LicensingInterceptor>() ist die gesamte Registrierung: Jede unäre und Streaming-Methode jedes gRPC-Dienstes in der App läuft nun durch die Schranke, bevor ihr Rumpf ausgeführt wird. Eine neu geschützte Methode hinzuzufügen ist ein Eintrag in der Abbildung (oder ein Attribut) — keine Zeile Durchsetzungscode in der Methode selbst.

Warum das der richtige Ansatzpunkt ist

Der Sinn, die Prüfung in den Interceptor zu schieben, ist derselbe wie beim Verschieben in die ASP.NET-Core-Autorisierung: Es ändert den Standard. Mit über die Dienstmethoden verstreuten if-Prüfungen bedeutet das Vergessen einer einzigen, dass eine Fähigkeit unlizenziert ausgeliefert wird — der Standard ist erlauben. Mit dem Interceptor ist der Standard ablehnen: Eine nicht abgebildete Premium-Methode verlangt dennoch eine gültige Lizenz, und eine geschützte verlangt ihre Berechtigung, bevor die Continuation jemals läuft. Die Entscheidung bleibt offline und fail-closed genau wie überall sonst in Keyright, der heiße Pfad ist ein gecachter Feldzugriff statt eines Netzwerkaufrufs, und der Client erhält einen präzisen gRPC-Status, auf den er reagieren kann, statt eines halb ausgeführten RPC.

Siehe Berechtigungen und Feature-Flags für das Fähigkeitsmodell, aus dem sich die Abbildung speist, gecachte Verifizierung auf dem heißen Pfad für das Schnappschuss-Muster und Berechtigungen als ASP.NET-Core-Autorisierungsrichtlinien für das HTTP-Geschwister dieses Ansatzpunkts.

Nebula.NET testen

Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.