Skip to content
← Todas las publicaciones
· Delta1 Labs LicensingKeyright

Acotar una licencia Keyright a un entorno

El mismo archivo de licencia tiende a fluir desde producción hacia staging, al portátil de un desarrollador y a través de CI, hasta que nadie sabe de qué entorno vino una validación y una clave de staging filtrada desbloquea producción sin que nadie lo note. Esta es una guía de migración: compara las tres formas en que los equipos separan los entornos —un producto por entorno, un archivo simple por entorno y un único producto con una entitlement env firmada— y después migra a la última en Keyright sin un día de corte. Cubre dónde aprende la aplicación su propio entorno (IHostEnvironment y el respaldo DOTNET_ENVIRONMENT / ASPNETCORE_ENVIRONMENT), una verificación de veinte líneas que falla en cerrado ante un entorno desconocido, un despliegue retrocompatible donde una clave heredada sin acotar sigue ejecutándose en cualquier sitio, y el límite honesto: el entorno lo declara tu propia configuración, así que esto es higiene y telemetría limpia, no un muro contra un operador que ajuste la variable.

Observa un único archivo de licencia el tiempo suficiente y acabará en todas partes. Emites una clave para el producto, la dejas caer en el despliegue de producción y, en un sprint, ya se ha copiado al entorno de staging para que pasen las pruebas de humo previas a producción, se ha pegado en el appsettings.Development.json de un desarrollador y se ha horneado en un secreto de CI para que corran las pruebas de integración. Ahora cuatro entornos presentan la misma clave firmada a tu instancia de Keyright, y han desaparecido tres hechos que te gustaría tener: no puedes saber a partir de una validación de qué entorno vino, una clave de staging que se filtra es una clave de producción, y el día en que quieras caducar antes la clave de staging descubres que es la clave de producción.

Esta entrada es una guía de migración. Compararemos las tres formas en que los equipos separan realmente los entornos, elegiremos la que conserva un único producto y una única ruta de código, y migraremos a ella en Keyright sin un día de corte —incluida la parte que la mayoría de los despliegues se saltan, que es dejar que la vieja clave sin acotar siga funcionando mientras se despliegan las nuevas claves acotadas.

Tres formas de distinguir producción de staging

Solo hay tres formas de hacer esto, y se diferencian en cuánta ceremonia y cuánta duplicación cuestan.

Un producto por entorno. Registra acme-studio-prod y acme-studio-staging como productos separados en tu servicio emisor, cada uno con su propia clave de firma, y envía una clave pública distinta por build. Funciona, y la separación es absoluta, pero ahora mantienes dos de todo —dos pares de claves, dos catálogos de entitlements, dos calendarios de rotación— y una funcionalidad que añades a uno has de recordar añadirla al otro. Esta es la respuesta correcta solo cuando staging y producción son genuinamente productos distintos con capacidades distintas, lo cual rara vez ocurre.

Un archivo simple por entorno, mismo producto. Emite dos licencias para el único producto y confía en la disciplina de despliegue para mantenerlas separadas. Nada en la clave dice para qué entorno es, así que nada impide que el archivo de staging corra en producción; en el momento en que alguien copia el archivo equivocado estás de vuelta donde empezaste, y el payload firmado no ayuda porque no lleva ningún entorno.

Un producto, con el entorno escrito en el payload firmado. Conserva un único producto y una única clave pública, y añade una entitlement scope:env que nombra el entorno o los entornos para los que la clave tiene licencia. La clave de staging, literalmente, no puede validarse como licenciada en producción, porque la aplicación comprueba su propio entorno contra la reclamación y la reclamación está cubierta por la firma. Ningún segundo producto, ninguna segunda rotación, una sola verificación. Esta es la forma a la que migramos.

Three ways to separate environmentsA · product per env+ absolute separation– two key pairs– two catalogues– two rotations– features drift apartB · bare file per env+ no payload change– relies on discipline– staging file runs  in production– payload says nothingC · signed env entitlement+ one key pair+ one gate, one code path+ staging key can't  validate in prod– env is self-reportedrecommendedC adds one entitlement and one check to the key you already ship — no second product, no second rotation schedule.

Lo que dice la clave

Una entitlement scope:env es una entitlement firmada corriente —una cadena dentro del payload canónico que la firma cubre— que contiene un conjunto separado por comas de nombres de entorno en los que la clave es válida. Una clave de producción nombra un entorno; una clave que quieras reutilizar entre tus propios niveles previos a producción nombra varios.

{
  "product":  "acme-studio",
  "licensee": "Contoso Ltd",
  "expiryUtc": "2027-11-16T00:00:00Z",
  "tier":     "pro",
  "entitlements": {
    "scope:env":   "production",
    "export":      "true",
    "max-seats":   "400"
  },
  "signature": "…"
}

El prefijo scope: es una convención, no una funcionalidad de Keyright, y se gana su sitio igual que lo hace site:: mantiene visiblemente separado dónde puede ejecutarse esta clave de qué desbloquea esta clave, de modo que nadie acabe condicionando la funcionalidad export a un entorno ni al revés. Como el valor está dentro del payload firmado, un cliente —o un desarrollador con prisa— no puede cambiar production por staging más de lo que puede empujar la caducidad un año: un byte cambiado y la aplicación ve LicenseStatus.SignatureInvalid.

Lo que la aplicación sabe de su propio entorno

La aplicación ha de responder a “¿qué entorno soy?” desde su propia configuración, sin conexión, al arrancar. En una aplicación ASP.NET Core o de host genérico la respuesta ya existe: IHostEnvironment.EnvironmentName, que el host resuelve desde DOTNET_ENVIRONMENT (o ASPNETCORE_ENVIRONMENT para el host web), con Production por defecto cuando no hay ninguno. Envuélvelo tras una interfaz para que la verificación siga siendo testeable y para que las aplicaciones sin host puedan dar la misma respuesta desde una variable de entorno sin más.

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
}

Una decisión deliberada: el envoltorio de host hereda el comportamiento “por defecto Production” del framework, pero el envoltorio de variable no. Para una verificación quieres que un entorno sin definir sea desconocido, no silenciosamente producción —un entorno desconocido sobre una clave acotada debería rechazarse, no colarse como el nivel más privilegiado. El caso del host es la excepción porque el framework ya ha tomado la decisión para toda la aplicación, de forma consistente, antes de que tu verificación corra.

La verificación

La verificación corre después de Validate() y solo hace algo cuando la clave lleva realmente una reclamación scope:env. El emparejamiento es una prueba de pertenencia sin distinción de mayúsculas contra el conjunto separado por comas, de modo que scope:env = "staging,production" admite ambos.

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

Conéctala al arrancar, después de las comprobaciones de firma y caducidad que el SDK ya realiza:

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

El orden importa: la verificación de entorno corre después de IsValid. Una clave con firma inválida nunca llega a la verificación, así que la cadena scope:env que un atacante podría haber escrito nunca se lee —las entitlements solo son fiables una vez verificada la firma que las cubre, y Keyright devuelve un conjunto de entitlements vacío para cualquier cosa que no haya validado.

Migrar sin un día de corte

La trampa en todo despliegue de aplicación de reglas es el día de corte: envías la verificación y las claves acotadas en la misma versión, el nodo de producción de un cliente arranca con la vieja clave sin acotar, la verificación no encuentra ninguna reclamación que reconozca y has convertido una actualización en una caída. La verificación de arriba está escrita para evitar exactamente eso —NotEnvScoped es un aprobado— pero merece la pena ser explícito sobre las tres fases.

Fase 1 — emisión retrocompatible. Empieza a emitir claves nuevas con scope:env presente, y deja intacta cada clave existente sin acotar. Como una reclamación ausente devuelve NotEnvScoped y eso se trata como “corre en cualquier sitio”, la vieja clave de producción sigue funcionando sin tocarla mientras las nuevas claves de staging y producción llevan su scope. Ningún nodo tiene que re-clavarse para actualizar.

Fase 2 — auditar, no aplicar. Envía la verificación calculando EnvStatus pero registrándolo en lugar de actuar sobre él. Lee los registros durante una versión. Aquí es donde descubres los nombres de entorno que no previste —el Staging2 que alguien levantó, el slot blue/green que reporta Production bajo un DOTNET_ENVIRONMENT distinto, el banco de pruebas de carga que heredó una clave de producción. El patrón de despliegue en modo auditoría se aplica aquí sin cambios.

Fase 3 — aplicar, y re-emitir. Cambia la verificación para que actúe sobre WrongEnv/Unknown, y re-emite las claves heredadas sin acotar como acotadas en su siguiente renovación. La clave sin acotar no es insegura —simplemente no dice nada sobre el entorno— así que no hay urgencia, solo una dirección: cada renovación reduce el radio de daño de una filtración en un entorno más.

Migrating in three phases, no flag dayPhase 1 · issue scopednew keys carry scope:envlegacy keys untouchedmissing claim = runs anywhereno re-keying to upgradePhase 2 · auditgate computes EnvStatuslogs, does not actsurfaces unexpected namesStaging2, blue/green slotsPhase 3 · enforceact on WrongEnv / Unknownre-issue legacy on renewalleak blast radius shrinksone environment at a time

Emitir una clave acotada, y el diagnóstico

En el lado emisor el scope es solo otra entitlement que ajustar. Sea como sea que acuñes claves —API de administración o CLI contra tu instancia de Keyright— las claves de producción y staging difieren en un campo:

# 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

Cierra la brecha de entrega igual que lo hace el flujo de licencia de sitio: envía un diagnóstico de una línea que imprima el entorno que la verificación comprobaría, desde exactamente la ruta de código que la verificación usa, para que “dice entorno equivocado” nunca se convierta en un ticket de soporte sobre cuál es el entorno realmente.

// yourapp --env-info
var app = new VariableAppEnvironment();
Console.WriteLine($"Resolved environment : {app.Name ?? "(unknown — DOTNET_ENVIRONMENT unset)"}");

Lo que el acotamiento de entorno prueba —y lo que no

Sé honesto en tu propio modelo de amenazas sobre qué es este vínculo.

El entorno se declara a sí mismo. scope:env se comprueba contra un valor que el proceso en ejecución lee de su propia configuración, y un operador que controla esa configuración puede poner DOTNET_ENVIRONMENT=Production en una máquina de staging y la verificación pasará. Así que esto no es un muro contra un operador decidido que posee el host —no pretende serlo. Lo que sí detiene es el accidente que es cien veces más común: la clave de staging copiada en producción y corriendo ahí en silencio durante un año, la clave de desarrollador que se filtró y ahora desbloquea el nivel de producción, el secreto de CI que resulta ser una licencia de producción. Esos son errores de configuración, y scope:env los convierte de silenciosos en un rechazo ruidoso y específico con el motivo adjunto.

Es un límite de higiene y telemetría, no un recuento de asientos. El acotamiento no limita cuántas máquinas corren una clave —una clave de producción con max-seats sigue contando asientos como siempre; el scope solo limita en qué nivel correrá. Los dos son ortogonales, y merece la pena mantenerlos así: una clave que es a la vez limitada por asientos y acotada por entorno te dice, en su telemetría, tanto cuántos nodos de producción están vivos como que ninguno de ellos es secretamente staging.

Para un límite no confiable, acota de otra forma. Si “staging” es el entorno de otro cliente en lugar de tu propio nivel, la configuración declarada por uno mismo es el instrumento equivocado por completo —vincula a algo que la otra parte no pueda afirmar, como hace el vínculo de licencia de sitio a dominio, o emite productos genuinamente separados. El acotamiento de entorno se gana su sitio cuando los entornos son todos tuyos, el riesgo es un error más que un adversario, y quieres que la clave misma —no un runbook de despliegue— sea lo que mantenga producción y staging separados.

Una licencia que corre en todas partes es cómoda hasta la primera filtración, cuando “en todas partes” deja de ser una ventaja. Escribir el entorno en la clave firmada cuesta una entitlement y una verificación de veinte líneas, migra sin un día de corte porque una clave sin acotar sigue corriendo en cualquier sitio, y da a cada validación una respuesta a la pregunta que tu registro de auditoría ha estado echando de menos: ¿de qué entorno era esta?

Prueba Nebula.NET

Endurece tu código .NET en minutos — empieza con la edición gratuita.