Funktionen & Editionen schützen

Ziel. Sie möchten, dass „Export“, „SSO“, „unbegrenzte Projekte“ — jede Pro-exklusive oder editionsspezifische Fähigkeit — sich aus der Lizenz des Kunden heraus einschaltet, lokal und ohne Serveraufruf verifiziert, und Sie möchten ändern, wer was bekommt, ohne einen neuen Build auszuliefern.

Wann Sie es einsetzen

• Verwenden Sie dies, wenn Ihr Produkt Funktionen hat, die vom gekauften Plan eines Kunden abhängen (ein kostenloses Tier vs. ein bezahltes Tier, Pro vs. Enterprise, Add-ons), und Sie möchten, dass die Entscheidung innerhalb der signierten Lizenz mitreist, damit sie offline funktioniert und sich nicht durch Bearbeiten einer Konfigurationsdatei umschalten lässt.
• Verwenden Sie dies, wenn Sie erwarten, dass sich Ihr Planangebot ändert: Schützen Sie über benannte Entitlements statt über die Edition, und ein künftiges Neuschnüren ist eine Dashboard-Änderung, kein Release.
• Nicht dies, wenn Sie Verbrauch verkaufen (Renderings, API-Aufrufe, KI-Generierungen) statt einer Fähigkeit — messen Sie das mit Credits. Und die Abdeckung, welche Produktversionen eine Lizenz ausführen darf, ist eine eigene Achse — siehe Release-Abdeckung.

Entitlements sind der Mechanismus hinter dieser ganzen Seite: Eine Lizenz trägt eine kleine Zuordnung benannter Flags und numerischer Limits, zusammen mit dem Tier signiert, die Ihre App zur Laufzeit zurückliest. Da sie in der signierten Nutzlast liegen, kann eine geleakte oder von Hand bearbeitete Lizenz kein Flag gewähren, das der Service nie signiert hat — die Signatur schlägt fehl, und das SDK verhält sich fail-closed und fällt auf Free zurück.

Was Sie tun (Anbieterseite)

Eine Edition (so nennt das Dashboard ein Tier) trägt eine Platzanzahl und eine Entitlement-Vorlage — die benannten Flags und numerischen Limits, die in jede daraus ausgestellte Lizenz eingebacken werden. Definieren Sie sie einmal pro Edition; jede Lizenz dieser Edition erbt sie.

Im Dashboard: Products → Ihr Produkt → Editions → Add edition (oder eine bestehende bearbeiten) und die Entitlements ausfüllen — ein boolesches Flag wie export oder ein numerisches Limit wie max-projects. Über die API ist es ein einziger Aufruf:

# eine Edition mit ihrer Entitlement-Vorlage definieren
curl -X POST $BASE/admin/products/acme-app/tiers -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"name":"pro","seats":3,"entitlements":{"export":"true","max-projects":"10"}}'

# eine höhere Edition, die ein Flag ergänzt und das Limit aufhebt
curl -X POST $BASE/admin/products/acme-app/tiers -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"name":"enterprise","seats":25,"entitlements":{"export":"true","sso":"true","max-projects":"unlimited"}}'

Entitlement-Werte sind auf der Leitung Strings: "true"/"false" für ein Flag, eine Ganzzahl oder das Literal "unlimited" für ein Limit. Wenn Sie aus dieser Edition eine Lizenz ausstellen, wird die Vorlage automatisch angewendet — die Entitlement-Zuordnung erscheint auf der Lizenz (GET /admin/licenses/{id} liefert ein entitlements-Objekt) und innerhalb des signierten Lease, den die App des Kunden verifiziert:

# eine pro-Lizenz ausstellen — sie erbt die Entitlements von pro
curl -X POST $BASE/admin/licenses -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"licensee":"Acme Inc.","product":"acme-app","tier":"pro","seats":3,"email":"owner@acme.com"}'

Ein Kunde, der etwas anderes braucht, erhält eine lizenzspezifische Überschreibung bei der Ausstellung: Übergeben Sie eine explizite entitlements-Zuordnung im Body von POST /admin/licenses (der Drawer Issue license des Dashboards bietet dasselbe unter seinen erweiterten Optionen), sodass Sie etwa sso einem einzelnen Pro-Konto gewähren können, ohne eine neue Edition zu erfinden. Die Überschreibung wird genau wie ein Vorlagen-Flag in die signierte Nutzlast dieser einen Lizenz eingebacken.

Entitlements werden bei der Ausstellung der Lizenz als Snapshot festgehalten und signiert — es gibt keinen Aufruf „Entitlements eines aktiven Schlüssels bearbeiten“, und ein erneutes Posten an /admin/licenses mit einer bestehenden id wird als Duplikat abgewiesen. Um zu ändern, was ein bereits ausgestellter Schlüssel freischaltet, stellen Sie dem Kunden eine neue Lizenz aus (mit den gewünschten Entitlements oder aus einer aktualisierten Edition) und lassen ihn diese aktivieren; der alte Schlüssel kann widerrufen werden, sobald er gewechselt hat. Das Bearbeiten der Vorlage einer Edition ändert nur die Lizenzen, die nach der Bearbeitung ausgestellt werden.

In Ihrem Code

Ihre App bettet nur den öffentlichen Schlüssel ein und liest Entitlements aus der validierten Lizenz — offline, ohne Serveraufruf (Aktivierung/Validate() hat den signierten Lease bereits geliefert und zwischengespeichert). Die Details zur Initialisierung des Clients stehen im .NET-SDK-Leitfaden; hier geht es nur um das Gating, in jedem SDK und über rohes HTTP.

Dieselben Entitlements, die Sie im Code lesen, sind genau das, was das Dashboard auf einer Lizenz zeigt — die bei der Ausstellung eingebackenen Flags:

.NET

using Keyright.Client;

// Gating auf Editionsebene: IsPaid ist true für jede Edition oberhalb von Free; für grobe Tiers nach der Edition verzweigen.
LicenseInfo info = License.Validate();          // offline, wirft nie; Fehler lösen sich zu Edition.Free auf
if (info.IsPaid)      ShowPaidChrome();          // Testversion ODER bezahlt — info.IsTrial unterscheidet sie
if (info.Edition == Edition.Enterprise) ShowEnterpriseOnlyPanel();

// Gating auf Funktionsebene: das Entitlement beim Namen abfragen — das ist der dauerhafte Weg zu schützen.
if (License.IsEnabled("export"))                 // boolesches Flag; ein fehlendes Flag liest sich als false (fail-closed)
    EnableExportCommand();

// Numerisches Limit: Sie übergeben den Fail-closed-Fallback, sodass ein fehlender/verstümmelter Wert nie als „mehr“ gelesen werden kann.
long maxProjects = License.GetLimit("max-projects", fallback: 1);
if (currentProjectCount >= maxProjects)
    PromptToUpgrade();

Node.js

const { info } = license.validate();                        // offline; Fehler lösen sich zur Edition 'free' auf
if (info.isPaid) showPaidChrome();                          // Testversion ODER bezahlt
if (info.edition === 'enterprise') showEnterpriseOnlyPanel();

if (info.entitlements.isEnabled('export')) enableExportCommand();   // fehlendes Flag -> false
const maxProjects = info.entitlements.getLimit('max-projects', 1);  // 'unlimited' -> eine riesige Zahl
if (currentProjectCount >= maxProjects) promptToUpgrade();

Python

from keyright import Edition

info = license.validate_info()                       # offline; Fehler lösen sich zu Edition.FREE auf
if info.is_paid:
    show_paid_chrome()                               # Testversion ODER bezahlt
if info.edition == Edition.ENTERPRISE:
    show_enterprise_only_panel()

if info.entitlements.is_enabled("export"):           # fehlendes Flag -> False
    enable_export_command()
max_projects = info.entitlements.get_limit("max-projects", fallback=1)   # "unlimited" -> sehr großer int
if current_project_count >= max_projects:
    prompt_to_upgrade()

Java

LicenseInfo info = client.validateInfo();            // offline; Fehler lösen sich zu Edition.FREE auf
if (info.isPaid()) showPaidChrome();                 // Testversion ODER bezahlt
if (info.edition == Edition.ENTERPRISE) showEnterpriseOnlyPanel();

if (info.entitlements.isEnabled("export")) enableExportCommand();   // fehlendes Flag -> false
long maxProjects = info.entitlements.getLimit("max-projects", 1);   // "unlimited" -> EntitlementSet.MAXLONG
if (currentProjectCount >= maxProjects) promptToUpgrade();

Beliebige Sprache (rohes HTTP)

# Kein SDK-Aufruf — lesen Sie die Flags direkt aus dem Lease, den Sie bereits verifiziert haben.
# Sobald die Signatur des Lease geprüft ist (siehe „Den Lease offline verifizieren“), trägt das
# signierte Lease-JSON ein "entitlements"-Objekt; das Flag ist Teil der signierten Nutzlast (das
# Segment |ent=), ein Lease, der sich verifizieren lässt, ist also einer, dessen Entitlements Sie vertrauen können:
#
#   "entitlements": { "export": "true", "max-projects": "10" }
#
# export aktiviert = entitlements["export"] ist "true"/"1"/"yes"   (fehlt -> aus, fail-closed)
# Projektlimit     = int(entitlements["max-projects"])           ("unlimited" -> keine Obergrenze; fehlt -> Ihr Fallback)

IsEnabled und GetLimit validieren jeweils an Ort und Stelle und verhalten sich fail-closed: Ein fehlendes Flag ist deaktiviert, ein fehlendes oder nicht parsbares Limit liefert Ihren Fallback, und "unlimited" liest sich als long.MaxValue. Wenn Sie mehrere Entitlements zusammen prüfen, validieren Sie einmal und verwenden das Ergebnis wieder:

LicenseInfo info = License.Validate();
bool canExport = info.Entitlements.IsEnabled("export");
long maxSeats  = info.Entitlements.GetLimit("max-seats", 1);

Was LicenseInfo für Ihre Oberfläche bereitstellt: IsPaid, Edition, IsTrial, StatusBadge (z. B. „Enterprise“ / „Pro Trial“), ExpiryUtc, DaysRemaining, Status und eine für Menschen lesbare Message, plus die Entitlements-Zuordnung selbst. Schützen Sie die Funktion über das Entitlement; verwenden Sie die Edition nur für grobes Chrome.

Nutzer von rohem HTTP (Go, Rust, PHP …) lesen dieselben Entitlements aus dem verifizierten Lease: Das signierte Lease-JSON trägt ein entitlements-Objekt, und nachdem Sie die Signatur des Lease verifiziert haben, lesen Sie die Flags direkt daraus. Die Entitlements sind Teil der kanonischen signierten Nutzlast (das Segment |ent=), ein Lease, der sich verifizieren lässt, ist also einer, dessen Entitlements Sie vertrauen können — das vollständige Verifizierungsrezept steht in Die HTTP-API direkt verwenden.

Ändern, was ein bestehender Kunde erhält. Das Bearbeiten der Vorlage einer Edition ändert nur künftige Lizenzen — ausgestellte Lizenzen behalten die Entitlements, mit denen sie signiert wurden, dieselbe Snapshot-Regel, die auch die Abdeckung verwendet. Um eine Lizenz zu ändern, die bereits im Feld ist, haben Sie zwei bestätigte Pfade: Fügen Sie eine lizenzspezifische Überschreibung hinzu (die Lizenz über ihre Dashboard-Seite / POST /admin/licenses mit derselben id neu ausstellen), was sie mit der neuen Entitlement-Zuordnung neu signiert, und der Kunde übernimmt sie bei der nächsten Lease-Aktualisierung; oder ändern Sie für eine ganze Edition die Vorlage und stellen die betroffenen Lizenzen neu aus. Eine Verlängerung verlängert die Laufzeit und signiert neu, ist aber auf Ablauf und Plätze beschränkt — die Neuausstellung ist der Weg, wenn sich der Entitlement-Satz selbst ändern muss.

Cloud vs. Self-Hosting

Entitlements funktionieren in beiden Modi identisch — dieselbe Vorlage, dieselben SDK-Aufrufe, dieselbe signierte Nutzlast. Die einzigen Unterschiede sind die üblichen:

• $BASE und $TOKEN. Cloud: https://keyright.delta1labs.com mit einem Team-/Sitzungs-Token. Self-Hosting: die URL Ihrer Instanz mit Ihrem KEYRIGHT_ADMIN_TOKEN.
• Welche Entitlements Sie vergeben können, hängt von Ihrem eigenen Plan (Cloud) oder Ihrer selbst gehosteten Edition ab — Entitlement-Namen erfinden Sie selbst, und sie bedeuten, was immer Ihre App festlegt; es gibt kein festes Vokabular. (Nicht zu verwechseln mit den Entitlements auf der Selbstlizenz der Instanz selbst, die Keyright-Funktionen wie SSO schützen — siehe Lizenzierung & Editionen.)

Prüfen

1. Definieren Sie eine Edition pro mit {"export":"true"} und ein Produkt ohne free; stellen Sie sich selbst einen pro-Schlüssel aus.
2. Vor der Aktivierung liefert Validate() Free und IsEnabled("export") ist false — der Befehl bleibt verborgen.
3. Aktivieren Sie den Schlüssel. Das Badge wechselt zu Pro, IsEnabled("export") liefert true, und der Export-Befehl erscheint. Trennen Sie das Netzwerk und starten Sie neu — die Entscheidung gilt weiterhin aus dem zwischengespeicherten Lease, was beweist, dass sie offline ist.
4. Fügen Sie der Edition "sso":"true" hinzu (oder übergeben Sie es als lizenzspezifische Überschreibung) und stellen Sie daraus eine neue Lizenz aus; aktivieren Sie diesen Schlüssel und aktualisieren Sie — das neue Flag erscheint ohne neuen App-Build. (Entitlements sind auf dem ursprünglichen Schlüssel bei der Ausstellung fixiert, daher ist das ein neuer Schlüssel, keine Bearbeitung des alten.)
5. Bearbeiten Sie eine zwischengespeicherte Lease-Datei von Hand (ein Flag umschalten) und validieren Sie erneut: Die Signatur schlägt fehl, und die App fällt auf Free zurück, was bestätigt, dass der Schutz nicht gefälscht werden kann.

Siehe auch

• .NET-SDK-Integration — die vollständige Client-Anleitung, auf der diese Snippets aufbauen.
• Die HTTP-API direkt verwenden — Entitlements aus einem verifizierten Lease in jeder Sprache lesen.
• Sicherheit & das Lease-Modell — warum ein signiertes Entitlement nicht gefälscht oder bearbeitet werden kann.
• Widerrufen, verlängern & Ablauf behandeln — die anderen Dinge, die Sie an einer aktiven Lizenz ändern.
• Credits & gemessene Nutzung — Verbrauch statt einer Fähigkeit schützen.