License Verification and Entitlement Model

Overview

This document describes the v1.0 license model, which governs product entitlement. In this model, entitlement is derived cryptographically from a signed license token, never from local configuration flags or environment variables alone. The product verifies the license and reads its capabilities and expiration date directly from the token's claims.

This platform-integrated model provides centralized control over licensing and allows for dynamic updates, such as key rotation, without requiring a new product release. It supersedes an earlier, fully offline model that relied on static license keys bundled into the product binary.

The core function of the license verification system is to confirm entitlement before enabling certain features, such as licensed write operations. It fails closed by design, meaning entitlement is never granted if verification fails for any reason.

How It Works

The licensing process involves three main components: the license token itself, the management of public keys used for verification, and a lifecycle of periodic re-verification.

The License Token

The license is a JSON Web Token (JWT) signed with the RS256 algorithm. The product cryptographically verifies this signature to ensure the token has not been tampered with and was issued by the legitimate licensing authority.

The token contains several claims that define the terms of the entitlement:

Verification Key Retrieval

To verify the license's signature, the product requires the licensing platform's public keys. These keys are not bundled permanently into the product. Instead, they are fetched from a JSON Web Key Set (JWKS) endpoint provided by the licensing platform.

This dynamic approach allows signing keys to be rotated by the platform operator without requiring a product update.

The key retrieval and verification flow is as follows:

flowchart TD
    subgraph Product Instance
        A[License Verification]
        B[Local Key Cache]
    end

    C[Licensing Platform JWKS Endpoint]

    A -- 1. Receives license to verify --> A
    A -- 2. Check cache for key with matching 'kid' --> B
    B -- 3a. Key found --> A
    A -- 4. Verify signature with cached key --> A
    B -- 3b. Key not found --> D{Refetch Keys}
    D -- 5. Request key set over HTTPS --> C
    C -- 6. Return JWKS --> D
    D -- 7. Update local cache --> B
    D -- 8. Provide new key --> A

1. When verifying a license, the product inspects the key ID (kid) in the JWT header.
2. It checks its local cache for the corresponding public key. The key set is cached for a period on the order of one day.
3. If the key is not in the cache, the product refetches the entire JWKS from the platform's endpoint over HTTPS. This ensures it retrieves any newly rotated keys.
4. The product updates its cache with the new key set and proceeds with signature verification.

Verification Lifecycle

License verification is not a one-time event. The product performs checks throughout its operational lifecycle to ensure entitlement remains valid.

• On Cold Start: The license is verified every time the product starts.
• Periodic Re-verification: During normal operation, the product re-verifies the license periodically (approximately once per day). The result of the last verification is cached between these checks.

If the licensing platform is unreachable when a periodic re-verification is due, the product does not fail immediately. Instead, it enters an offline grace period. For more details, see the documentation on Offline Grace.

API Key Management

Separate from the license token, certain integrations with the licensing platform are authenticated using a product API key. These keys follow a strict scoping rule: one key per (customer, product, environment) triple.

• An API key issued for one environment (e.g., staging) must not be reused in another (e.g., production).
• Keys must be stored in a secure secret store, not in the product database.
• Key rotation is managed through the licensing platform.

Troubleshooting

Failed Verification

If a license fails verification, the product fails closed for entitlement. This means that after any applicable offline grace period, all licensed write operations are disabled. The product will never "assume licensed" status if a key is missing or a signature is invalid; it will always surface an error.

Verification can fail for several reasons:

• The license signature is invalid or cannot be verified.
• The license has expired.
• The installation binding does not match the current installation.
• The license format version is unsupported.

For specific error codes related to licensing failures, see the documentation on Offline Grace.

Summary of v1.0 License Model

See Also

• Licensing Overview: A high-level introduction to the licensing system.
• Capacity Counting: Details on how max_discovered_services and max_converted_services are measured.
• Offline Grace: Describes the product's behavior when it cannot reach the licensing platform.
• Egress Allow-list: Information on network endpoints the product may need to contact, including the licensing platform.

All SOAP-to-REST docs