Define settings for custom license models

When you’re creating a custom license model, use the JSON-formatted rules below to define the behavior and constraints for the model.

The custom license model configuration accepts any combination of behaviours and constraints. Make sure you validate and review that the resulting license model works as expected.

There are some minimum recommendations for creating a working license model:

• A license model only makes sense if you set a (non-zero) value in either leaseTimeCheckOut or leaseTimeCache in the LeaseTimeBehavior behavior rule. Otherwise license leases expire immediately after they’re created.

• In addition, if you don’t specify any sessionAnchors values with the ConcurrentSessions constraint rule, one license seat can be consumed on an unlimited number of devices, which may not be the desired behavior.

In addition, a license model can only restrict license consumption based on one type of credit using either SeatCountConstraint, UseCountConstraint, or AggregateUseConstraint. If the license model used by a license restricts consumption based on more than one type of credit, the license consumption request fails.

See also use cases for some of the most commonly applied constraints.

Behavior rules

Use these rules to define the behavior of a custom license model.

LeaseTimeBehavior

Define the behavior of license leases, which are created when end users and device clients start consuming the license.

Here’s an example rule.

{
   "LeaseTimeBehavior": {
      "leaseTimeCheckOut": 2592000000,
      "refreshTimeCheckOut": 12600000,
      "leaseTimeCache": 7200000,
      "refreshTimeCache": 3600000,
      "cooldownTime": 0,
      "allowLeaseExtension": true,
      "allowLeaseRelease": true
   }
}

With the example rule above, license leases work as follows:

• When an end user or device client is consuming a license offline, the license token is valid for 30 days and the recommended token refresh time is every 3,5 hours after the license lease was issued. In online consumption, the token is valid for 2 hours and the recommended token refresh time is every 1 hour.

• License leases can be extended. (This means our example license model must also specify the constraint rules that define how the extending is done.)

• Licenses can be released, and they become immediately available to other end users and device clients after releasing.

Fields:

• leaseTimeCheckOut

  Define the maximum license token (lease) validity for offline use. This maximum value is also used as a default value if the client application doesn’t request a specific duration.

  Format: milliseconds

• refreshTimeCheckOut

  Define the recommended token refresh time in offline use, counted from the lease issuing time (the iat claim in the license token).

  Format: milliseconds

• leaseTimeCache

  Define the maximum license token (lease) validity for online use. This maximum value is also used as a default value if the client application doesn’t request a specific duration.

  Format: milliseconds

• refreshTimeCache

  Define the recommended token refresh time in online use, counted from the lease issuing time (the iat claim in the license token).

  Format: milliseconds

• cooldownTime

  Define the delay after which a license becomes available to other end users and device clients after it has been released.

  Format: milliseconds

  To have a license become available immediately after its release, you can leave out the attribute from the model, or set the value to 0 (or empty or null).

• allowLeaseExtension

  Define whether or not an existing license lease can be extended.

  Possible values:

  • true (default)

  • false

  For a fixed-length lease, set this to false.

• allowLeaseRelease

  Define whether or not an existing license lease can be released.

  Possible values:

  • true (default)

  • false

LicensePoolBehavior

Define whether a new license is added or the existing license is updated when you grant a license and the entitlement already contains a license for the same licensed item.

With this example rule, a new license is added every time.

{
   "LicensePoolBehavior": {
      "behavior": ""
   }
}

Fields:

• behavior

  Define where the seats, use count, and use time are added.

  Possible values:

  • singlePool: The license credit is added to the existing license.

  • operation: A new license is added with the defined license credit.

  If empty, operation is used.

LicenseLockingBehavior

Define if license locking is used to optimize response times to license consumption requests.

If multiple requests to the same license are received simultaneously, license locking avoids the risk that one of them would exceed the license credit.

This example rule disables license locking.

{
   "LicenseLockingBehavior": {
      "lockMode": "NO_LOCKING"
   }
}

Fields:

• lockMode

  Define if license locking is used.

  Possible values:

  • LOCK_LICENSE: Enabled

  • NO_LOCKING: Disabled

If the rule is not included or it’s empty, LOCK_LICENSE is used.

Constraint rules

Use these rules to define the constraints for a custom license model.

ConcurrentSessions

Define the rules for concurrent license consumption per license seat, for example, whether an end user can consume the license on multiple devices concurrently while still consuming only one seat.

Define the limits on how many concurrent license sessions are allowed per seat for one user or device client, and use “session anchors” to define what is counted as a license session.

This example uses the most common approach where license sessions are counted based on the devices on which the license is consumed. With this example, a user or device client can only consume a license seat on one device concurrently (counting in both online and offline consumption). Consuming the license on another device at the same time consumes another seat.

{
   "ConcurrentSessions": {
      "maxCache": 1,
      "maxCheckOut": 1,
      "maxTotal": 1,
      "leaseTrackingMode": "IGNORE_LEASE_ID",
      "sessionAnchors": {
         "__objType": "ArrayList",
         "Items": [{
            "__objType": "String",
            "value": "Hardware"
         }]
      }
   }
}

There may be some rare use cases for using both session anchors and additional “lease anchors”. Using lease anchors in practice means that a license session can contain multiple concurrent license leases.

The following example could be used in a use case where your client application has a number of processes created at startup, each one with its own lifecycle. Even though each process consumes the license and has a separate license lease, you might not want them to be considered when the limits on concurrent consumption per seat are checked.

With this example, three concurrent license sessions are allowed per seat for one user or device client, and license sessions are counted based on the devices on which the license is consumed. However, an unlimited number of processes can be running on the same device, and they are still counted into the same license session on that device.

{
   "ConcurrentSessions": {
      "maxCache": 3,
      "maxCheckOut": 3,
      "maxTotal": 3,
      "sessionAnchors": {
         "__objType": "ArrayList",
         "Items": [{
            "__objType": "String",
            "value": "Hardware"
         }]
      },
      "leaseAnchors": {
         "__objType": "ArrayList",
         "Items": [{
            "__objType": "String",
            "value": "LicensedProcess"
         }]
      }
   }
}

This last example shows another rare use case where two types of session anchors are used. Three concurrent license sessions are allowed per seat, and each device on which the license is consumed and each process running on a device is counted as a separate license session. In this case, you would need to be careful that your client application releases the lease even if a process crashes.

{
   "ConcurrentSessions": {
      "maxCache": 3,
      "maxCheckOut": 3,
      "maxTotal": 3,
      "sessionAnchors": {
         "__objType": "ArrayList",
         "Items": [{
               "__objType": "String",
               "value": "Hardware"
            },
            {
               "__objType": "String",
               "value": "LicensedProcess"
            }
         ]
      }
   }
}

Fields:

• maxCache

  Define the number of concurrent license sessions allowed per seat for a user or device client in online use.

  For example, if you set this to 1 and sessionAnchors to Hardware, the license can only be consumed on one device at the same time.

  Format: positive integers

• maxCheckOut

  Define the number of concurrent license sessions allowed per seat for a user or device client in offline use.

  Format: positive integers

• maxTotal

  Define the total number of concurrent license sessions allowed per seat for a user or device client.

  Format: positive integers

• leaseTrackingMode

  Define how lease chaining is used.

  When lease chaining is enforced and hardware with a specific identifier gets a license lease (a seat), consecutive requests to refresh the lease must contain the JSON Web Token ID (JTI) of the previous lease.

  The JTI (also referred to as leaseId) is expressed as the jti claim in the JWT payload.

  Possible values:

  • IGNORE_LEASE_ID: Lease chaining is not required.

  • USE_LEASE_ID_WHEN_PRESENT: Lease chaining is enabled but not enforced.

  • REQUIRE_LEASE_ID: Lease chaining is enforced. The JTI must be provided on license renewal to extend the existing lease, otherwise this is handled as a request for a new lease.

• sessionAnchors

  Use session anchors to define what is identified as a separate license session.

  The ConcurrentSessions rule’s maximum limits for concurrent sessions are checked against devices, processes, licensed resources, or licensed items (or a combination of these) depending on the anchors you define.

  Possible values:

  • Hardware. Anchor concurrent consumption to the devices on which the license is consumed.

    Requires the hw parameter in the license consumption request.

  • LicensedProcess. Anchor concurrent consumption to the processes (process IDs) consuming the license.

    Requires the process parameter in the license consumption request.

    If you include this anchor, also include Hardware as an anchor (see the examples above).

  • LicensedResource. Anchor concurrent consumption to the external resources that are being consumed.

    Requires the resource parameter in the license consumption request.

  • LicensedItem. Anchor concurrent consumption to the aggregated licensed items that are being consumed.

    No additional parameters required.

• leaseAnchors

  Define additional anchors to session anchors, which allows having multiple simultaneous leases per session.

  Possible values (see descriptions above in sessionAnchors):

  • LicensedProcess

  • LicensedItem

Note: Depending on how you’re using anchors, make sure that you’re aware of how leases will be created and that your client application releases them correctly. For example, if you’re only using devices as a session anchor, each device will have its own lease. However, if you’re also using processes as a lease anchor, each process on a device will have its own lease.

SeatCountConstraint

Restrict license consumption based on the license’s seat count.

You can use this both with organizations’ license pools and with personal licenses (where the seat count is 1).

The seat count restriction is enabled in the system by default. If you don’t want to apply this restriction in the license model, include this rule and disable the tracking. In this case, use one of the other rules to restrict consumption, for example, based on the use count (UseCountConstraint) or use time (AggregateUseConstraint).

With this example rule, license consumption is not restricted based on the seat count.

{
   "SeatCountConstraint": {
      "trackingMode": "NOT_TRACKED"
   }
}

Fields:

• trackingMode

  Define whether license consumption is restricted based on the license’s seat count.

  Possible values:

  • TRACKED: Restricted

  • NOT_TRACKED: Not restricted

  If empty, NOT_TRACKED is used.

AggregateUseConstraint

Restrict license consumption based on the license’s use time.

If you don’t include this rule, use one of the other rules to restrict consumption, for example, based on the seat count (SeatCountConstraint) or use count (UseCountConstraint).

Your 10Duke Enterprise configuration must have the use time credit feature enabled. Contact the 10Duke Integration Support team if needed.

As an example to illustrate how you can restrict license use based on use time, you could have a photo editing software, and you want licenses that restrict its use based on the total use time allowed during the license validity time. For example, you want to grant access to a customer organization for 1 year and allow them a maximum of 1200 hours of use. If each application session consumes a minimum of 24 hours, the license allows the organization’s users to run a maximum of 50 photo editing sessions in total over the course of a year.

This example rule has tracking based on use time enabled.

{
   "AggregateUseConstraint": {
      "trackingMode": "TRACK_BY_LEASE"
   }
}

Fields:

• trackingMode

  Possible values:

  • TRACK_BY_LEASE: Restrict usage based on use time.

    The duration of every license lease is added to the use time consumed from the license.

    As an exception, when a client renews a license lease, only the time consumed from the previous lease is added to the use time consumed from the license. For example, if a client starts consuming a license with a 1-day lease duration, and renews the lease after 2 hours for another 1-day lease duration, this increases the use time consumed from the license by 2 hours.

  • NOT_TRACKED: Not restricted

UseCountConstraint

Restrict license consumption by the license’s use count. Each license consumption request must declare the use count to be consumed.

If you don’t include this rule, use one of the other rules to restrict consumption, for example, based on the seat count (SeatCountConstraint) or use time (AggregateUseConstraint).

Your 10Duke Enterprise configuration must have the use count credit feature enabled. Contact the 10Duke Integration Support team if needed.

For more information on use count licenses, see example use cases and how to provision a use count license.

With this example rule, license consumption is not restricted based on the use count.

{
   "UseCountConstraint": {
      "trackingMode": ""
   }
}

Fields:

• trackingMode

  Define whether license consumption is restricted based on the license’s use count.

  Possible values:

  • TRACK_BY_CALLER_CONSUMPTION_COUNT: Track usage based on the count requested by the client application.

  • NOT_TRACKED: Not restricted

If the rule is not included or it’s empty, NOT_TRACKED is used.

VersionConstraint

Restrict license consumption to the software versions specified in the license.

When versioning is enforced, the client application must declare in the license consumption request what version of the software is running on the device.

This example rule enforces an exact version matching constraint between the version declared in the consumption call and the version defined in the license.

{
   "VersionConstraint": {
      "versionChecker": "com.tenduke.sdk2.utils.object.ExactVersionMatcher",
      "versionCheckPolicy": "CheckLicenseVersion"
   }
}

Fields:

• versionChecker

  Define the fully qualified name of the class that implements version checking.

  Possible values:

  • com.tenduke.sdk2.utils.object.ExactVersionMatcher: Exact matching

  • com.tenduke.sdk2.utils.object.RegexVersionMatcher: Regular expression matching

  • com.tenduke.sdk2.utils.object.SemanticVersionMatcher: Semantic version (range) matching

• versionCheckerPolicy

  Define whether versions are checked and from where.

  Possible values:

  • CheckCreditVersion: Restricting is done based on the location/schema option of the license version in the license credit (in a credit-based deployment).

  • CheckLicenseVersion: Restricting is done based on the location/schema option of the license version in the license itself.

  • AllowAnyVersion: Allow any version—restricting based on software version is disabled.

IpAddressConstraint

Restrict license consumption based on allowed IP locations (an IP range and/or Geo IP location). This rule is most commonly used to limit license consumption to certain locations.

To use this constraint:

• An integration to a third-party API service and IP database is required to resolve the IP location of the calling client application (a commercial license is required).

• You must create a license model and product package per region.

This example rule only allows license consumption if the caller’s IP address can be resolved and if it either matches the allowed IP range 212.68.32.0/28-2a00:1450:4010:c03::00/120 or the Geo IP location is Canada.

{
   "IpAddressConstraint": {
      "allowedIpRanges": {
         "__objType": "ArrayList",
         "Items": [{
               "__objType": "String",
               "value": "212.68.32.0/28"
            },
            {
               "__objType": "String",
               "value": "2a00:1450:4010:c03::00/120"
            }
         ]
      },
      "allowedGeoIpLocations": {
         "__objType": "GeolocationBoundaries",
         "boundaries": {
            "__objType": "Iso3166CountryCodeBoundaries",
            "countries": {
               "__objType": "ArrayList",
               "Items": [{
                  "__objType": "String",
                  "value": "CA"
               }]
            }
         },
         "allowUnresolvedGeoIpLocation": "false"
      }
   }
}

Fields:

• allowedIpRanges

  Define the allowed IP range.

  Format: IPv4 or IPv6 address range

  Example value: 212.68.32.0/28

• allowedGeoIpLocations

  Define the country code of the area from which geocoded IP addresses are allowed.

  Possible values: ISO 3166 Alpha-2 country codes (the two-character format)

  Example value: FI (Finland)

• allowUnresolvedGeoIpLocation

  Define whether or not license consumption is allowed even if resolving the location fails.

  Possible values:

  • true

  • false

AssignedLicenseConstraint

Use named seats for the licenses.

If you don’t include this rule, the license model uses floating seats: consuming a license doesn’t require a seat reservation.

Example 1: With this rule, an end user or a device client must have an existing seat reservation to start consuming a license. After a seat has been assigned to a certain end user or device client, it cannot be reassigned to another user or device client.

{
   "AssignedLicenseConstraint": {
      "allowLazyReservation": false,
      "seatReservationPolicy": "UNLIMITED_RESERVATIONS",
      "requiredAssignmentReservationType": "reserved",
      "reservationReleaseAllowed": false
   }
}

Example 2: Like above, an end user or a device client must have an existing seat reservation to start consuming a license. However, this rule allows seats to be reassigned from one user or device client to another, but only for the limited number of times defined in the product package.

{
   "AssignedLicenseConstraint": {
      "allowLazyReservation": false,
      "seatReservationPolicy": "LIMITED_RESERVATIONS",
      "requiredAssignmentReservationType": "reserved",
      "reservationReleaseAllowed": true
   }
}

Fields:

• allowLazyReservation

  Define whether an end user or a device client can start consuming a license without having an existing reservation, and a reservation is automatically created the first time the user or device client consumes the license.

  Possible values:

  • true

  • false

• seatReservationPolicy

  Define whether there are limitations to making seat reservations.

  Possible values:

  • UNLIMITED_RESERVATIONS: Unlimited seat reservations are allowed.

  • LIMITED_RESERVATIONS: Seat reservations are allowed for a limited number of times.

    You define the limit itself in the product package. In each product package that uses this license model, define a seat reservation count multiplier for each licensed item.

• requiredAssignmentReservationType

  Define that a user or a device client must have a seat reservation to be able to consume a license.

  Possible values: reserved

• reservationReleaseAllowed

  Define if releasing a seat reservation is allowed, that is, whether license seats can be reassigned from one user or device client to another.

  Possible values:

  • true

  • false

UtilizationConstraint

Allow over-usage of licenses by extending their seat count, use time, or use count.

Here are two example rules that allow over-usage of license seats.

Example 1: This rule allows over-usage by two seats on top of the initial license seats granted.

{
   "UtilizationConstraint": {
      "itemCountExtUnit": "count",
      "itemCountExt": 2
   }
}

Example 2: This rule allows over-usage by 2.5% on top of the initial license seats granted. For example, a license with 100 seats could be extended with three seats (2.5 rounded up).

{
   "UtilizationConstraint": {
      "itemCountExtUnit": "percentage",
      "itemCountExt": 2.5
   }
}

Fields:

• itemCountExt

  Define how much a license’s seat count is increased after the original quantity has been reached.

  Depending on the value of itemCountExtUnit, define either the number of extra seats or a percentage of the license’s seat count to be allowed for over-usage.

  If you use a decimal percentage, the system rounds up the resulting value (itemCountExt × the total number of license seats granted) to the nearest integer from the half point value of 0.5.

  Format: Decimal number

  Example value: 2.5

• itemCountExtUnit

  Define whether license over-usage based on seat count is defined as a number of extra seats or as a percentage of the license’s seat count.

  Possible values:

  • count

  • percentage

  If empty, percentage is used.

• useTimeExt

  Define how much a license’s use time is extended after the original time has been reached.

  Depending on the value of useTimeExtUnit, define either the amount of extra time (in milliseconds) or the percentage of the total license use time to be added.

  If you use a decimal percentage, the system rounds up the resulting value (useTimeExt × the total amount of license use time granted) to the nearest integer from the half point value of 0.5.

  Format: Decimal number

  Example value: 2.5

• useTimeExtUnit

  Define whether license over-usage based on use time is defined as an amount of time or as a percentage of the total license use time.

  Possible values:

  • count

  • percentage

  If empty, percentage is used.

• useCountExt

  Define how much a license’s use count is increased after the original count has been reached.

  Depending on the value of useCountExtUnit, define either the number of extra uses or a percentage of the license’s total use count to be added.

  If you use a decimal percentage, the system rounds up the resulting value (useCountExt × the total number of license units granted) to the nearest integer from the half point value of 0.5.

  Format: Decimal number

  Example value: 2.5

• useCountExtUnit

  Define whether license over-usage based on the use count is defined as a number or as a percentage of the license’s total use count.

  Possible values:

  • count

  • percentage

  If empty, percentage is used.

ConsumptionConstraint

Define how many license seats a single user or a device client can consume.

This example rule allows one seat per user.

"ConsumptionConstraint":{"maxConsumptionCount":1}

Fields:

• maxConsumptionCount

  Define how many license seats a single user can consume.

  Format: Positive integers

ConsumptionLockConstraint

Prevent the same kind of a license from being used repeatedly on the same device, for example, to prevent the abuse of trial licenses.

The anchor specified with this constraint is used together with the lock scope defined during license provisioning to create a locking. See more information on preventing the abuse of trial licenses and how to provision a trial license.

Here’s an example rule.

{
   "ConsumptionLockConstraint": {
      "consumptionLockAnchor": "Hardware"
   }
}

Fields:

• consumptionLockAnchor

  Possible values:

  • Hardware: Anchor the locking to the hardware ID of the device on which the license is first consumed.

    Requires the hw parameter in the license consumption request.