Provision licenses with product activation codes

By using license activation codes, you can provision licenses that your customers can redeem later when they take your software into use. You can provision licenses with activation codes to both B2B and B2C customers.

This article explains the steps for creating a complete license activation code setup for one product package. When a customer redeems an activation code, they are granted a license to each licensed item in the product package.

Repeat the steps for each product package that you want to license using activation codes.

Overview

Here’s an overview of the steps needed:

1. In 10Duke SysAdmin, create a configuration for license provisioning: how 10Duke Enterprise grants licenses using the specified product package when a customer redeems an activation code.

2. As part of this configuration, also define the configuration for the activation codes.

   If you have multiple resellers distributing the activation codes, you can define reseller-specific configurations to help you track the usage of codes.

3. Implement the activation of licenses based on redeemed activation codes.

   This includes implementing the UI (typically a web page) where customers can redeem the codes.

4. Generate the activation codes with the 10Duke Activation Code Generator.

   You can also allow your resellers to generate activation codes themselves.

The 10Duke Activation Code Generator is a command line tool that runs independently and doesn’t connect to the 10Duke Enterprise server.

The tool generates activation codes that are cryptographically signed, and 10Duke Enterprise validates the signature when a customer redeems a code.

The codes use the following 32 characters: ABCDEFGHJKLMNPQRSTUVWXYZ23456789. This set includes unambiguous English uppercase characters and digits—characters O and I and digits 0 and 1 are not included.

Each validation code contains the following data:

• A product code that identifies the related activation code configuration in 10Duke Enterprise

• A unique sequence number

• A signature (a hash-based message authentication code, HMAC)

Before you start

To get started, contact the 10Duke Integration Support team about the following:

• You need the 10Duke Activation Code Generator command line tool.

• Your SysAdmin configuration must have the activation code-based license provisioning feature enabled. Check if you can see the PRODUCT CONFIGURATION > License Provisioning section in the left sidebar in SysAdmin, and contact the 10Duke Integration Support team if needed.

In addition:

• Create a product package that contains the licensed items needed.

• If you want to use reseller-specific activation codes, create an organization for each reseller.

Step 1: Create the configurations for license creation and activation codes

Create the configurations in SysAdmin:

1. Start by creating the configuration for how 10Duke Enterprise grants licenses to a customer who redeems an activation code.

   You can have more than one valid configuration for the same product package if needed. An example use case for this would be that you want to apply a different validity time to the licenses, for example, if you’re offering both trial and full licenses.

2. Next, in the license creation configuration you just created, add one or more activation code configurations.

   Multiple activation code configurations can be useful, for example, if you have multiple resellers distributing activation codes. When the resellers use different types of activation codes, you can track the usage of codes per reseller.

   Another use case for multiple activation code configurations is that you want to apply a different validity time to different batches of activation codes based on how the codes will be distributed.

See detailed steps on how to create the configurations.

Step 2: Implement the activation of licenses when codes are redeemed

Next, implement the activation of licenses when customers redeem activation codes.

You must also implement the UI where they can redeem the codes. 10Duke Enterprise only provides the API endpoint for this.

Create consumer users and organizations

License activation in 10Duke Enterprise requires the following:

• A consumer user must have a user account.

  You can handle user account creation, for example, by providing self-registration with the 10Duke Login Application component or by sending the user an email invitation to register.

• A company customer must have an organization defined.

  You can create the organizations manually in SysAdmin or use the 10Duke Identity Management REST API.

When a consumer or company customer redeems an activation code, an entitlement is automatically created for the user or organization if they don’t have one yet, and with an organization, it’s set as the default entitlement.

Activate personal licenses

Use the 10Duke Entitlement Management REST API to implement the license activation requests with an activation code and to grant personal licenses to users in their personal entitlement.

Send a request to /users/{userId}/activate-licenses.

This is an example flow:

1. A user opens the application.

2. The user is asked to log in.

3. When the user has been authenticated, they are shown a dialog to activate a license.

4. The user enters an activation code.

5. The application makes a request to the API endpoint containing information about the authenticated user and the activation code.

6. A personal license is granted to the user.

Activate organization licenses

Use the Entitlement Management REST API to implement the license activation requests with an activation code and to grant licenses in the organization’s default entitlement.

Send a request to /organizations/{orgId}/activate-licenses.

This is an example flow:

1. A user opens the application.

2. The user is asked to log in.

3. When the user has been authenticated, they are shown a dialog to activate a license for their organization.

   Note the following:

   • If more than one organization is available, the user must be able to select the target organization.

   • If you allow both personal and organization license activations, the user must be prompted to make a choice.

4. The user enters an activation code.

5. The application makes a request to the API endpoint containing information about the organization selected and the activation code.

6. A license is granted to the organization.

Step 3: Generate and distribute activation codes

Your setup is now ready, and you can start generating activation codes with the 10Duke Activation Code Generator and distributing the codes.

If your resellers will be generating activation codes, provide them with the code generator ZIP package and the command template you have copied from the activation code configuration in SysAdmin.

Install 10Duke Activation Code Generator

1. Install Java Runtime Environment (JRE).

2. Unzip the 10Duke Activation Code Generator package.

3. Add the code generator to PATH so that you can execute it by just writing duke-code on the command line instead of referring to the full path to where you unzipped it.

4. Test the installation by running the following command:

   duke-code hmac help

Generate activation codes

Run a command using the template you have copied from the activation code configuration in SysAdmin.

The command template you copied has the following type of format:

$ ./duke-code hmac -k -p PC -h 9 -s 5 -g 4 -z - -f 0 1

Edit the last two parameters in the template (-f 0 1): define first the number from which sequence numbering starts and then how many codes you want to generate. The unedited template above would start sequence numbers from 0 (zero) and generate one code.

Note: It’s important that you correctly manage sequence numbers when you generate codes, and that you don’t use the same sequence numbers again after you have distributed the codes. This ensures that each code is unique and that you can generate new unique codes on demand.

For example, if you first generate 100 activation codes with sequence numbers 0-99, start the sequence numbers of the next batch from 100:

1. For the first batch of codes, you would use the following type of a command:

   duke-code hmac --key --product-code PC --from 0 100

2. And for the next batch, you would use:

   duke-code hmac --key --product-code PC --from 100 100

Next steps

If you later need to edit or delete either a license creation configuration or an activation code configuration, the activation codes created with the previous settings become invalid. Generate and distribute new activation codes as needed.

The changes don’t affect licenses that have already been granted with the earlier codes.