Licencias de software

La mayoría de los productos de software necesitan una forma de controlar quién puede usarlos y bajo qué condiciones. Ya sea que distribuyas una aplicación de escritorio, un servidor local, una herramienta de línea de comandos o un SDK, necesitas responder preguntas como: «¿Este usuario ha pagado?», «¿Cuántos puestos están permitidos?», «¿Esta licencia sigue siendo válida?» y «¿Este dispositivo puede ejecutar el software?»

Auris Licensing proporciona un sistema completo para emitir, validar y gestionar claves de licencia de software. Está integrado en la plataforma Auris junto con la autenticación y la autorización, para que puedas vincular las licencias directamente a tus usuarios, organizaciones y tenants existentes.

El modelo de licencias

Auris Licensing se organiza en torno a tres conceptos fundamentales: Políticas, Claves y Derechos. Forman una jerarquía que separa la plantilla (qué tipo de licencia) de la instancia (una licencia específica emitida a un cliente específico) de las concesiones (lo que la licencia realmente otorga).

Políticas

Una política es una plantilla que define las reglas y la forma de una categoría de licencias. Se crean políticas antes de emitir claves. Un mismo producto puede tener varias políticas — una para prueba, una para un plan personal, una para un plan empresarial.

Una política define:

Las políticas son inmutables por diseño. Cuando necesitas cambiar las condiciones para nuevos clientes, creas una nueva versión de la política. Las claves existentes emitidas bajo la política anterior conservan sus condiciones originales, salvo migración explícita.

Claves

Una clave es una instancia de licencia específica emitida a partir de una política y otorgada a un titular. El titular puede ser un usuario, una organización o un dispositivo — dependiendo de tu modelo de licencia.

Cuando se crea una clave, Auris:

1. Genera la cadena de clave según el formato definido por la política
2. Registra la asociación entre la clave, la política y el titular
3. Calcula los derechos iniciales a partir de los valores por defecto de la política
4. Establece la fecha de expiración (si la política tiene una duración)
5. Emite un evento license.key.created (para webhooks y automatización)

Las claves tienen un ciclo de vida:

Created → Active → [Suspended] → [Expired | Revoked]

• Active: La clave pasa las verificaciones de validación y el titular puede usar el software.
• Suspended: Desactivada temporalmente (p. ej., fallo de pago). Puede reactivarse.
• Expired: El período de validez de la clave ha transcurrido. No puede reactivarse sin emitir una nueva clave o extender la expiración.
• Revoked: Invalidada permanentemente por un administrador. No puede reactivarse.

Derechos

Los derechos son lo que la clave realmente otorga en tiempo de ejecución. Son los permisos y límites concretos que tu aplicación verifica.

Los derechos incluyen:

• Indicadores de funcionalidades: Valores booleanos con nombre (p. ej., advanced-analytics, custom-branding, api-access)
• Cantidad de puestos: Cuántos usuarios pueden usar el software de manera simultánea o en total
• Cantidad de dispositivos: En cuántas máquinas se puede activar la clave
• Fecha de expiración: Cuándo expiran los derechos
• Metadatos: Pares clave-valor arbitrarios para lógica de licencias personalizada

Aunque los derechos se derivan inicialmente de la política, pueden sobrescribirse por clave. Esto te permite manejar excepciones sin crear una nueva política — por ejemplo, otorgar 5 puestos adicionales a un cliente específico como parte de un acuerdo negociado.

Modos de validación

Cuando tu aplicación necesita verificar si una licencia es válida, realiza una comprobación de validación. Auris soporta tres modos de validación, cada uno con diferentes compromisos entre seguridad, disponibilidad y latencia.

Validación en línea

Cada comprobación de validación realiza una llamada API a Auris:

Client → POST /api/licensing/validate → Auris API → Database → Response

La API verifica que la clave existe, está activa, no ha expirado y que el dispositivo/usuario actual está dentro de los límites permitidos. La respuesta incluye el objeto completo de derechos.

Fortalezas: Siempre actualizado. Las revocaciones surten efecto inmediatamente. El conteo de puestos y dispositivos es preciso en tiempo real.

Debilidades: Requiere conectividad de red. Añade latencia a cada verificación. Si Auris es inalcanzable, la aplicación no puede validar.

Ideal para: Aplicaciones SaaS, aplicaciones web y cualquier entorno con conectividad a Internet confiable.

Validación híbrida

Primero en línea, con un JWT firmado como respaldo para escenarios sin conexión:

Client → POST /api/licensing/validate → Success? Use response
                                       → Failure/timeout? Use cached JWT

Cuando una validación en línea tiene éxito, la API devuelve un token de licencia firmado (JWT) junto con los derechos. El cliente almacena en caché este JWT localmente. Si un intento de validación posterior falla (error de red, tiempo de espera agotado), el cliente recurre al JWT almacenado en caché.

El JWT de licencia contiene:

{
  "sub": "key_abc123",
  "iss": "https://api.altovar.net",
  "iat": 1710000000,
  "exp": 1710086400,
  "entitlements": {
    "features": ["advanced-analytics", "api-access"],
    "maxSeats": 10,
    "maxDevices": 5
  },
  "policy": "pol_enterprise",
  "licensee": {
    "type": "organization",
    "id": "org_xyz"
  }
}

El JWT está firmado con la clave privada del tenant (RS256). Tu aplicación verifica la firma usando la clave pública del endpoint JWKS — no se necesita ninguna llamada de red a Auris para la validación en caché.

Fortalezas: Funciona sin conexión durante la vigencia del claim exp del JWT. Las verificaciones en línea mantienen los derechos actualizados. Degradación gradual.

Debilidades: Durante los períodos sin conexión, las revocaciones y los cambios de derechos no se reflejan hasta que el JWT expire y una nueva verificación en línea tenga éxito.

Ideal para: Aplicaciones de escritorio, aplicaciones móviles y entornos con conectividad intermitente.

Validación sin conexión

Validación únicamente por JWT, sin ninguna dependencia de red:

Client → Verify JWT signature locally → Check exp claim → Read entitlements

El JWT de licencia se emite una sola vez (durante la activación) y se almacena en el cliente. Cada comprobación de validación es una operación criptográfica local — verificar la firma, comprobar la expiración, leer los derechos.

Fortalezas: Cero dependencia de red. Validación en menos de un milisegundo. Funciona en entornos aislados.

Debilidades: Los cambios de derechos requieren volver a emitir y reimportar el JWT. Las revocaciones dependen del mecanismo separado de lista de revocación (ver Revocación).

Ideal para: Software local, sistemas embebidos, entornos aislados y cualquier escenario donde el cliente no puede o no debe contactar una API externa.

Licencias flotantes

Las licencias tradicionales por puesto asignan puestos de forma permanente — si tienes 10 puestos, solo 10 usuarios nombrados pueden usar el software. Las licencias flotantes adoptan un enfoque diferente: los puestos se arriendan temporalmente y se devuelven cuando ya no se usan.

Esto es ideal para organizaciones donde muchos empleados necesitan acceso ocasional pero pocos usan el software simultáneamente. Una empresa con 50 empleados podría necesitar solo 10 puestos flotantes si no más de 10 personas usan el software al mismo tiempo.

Cómo funcionan las licencias flotantes

El ciclo de vida de las licencias flotantes tiene tres operaciones:

Checkout

Cuando un usuario inicia la aplicación, el cliente solicita un arrendamiento de puesto a Auris:

POST /api/licensing/checkout
{
  "key": "key_abc123",
  "userId": "user_alice",
  "leaseDuration": 30  // minutes
}

Auris verifica si hay un puesto disponible (arrendamientos activos < puestos máx.). Si hay un puesto disponible, crea un registro de arrendamiento con un tiempo de expiración y devuelve un token de arrendamiento. Si todos los puestos están ocupados, el checkout falla con un error SEATS_EXHAUSTED.

Heartbeat

Mientras el usuario usa activamente el software, el cliente extiende periódicamente el arrendamiento:

POST /api/licensing/heartbeat
{
  "leaseId": "lease_xyz",
  "extend": 30  // minutes
}

El heartbeat reinicia el temporizador de expiración del arrendamiento. Si el cliente deja de enviar heartbeats (caída de la aplicación, pérdida de red, ausencia del usuario), el arrendamiento expirará de forma natural.

Checkin

Cuando el usuario cierra la aplicación, el cliente libera explícitamente el puesto:

POST /api/licensing/checkin
{
  "leaseId": "lease_xyz"
}

El arrendamiento se elimina inmediatamente, liberando el puesto para otro usuario. Si el cliente no realiza el checkin (caída, cierre forzado), el arrendamiento expira automáticamente después de que transcurra la duración del arrendamiento.

Expiración de arrendamientos y recuperación

El mecanismo de expiración automática es fundamental para las licencias flotantes. Sin él, un cliente que se haya caído ocuparía un puesto permanentemente. Auris ejecuta una limpieza periódica que elimina los arrendamientos expirados, asegurando que los puestos siempre sean recuperables.

La duración del arrendamiento es un equilibrio entre capacidad de respuesta y resiliencia:

• Arrendamientos cortos (5-10 minutos): Los puestos se recuperan rápidamente después de una caída, pero el tráfico de heartbeat es mayor.
• Arrendamientos largos (30-60 minutos): Menos tráfico de heartbeat, pero un cliente caído ocupa un puesto durante más tiempo.

La duración recomendada por defecto es de 15 a 30 minutos, con heartbeats enviados a la mitad del intervalo del arrendamiento.

Activación sin conexión

Algunos entornos no tienen acceso a la red — sistemas de planta de fábrica, redes gubernamentales clasificadas, dispositivos médicos, sistemas de control industrial. Para estos escenarios, Auris soporta un flujo de activación completamente sin conexión que nunca requiere que el cliente se comunique directamente con la API de Auris.

El flujo de activación sin conexión

El proceso involucra un intermediario humano que transporta datos entre la máquina aislada y una máquina con acceso a la API o la consola:

Paso 1: El cliente genera una carga útil de solicitud

La aplicación cliente recopila la clave de licencia y una huella del dispositivo, las empaqueta en una carga útil estructurada y la codifica como una cadena base64:

{
  "key": "key_abc123",
  "fingerprint": "fp_sha256_a1b2c3d4e5f6...",
  "requestedAt": "2025-06-15T10:30:00Z",
  "clientVersion": "2.4.1"
}

El usuario copia esta cadena base64 (mostrada como texto o código QR) y la lleva a una máquina conectada.

Paso 2: El administrador envía la solicitud

El administrador pega la carga útil de la solicitud en la consola de Auris (en Licensing > Offline Activations) o la envía a través de la API:

POST /api/licensing/activate/offline
{
  "requestPayload": "eyJrZXkiOiAia2V5X2FiYz..."
}

Auris valida la clave, registra la huella del dispositivo y genera un token de respuesta firmado — un JWT que contiene todos los derechos, vinculado a la huella específica del dispositivo.

Paso 3: El cliente importa el token de respuesta

El administrador copia el token de respuesta de vuelta a la máquina aislada. La aplicación cliente lo importa, verifica la firma con una clave pública incluida o previamente obtenida, y activa la licencia.

A partir de este momento, el cliente valida la licencia completamente sin conexión verificando la firma del JWT y comprobando sus claims.

Huella del dispositivo

Las licencias vinculadas a dispositivos requieren una forma de identificar máquinas de manera confiable. Auris utiliza una huella compuesta construida a partir de múltiples atributos de hardware y sistema operativo, condensada en un identificador estable.

La huella se calcula a partir de una combinación de:

• Modelo y número de núcleos del procesador
• Memoria total del sistema
• Tipo y versión del sistema operativo
• Números de serie de los discos
• Direcciones MAC de las interfaces de red (filtrando adaptadores virtuales)
• ID de máquina o UUID de hardware (específico de la plataforma)

Ningún atributo se usa de forma aislada, porque cualquiera puede cambiar (una ampliación de RAM, una nueva tarjeta de red). En su lugar, la huella usa un algoritmo de coincidencia por umbral: si un número suficiente de atributos aún coinciden, la huella se considera de la misma máquina. Esto tolera cambios menores de hardware mientras detecta cuándo una licencia ha sido trasladada a una máquina fundamentalmente diferente.

El umbral es configurable por política:

Cuando se detecta una discrepancia de huella más allá de la tolerancia configurada, la validación falla con un error DEVICE_MISMATCH. El usuario final debe desactivar el dispositivo anterior (si es accesible) o contactar al administrador para restablecer la vinculación del dispositivo.

Revocación

Revocar una clave de licencia significa impedir permanente o temporalmente que pase la validación. La rapidez con la que la revocación surte efecto depende del modo de validación.

Revocación en línea

Cuando una clave es revocada y el cliente usa validación en línea, la revocación es inmediata. La siguiente llamada a POST /api/licensing/validate devuelve:

{
  "ok": true,
  "data": {
    "valid": false,
    "code": "KEY_REVOKED",
    "message": "This license key has been revoked."
  }
}

No se necesita ningún mecanismo adicional — el servidor es la fuente de verdad.

Revocación sin conexión

Cuando el cliente usa validación sin conexión o híbrida, el JWT de la clave revocada sigue siendo criptográficamente válido hasta que expire. Para abordar esto, Auris publica una lista de revocación — un JWT firmado que contiene un arreglo de identificadores de claves revocadas y sus marcas de tiempo de revocación.

{
  "iss": "https://api.altovar.net",
  "iat": 1710000000,
  "exp": 1710086400,
  "revoked": [
    { "key": "key_abc123", "revokedAt": "2025-06-15T14:00:00Z" },
    { "key": "key_def456", "revokedAt": "2025-06-14T09:30:00Z" }
  ]
}

Los clientes que soportan validación sin conexión deben obtener periódicamente la lista de revocación desde el endpoint conocido (GET /api/licensing/.well-known/revocation-list) y almacenarla en caché localmente. Durante la validación sin conexión, el cliente verifica el JWT de licencia y la lista de revocación en caché.

Período de gracia y TTL

La revocación en escenarios sin conexión es inherentemente retardada. Dos opciones de configuración controlan el compromiso:

El período de gracia existe para prevenir una interrupción abrupta en entornos donde la conectividad es infrecuente. Un cliente aislado que obtiene la lista de revocación semanalmente aún respetará las revocaciones dentro de la ventana de gracia. Después del período de gracia, la clave se bloquea definitivamente independientemente del estado de la caché.

Portal del cliente

Auris Licensing incluye un portal orientado al cliente donde los usuarios finales (titulares de licencia) pueden ver y gestionar sus propias licencias sin contactar al proveedor del software.

Cómo funciona

El portal del cliente se accede a través del mismo flujo de inicio de sesión alojado por Auris utilizado para la autenticación. Cuando un usuario inicia sesión, solo ve las licencias asociadas a su cuenta — directamente (claves vinculadas al usuario) o a través de su membresía organizacional (claves vinculadas a la organización).

El portal proporciona:

• Resumen de licencias: Todas las claves activas, expiradas y suspendidas con sus derechos
• Gestión de dispositivos: Ver dispositivos activados, desactivar un dispositivo para liberar un espacio
• Tokens sin conexión: Descargar JWT de licencia firmados para uso sin conexión
• Historial de uso: Uso de puestos a lo largo del tiempo (para licencias flotantes)
• Estado de renovación: Fechas de expiración y enlaces de renovación (si la integración de pago está configurada)

Separación de la gestión administrativa

El portal del cliente es distinto de la consola de Auris. Los administradores en la consola tienen control total sobre todas las licencias, políticas y claves de todos los clientes. El portal del cliente muestra solo lo que pertenece al usuario autenticado.

Esta separación significa:

• Los usuarios finales no pueden ver las licencias de otros clientes
• Los usuarios finales no pueden modificar la configuración de las políticas ni crear nuevas claves
• Los usuarios finales pueden realizar acciones de autoservicio (desactivar un dispositivo, descargar un token sin conexión) sin intervención del administrador
• Los administradores pueden deshabilitar acciones de autoservicio específicas por política si es necesario

Automatización

La gestión manual de licencias no escala. Cuando un cliente paga por tu software, quieres que la clave de licencia se emita automáticamente. Cuando una suscripción caduca, quieres que la clave se suspenda. Auris Licensing se integra con proveedores de pago y el sistema de eventos de Auris para automatizar todo el ciclo de vida.

Integración de webhooks de pago

Auris soporta integración directa con Stripe y PayPal para licencias impulsadas por pagos:

Stripe:

• checkout.session.completed → Crear una nueva clave según la política apropiada
• invoice.paid → Extender la expiración de la clave (renovación de suscripción)
• invoice.payment_failed → Suspender la clave (período de gracia configurable)
• customer.subscription.deleted → Revocar o expirar la clave

PayPal:

• PAYMENT.SALE.COMPLETED → Crear una nueva clave
• BILLING.SUBSCRIPTION.RENEWED → Extender la expiración
• BILLING.SUBSCRIPTION.CANCELLED → Revocar o expirar la clave
• BILLING.SUBSCRIPTION.SUSPENDED → Suspender la clave

Mapeo evento-acción

Más allá de los webhooks de pago, el sistema de eventos de Auris te permite definir reglas de automatización personalizadas. Cualquier evento de licencia puede desencadenar una acción:

Estas reglas se configuran en la consola de Auris en Licensing > Automation Rules o a través de la API. Se integran con el mismo Actions Engine utilizado para los flujos de autenticación, permitiéndote usar acciones JavaScript personalizadas para lógica compleja.

Cómo encaja todo

El sistema de licencias en Auris no es una funcionalidad aislada — está integrado en la plataforma más amplia de gestión de identidades y accesos:

• Los usuarios y organizaciones de Auris IAM son los titulares de licencia. No se necesita una base de datos de usuarios separada.
• La autenticación a través de Auris Hosted Login controla el acceso al portal del cliente.
• Los permisos RBAC controlan quién puede gestionar licencias en la consola (manage:licenses, view:licenses).
• El FGA puede usarse junto con las licencias para un control de acceso granular a recursos dentro de una aplicación con licencia.
• Los webhooks notifican a tus sistemas sobre eventos de licencia en tiempo real.
• Los registros de auditoría registran cada operación de licencia (clave creada, validada, revocada, dispositivo activado).

Esta integración significa que defines usuarios una sola vez, los autentificas una sola vez, y gestionas tanto el control de acceso como las licencias desde una única plataforma.

Conceptos relacionados

• Sessions & Token Rotation — Cómo funcionan las sesiones y los JWT en Auris
• Tokens Explained — Estructura, firma y verificación de JWT
• Actions & Sandboxed Execution — Lógica de automatización personalizada para eventos de licencia
• Multi-Tenancy — Cómo funcionan las licencias entre tenants
• OAuth 2.0 & OIDC — El marco de autenticación que impulsa el portal del cliente