Provision licenses with activation codes

By using 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 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 the configurations for license provisioning and activation code generation.

   1. Create a configuration for license provisioning: how 10Duke Enterprise will provision licenses using a single product package when a customer redeems an activation code. Create a separate configuration for each product package you want to provision licenses with.

   2. As part of each license provisioning configuration, define at least one 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 the codes.

2. Implement the provisioning of licenses based on redeemed activation codes.

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

3. 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)

Limitations

• You cannot specify the target entitlement in the license provisioning configuration. Organization licenses are always provisioned to the organization’s default entitlement.

• You cannot define a lock scope when provisioning licenses using activation codes. See more about using a lock scope to prevent the abuse of the trial licenses.

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 ACTIVATION CODES > Configurations 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 configurations for license provisioning and activation codes

Create the configurations in SysAdmin:

1. Start by creating the configuration for how 10Duke Enterprise provisions licenses to a customer (a user or an organization) 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 provisioning 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 license provisioning when codes are redeemed

Next, implement the provisioning of licenses through the 10Duke Entitlement Management REST API when customers redeem activation codes.

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

Create consumer users and organizations

License provisioning in 10Duke Enterprise requires the following:

• A consumer customer 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 customer an email invitation to register. You can send invitations manually in SysAdmin or use the 10Duke Identity Management REST API.

• 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. With an organization, it’s also set as the default entitlement.

Provision licenses

10Duke Entitlement Management REST API operations for provisioning licenses using an activation code:

An example flow for personal licenses

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 an API request containing information about the authenticated user and the activation code.

6. A personal license is provisioned to the user.

An example flow for organization licenses

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 redeeming both personal and organization activation codes, the user must be prompted to make a choice.

4. The user enters an activation code.

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

6. A license is provisioned 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

After completing the setup and distributing the activation codes, you can track the usage of the codes and maintain the configurations as needed.

Tracking usage of activation codes

After distributing activation codes, you can track how they have been used.

You can, for example, find out what activation codes a particular organization or user has redeemed. If you have associated activation code configurations with a reseller organization, you can find out which of their activation codes have been redeemed.

You can also check the status of an individual activation code to find out whether it has been redeemed yet, or if it’s blocked and cannot be used. (Note that an activation code may also be unusable because the associated activation code configuration has been changed or deleted.)

10Duke Entitlement Management REST API operations for tracking the usage of activation codes:

Maintenance

It’s possible to make changes to the SysAdmin configurations if needed. Possible use cases are that you want to extend a configuration’s validity, or you want to add new activation code configurations to enable generating more activation codes.

However, note the following limitations:

• In a license provisioning configuration, we recommend that you do not change the product package used by the configuration after you have already distributed activation codes.

  If you need to provision licenses with another product package, create a new license provisioning configuration for this.

  A possible exception is that you want to switch to using a product package that is effectively a newer version of the current product package, and you want to allow using the existing (unused) activation codes to get licenses to this new version.

• In an activation code configuration, you can change the configuration’s name and validity. Changing the code generation settings invalidates the activation codes generated with the previous settings, and they can no longer be redeemed.

  If you need to generate and distribute new activation codes, create a new activation code configuration for this.

An activation code is also invalidated if you delete the license provisioning configuration or activation code configuration related to the code.

If needed, you can block individual activation codes to prevent redeeming them.

Changes to the configurations or activation codes have no effect on any licenses that have already been provisioned using activation codes. If changes are needed to the licenses themselves, you can update them in the usual manner through the license transaction they were created with, either using SysAdmin or the Entitlement Management REST API.

10Duke Entitlement Management REST API operations to use for maintenance: