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.

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

Recommendations

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, there are no concurrency restrictions. For example, one license seat can be consumed on an unlimited number of devices, which may not be the desired behavior.

Limitations

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.
In all fields that use values in milliseconds, the maximum value is 2^63.

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 how license credit (seats, use count, or use time) is granted if the entitlement already contains a license for the same licensed item. You can choose to either create a new license, or add the granted credit to the existing license. With the out-of-the-box floating license model, a new license is always created.

This rule only affects licenses granted through the Graph API, and licenses granted using the legacy features in 10Duke SysAdmin that don’t create transactions for the licenses.

Licenses granted using transactions in SysAdmin or through the 10Duke Entitlement Management REST API always create a new license in this situation.

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

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

Fields:

behavior

Define where the granted credit is added.

Possible values:
- singlePool: The granted credit is added to the existing license.
  
  When granting the license, the same validity period must be used as in the existing license, or granting the license fails.
- operation: A new license is created with the granted 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.
- Version. Anchor concurrent consumption to the version of the software that is consuming the license.
  
  Requires the version parameter in the license consumption request.
leaseAnchors

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

Possible values: The same as in sessionAnchors.

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.

This means the total cumulative use time by users or device clients cannot exceed the amount of use time specified in the license. When the license is being consumed, the time consumption is calculated in milliseconds.

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 end 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.

When the ConcurrentSessions constraint is used to restrict concurrent license consumption per seat, this constraint can be used to prevent a user or device client from using an excessive number of seats when the concurrency limit has been reached.

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. Note that if the product package (or any licensed item in it) uses a license model that applies this constraint, the provisioning request must always either define a lock scope or specifically disable the 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.