Restreindre une licence Keyright à un environnement
Le même fichier de licence a tendance à passer de la production vers le staging, sur le portable d'un développeur et dans la CI, jusqu'à ce que plus personne ne sache de quel environnement venait une validation et qu'une clé de staging fuitée déverrouille la production sans que personne ne le remarque. Voici un guide de migration : comparez les trois façons dont les équipes séparent les environnements — un produit par environnement, un simple fichier par environnement et un produit unique avec une entitlement env signée — puis migrez vers la dernière sur Keyright sans jour de bascule. Il couvre où l'application apprend son propre environnement (IHostEnvironment et le repli DOTNET_ENVIRONMENT / ASPNETCORE_ENVIRONMENT), une vérification de vingt lignes qui échoue en mode fermé face à un environnement inconnu, un déploiement rétrocompatible où une ancienne clé non restreinte continue de s'exécuter partout, et la limite honnête : l'environnement est déclaré par votre propre configuration, donc il s'agit d'hygiène et de télémétrie propre, pas d'un mur contre un opérateur qui règle la variable.
Observez un fichier de licence unique assez longtemps et il finira partout. Vous émettez une clé pour le produit, vous la déposez dans le déploiement de production et, en un sprint, elle a déjà été copiée dans l’environnement de staging pour que les tests de fumée d’avant-production passent, collée dans le appsettings.Development.json d’un développeur et intégrée dans un secret de CI pour que les tests d’intégration s’exécutent. Désormais quatre environnements présentent la même clé signée à votre instance Keyright, et trois faits que vous aimeriez avoir ont disparu : vous ne pouvez pas dire, à partir d’une validation, de quel environnement elle venait, une clé de staging qui fuite est une clé de production, et le jour où vous voudrez expirer la clé de staging plus tôt vous découvrirez qu’elle est la clé de production.
Cet article est un guide de migration. Nous comparerons les trois façons dont les équipes séparent réellement les environnements, choisirons celle qui conserve un produit unique et un chemin de code unique, et migrerons vers elle sur Keyright sans jour de bascule — y compris la partie que la plupart des déploiements oublient, qui consiste à laisser l’ancienne clé non restreinte continuer de fonctionner pendant que les nouvelles clés restreintes se déploient.
Trois façons de distinguer la production du staging
Il n’existe que trois formes pour cela, et elles diffèrent par le cérémonial et la duplication qu’elles coûtent.
Un produit par environnement. Enregistrez acme-studio-prod et acme-studio-staging comme produits distincts dans votre service émetteur, chacun avec sa propre clé de signature, et livrez une clé publique différente par build. Cela fonctionne, et la séparation est absolue, mais vous maintenez désormais deux de tout — deux paires de clés, deux catalogues d’entitlements, deux calendriers de rotation — et une fonctionnalité que vous ajoutez à l’un, vous devez penser à l’ajouter à l’autre. C’est la bonne réponse uniquement lorsque le staging et la production sont véritablement des produits différents aux capacités différentes, ce qui est rare.
Un simple fichier par environnement, même produit. Émettez deux licences pour le produit unique et comptez sur la discipline de déploiement pour les garder séparées. Rien dans la clé ne dit pour quel environnement elle est, donc rien n’empêche le fichier de staging de s’exécuter en production ; dès que quelqu’un copie le mauvais fichier vous revenez au point de départ, et le payload signé n’aide pas puisqu’il ne porte aucun environnement.
Un produit, avec l’environnement écrit dans le payload signé. Conservez un produit unique et une clé publique unique, et ajoutez une entitlement scope:env qui nomme le ou les environnements pour lesquels la clé est licenciée. La clé de staging ne peut littéralement pas se valider comme licenciée en production, parce que l’application compare son propre environnement à la revendication et que la revendication est couverte par la signature. Aucun second produit, aucune seconde rotation, une seule vérification. C’est la forme vers laquelle nous migrons.
Ce que dit la clé
Une entitlement scope:env est une entitlement signée ordinaire — une chaîne dans le payload canonique que la signature couvre — contenant un ensemble de noms d’environnement séparés par des virgules dans lesquels la clé est valide. Une clé de production nomme un environnement ; une clé que vous voulez réutiliser entre vos propres paliers d’avant-production en nomme plusieurs.
{
"product": "acme-studio",
"licensee": "Contoso Ltd",
"expiryUtc": "2027-11-16T00:00:00Z",
"tier": "pro",
"entitlements": {
"scope:env": "production",
"export": "true",
"max-seats": "400"
},
"signature": "…"
}
Le préfixe scope: est une convention, pas une fonctionnalité de Keyright, et il mérite sa place de la même manière que site: : il garde visiblement séparé où cette clé peut s’exécuter de ce que cette clé déverrouille, afin que personne ne conditionne plus tard la fonctionnalité export à un environnement ou l’inverse. Comme la valeur est à l’intérieur du payload signé, un client — ou un développeur pressé — ne peut pas plus changer production en staging qu’il ne peut repousser l’expiration d’un an : un octet modifié et l’application voit LicenseStatus.SignatureInvalid.
Ce que l’application sait de son propre environnement
L’application doit répondre à « quel environnement suis-je ? » à partir de sa propre configuration, hors ligne, au démarrage. Dans une application ASP.NET Core ou à hôte générique la réponse existe déjà : IHostEnvironment.EnvironmentName, que l’hôte résout depuis DOTNET_ENVIRONMENT (ou ASPNETCORE_ENVIRONMENT pour l’hôte web), avec Production par défaut quand aucun n’est défini. Encapsulez-le derrière une interface pour que la vérification reste testable et pour que les applications sans hôte puissent fournir la même réponse depuis une simple variable d’environnement.
public interface IAppEnvironment
{
string? Name { get; } // "Production", "Staging", … ; null when genuinely unknown
}
// Host apps: let the framework resolve DOTNET_ENVIRONMENT / ASPNETCORE_ENVIRONMENT.
public sealed class HostAppEnvironment(IHostEnvironment env) : IAppEnvironment
{
public string? Name =>
string.IsNullOrWhiteSpace(env.EnvironmentName) ? null : env.EnvironmentName;
}
// Console / worker without a host: same variables, explicit fallback order.
public sealed class VariableAppEnvironment : IAppEnvironment
{
public string? Name =>
Environment.GetEnvironmentVariable("DOTNET_ENVIRONMENT")
?? Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT");
// intentionally NOT defaulting to "Production": see the gate — unknown fails closed
}
Un choix délibéré : l’enveloppe d’hôte hérite du comportement « Production par défaut » du framework, mais l’enveloppe de variable non. Pour une vérification, vous voulez qu’un environnement non défini soit inconnu, pas silencieusement production — un environnement inconnu sur une clé restreinte devrait être refusé, pas laissé passer comme le palier le plus privilégié. Le cas de l’hôte est l’exception parce que le framework a déjà pris la décision pour toute l’application, de façon cohérente, avant que votre vérification ne s’exécute.
La vérification
La vérification s’exécute après Validate() et ne fait quelque chose que lorsque la clé porte réellement une revendication scope:env. La correspondance est un test d’appartenance insensible à la casse contre l’ensemble séparé par des virgules, de sorte que scope:env = "staging,production" admet les deux.
public enum EnvStatus { Ok, NotEnvScoped, Unknown, WrongEnv }
public static class EnvGate
{
public static EnvStatus Check(LicenseInfo info, IAppEnvironment app)
{
var claim = info.Entitlements.GetRaw("scope:env");
if (string.IsNullOrWhiteSpace(claim))
return EnvStatus.NotEnvScoped; // legacy/unscoped key: nothing to check
var here = app.Name;
if (string.IsNullOrWhiteSpace(here))
return EnvStatus.Unknown; // fail closed: unknown ≠ allowed
var allowed = claim.Split(',', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries);
foreach (var e in allowed)
if (string.Equals(e, here, StringComparison.OrdinalIgnoreCase))
return EnvStatus.Ok;
return EnvStatus.WrongEnv; // e.g. staging key launched in Production
}
}
Branchez-la au démarrage, après les vérifications de signature et d’expiration que le SDK effectue déjà :
static readonly KeyrightClient License = KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-studio",
PublicKeyBase64 = AcmeKeys.LicensePublicKey, // public key only; safe to ship
});
LicenseInfo info = License.Validate(); // signature, product, expiry
if (!info.IsValid) { RunEvaluation(info); return; }
var env = EnvGate.Check(info, app); // app resolved from DI or the variable wrapper
if (env is not (EnvStatus.Ok or EnvStatus.NotEnvScoped))
{
RunEvaluation(info, reason: env); // "this key is licensed for staging, not Production"
return;
}
RunLicensed(info);
L’ordre compte : la vérification d’environnement s’exécute après IsValid. Une clé à la signature invalide n’atteint jamais la vérification, donc la chaîne scope:env qu’un attaquant aurait pu saisir n’est jamais lue — les entitlements ne sont dignes de confiance qu’une fois la signature qui les couvre vérifiée, et Keyright renvoie un ensemble d’entitlements vide pour tout ce qui n’a pas validé.
Migrer sans jour de bascule
Le piège de tout déploiement d’application de règles est le jour de bascule : vous livrez la vérification et les clés restreintes dans la même version, le nœud de production d’un client démarre avec l’ancienne clé non restreinte, la vérification ne trouve aucune revendication qu’elle reconnaisse et vous avez transformé une mise à jour en panne. La vérification ci-dessus est écrite pour éviter exactement cela — NotEnvScoped est un succès — mais il vaut la peine d’être explicite sur les trois phases.
Phase 1 — émission rétrocompatible. Commencez à émettre de nouvelles clés avec scope:env présent, et laissez intacte chaque clé existante non restreinte. Comme une revendication absente renvoie NotEnvScoped et que cela est traité comme « s’exécute partout », l’ancienne clé de production continue de fonctionner sans y toucher pendant que les nouvelles clés de staging et de production portent leur portée. Aucun nœud n’a besoin d’être re-clé pour la mise à jour.
Phase 2 — auditer, ne pas appliquer. Livrez la vérification qui calcule EnvStatus mais le journalise au lieu d’agir dessus. Lisez les journaux pendant une version. C’est là que vous découvrez les noms d’environnement que vous n’aviez pas prévus — le Staging2 que quelqu’un a monté, le slot blue/green qui rapporte Production sous un DOTNET_ENVIRONMENT différent, le banc de test de charge qui a hérité d’une clé de production. Le schéma de déploiement en mode audit s’applique ici sans changement.
Phase 3 — appliquer, et réémettre. Faites basculer la vérification pour qu’elle agisse sur WrongEnv/Unknown, et réémettez les clés héritées non restreintes comme restreintes à leur prochain renouvellement. La clé non restreinte n’est pas non sécurisée — elle ne dit simplement rien de l’environnement — donc il n’y a pas d’urgence, seulement une direction : chaque renouvellement réduit le rayon d’impact d’une fuite d’un environnement de plus.
Émettre une clé restreinte, et le diagnostic
Côté émetteur, la portée n’est qu’une entitlement de plus à régler. Quelle que soit la façon dont vous frappez les clés — API d’administration ou CLI contre votre instance Keyright — les clés de production et de staging diffèrent par un champ :
# production key
keyright issue --product acme-studio --licensee "Contoso Ltd" \
--entitlement scope:env=production --entitlement max-seats=400 --expiry 2027-11-16
# a single key reusable across your own pre-prod tiers
keyright issue --product acme-studio --licensee "Contoso Ltd (pre-prod)" \
--entitlement scope:env=staging,qa --expiry 2027-11-16
Comblez l’écart de transmission comme le fait le flux de licence de site : livrez un diagnostic d’une ligne qui imprime l’environnement que la vérification contrôlerait, depuis exactement le chemin de code que la vérification utilise, afin que « il dit mauvais environnement » ne devienne jamais un ticket de support sur ce qu’est réellement l’environnement.
// yourapp --env-info
var app = new VariableAppEnvironment();
Console.WriteLine($"Resolved environment : {app.Name ?? "(unknown — DOTNET_ENVIRONMENT unset)"}");
Ce que la restriction d’environnement prouve — et ce qu’elle ne prouve pas
Soyez honnête dans votre propre modèle de menaces sur ce qu’est ce lien.
L’environnement est auto-déclaré. scope:env est comparé à une valeur que le processus en cours lit depuis sa propre configuration, et un opérateur qui contrôle cette configuration peut poser DOTNET_ENVIRONMENT=Production sur une machine de staging et la vérification passera. Ce n’est donc pas un mur contre un opérateur déterminé qui possède l’hôte — ce n’est pas censé l’être. Ce qu’elle arrête, c’est l’accident cent fois plus courant : la clé de staging copiée en production et y tournant en silence pendant un an, la clé de développeur qui a fuité et déverrouille maintenant le palier de production, le secret de CI qui s’avère être une licence de production. Ce sont des erreurs de configuration, et scope:env les transforme de silencieuses en un refus bruyant et précis avec la raison jointe.
C’est une frontière d’hygiène et de télémétrie, pas un décompte de sièges. La restriction ne limite pas combien de machines exécutent une clé — une clé de production avec max-seats compte toujours les sièges comme elle l’a toujours fait ; la portée limite seulement dans quel palier elle s’exécutera. Les deux sont orthogonaux, et il vaut la peine de les garder ainsi : une clé qui est à la fois limitée en sièges et restreinte à un environnement vous dit, dans sa télémétrie, à la fois combien de nœuds de production sont actifs et qu’aucun d’eux n’est secrètement du staging.
Pour une frontière non fiable, restreignez autrement. Si « staging » est l’environnement d’un autre client plutôt que votre propre palier, la configuration auto-déclarée est le mauvais instrument par excellence — liez à quelque chose que l’autre partie ne peut pas affirmer, comme le fait le lien de licence de site au domaine, ou émettez des produits véritablement distincts. La restriction d’environnement mérite sa place quand les environnements sont tous les vôtres, que le risque est une erreur plutôt qu’un adversaire, et que vous voulez que la clé elle-même — pas un runbook de déploiement — soit ce qui garde la production et le staging séparés.
Une licence qui s’exécute partout est pratique jusqu’à la première fuite, où « partout » cesse d’être un atout. Écrire l’environnement dans la clé signée coûte une entitlement et une vérification de vingt lignes, migre sans jour de bascule parce qu’une clé non restreinte s’exécute toujours partout, et donne à chaque validation une réponse à la question que votre journal d’audit cherchait : de quel environnement venait-elle ?
Essayez Nebula.NET
Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.