Links

Account Based Licensing

Account Based Licensing (ABL) allows license activation to be done automatically, after the user signs into the application. With ABL, instead of securely distributing the activation codes, the software vendors use their authentication platform to associate the licenses with specific users.

How it works

Our platform needs a reliable way to determine and verify the identity of users who successfully sign into the application, which requires license activation. Most identity provider services use the OpenID Connect (OIDC) authentication protocol nowadays, where the user identity is encapsulated inside the JWT access/identity token obtained during the authentication process. The server-side resources like APIs then use the token to verify the user's identity and access rights. With proper configuration done on the identity provider's side, the same JWT token can also be used for the license activation.
Please follow the next steps for successful account-based licensing integration within Zentitle 2.

Configure ABL for your account [Z2]

In the UI, go to the Account Based Licensing page (inside the End Users section) and fill in all the required information:
  • IDP URL - root URL of the identity provider. Only identity providers compliant with the OpenID protocol are supported right now. The URL is required to retrieve the IDP details from the OIDC metadata endpoint. The most important information is the cryptographic keys used to sign the JWT tokens - so that the licensing server can verify the authenticity and integrity of the tokens provided by the client application.
  • Username claim - the name of the claim inside the token, which should be used to retrieve the username associated with the seat when activating the license (email, name, user_name, etc.).
  • Entitlements claim - the claim that holds the list of entitlement IDs that the user can activate the license against. The name of the claim depends on the configuration done in the Identity Provider service, as described in the next step (e.g., z2/entitlements).

Manage users' entitlements [IDP]

Without the activation codes, the only way to determine if the user can activate the license for a given product is by retrieving the list of entitlements from the provided JWT token.
It's necessary to configure the IDP to include entitlement IDs in the JWT token's Entitlements claim.
The example below shows how it can be done in Auth0, one of the most popular authentication platforms.
  1. 1.
    Go to the Actions -> Flows -> Login flow and add a new action responsible for adding the entitlements claim to the JWT tokens:
  2. 2.
    Define the code for creating the entitlements claim (in this case named z2/entitlements):
    exports.onExecutePostLogin = async (event, api) => {
    const { entitlements } = event.user.user_metadata;
    api.idToken.setCustomClaim(`z2/entitlements`, entitlements);
    };
After configuring the action required to have the entitlements claim in the token, you can manage the entitlements for individual users by adding/editing the "entitlements" metadata field. We are editing the metadata manually in this sample, but we expect some automation to manage this metadata field in production use cases.

Activate the license using the OpenID Token [Client App]

After the ABL and IDP have been configured, the seat can be activated using the JWT token obtained from the Identity Provider when performing the user authentication in the client application.
To do so, execute an API call [POST] {licensing_api_url}/activate with body
{
"productId": "prod_vs1ueDlrLU61_HIIeDrTjA",
"activationCredentials": {
"type": "openIdToken",
"token": "JWT TOKEN"
},
"seatId": "demoSeatId",
"seatName": "demoSeatName"
}
The rest of the client application logic related to licensing is the same as in the case of using the activation code for seat activation.