Kulanzfenster für einen vorübergehenden Lizenzserver-Ausfall
Eine Online-Lizenzprüfung, die sofort hart fehlschlägt, sobald Ihr Keyright-Ausstellungsdienst kurz nicht erreichbar ist, macht aus einem DNS-Aussetzer oder einem Routine-Deployment einen für Kunden sichtbaren Ausfall. Dieser Artikel zeigt, wie Sie vorübergehende Ausfälle mit einem konfigurierbaren Kulanzfenster über einem signierten, zwischengespeicherten Validierungsergebnis abfedern: indem Sie „Dienst nicht erreichbar" (vorübergehend, weiterlaufen) von „Lizenz widerrufen" (endgültig, sofort fail-closed) unterscheiden, die Kulanz über die vom Dienst selbst signierten Zeitstempel begrenzen, damit niemand sie durch Trennen des Netzes verlängert, jeden Cache-Lauf protokollieren und sauber fail-closed gehen, sobald das Fenster erschöpft ist.
Eine Online-Lizenzprüfung bringt Ihnen Dinge, die eine Offline-Prüfung nicht kann: Echtzeit-Sitzzählung, sofortigen Widerruf, Nutzungsmessung. Doch sie bringt einen Fehlermodus mit, den man leicht aus Versehen einbaut. Behandelt Ihr Code jeden Fehlschlag beim Erreichen des Ausstellungsdienstes als gescheiterte Validierung, dann werden beim ersten Mal, dass Ihre selbst gehostete Keyright-Instanz kurz nicht erreichbar ist — ein DNS-Aussetzer, ein rollierendes Deployment, ein Proxy, der eine Verbindung kappt — alle zahlenden Kunden auf einen Schlag gesperrt. Ein dreißigsekündiges Infrastrukturereignis wird zu einem dreißigsekündigen kundenseitigen Ausfall, und den Support-Tickets ist es egal, dass die Lizenz die ganze Zeit gültig war.
Die Lösung ist nicht, mit dem Online-Prüfen aufzuhören. Sie besteht darin, „der Dienst hat Nein gesagt” nicht länger mit „ich konnte den Dienst nicht erreichen” zu verwechseln und den zweiten Fall auf einem signierten, zwischengespeicherten Ergebnis für ein begrenztes Kulanzfenster abzufedern.
Kernaussage: Speichern Sie die letzte erfolgreiche Validierung lokal zwischen, signiert, damit sie nicht gefälscht werden kann. Ist der Dienst nicht erreichbar, honorieren Sie das zwischengespeicherte Ergebnis weiter für ein konfigurierbares Kulanzfenster, begrenzt durch die eigenen signierten Zeitstempel des Dienstes (damit niemand es durch Trennen verlängert). Ist der Dienst erreichbar und sagt, die Lizenz sei widerrufen oder abgelaufen, gehen Sie sofort fail-closed. Protokollieren Sie jeden Cache-Lauf, und gehen Sie sauber fail-closed, sobald das Fenster erschöpft ist.
Die zwei Fehlschläge, die sich nicht gleichen dürfen
Jede Online-Revalidierung endet an einem von drei Orten, und das gesamte Design hängt daran, sie getrennt zu halten.
- Bestätigt. Der Dienst hat geantwortet und die Lizenz ist in Ordnung. Erneuern Sie das zwischengespeicherte Lease und fahren Sie fort.
- Endgültiges Nein. Der Dienst hat geantwortet, und die Antwort lautet widerrufen, abgelaufen oder Sitz entzogen. Das ist endgültig. Sie müssen jetzt fail-closed gehen — die Kulanz gilt nicht, denn die Lizenz ist tatsächlich nicht mehr gültig.
- Nicht erreichbar. Der Dienst hat überhaupt nicht geantwortet: ein Verbindungs-Timeout, ein DNS-Fehler, ein
502eines Reverse-Proxys mitten im Deployment. Sie haben nichts über die Lizenz erfahren. Das Letzte, was der Dienst Ihnen gesagt hat, gilt weiterhin, also honorieren Sie es weiter — eine Weile.
Der Fehler besteht darin, den zweiten und dritten Fall in einem einzigen „Validierung fehlgeschlagen”-Zweig zusammenzufassen. Ein Widerruf und eine gekappte TCP-Verbindung sind gegensätzliche Tatsachen. Das eine bedeutet, der Kunde soll stoppen; das andere bedeutet, Ihr Netz hatte einen Schluckauf und der Kunde sollte es nicht bemerken.
Das Kulanzfenster konfigurieren
Die Kulanz wird einmalig konfiguriert, dort, wo Sie den Client initialisieren. GracePeriod ist, wie lange eine gültig zwischengespeicherte Lizenz nach der letzten erfolgreichen Bestätigung weiterläuft, während der Dienst nicht erreichbar ist. MaxOfflineDuration ist die absolute Obergrenze, wie lange ein zwischengespeichertes Lease überhaupt je honoriert wird, egal wie oft die Kulanz sich sonst zurücksetzen würde — es ist Ihr Sicherheitsnetz gegen eine Maschine, die offline geht und offline bleibt.
static readonly KeyrightClient License = KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-suite",
PublicKeyBase64 = "MIIBIjANBgkq...", // ships in your binary; not a secret
ServiceUrl = "https://keyright.example.com", // your self-hosted instance
GracePeriod = TimeSpan.FromHours(72), // ride out outages this long after last contact
MaxOfflineDuration = TimeSpan.FromDays(14), // absolute ceiling on cached operation
});
Wählen Sie GracePeriod so, dass es Ihr schlimmstes realistisches vorübergehendes Ereignis bequem übersteigt — ein langes Deployment, eine Zertifikatsrotation, ein regionaler Netz-Aussetzer — aber nicht so lang, dass ein wirklich gekündigter Kunde wochenlang läuft. Zweiundsiebzig Stunden decken einen Vorfall am Freitagabend ab, den bis Montag niemand ansieht. MaxOfflineDuration ist die längere, grobere Grenze; stellen Sie sie auf Ihren Abrechnungstakt ein, damit eine Maschine, die nie nach Hause telefoniert, es irgendwann tun muss.
Aktualisieren: hier lebt die Trennung vorübergehend-vs-endgültig
Validate() bleibt genau das, was es immer war: eine reine, offline durchgeführte Prüfung des zwischengespeicherten Lease gegen Ihren eingebetteten öffentlichen Schlüssel, die nie eine Ausnahme wirft und nie das Netz berührt. Die Online-Arbeit geschieht in RefreshAsync, und ihr Ergebnis ist der Ort, an dem Sie die beiden Fehlschläge unterscheiden.
RefreshResult refresh = await License.RefreshAsync(ct);
switch (refresh.Status)
{
case RefreshStatus.Confirmed:
// Service reachable, license good. SDK has already renewed the signed
// cached lease (new ConfirmedAtUtc), so the grace window resets.
break;
case RefreshStatus.Revoked:
case RefreshStatus.Expired:
case RefreshStatus.SeatWithdrawn:
// Service reachable and said no. Definitive — DO NOT enter grace.
GateApplication(refresh.Reason);
break;
case RefreshStatus.ServiceUnreachable:
// We learned nothing. The cached lease still stands within its grace window.
_log.LogWarning("Keyright unreachable ({Detail}); running on cached validation.",
refresh.Detail);
break;
}
Wenn Sie Ausnahmen auf einem tieferen Pfad bevorzugen, taucht der Konnektivitätsfehler als typisierte Ausnahme auf, die Sie abfangen können, während eine endgültige Ablehnung das nicht tut — sie kommt als Ergebnis zurück, das Sie prüfen müssen:
try
{
await License.RefreshAsync(ct); // throwOnUnreachable: true overload
}
catch (KeyrightServiceUnreachableException ex)
{
// Transient only: DNS, connect timeout, 5xx from a proxy. Keep the cached lease.
_log.LogWarning(ex, "Transient Keyright outage; grace window active.");
}
Die Regel, die man behalten muss: Eine KeyrightServiceUnreachableException (oder RefreshStatus.ServiceUnreachable) ist das Einzige, was in die Kulanz führt. Ein widerrufenes oder abgelaufenes Ergebnis ist nie ein Konnektivitätsproblem, erhält also nie den Vertrauensvorschuss.
Sie rufen RefreshAsync nicht auf dem heißen Pfad auf. Führen Sie es per Timer aus — alle paar Minuten oder beim Fortsetzen der App — und lassen Sie Validate() dazwischen jede tatsächliche Sperrentscheidung aus dem zwischengespeicherten Lease bedienen.
Die zwischengespeicherte Validierung und ihren signierten Zeitstempel lesen
Wenn Validate() aus dem Cache statt aus einer frischen Bestätigung antwortet, sagt LicenseInfo Ihnen das und trägt den signierten Zeitstempel, der das Kulanzfenster begrenzt. Jedes Feld hier ist von der Signatur des Dienstes über dem Lease abgedeckt, also kann keines auf der Platte bearbeitet werden, ohne die Verifizierung zu brechen.
LicenseInfo info = License.Validate();
if (info.ValidationSource == ValidationSource.Cache)
{
DateTimeOffset confirmedAt = info.Lease.ConfirmedAtUtc; // signed by the service
TimeSpan remaining = info.GraceRemaining; // how long cached operation is still allowed
_log.LogInformation(
"Running on cached license: last confirmed {ConfirmedAt:u}, grace remaining {Remaining}.",
confirmedAt, remaining);
if (remaining < TimeSpan.FromHours(6))
ShowBanner($"License server unreachable. Reconnect within {remaining:hh\\:mm} to stay licensed.");
}
if (info.Edition == LicenseEdition.Community)
{
// Grace exhausted (or never licensed): the SDK has already fallen back to
// Community Edition. Gate the paid entitlements, cleanly.
DisablePaidFeatures();
}
Beachten Sie das Rückfallziel: Ist die Kulanz erschöpft, fällt ein selbst gehostetes Deployment auf Community Edition zurück, es stürzt nicht ab. Bezahlte Berechtigungen lesen sich über dieselben IsEnabled / GetLimit-Aufrufe als deaktiviert, die Sie ohnehin verwenden, sodass fail-closed zu gehen nur Ihre gewöhnliche Sperrlogik ist, die ihre Arbeit tut — ohne einen speziellen „wir haben Sie ausgesperrt”-Codepfad.
Uhr-Überlegungen: warum Sie die Kulanz nicht durch Trennen betrügen können
Der naheliegende Angriff auf jedes Offline-Kulanzfenster besteht darin, das Netz zu trennen und die Uhr zurückzustellen, damit die Kulanz nie verstreicht. Keyright schließt das an zwei Fronten.
Die Kulanz wird ab einem signierten Zeitpunkt gemessen, nicht ab einem lokalen. Der Countdown läuft ab Lease.ConfirmedAtUtc, das der Dienst bei seiner letzten Antwort signiert hat. Ein Nutzer kann seine Maschinenuhr ändern, aber er kann einen Zeitstempel, der innerhalb einer signierten Nutzlast liegt, nicht verschieben, ohne die Signatur zu invalidieren — und eine ungültige Signatur geht sofort fail-closed.
Eine zurückgedrehte Uhr wird als Manipulation behandelt. Neben dem signierten Zeitstempel hält das SDK einen monotonen Marker und die letzte signierte Serverzeit vor, die es gesehen hat. Zeigt die Systemuhr später eine frühere Zeit als dieser Höchststand — die Signatur eines absichtlichen Zurückdrehens — hört das SDK auf, der lokalen Uhr zu vertrauen, und geht fail-closed, statt eine unbegrenzte Kulanz zu gewähren:
if (info.ClockStatus == ClockStatus.WentBackwards)
{
// Wall clock is earlier than the last signed server time we recorded.
// Treat as tamper: do not extend grace.
GateApplication("System clock rolled back; reconnect to re-validate.");
}
MaxOfflineDuration ist das letzte Sicherheitsnetz. Selbst wenn alle Uhr-Prüfungen bestanden würden, wird kein zwischengespeichertes Lease über ConfirmedAtUtc + MaxOfflineDuration hinaus honoriert. Das Ziehen des Kabels erkauft genau GracePeriod, und über wiederholte kurze Ausfälle hinweg erkauft es höchstens MaxOfflineDuration insgesamt — niemals für immer.
Telemetrie, während auf zwischengespeicherter Validierung gelaufen wird
Auf Cache zu laufen ist ein degradierter Zustand, und Sie wollen wissen, dass er eintritt, bevor ein Kunde es Ihnen sagt. Zwei Dinge lohnen sich zu emittieren. Erstens eine strukturierte Protokollzeile jedes Mal, wenn eine Sperrentscheidung aus dem Cache statt aus einer frischen Bestätigung bedient wird — genau der ValidationSource == Cache-Zweig oben — mit confirmedAt und remaining, damit Sie sehen, wie tief eine Flotte in das Fenster abgedriftet ist. Zweitens eine Metrik oder ein Gesundheitssignal, auf das Sie alarmieren können: Ist ein nennenswerter Anteil der Instanzen gleichzeitig auf zwischengespeicherter Validierung, dann hat Ihr Ausstellungsdienst einen schlechten Tag, nicht eine Handvoll einzelner Kunden, die offline gehen. Halten Sie den Schlüssel selbst aus diesen Protokollen heraus (auf ein Präfix kürzen), so wie Sie es überall sonst täten.
Sauber fail-closed gehen
Wenn die Kulanz schließlich verstreicht — MaxOfflineDuration erreicht, Uhr-Zurückdrehen erkannt oder ein endgültiger Widerruf kam zurück, sobald der Dienst erreichbar war — ist der Endzustand derselbe, und er sollte undramatisch sein. Validate() gibt LicenseEdition.Community zurück, bezahlte Berechtigungen lesen sich als deaktiviert, und Ihre bestehende Sperrlogik reduziert die App auf ihre kostenlose Oberfläche. Der Kunde sieht eine klare, umsetzbare Meldung („erneut verbinden, um neu zu validieren”) statt einer Stack-Trace, und sobald der Dienst wieder erreichbar ist, bestätigt ein einziges RefreshAsync die Lizenz und stellt die volle Funktion wieder her — ohne Neuinstallation und ohne erneute Schlüsseleingabe.
Das ist die ganze Gestalt der Sache: Ein Ausfall, den Sie verursacht haben, sollte Ihren Kunden nichts kosten, eine Kündigung sollte ihn seine bezahlten Funktionen zügig kosten, und der Unterschied zwischen beiden ist ein signierter Zeitstempel und ein begrenztes Fenster — niemals eine gekappte Verbindung, die für ein Urteil gehalten wird.
Nebula.NET testen
Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.