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.

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

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

Limitations

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 start consuming the license.

Here’s an example rule.

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

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

  • When an end user 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.

  • When the client application requests for a new token, the new validity end time is counted from the time of the request, and any remaining validity time is ignored.

  • 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 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

  • incrementModel

    Define how license consumption time is counted when the client application requests for a new license: whether the remaining consumption time is included or ignored.

    Possible values:

    • relative: The new consumption time is counted starting from the time of the request (remaining consumption time is ignored).

    • stack: The new consumption time is added on top of the remaining consumption time.

    For example, if the current lease is still valid for 1 hour and the client application requests a new license for 2 hours, with relative the new validity end time is 2 hours from the time of the request, and with stack, 3 hours.

    Note: If you want to track use time with the license model, make sure to use the correct value combination together with AggregateUseConstraint.

    If empty, relative is used.

  • cooldownTime

    Define the delay after which a license becomes available to other end users 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": ""
   }
}

Fields:

  • lockMode

    Define if license locking is used.

    Possible values: LOCK_LICENSE

    If empty, license locking is not 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 anchors”. Using additional 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"
         }]
      },
      "additionalAnchors": {
         "__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.

  • additionalAnchors

    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 an additional 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 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

Define how license use time is recorded. This rule is required for licenses that grant use time.

This rule must be used in combination with the LeaseTimeBehavior constraint, and the correct value depends on what you set in incrementModel in LeaseTimeBehavior.

If you don’t include this rule, use 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 defines that use time is tracked using the “fair” model. This requires that LeaseTimeBehavior has incrementModel set to relative.

{
   "AggregateUseConstraint": {
      "incrementModel": "fair"
   }
}

Fields:

  • incrementModel

    Possible values:

    • fair

      Use this value if LeaseTimeBehavior has incrementModel set to relative.

      This combination is a fair model because the actual use time is tracked, and a license consumption refresh call adds only the additional time in relation to the original consumption time.

      The fair increment model appends the time difference from the last consumption to aggregate time.

      Example: A client consumes a license with a 1-day duration. After 2 hours, the client refreshes the license with a new consumption call for another 1-day duration. The addition to aggregate use time at the time of the first call was 1 day. The fair increment that results from the second call adds 2 hours to the aggregated use time.

    • append

      Use this value if LeaseTimeBehavior has incrementModel set to stack.

      With this combination, every license consumption stacks the consumption time on top of the previous value.

      The append increment model appends consumption duration time mechanically. It never considers the time difference between consecutive calls and compares that to the consume duration.

      Example: A client application consumes a license with a 1-day duration. The client makes a license refresh call after 2 hours. The resulting aggregated use time after the second call is 2 days (mechanically adding a 1-day duration from both calls).

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 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, a user must have an existing seat reservation to start consuming a license. After a seat has been assigned to a certain user, it cannot be reassigned to another user.

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

Example 2: Like above, a user must have an existing seat reservation to start consuming a license. However, this rule allows seats to be reassigned from one user 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 a user can start consuming a license without having an existing reservation, and a reservation is automatically created the first time the user consumes the license.

    Possible values:

    • true

    • false

  • seatReservationPolicy

    Define whether there are limitations to making seat reservations.

    Possible values:

  • requiredAssignmentReservationType

    Define that a user 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 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 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

On this page