Handle and store license tokens

This article gives some instructions and best practices for how your client application needs to handle and store the JSON Web Token (JWT) license tokens that 10Duke Scale returns at checkout and heartbeat.

Verify the signature of license tokens

When 10Duke Scale grants a JWT license token at checkout or heartbeat, it signs the token using a private key.

To protect against the misuse of licenses, it’s critical that your client application always verifies the signature of a received license token. Your application should also verify the signature whenever it reads the license token from storage (for example, from disk or a database).

To verify the signature, your application needs the public key that corresponds to the private key that the license token was signed with.

  1. To determine which key you need, find the ID of the key pair in the license token’s JWT header, the kid header claim.

  2. To get the public key, we recommend that client applications connected to the Internet always retrieve it from 10Duke Scale. This enables rolling of the keys in 10Duke Scale as needed.

    Use the 10Duke Scale License Management API operation GET /licensing-signing-keys/.well-known/jwks.json, which returns the keys in JSON Web Key Set (JWKS) format (see RFC 7517).

    When client applications are deployed in an environment with no Internet access, they must store the public key. You can find the keys in the UI console, in SETTINGS > Token validation keys. The Key id column shows the ID of the key pair, and you can copy the public key from the Public key column.

  3. To verify the signature of license tokens, you can use the 10Duke Scale SDKs that provide support for checking out licenses and handling license tokens.

    You can also find libraries for various platforms and languages on the jwt.io website.

Validate the content of license tokens

After verifying the signature, the license token claims must be matched against what the client application expects.

  • If available, match the aud claim in the license token against your client application ID which your application sent in the checkout request’s cliApiKey claim (intended to carry the OAuth client ID of the application).

  • Check that the license consumer matches:

    • If the request was authorized using a 10Duke Scale JWT token, check that licenseConsumerId in the license token matches lcid in the authorization JWT token.

    • If the request was authorized using an ID token, check that licenseConsumerConnectedIdentityId in the license token matches sub in the ID token.

    If the request was authorized using a license key, no separate check on the license consumer is needed.

  • Match the client application claims in clientClaims in the license token against what the client application knows about itself.

    This includes matching the hardware ID in the license token against the hardware ID of the device on which the client application is running.

  • Check that productName and features in the license token apply to the features or functionality in the client application that the license consumer is trying to access.

  • Check that the license token is valid: that the current time is between the iat and exp timestamps.

Recommendations on storing license tokens

The license token can be stored, for example, as a file in the client application.

If the license token has a short validity time, it’s sufficient to save it in the client application memory.

However, if the license token has a longer validity time and needs to be valid also after restarting the client application, we recommend that you save it in the registry or on disk. If possible, use a safe location where any application-specific data is stored.

See more

Contents