Local License Server Management

To be able to use the LLS API as a fully-featured replacement of the regular Licensing API, LLS service’s license has to be activated.

LLS is a standalone Zentitle product, which can be activated as any other product on the platform - using the activation code from the entitlement. Ask the Zentitle support team to configure an LLS license for you and provide an activation code.

The person responsible for activating the LLS (LLS admin) should have access to the LLS Management API and the End User Portal. LLS doesn’t have any ‘proper' UI, but there is a Swagger UI that exposes existing LLS Management API endpoints.

LLS License Management endpoints

There are 5 API endpoints in LLS that you can use for LLS license management:

• GET api/lls/license/status To retrieve the current license status (OfflineActivated, NotActive) and details like license expiration date, etc.

• POST api/lls/license/generate-activation-token To generate the offline activation token, which needs to be provided to the end-user portal.

• POST api/lls/license/activate To activate the license using the offline activation response token copied over from the end user portal.

• POST api/lls/license/refresh To refresh (extend) the currently active license using the offline refresh token copied over from the end user portal.

• POST api/lls/license/deactivate To immediately deactivate the LLS license. This endpoint returns a deactivation token, which needs to be pasted to the end user portal to release the license on the server.

License activation

LLS uses offline activation flow as we assume there is no access to the global internet network from the machine on which the LLS is running.

Once the LLS license is activated, the entitlements can be exported to the LLS service from the cloud.

License Refresh

Unless a perpetual license has been applied for the LLS, the license has to be periodically refreshed so it doesn’t expire and LLS doesn’t fall into the 'not active' mode when its “Licensing API“ cannot be used anymore.

License Deactivation

When the LLS is no longer used, its license can be deactivated. Even with the deactivated license, the entitlements and their data are still available in the LLS database.

However, the LLS “Licensing API“ can’t be used anymore (the endpoints return 405 response) until it's activated again.

Once is the deactivation token passed to the End User Portal, the LLS activation is deleted from the server, and the LLS host is tracked as 'not active.' That way, when exporting the entitlement, the inactive LLS cannot be chosen as a target for the entitlement import.

---

Entitlement Management

To use the entitlement in the offline environment where the LLS has been installed, the entitlement has to be exported from the server and imported to the LLS.

Entitlement export token

The entitlement is exported from the LLS as an encrypted token. The token can be generated multiple times, and it always carries the latest entitlement’s server state.

Each token is digitally signed and encrypted so that the LLS server can verify the authenticity and integrity of the data represented in the token. Only the LLS instance selected during the entitlement export process is able to decrypt the token and import the data.

The token contains the following information:

1. Version number - identifies a token version, should be increased when there is a breaking change introduced to the token’s format

2. Token id - unique for each generated token. LLS keeps track of all the applied tokens so that the same entitlement token cannot be imported twice by accident.

3. Session id - for more details, see entitlement export session. For each entitlement, LLS keeps track of the currently active session. That way, the user cannot accidentally import a token that has not been applied in LLS before but has been generated for one of the previous (and no longer active) entitlement export sessions.

4. Issue date - the date when the token has been generated. LLS doesn’t allow importing an export token with a lower issue date than the one in the previously applied token so that the old data doesn’t accidentally override the entitlement.

5. Payload - serialized entitlement data. LLS inspects the entitlement data and accordingly updates/creates the entitlement record in the LLS DB.

In the current implementation, the entitlement is locked for editing after the export to LLS. Because of that, every time an export token is downloaded, it represents the same entitlement state. LLS doesn’t allow importing a token for the same entitlement multiple times in one export session.

Entitlement export session

The entitlement export session starts when the first entitlement export token has been generated for the given LLS server. It lasts until the entitlement is withdrawn from the LLS and imported back to the server.

Over time, there can be multiple delegation sessions even for the same entitlement and LLS server if the cycle [export entitlement into LLS] -> [withdraw entitlement from LLS] repeats multiple times.

Entitlement export

After the LLS license has been activated, an entitlement can be exported from the Management UI and imported into the LLS service. After the entitlement has been imported, the client applications can activate their licenses against the LLS API using the same approach as if they were using the “proper“ Licensing API.

The LLS’s POST api/lls/entitlement/import endpoint should be used for importing the entitlement token into the LLS app.

Entitlement Deletion from LLS / Import back to the Cloud

Entitlement can be deleted from the LLS using the DELETE api/lls/entitlements/{entitlementId} API call on the LLS side. When the endpoint is called, the entitlement’s data is deleted from the LLS database, and an entitlement deactivation confirmation token is generated. After applying the token on the server, the entitlement host changes back to the cloud value, and the associated LLS export session ends.

When the entitlement is exported again, either to the same or another LLS instance, a new export session starts.

Entitlements state

There are the following endpoints for inspecting the details of imported entitlements and their activations:

• api/lls/entitlements to go through the list of all the imported entitlements

• api/lls/entitlement/{entitlementId} to retrieve the details about the specific entitlement

• api/lls/entitlement/{entitlementId}/activations to go through the all the entitlement’s activations, which were created using LLS “Licensing API“

• api/lls/entitlement/{entitlementId}/activations-log to go through the logs of the entitlement’s activations

Current Limitations

• Only entitlements without active seats can be exported

• The exported entitlement cannot be longer edited, as there is no way to propagate the changes into the LLS

• The overdraft seat limit is not supported in LLS, as it is hard to monitor and regulate the overdraft seat usage in the LLS's offline environment. Even if the exported entitlement has the overdraft seat limit configured, its value is ignored, and the maximum activation count depends solely on the seat count.

• Only entitlements without active seats can be exported

• The exported entitlement cannot be longer edited, as there is no way to propagate the changes into the LLS