Skip to content
← Todas las publicaciones
· Delta1 Labs DeploymentKeyright

Sembrar una licencia Keyright desde un instalador WiX/MSI

El software de escritorio empresarial no lo activa la persona que lo ejecuta. Se distribuye de forma silenciosa mediante directivas de grupo, Intune o SCCM con msiexec /qn, hacia máquinas cuyos usuarios nunca ven un cuadro de diálogo y a menudo no pueden alcanzar tu servicio de licencias. Esta guía práctica construye el despliegue que la mayoría de los ISV acaban necesitando: un MSI que coloca una licencia firmada a nivel de máquina bajo ProgramData para que la app ya tenga licencia en el primer arranque, además de la alternativa de pasar una clave de activación como propiedad del MSI y dejar que la app la reclame una vez en línea. Cubre la autoría en WiX v5, dónde debe residir el archivo para que todos los usuarios de Windows del equipo compartan un asiento, la acción personalizada diferida que escribe una clave que la app recogerá, las opciones del SDK que hacen que ProgramData sea autoritativo y las líneas de comando de msiexec que un administrador pega en su herramienta de despliegue.

Una app de consumo pide la clave de licencia a la persona que está frente al teclado. El software empresarial casi nunca llega a hacerlo. Aparece en un portátil a través de Intune, de una GPO de instalación de software, de una secuencia de tareas de SCCM: msiexec /i Acme.msi /qn ejecutado por la cuenta SYSTEM, sin ventana, sin usuario, a menudo sin ninguna ruta a la internet pública. Si tu experiencia de primer arranque es «escribe aquí tu clave», ese despliegue aterriza en unos cuantos miles de máquinas mostrando un cuadro de diálogo de activación frente al que no hay nadie sentado.

Así que la licencia debe estar colocada antes del primer arranque, puesta allí por el instalador. Este artículo lo construye para una app de escritorio .NET con licencia de Keyright, usando WiX v5 para el MSI. Hay dos formas —incluir una licencia de sitio firmada, o pasar una clave de activación como propiedad— y la primera es la que quieres para cualquier cosa aislada de la red (air-gapped). Haremos ambas, y dedicaremos la mayor parte del tiempo al detalle que lo hace funcionar o fracasar: dónde va el archivo.

El lugar equivocado: AppData por usuario

El destino por defecto del SDK de Keyright para un lease activado y una licencia sin conexión es {LocalApplicationData}\Keyright\{product}\, es decir, %LocalAppData%: una carpeta por usuario. Eso es exactamente lo correcto cuando un usuario activa la app por sí mismo. Es exactamente lo equivocado para un instalador, por dos razones.

Un MSI que se ejecuta en una instalación silenciosa a nivel de máquina corre como NT AUTHORITY\SYSTEM. Su %LocalAppData% es C:\Windows\System32\config\systemprofile\AppData\Local: una carpeta que ningún usuario interactivo leerá jamás. E incluso si suplantaras al usuario que instala, un despliegue de máquina no sabe qué usuario ejecutará la app; pueden ser diez personas distintas en una estación de trabajo compartida, o un usuario que todavía no ha iniciado sesión cuando se ejecuta la instalación.

Un despliegue con licencia de máquina quiere una sola licencia, legible por todos los usuarios del equipo, escrita una vez por el instalador. Para eso está %ProgramData% (CommonAppDataFolder, C:\ProgramData): a nivel de máquina, legible por todos y el hogar natural de una licencia que pertenece al dispositivo en lugar de a una persona.

Where the installer should put the licensemsiexec /qnruns as SYSTEMper-user AppData — wrong%LocalAppData% → System32\config\systemprofileno interactive user ever reads this folderUser A: noneUser B: noneProgramData — right%ProgramData%\Keyright\acme-studio\license.jsonmachine-wide, world-readable, written onceUser A: licensedUser B: licensedone machine fingerprint → one seatboth users present the same machineId; the service binds a single deviceA device-licensed deployment keeps the license with the device, not with whichever person logs in first.

Forma 1: incluir una licencia de sitio firmada

Para un cliente de volumen o de sitio emites un documento de licencia firmado y lo envías dentro del MSI. Como una licencia de Keyright es una carga firmada cuya seguridad es la firma y no el secreto, es seguro llevarla en un instalador; un byte editado la invalida. Emítela perpetua (o bloqueada al nodo del despliegue si bloqueas los equipos de sitio) para que nada en la máquina final tenga que llamar a casa.

La autoría en WiX es un componente corriente que coloca el archivo en una subcarpeta de ProgramData:

<!-- Acme.Studio.wxs — WiX v5 -->
<Package Name="Acme Studio" Manufacturer="Acme Ltd"
         Version="4.2.0" UpgradeCode="7c3f9e10-7b22-4a8f-9f2e-6d4c1b0a55e1"
         Scope="perMachine">

  <StandardDirectory Id="CommonAppDataFolder">
    <Directory Id="AcmeData" Name="Keyright">
      <Directory Id="AcmeProduct" Name="acme-studio" />
    </Directory>
  </StandardDirectory>

  <!-- The signed site license, shipped in the MSI, written to ProgramData. -->
  <Component Id="SiteLicense" Directory="AcmeProduct" Guid="*">
    <File Id="LicenseJson" Source="licenses\site-license.json" Name="license.json" />
  </Component>

  <Feature Id="Main">
    <ComponentRef Id="SiteLicense" />
    <!-- app files … -->
  </Feature>
</Package>

CommonAppDataFolder se resuelve a C:\ProgramData, así que el archivo acaba en C:\ProgramData\Keyright\acme-studio\license.json. Una instalación por máquina le da a ese árbol una ACL que todos los usuarios pueden leer y solo los administradores pueden escribir, que es exactamente lo que quieres para una licencia: legible por quien ejecute la app, no editable por él.

Ahora el SDK tiene que mirar allí. Por defecto lee la ruta por usuario, así que para un producto con licencia de máquina apunta DefaultLicensePath (la ubicación de reserva ambiental) a la copia en ProgramData:

using Keyright;

static KeyrightClient CreateLicenseClient()
{
    string machineWide = Path.Combine(
        Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
        "Keyright", "acme-studio");

    var options = new KeyrightOptions
    {
        Product            = "acme-studio",
        PublicKeyBase64    = AcmeKeys.LicensePublicKey,   // public key only; safe to ship
        ServiceUrl         = "https://licensing.acme.example",
        DefaultLicensePath = Path.Combine(machineWide, "license.json"),
        // Lease/state stay per-user; only the seeded license is machine-wide.
    };

    return KeyrightClient.Initialize(options);
}

DefaultLicensePath es la fuente ambiental: se consulta después de un LicenseFilePath explícito o de la variable de entorno KEYRIGHT_LICENSE, pero antes de que la app recurra a «sin licencia». Esa precedencia importa: un cliente de sitio que más tarde compre una actualización por asiento puede dejar un archivo más nuevo en la ruta explícita o fijar la variable de entorno sin que tengas que recortar de nuevo el MSI, y gana sobre la sembrada. En el primer arranque client.Validate() encuentra el documento sembrado, lo verifica sin conexión contra la clave pública incrustada, y la app tiene licencia sin cuadro de diálogo y sin red.

LicenseInfo info = client.Validate(out LicenseSourceKind source);
// info.IsValid == true, source == LicenseSourceKind.LicenseFile,
// info.Licensee == "Globex Corporation", info.ExpiryUtc == null

Como la licencia sembrada es perpetua, el SDK no escribe ningún estado local para ella —ni lease, ni marca de tiempo de primer visto— así que no hay nada por usuario que pueda fallar y nada que una desinstalación tenga que limpiar más allá del archivo que el MSI posee.

Forma 2: pasar una clave de activación como propiedad del MSI

Algunos despliegues tienen licencia por asiento, no por sitio, y el administrador tiene una clave en lugar de un archivo firmado. Aquí no quieres activar durante la instalación: una activación en línea desde una acción personalizada diferida que corre como SYSTEM es la llamada de red menos fiable de tu producto, y toma la huella del contexto de seguridad equivocado. En su lugar, deja que el instalador prepare la clave, y deja que la app se active sola en el primer arranque, en el contexto del usuario, donde puede alcanzar el servicio y presentar la identidad real de la máquina.

Declara una propiedad pública para que el administrador pueda suministrar la clave en la línea de comandos, y hazla Secure para que sobreviva al cambio a la fase de ejecución diferida (SYSTEM):

<Property Id="LICENSEKEY" Secure="yes" />

<!-- Deferred CA needs its data marshalled in via a same-named property. -->
<SetProperty Id="StageLicenseKey" Value="[LICENSEKEY]"
             Before="StageLicenseKey" Sequence="execute"
             Condition="LICENSEKEY" />

<CustomAction Id="StageLicenseKey" BinaryRef="AcmeCa"
              DllEntry="StageLicenseKey" Execute="deferred"
              Impersonate="no" Return="check" />

<InstallExecuteSequence>
  <Custom Action="StageLicenseKey" After="InstallFiles" Condition="LICENSEKEY" />
</InstallExecuteSequence>

La acción personalizada escribe la clave en un archivo de traspaso conocido y a nivel de máquina. Deliberadamente no hace nada de red: solo deja una miga de pan que la app consumirá:

// WiX v5 custom action (WixToolset.Dtf.WindowsInstaller)
using WixToolset.Dtf.WindowsInstaller;

public class CustomActions
{
    [CustomAction]
    public static ActionResult StageLicenseKey(Session session)
    {
        // Deferred CAs cannot read properties directly; the value arrives as CustomActionData.
        string key = session["CustomActionData"]?.Trim() ?? "";
        if (key.Length == 0) return ActionResult.Success;

        string dir = Path.Combine(
            Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
            "Keyright", "acme-studio");
        Directory.CreateDirectory(dir);
        File.WriteAllText(Path.Combine(dir, "pending-activation.key"), key);
        return ActionResult.Success;
    }
}

En el primer arranque la app busca esa miga de pan, activa una vez y la borra para que la activación nunca se repita:

static async Task EnsureActivatedAsync(KeyrightClient client)
{
    // Already licensed from a cached lease? Nothing to do.
    if (client.Validate().IsValid) return;

    string pending = Path.Combine(
        Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData),
        "Keyright", "acme-studio", "pending-activation.key");

    if (!File.Exists(pending)) return;   // no staged key; fall back to the UI's "Enter key" flow

    string key = (await File.ReadAllTextAsync(pending)).Trim();
    ActivationResult result = await client.ActivateAsync(key);

    if (result.Status == LicenseStatus.Ok)
        File.Delete(pending);            // consumed; do not re-activate on next launch
    else if (result.Status == LicenseStatus.SeatLimit)
        File.Delete(pending);            // a real answer, not a transient failure — stop retrying
    // On a transient/offline failure, leave the file so the next launch retries.
}

La activación corre como el usuario, almacena su lease por usuario y vincula el asiento a la máquina en la que la app realmente se ejecuta. Mantén la activación idempotente de tu lado (ya lo es en Keyright) para que dos usuarios en el mismo PC compartido que consuman la misma clave preparada refresquen un asiento en lugar de quemar dos: ambos presentan la misma huella de máquina, y el segundo ActivateAsync refresca el registro de dispositivo del primero.

Two ways to seed, one licensed first runShape 1 — site license (offline)MSI Component writesProgramData\…\license.jsonfirst launch:Validate() offline, no netlicensed, no dialogsource = LicenseFile · perpetualShape 2 — activation key (online, first run)msiexec … LICENSEKEY=…deferred CA stagespending-activation.keyfirst launch reads keyActivateAsync() onlinecache lease · delete keylicensed, no dialogseat bound to machineper-user lease cachedActivation runs in the user's context on first launch — never from the SYSTEM custom action.

Las líneas de comando que un administrador realmente ejecuta

Sea lo que sea que construyas, la salida es una línea que alguien pega en una GPO, en una app Win32 de Intune o en un programa de SCCM. Documenta estas junto al MSI:

:: Site license baked into the MSI — nothing to pass, fully silent, works offline.
msiexec /i Acme.Studio.msi /qn /l*v %TEMP%\acme-install.log

:: Per-seat: hand the installer the activation key. Quote it; keys can contain punctuation.
msiexec /i Acme.Studio.msi /qn LICENSEKEY="ACME-7F3A-9C21-5E08-BD44"

:: Intune Win32 app "install command" is the same line; detection rule = the app's EXE/version.

Dos advertencias que vale la pena poner en manos del administrador. Los nombres de propiedad pasados en la línea de comandos deben ser públicos (en mayúsculas) o el MSI los descarta: LICENSEKEY, nunca licenseKey. Y una clave en una línea de comandos puede aparecer en el registro detallado del MSI y, brevemente, en la lista de procesos; prefiere la forma de la licencia de sitio incluida para cualquier cosa sensible, y si debes pasar una clave, marca la propiedad como Secure y di a los administradores que no habiliten el registro /l*v por paquete en transcripciones compartidas.

Desinstalación, reparación y actualización

El componente que posee license.json hace que el ciclo de vida del archivo sea el del MSI. Una desinstalación estándar lo elimina, lo cual es correcto: el dispositivo ya no tiene licencia para ejecutar el producto. Una reparación (msiexec /f) vuelve a colocar la licencia de sitio incluida, sanando un archivo que un usuario borró. Una actualización mayor lo reemplaza con lo que sea que lleve el nuevo MSI, así que si envías una licencia de sitio nueva en una compilación nueva, esta sustituye limpiamente a la antigua.

La clave de activación preparada es distinta: no es un componente del MSI (el instalador la escribe, no es un archivo enviado), así que una desinstalación no eliminará pending-activation.key a menos que añadas una entrada RemoveFile; añádela, para que una reinstalación no reactive contra una clave que el cliente haya rotado desde entonces. El lease por usuario que la app almacenó es AppData por usuario y está fuera del alcance del instalador por diseño; si el cliente está retirando la máquina, haz que desactive primero dentro de la app, o libera el dispositivo desde el panel Devices de la licencia en el panel de Keyright, igual que cualquier traslado de asiento.

<Component Id="CleanStagedKey" Directory="AcmeProduct" Guid="*">
  <RemoveFile Id="RmPendingKey" Name="pending-activation.key" On="uninstall" />
</Component>

Lo que hay que llevarse

El software empresarial lo instala una herramienta y lo ejecuta un desconocido, así que la licencia tiene que estar colocada antes de que nadie abra la app. Ponla donde el dispositivo pueda leerla —%ProgramData%, no AppData por usuario— y deja que el MSI posea su ciclo de vida. Si el despliegue está aislado de la red o tiene licencia de sitio, incluye una licencia perpetua firmada y apunta DefaultLicensePath a ella; el primer arranque tiene licencia sin red y sin cuadro de diálogo. Si es por asiento, prepara la clave desde una acción personalizada diferida y deja que la app se active sola en el primer arranque en el contexto del propio usuario, donde la huella y la red son reales. En cualquier caso, la persona que enciende el portátil ve tu producto funcionando, que es el único primer arranque aceptable para un software que no compró y no puede activar.

Prueba Nebula.NET

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