Tutorial: User-Based Licensing
Cloud Licensing with Sentinel LDK CL Service and Sentinel EMS

Looking for a powerful, centralized, role-based solution for handling all of your software protection, licensing, and entitlement needs? You've come to the right place!

•Sentinel LDK is a comprehensive, out-of-the-box software monetization solution that protects and licenses your applications and services, so that you can maximize revenues while introducing flexible and customer-centric offerings into the market.

•Sentinel EMS entitlement management system has a straightforward design that walks you through the process of defining the various features and products that match the features and products in your back office system (ERP, CRM, billing system, or sales system).

The Sentinel LDK CL Service combines Sentinel LDK and Sentinel EMS to offer a user-centric approach to cloud licensing fulfillment in which Thales securely hosts the CL service for you on its servers. The CL service gives you and your customers granular control over who can access a cloud license. (You can optionally delegate end-user account management to customer administrator users.)

The CL service described in this tutorial consists of two primary components: Sentinel EMS, which handles license fulfillment, user management, and user-to-product associations, and Sentinel LDK, which manages cloud licenses and user authentication.

This tutorial focuses on user-based licensing. User-based licensing uses OAuth to enable end users to access the vendor's application or service using login credentials—for example, their user name or email address and their password. End users can log in to the application from any supported device without the need to activate a license or install anything special on the device. With user-based licensing, the user is authorized instead of the device. By associating products with users, vendors and customers can quickly enable or disable user access without the need for updating entitlements as long as other license details remain the same.

TIP

•Thales also offers identity-based licensing, in which credentials are installed directly on a device, so that anyone with access to that device can use the vendor's protected application or service. View the tutorial

• To learn more about the various licensing methods that Sentinel LDK offers, see Choosing and Integrating Hardware-, Software-, and Cloud Licensing.

The Basics

The following are the foundation of Sentinel EMS with Sentinel LDK enforcement. It's important to understand these terms before you perform the steps in this tutorial.

Sentinel EMS

Sentinel® EMS™ is a web-based solution that provides you with a centralized interface for all your license and entitlement management functions. It offers an easy-to-use interface for all your back office systems and a variety of advanced data collection and reporting functions. Learn More Sentinel EMS can help you in maximizing profitability by minimizing the internal costs and resources required for license fulfillment, improving operation processes, empowering channel partners, and improving the end user experience by streamlining license activation for end users. For more information, see the Sentinel EMS User Guide.

Sentinel LDK Envelope

Sentinel LDK Envelope provides both copy and reverse-engineering protection for applications on various platforms. Its easy-to-use user interface enables you to apply protection to executable files and DLLs in minutes. Learn More For applications that require a single license (one feature per binary), you can handle both licensing and protection using Envelope. However, for the most flexible licensing and highest level of copy protection, Thales recommends implementing both Sentinel Licensing API and Sentinel LDK Envelope. For more information, see Sentinel LDK Envelope Protection.

ToolBox and Sentinel Licensing API

Sentinel LDK ToolBox is an interactive application that enables software developers to learn about the various Sentinel LDK APIs. With this tool, you can execute API functions, observe their behavior, and copy the corresponding source code for integration into your own applications. For more information, see the Sentinel LDK ToolBox User Guide.

Sentinel Licensing API enables you to integrate fine-grained license enforcement into your application for an unlimited number of features, thereby ensuring end-user compliance with licensing terms. Each feature in your application is integrated separately using a unique feature ID and login API call. For more information, see the Sentinel LDK Software Protection and Licensing Guide.

Features

Features are the basic building blocks of products and licenses. Each feature can represent anything from a functional component to an entire application. Learn More This means that you can create a separate feature for a specific functionality, such as "Print" or "Edit & Save", or you can create a feature for each module or for an entire application.

After you define at least one feature in the Sentinel EMS catalog, you can add that feature to a product. This enables you to sell a product with one or more licensed features.

Feature ID (Sentinel LDK) and Feature Identifier (Sentinel EMS). This unique number identifies the feature in your Sentinel LDK application and in Sentinel EMS. During runtime, your application utilizes the Sentinel Licensing API (login function) to consume a license with the specific feature ID. Sentinel LDK Runtime determines whether the user has a valid license to use the corresponding feature. Always ensure that the feature identifier in Sentinel EMS is identical to the feature ID in the Sentinel LDK application you are using to protect your application (Sentinel LDK Envelope or Sentinel Licensing API).

Products

A product represents a saleable item in your organization—such as a software application—usually with a SKU or similar unit. You can package products with individual features and memory files. Learn More Both features and memory files are optional.

License models and terms. Sentinel LDK enforcement provides configurable, out-of-the-box license models.

You assign a license model and license terms to a feature when you add the feature to a product.

Setting license terms per feature occurrence lets you vary the license terms as needed. This flexibility gives you full control over feature usage whether you include one feature per product, the same feature in multiple products, or multiple copies of a feature in a single product.

When ready, you add products to entitlements so that the vendor can generate licenses for distribution to customers.

Entitlements

An entitlement is a customer order for one or more products. Similar to orders in your back office system (ERP, CRM, billing system, or sales system), an entitlement specifies the products that a customer is entitled to use. Learn More It also includes contact details, the products ordered, the features and memory files bundled in the products, licensing terms, the number of copies of your product that are available to that customer (quantity), and the entitlement ID (EID). Each entitlement can also be mapped to an actual order or other reference ID in your system using the External ID or Ref ID fields in Sentinel EMS.

When an entitlement is ready to be processed, you mark it as complete. That enables the next step, which is generating a license and pushing it to the cloud using Produce and Push.

TIP Want to learn more about any of the concepts and terminology used in Sentinel EMS with Sentinel LDK enforcement? Check out the Glossary at the end of this tutorial.

Tutorial Workflow

This tutorial showcases how to use Sentinel LDK and Sentinel EMS to protect and license an application. You will use a sample TextEditor application that has two separately licensable features: Edit & Save and Print. To simplify this tutorial, TextEditor is already integrated with the necessary Sentinel LDK Licensing API calls to manage and consume licenses for each feature.

Learn about the different personae in the Sentinel EMS and Sentinel LDK workflows

•Vendors. Vendors develop and sell software. They use Sentinel LDK to protect their applications and services, and to enforce licensing. They use the Sentinel EMS vendor portal to generate and manage licenses and user accounts. View the different Sentinel LDK and Sentinel EMS personae in the vendor's organization

•Customer Administrator Users. (Optional) Vendors can delegate end-user account management directly to their customers by creating administrator users. The administrator user uses the Sentinel EMS customer portal to create end-user accounts.

•End users. The customers' end users use their licensed software.

Typically, the product owner defines the features and products in the catalog, the order taker then defines the entitlement, and the vendor generates the license.

Initial Setup, License Integration, Application Protection, and Testing

This end-to-end workflow illustrates the license integration and application protection process for developers and product owners, focusing on testing and integration.

Production and License Fulfillment for a Vendor's Customers

This end-to-end workflow for Sentinel EMS personae occurs after testing is done, focusing on actual production and license fulfillment for a vendor’s customers.

See what's not included in this workflow

Before You Begin

•Review The Basics to learn about the Sentinel LDK and Sentinel EMS components.

•Make sure that your Thales account enables you to access Sentinel EMS. At minimum, you need a role in Sentinel EMS that includes Customer Management permissions. Contact your Thales representative for assistance if needed.

Create a Catalog

In this section, you create a catalog that includes your saleable items—a feature and a product. Make sure that you are logged on to the Sentinel EMS vendor portal. Show me how

Step 1: Create a Feature

The first step in creating a catalog is defining features.

1.From the navigation pane, select Catalog > Features.

2.In the Features page, click Add Feature .

3.In the Add Feature page, if the Namespace list is displayed, select the namespace you want to use. If you have your organization's batch code (known as a namespace in Sentinel EMS), you may want to select that namespace. Otherwise, select DEMOMA to use the demo namespace and batch code.

4.In the Add Feature page, in the Name field, enter Edit & Save.

5.In the Identifier field, enter 501.
When you create your own features, you can use the default identifier or apply another identifier to match an existing feature in one of your company's products.

The identifier must match the feature ID in the Sentinel LDK application you are using to protect your application (Sentinel LDK Envelope or Sentinel Licensing API) as described in Features.

NOTE If Sentinel EMS supports additional enforcements, you may see additional fields. These fields are not relevant for Sentinel LDK and can safely be ignored.

6.Click Save.

7.Now add another feature. In the Features page, click Add Feature .

8.In the Add Feature page, if the Namespace list is displayed, select the namespace you want to use. If you have your organization's batch code, you may want to select that namespace. Otherwise, select DEMOMA to use the demo namespace and batch code.

9.In the Add Feature page, in the Name field, enter, Print.

10.In the Identifier field, enter 502.

NOTE The TextEditor sample used in this tutorial already embeds Sentinel LDK Licensing API calls for feature IDs 501 and 502. When working with your own applications, you would share the feature identifiers with your developers. The developers would then include these as feature IDs in Sentinel LDK Licensing API login calls from the relevant sections in the application code. This enables the application to determine if the customer has access to a valid license for each feature.

You've created your first features. Next, you will add these features to a product.

Step 2: Create a Product

Now that you created your features, you can add them to a product. This is known as associating features with a product.

1.From the navigation pane, select Catalog > Products.

2.In the Products page, click Add Product .

3. If Sentinel EMS includes support for other enforcements in addition to Sentinel LDK, you need to select the relevant enforcement before continuing.

In the Add Product page, in the Enforcement Type field (not shown), select Sentinel LDK. Otherwise, skip to the next step.

4.In the Add Product page, if the Namespace list is displayed, select the namespace you used when creating a feature. Otherwise, skip to the next step.

5.In the Add Product page, in the Name field, enter TextEditor.

6.In the Identifier field, leave the default value.

Later, when working with your own products, you can change the number to match an existing product identifier in your saleable product.

7.Expand Additional Attributes, click the Locking Type arrow (not shown), and select an SL AdminMode-related locking type, or leave the default HL or SL AdminMode or SL UserMode value as is.

8.In the Available Features area of the Associate Features pane, click the features you created one by one and add them to the Associated Features pane.

NOTE In the Associated Features pane, a value for Default License Model may or may not be displayed depending on your Sentinel EMS configuration.

9. Let's configure the license models for each feature.

In the Associated Features pane, either select the check box for the Edit & Save feature and click the Configure License Model button, or, under Actions, click Configure License Model.

10. Set the license model for the Edit & Save feature.

Let's apply an annual subscription license that starts when the license is generated.

a. Click the Name arrow and select Time from License Generation, which is one of the available license models. Notice that the displayed attributes change to reflect the selected license model.

b. Under License Terms, in the Number of Days box, enter 365. (When the Allow Overwrite check box is selected, the order taker can modify the number of days later when creating an entitlement for a customer.)

c. Under Concurrency, set Enable Concurrency to Yes. This is required for using Produce and Push to activate an entitlement.

d. In the Concurrent Instances box, enter the number of license instances that need to be able to run at the same time, for example, 2. You must set a minimum of 1 to use Produce and Push to activate an entitlement.

e. Click Save.The license configuration for the Edit & Save feature is saved.

11.In the Associated Features pane (not shown), follow the steps described earlier to open the Configure License Model dialog box for the Print feature. Make sure to clear the check box for Edit & Save if you selected it earlier.

Let's apply an execution-based license.

a. Click the Name arrow and select Execution Count, which is one of the available license models. Notice that the displayed attributes change to reflect the selected license model.

b. Under License Terms, in the Executions box, enter 5.

c. Under Concurrency, set Enable Concurrency to Yes. As mentioned earlier, this is required for using Produce and Push to activate an entitlement.

d. In the Concurrent Instances box, enter the number of license instances that need to be able to run at the same time, for example, 2. You must set a minimum of 1 to use Produce and Push to activate an entitlement.

e. Click Save.The license configuration for the Print feature is saved.

12. In the Add Product page (not shown), click Save. The product is created as a draft.

13.In the Products page, for the product you created, in the Actions column, click the Complete button.

14.In the confirmation box that opens, click Complete (not shown). This makes the product available for distribution.

You've successfully created your first product, TextEditor.

Define a Customer and Administrator User

In this section, you define a customer for the entitlement that you will be creating later. At this stage, you will also create an administrator user for the customer. Adding an administrator user lets you delegate product-to-user association management directly to the customer. Without an administrator user, you, the vendor, would have the sole responsibility of associating products with your customers' end users. Make sure that you are logged on to the Sentinel EMS vendor portal. Show me how

Step 1: Create a Customer

When working with cloud licensing, every entitlement is associated with a customer. We are going to create a customer now, but you can create customers whenever needed at any stage of the process prior to generating a license. Make sure that you are logged in to the Sentinel EMS vendor portal.

1.From the navigation pane, select Customers > Customers.

2.In the Customers page, click Add Customer .

3.In the Add Customer page, if the Market Group list is displayed, select the market group for the namespace that you are using, for example, DEMOMA.

4.In the Add Customer page, in the Name field, enter a name for the customer that you are creating, for example Papyrus & Words. You can enter any customer name that you want.

5.Leave the Identifier blank, so that a customer identifier will be generated automatically when you save the customer.

6.In the Associated Users area, if an administrator user already exists, you can select that user to link to this customer. All types of users are listed here—not just administrator users. You can search by various fields to find the user that you need.

In our case, though, we have not yet created an administrator user. Let's do that now after we save the customer.

7.Click Save.

You've created your customer. Next, you will assign an administrator user to this customer.

Step 2: Create an Administrator User

Before we continue, let's create an administrator user who will manage the product-to-user association for our customer. The administrator user is typically a procurement, contract, or purchasing manager who handles licenses within an organization.

This will save us time when creating an entitlement because the administrator user is automatically assigned to the entitlement when you select the customer. (If several users are associated a customer, you may need to specify the relevant administrator user.)

1.From the navigation pane, select Customers > Users.

2.In the Users page, click Add User Add Contact .

3.In the Add User page, if the Market Group list is displayed, select the market group for the namespace that you are using, for example, DEMOMA.

4.In the Add User page, in the User ID field, enter an identifier for the user that you are creating, such as 123456. You can enter any identifier that you want, including a name or email address.

5.In the Email field, enter your email address. The image shows an example.

6.In the Password field, enter a password that you will remember. Click the password criteria icon to see the criteria.

You can use this password to log on to the Sentinel EMS customer portal to manage the product-to-user associations that you handle.

7.In the Name field, enter a name for the administrator user, such as Robin Early. You can enter your own name if you want.

8.Under User Type, select Administrator. Only administrator users can manage product-to-user associations for cloud licensing.

9.In the Customer field, start typing the name of the customer that you created earlier. As you type, a list of suggestions is displayed. Select the relevant entry. This associates the user with the specified customer when you save the customer.

10.Click Save.

You've created your user. In the Users page (not shown), you can expand the user that you just created to view the various user attributes.

Next, you will create entitlement and generate licenses.

Generate a License and Push It to the Cloud

In this section, you generate a license and push that license to the Thales Hosted Cloud License Server using Sentinel EMS with Sentinel LDK enforcement.

First, you will generate an entitlement to fulfill an order for a specific customer. Then you will use Produce and Push to generate a cloud license for the product features included in the entitlement. The license will automatically be pushed to the Thales Hosted Cloud License Server, making it ready to share with the customer's end users. Make sure that you are logged on to the Sentinel EMS vendor portal. Show me how

Step 1: Create an Entitlement

In this step, you are creating an entitlement.

1.From the navigation pane, select Entitlements.

2.In the Entitlements page, click Add Entitlement .

3.In the Add Entitlement page, under Assign Customer / Channel Partner, set the required fields:

a. If the Market Group list is displayed, select the market group that you are using, for example, DEMOMA.

b. In the Customer field, start typing the name of the customer that you created earlier. As you type, a list of suggestions is displayed. Select the relevant entry. You must specify a customer to use Produce and Push to activate an entitlement.

c. In the User Email field, verify that the email address of the administrator user that is associated with the customer is displayed. Earlier, you defined yourself as the administrator user, so this should be your email address. Specifying the relevant email address enables your organization to delegate license management to the customer via the Sentinel EMS customer portal.

4.Expand Define Entitlement Attributes > Additional Attributes and optionally set one or more of the following.

a. (Optional) Set Allow Activation to Yes and ensure that Vendor Only is selected. This ensures that end users that access the Sentinel EMS customer portal cannot activate the products in the entitlement.

b. (Optional) Set Entitlement as a Whole to Yes. This recommended setting enables you to activate all products at once without the need for selecting each product.

c. (Optional) Set Send Notification to Yes. This sends an email to the email address specified in the User Email field, notifying them that the entitlement is ready for activation.

5.In the Associate Products / Product Suites pane, under Available Products, click the product you created to add it to the Associated Products / Product Suites section.

6.Click Save to save the entitlement as a draft. (If you skip this and go to another tab, your input will be lost.)

7.In the Entitlements page, in the Actions column, click Mark as Complete to complete the entitlement.

(The image shows the Draft status prior to confirmation.)

8.In the confirmation box, click Complete (not shown). The entitlement details are saved. An Entitlement Certificate email is sent to the user email address you entered earlier.

(The image shows the Completed status post-confirmation.)

In the next step, you will use "Produce and Push" to generate a cloud license and push the license to the Thales service-hosted, cloud license manager server.

Step 2: Use Produce and Push to Generate a Cloud License and Push the License to Thales' Service-Hosted, Cloud License Manager Server

In this step, you generate a cloud license and push the license to the Thales service-hosted, cloud license manager server in a single step.

1.From the navigation pane, select Entitlements.

2.Expand the entitlement you created and click Produce & Push.

3. In the Activate Products page, verify that the Activatee Email is correct.

4.Click Produce & Push to generate a new key with the required licenses.

TIP If you ever need to update this key, the Generate Licenses area lets you choose between generating a new key or updating the licenses on the existing key.

Unless needed, Thales recommends that you update the existing key. By maintaining a single key for each customer, you limit confusion and ease maintenance over time.

5.The Activate Products page displays information about the products you are activating.

6.Click Done. A license certificate is sent to the activatee email address that you specified earlier.

The license certificate email does not include a license string because the end user accesses the cloud license using credentials instead of a license string.

7.The key is marked as Activated, and the license is now stored on Thales' service-hosted, cloud license manager server.

8.(Optional) View the key in the Sentinel Keys page.

In the navigation pane, click Sentinel Keys. The Status column indicates the status of the Sentinel key.

The Enabled status means that the license was pushed successfully to the cloud license manager server. You can expand the key line item and switch between the tabs to view the associated products and features, associated memory, and key attributes.

TIP When there are multiple keys on the page, you may want to search by customer to locate the key.

Congratulations! You successfully generated a CL (cloud licensing) key.

Define an End User and Associate a Product

In this section, you define an end user for the licensed application and associate a product with that end user.

In a real-life scenario, you would define as many end users as needed. To enable user-based licensing, each end user must be associated with a customer. After defining end users, you would then associate those users with the products for which they need access. This allows you to manage access by enabling or disabling products for each user as necessary.

Although you can perform this step from either the Sentinel EMS vendor portal or the Sentinel EMS customer portal, this tutorial explains the steps using the Sentinel EMS vendor portal. Show me how

Step 1: Define an End User

You will now define an end user and associate that user to the customer.

1.From the navigation pane, select Customers > Users.

2.In the Users page, click Add User Add Contact .

3.In the Add User page, if the Market Group list is displayed, select the market group for the namespace that you are using, for example, DEMOMA.

4.In the User ID field, enter an identifier for the user that you are creating, such as MyUser. You can enter any identifier that you want, including a name or email address.

5.In the Email field, enter an end user email address. To receive a notification when the entitlement is activated, enter an email address to which you have access. (Do not use the administrator email address that you entered earlier.) The image shows an example.

6.In the Password field, enter a password that you will remember. Click the password criteria icon to see the criteria.

The end user can use this password to log on to the Sentinel EMS customer portal.

7.In the Name field, enter a name for the end user, such as MyUser. You can enter your own name if you want.

8.Under User Type, select Standard.

10.Click Save.

You've created your end user. In the Users page (not shown), you can expand the user that you just created to view the various user attributes.

Next, you will associate a product with the end user.

Step 2: Associate a Product with the End User

You will now associate the end user with a product.

1.From the navigation pane, select Customers > Product-to-User Association.

2.In the Customer field, start typing the name of the customer that you created earlier. As you type, a list of suggestions is displayed. Select the relevant entry.

3.In the Search box, select Product Name, and enter TextEditor, which is the name of the product to which you want to associate the user.

4.In the Actions column of the product, select Manage User Association.

5.In the Available Users pane of the Manage User Association page, click the end user that you created earlier. The user is moved to the Associated Users pane.

6.Click Save.

You've now associated your user with a product.

Next, you will set up an OAuth Client.

Set an OAuth Client

In this section, you set OAuth client authentication to enable end users to access your application. The tasks related to configuring the OAuth client are not dependent on other steps performed in Sentinel EMS or Sentinel LDK and can be done at any time.

This tutorial assumes that you have a basic understanding of OAuth. If you are not familiar with OAuth, we recommend reviewing the section describing OAuth in the Sentinel EMS User Guide for Sentinel LDK. To learn more about the hasp_auth.ini file described below, see Sentinel LDK Software Protection and Licensing Guide.

Make sure that you are logged on to the Sentinel EMS vendor portal. Show me how

Step 1: Set the OAuth Client in Sentinel EMS

In this step, you set the OAuth client authentication in Sentinel EMS.

When you create an OAuth client, the attribute values that you set depend on the type of application. In this tutorial, you are providing client access to the TextEditor application, which is a desktop application, so you will apply a public client. For a SaaS application, you would set a confidential client.

For example, if you are setting the OAuth client for a public application, which is suitable for an on-premises or desktop application, you would select the Public client type, set the Redirect URI to http://localhost/<path>, and set the PKCE Code Challenge Method to Plain. Similarly, if you are setting the OAuth client for a confidential application, which is suitable for SaaS applications, you would set the confidential client credentials.

1.From the navigation pane, select Identities & Access > OAuth Clients.

2.In the OAuth Clients page, Click Add OAuth Client Add Contact .

3.In the Add OAuth Client page, in the Name field, enter a name for the OAuth client that you are creating, such as OAuthClientForTextEditorApp. You can enter any name that you want up to 255 characters.

4.Leave the Client ID field blank. When you click Save, an ID will be generated automatically. Whether you enter a value or enable Sentinel EMS to generate a value for you, the ID is automatically prefixed with "app-", as shown in the example. (If you want to specify a client ID, you can enter alphanumeric characters, underscores, and hyphens.)

5.In the Client Type field, select Public. The Grant Type is automatically set to Authorization Code.

6.In the Redirect URIs field, enter the callback URL where the end user is redirected after successfully authenticating and authorizing the client application, for example: http://localhost/v1/callback

7.Under PKCE Code Challenge Method, select Plain.

8.Click Save.

You've set an OAuth Client in Sentinel EMS.

Next, you will add the OAuth Client to your application.

Step 2: Add the OAuth Client to Your Application

Now that you have created your OAuth Client, it is time to add the OAuth Client to your application.

User-based licensing uses OAuth authentication to enable end users to access your application. You set the OAuth client attribute values according to the type of application. TextEditor is a desktop application, which requires you to set a public client type and an authorization code grant type.

1.Navigate to: %ProgramFiles(x86)%\Thales\Sentinel LDK\Redistribute\Authentication Runtime\

2.Copy the hasp_auth.ini, hasp_auth.exe, and the welcome.htm files from this folder

3.Paste these files in the %Program Files (x86)%\Thales\Sentinel LDK\Samples\Tutorial\TextEditor folder.

4.Open the hasp_auth.ini file in any text editor and ensure that the following values are filled in for their respective fields.

SNTL_TOKEN_URI=https://<your-identity-provider-URL>/auth/realms/<realm-ID>/protocol/openid-connect/token (for example, https://my-idp.example.com/auth/realms12a12aa0-1234-1aa2-1aa2-a123b1234567/protocol/openid-connect/token)
SNTL_AUTHZ_URI=https://<your-identity-provider-URL>/auth/realms/<realm-ID>/protocol/openid-connect/auth (for example, https://my-idp.example.com/auth/realms/12a12aa0-1234-1aa2-1aa2-a123b1234567/protocol/openid-connect/auth)
SNTL_LM_HOST=<your-Sentinel-EMS-URL> (for example, myorg.example.com)
SNTL_CLIENT_ID=app-<your-client-ID> (for example, app-11aaa111-a111-1aaa-1111-11aaaaaaa1aa)
SNTL_REDIRECT_URI=http://localhost/v1/callback
SNTL_CODE_CHALLENGE_METHOD=plain
SNTL_STORE_AUTHZ=false
SNTL_SCOPE=openid

NOTE Set the SNTL_AUTH_PROXY and SNTL_AUTH_PROXY_PWD values if you are using a proxy. Otherwise, you can leave them blank or delete them.

5.Save and close the hasp_auth.ini file.

6.Verify that the authentication works as expected.

Launch TextEditor. If OAuth integration is successful, a sign-in page opens. Enter your credentials and verify that TextEditor opens.

You have successfully integrated OAuth with your application.

Integrate Licensing and Protection

This section is intended only for developers. It's time to protect the TextEditor application by using Sentinel LDK Envelope. Sentinel LDK Envelope utilizes the Sentinel LDK Licensing API to establish a strong binding between the protected software and the license installed in the protection key.

Step 1: License the Features in Your Application Using Sentinel LDK Licensing API

Now that you have associated products with users, you (the developer) can use Sentinel LDK Licensing API to implement and test the licensing integration of the required features. You can license each of these features using Sentinel EMS. This provides granular control over the functionality available to users based on their licenses.

TextEditor is already integrated with the necessary Sentinel LDK Licensing API calls to manage (or consume) licenses for the Edit & Save and Print features for this tutorial. You do not need to perform additional integration steps to enable licensing functionality in this tutorial.

You can review TextEditor’s source code and comments to see how the Edit & Save and Print features are integrated with the Sentinel LDK Licensing API.

1. Navigate to the %ProgramFiles(x86)%\Thales\Sentinel LDK\Samples\Licensing\csharp\TextEditor folder to access the source code.

2.Open EditorForm.cs, for example, to view the source code, as shown in the snippet.

Notice the constants that define the feature IDs for Edit & Save and Print.

When the TextEditor application loads, Sentinel Licensing API validates the licenses for each feature. This best practice ensures that end users can see which features are available for use as soon as they log in to the application. Otherwise, a feature might appear disabled or return an error when a user tries to use it.

In this sample, Sentinel Licensing API logs in to the Edit & Save feature immediately, enabling users to start consuming the license as soon as they open TextEditor.

Sentinel Licensing API logs in to the Print feature to consume a license only when a user actually tries to print (not shown). Validating the license when the application loads and logging in to the feature only when needed prevents unnecessary license consumption, which is especially useful for execution count-based licenses.

Copy

...
                        
namespace TextEditor
{
    public partial class EditorForm : Form
    {
        private String filePath = String.Empty;
        private static string defaultScope = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?> " +
                                             "<haspscope/> ";
        // Set the constants for the licensed features 
        // Sentinel Licensing API uses these constants to determine whether a valid license exists for each feature ID
        // In Sentinel EMS, these same feature IDs must be used to define the features in the catalog
        const int LDK_FEATURE_Edit = 501;
        const int LDK_FEATURE_Print = 502;

        public EditorForm()
        {
            InitializeComponent();
        }
        
        ...

        private void printToolStripMenuItem_Click(object sender, EventArgs e)
        {
            // Log in to the licensed Print feature
            HaspFeature feature = new HaspFeature(LDK_FEATURE_Print);
            Hasp hasp = new Hasp(feature);

            HaspStatus status = hasp.Login(VendorCode.Code, defaultScope);
            if (HaspStatus.StatusOk == status)
            {
                PrintTxt(this.textBox.Text);
            }
            else
            {
                MessageBox.Show("Print license not found.",
                    "TextEditor",
                    MessageBoxButtons.OK,
                    MessageBoxIcon.Question,
                    MessageBoxDefaultButton.Button2);
            }
        }
        ...

        private void EditorForm_Load(object sender, EventArgs e)
        {
            // Sentinel Licensing API determines if a valid license exists for the Edit & Save feature 
            // and logs in to consume the license
            HaspFeature feature = new HaspFeature(LDK_FEATURE_Edit);
            Hasp hasp = new Hasp(feature);

            HaspStatus status = hasp.Login(VendorCode.Code, defaultScope);
            if (HaspStatus.StatusOk != status)
            {
                this.newToolStripMenuItem.Enabled = false;
                this.saveToolStripMenuItem.Enabled = false;
                this.saveAsToolStripMenuItem.Enabled = false;
                this.textBox.ReadOnly = true;
                this.Text = this.Text + " - " + "Viewer Mode";
            }

            // Sentinel Licensing API determines if a valid license exists for the Print feature
            String scope =
                "<?xml version=\"1.0\" encoding=\"UTF-8\" ?> " +
                "<haspscope>" +
                "    <feature id=\"" +
                LDK_FEATURE_Print +
                "\"/>" +
                "</haspscope>";
            String format =
                "<haspformat root=\"hasp_info\">" +
                "    <feature>" +
                "       <attribute name=\"id\" />" +
                "       <attribute name=\"locked\" />" +
                "       <attribute name=\"expired\" />" +
                "       <attribute name=\"disabled\" />" +
                "       <attribute name=\"usable\" />" +
                "    </feature>" +
                "</haspformat>";
            String info = null;

            status = Hasp.GetInfo(scope, format, VendorCode.Code, ref info);
            if (HaspStatus.StatusOk != status)
            {
                this.printToolStripMenuItem.Enabled = false;
            }
        }
    }
}

Step 2: Protect Your Application Using Sentinel LDK Envelope

In this section, you are using Sentinel Envelope to protect the TextEditor application.

1.From the Start menu, select Sentinel LDK. The Sentinel LDK Launcher opens.

2.Click Envelope to launch Sentinel LDK Envelope. Sentinel LDK Envelope opens to enable you to protect your application or service.

3. In the Sentinel Envelope Project pane, select Sentinel Vendor Code.

4.Select Use Vendor Code from file.

5.If not displayed by default, navigate to %ProgramFiles(x86)%\Thales\Sentinel LDK\VendorCodes\, and select DEMOMA.hvc

6.In the Sentinel Envelope Project pane, select Programs.

7.On the right side of the Programs pane, click Add Programs.

8.In the Add Programs window (not shown), navigate to the %ProgramFiles(x86)%\Thales\Sentinel LDK\Samples\Tutorial\TextEditor folder.

9.Select TextEditor.exe and click Open. TextEditor.exe is added to the Program list.

10.In the Sentinel Envelope Project pane, under Programs, select TextEditor.exe.

11.At the bottom-right of the Protection Details pane, click Protect. The Protection Status dialog box (not shown) shows the progress and displays a message when the protection is complete.

12.Click Close to close the dialog box when the protection process is complete.

13.Close Sentinel LDK Envelope. You are prompted to save the changes to the current project.

14.Click Save. The Save As dialog box is displayed. In the File Name field, enter Tutorial_TextEditor (or any name of your choice) and click Save.

Now that you have licensed the features and protected the application, it's time to test and validate the licensing and protection. Continue with End User Starts Using the Application / Test Your Application.

End User Starts Using the Application / Test Your Application

Now that the application is ready to use and the customer's end user is associated with your protected application or service, you can launch TextEditor.

For the purposes of this training, let's assume that:

• Your application is already packaged together with Sentinel Run-time Environment.

•You, the developer, want to verify that the application is protected and that the licenses are working correctly.

Launch and Test the Application on the Client Machine (End User's Device)

This step demonstrates how to launch and test the TextEditor application. You can also see how its licenses are used.

1.Before you begin testing, ensure that the hasp_net_windows.dll file from %ProgramFiles(x86)%\Thales\Sentinel LDK\Samples\Tutorial\TextEditor is in the output folder where TextEditor.exe is located.

2.Open the Tutorial_TextEditor folder you created and double-click the protected Texteditor.exe program to launch the TextEditor application.

You can see that the TextEditor application is protected in the following ways:

•The size of a protected application is larger than an unprotected application.

•The application load time of a protected application is slightly longer.

•When you use DEMOMA, a message box opens letting you know that the program is protected with a demo Sentinel protection key.

3.Test the TextEditor application to ensure that the licenses work correctly.

TextEditor should run in editor mode enabling you to add and edit text and to open a text file. Try saving and printing the document.

If TextEditor opens in viewer mode, the text area appears disabled, and you can open a document, but you cannot edit or print it. Verify that the licenses and feature IDs are configured correctly for the Edit & Save and Print features in Sentinel EMS and Sentinel Licensing API.

4.(Optional) You can log in to Sentinel Admin Control Center (ACC) to view and manage how licenses for Edit & Save and Print are consumed. Enter http://localhost:1947 in the address field of the web browser to open Sentinel Admin Control Center on your local machine.

Ensure that the Sentinel LDK License Manager service is active on the machine where Admin Control Center runs.

5.From the navigation pane, go to the Features page. For detailed information, see the Sentinel Admin Control Center User Guide.

6.In the Restrictions column. You can see that:

a. For Edit & Save, the time period is set as 365 days (as configured in Sentinel EMS) with the start and end dates and times.

b.For Print, five executions are available.

Congratulations! You licensed and protected the TextEditor application.

Glossary

Let's review the concepts and terminology that you need to know to work with Sentinel LDK enforcement in Sentinel EMS.

Show the Glossary

Concept	Description
Activation (License Generation)	The process of generating a license package (V2CP file) for one or more products. A license can be locked to a specific device, or it can be unlocked, as described in Unlocked from Device (Product).
Application	In the context of Sentinel LDK, application or protected application refers to the vendor's application or service, which is licensed and protected by the Sentinel LDK Licensing API (native or REST) and/or Sentinel Envelope, and optionally packaged with Sentinel Run-time Environment. For more details on these components, see Sentinel LDK and navigate to the relevant guide.
Batch Code	See Namespace (Batch Code).
Burning a Key	Activates an entitlement by installing the license file directly on a Sentinel HL key (dongle).
Catalog	A container for all of your assets, including products, features, memory files, license models, and namespaces. For more details, see Sentinel EMS User Guide for Sentinel LDK.
C2V and V2CP files	C2V (Customer-to-Vendor). A file containing data about deployed Sentinel protection keys or data about the customer's device, such as its fingerprint. The customer sends the C2V file to the vendor through an automated process or by other means, such as email. The vendor or an automated backend process then uses the C2V file to generate a license for the customer when activating an entitlement. V2CP (Vendor-to-Customer Package file). A package file from the software vendor that contains one or more license update files (V2C files) for the customer's Sentinel protection key.
Cloud Licensing Permissions	Cloud licensing permissions control access and usage permissions for CL keys. Permissions are set at global, customer, and machine account levels. For more details, see Sentinel EMS User Guide for Sentinel LDK.
Customers and Users	A customer can be an organization that owns an entitlement or a current or potential buyer of an entitlement. Typically, you generate entitlements for a customer who has placed an order. A customer can have one or more users.
DEMOMA	Batch Code/Namespace used for evaluation purposes. DEMOMA's corresponding Vendor Code is available in the VendorCodes folder of your Sentinel LDK installation. This batch code is useful for evaluating all Sentinel LDK workflows but cannot be used for production as any Sentinel LDK customer or evaluator can generate such licenses.
Devices	In Sentinel EMS with Sentinel LDK, a device is any hardware on which customers can install your licensed application, including, but not limited to, computers, tablets, phones, and watches. See also: Tutorial: User-Based Licensing Cloud Licensing with Sentinel LDK CL Service and Sentinel EMS
Enforcement	Licensing technology, such as Sentinel LDK, that controls and secures your software by controlling usage terms and conditions for specific functionalities, and by applying security measures to prevent bypassing these terms and conditions.
Entitlement	An entitlement grants an end user the right to use a software package or service. It defines the product details, the authorized users, and the order's validity period.
Envelope (Sentinel LDK Envelope)	Sentinel LDK Envelope provides both copy and reverse-engineering protection for applications on various platforms. Envelope utilizes the Sentinel LDK Licensing API and numerous anti-cracking technologies to establish a strong binding between the protected software and the license installed in the protection key. For more information, see Sentinel LDK Envelope Protection.
Feature	Features are the basic building blocks of products and licenses. A feature can represent anything from a functional component to an entire application. After you define at least one feature in the Sentinel EMS catalog, you can add that feature to a product. This enables you to sell a product with one or more licensed features.
Feature ID and Feature Identifier	A unique number that identifies the feature in both your Sentinel LDK application and Sentinel EMS. During runtime, Sentinel Licensing API acts on behalf of your application to validate feature licenses. It does this by specifying the feature ID as part of the login call to the license for that feature ID. Therefore, the identical number must be used in both the feature identifier in Sentinel EMS and the feature ID in the relevant Sentinel LDK application (Sentinel LDK Envelope or Sentinel Licensing API).
Feature ID 0 (Default Feature)	A default feature ID that is always available in a Sentinel protection key and can be used to provide copy protection without the need to fulfill a Sentinel LDK license. This feature's license model is always Perpetual and cannot be modified to use other licensing terms. When you protect an application with Envelope, Feature ID 0 is applied by default if you do not choose any other feature ID for licensing the application. In Sentinel SL and CL keys, any key produced by the vendor includes Feature ID 0, regardless of whether other features or memory are defined. In Sentinel HL keys, all keys that leave the Thales factory already contain Feature ID 0 enabled. If no additional licenses are needed (for example, if only Envelope protection is used), these keys can be distributed directly to users to enforce copy protection of the software.
License Model	The license terms for a feature. You set the license model when adding a feature to a product, or when modifying a feature in an entitlement. License models: •Define in Entitlement. Enables the order taker to define the license type when creating an entitlement (when each individual order is processed). (Available only when creating a Product.) •Execution Count. The maximum number of times the feature may be used. (Not relevant for products that are not locked to a device. See Unlocked from Device (Product).) •Expiration Date. The date on which the license for the feature will expire. •Perpetual. Default license model. The license can be used an unlimited number of times and for an unlimited period of time. •Time from First Use. (Also known as Time Period.) The number of days until the license expires. The number of days is counted from the date on which the licensed feature is first used. •Time from License Generation. The number of days until the license expires. The number of days is counted from the date on which the license is generated. (Not relevant for products that are not locked to a device. See Unlocked from Device (Product).) For more details, see Sentinel EMS User Guide for Sentinel LDK.
Licensing API	Sentinel LDK Licensing API is the interface for inserting calls to a Sentinel protection key from your application source code.
Locking Type	The level of protection for a product according to the type of Sentinel protection key supplied with the product. You set the locking type when defining a product. Locking types can be hardware-based (Sentinel HL keys) or software-based (Sentinel SL keys). When using the Cloud Licensing service, you must select one of the SL AdminMode options, such as the default HL or SL AdminMode or SL UserMode option. The following locking types are available: •HL. Use for burning licenses on physical, Sentinel HL keys (dongles). •SL UserMode. Use for activating licenses on Sentinel SL UserMode keys (software). •Does not require the installation of Sentinel Run-time Environment (RTE). • Provides limited security for products that are not locked to a device than SL Admin mode. •Provides the highest level of compatibility with future operating system updates. •SL AdminMode. Use for activating licenses on Sentinel SL AdminMode keys (software). •Requires the installation of Sentinel Run-time Environment (RTE). •Supports all license terms, including concurrency and detachable licenses. •Provides a high level of compatibility with future operating system updates. •HL or SL AdminMode. Use for either Sentinel HL keys or Sentinel SL AdminMode keys. •HL or SL AdminMode or SL UserMode. (Default) Use this locking type if the decision on which type of Sentinel protection key is to be shipped with the product is made when each order is processed. For more details, see Sentinel EMS User Guide for Sentinel LDK.
Market Group	A market group applies data access control for specific catalog elements and their entitlements. Typically, a target group of users share common characteristics, such as geographical locations or business units. For more details, see Sentinel EMS User Guide for Sentinel LDK.
Memory	Memory files let you store sensitive data in the Sentinel protection key. For example, you might want to store user data or your own customized license code. You create memory files from the Memory tab. You associate memory files when creating a product. For more details, see Sentinel EMS User Guide for Sentinel LDK.
Namespace (Batch Code)	A namespace, which is known as a "batch code" in Sentinel LDK, represents your company's unique vendor code. When you order Sentinel protection keys from Thales, you specify your namespace, which is both written to the keys before dispatch and printed on the outside of each Sentinel HL key. Your company can have one or more namespaces. The namespace for Sentinel protection keys with a demo vendor code is DEMOMA. In Sentinel EMS, a namespace also acts as a workspace, differentiating between separate storage locations. If you have multiple namespaces, the features, memory files, and products in each namespace are available only to those users who have permissions for that namespace. Users with roles that have entitlement-related permissions (such as order takers) can access these items from all namespaces. For more details, see Sentinel EMS User Guide for Sentinel LDK.
OAuth Client	An OAuth client refers to an application or service that can make requests for protected resources on behalf of the resource owner after the resource owner grants authorization. For more details, see Sentinel EMS User Guide for Sentinel LDK.
Produce and Push	"Produce and Push" generates a cloud license and pushes the license to the Thales service-hosted, cloud license manager server in a single step. You use produce and push to activate an entitlement, which generates a CL (cloud licensing) key for the relevant products. For more details, see Sentinel EMS User Guide for Sentinel LDK.
Role	A role is a set of permissions for using specific entities in Sentinel EMS. For more details, see Sentinel EMS User Guide for Sentinel LDK.
ToolBox (Sentinel LDK ToolBox)	Sentinel LDK ToolBox is a GUI application that helps software engineers use Sentinel LDK APIs and generate source code. For more details, see Sentinel LDK ToolBox User Guide.
Unlocked from Device (Product)	A product that is distributed with a license that is not locked to a specific device and can therefore be installed freely by any user on any device. Typical uses include: • Trial licenses (free for up to 90 days), which can start from the date of license generation or first use, depending on the License Model. (The Execution Count and Time From License Generation license models are not relevant for products that are not locked to a device.) •"Unlimited" products in an application for which you use Envelope to protect your intellectual property (IP). These products may or may not contain licensing restrictions. For example, you might decide to apply a Perpetual license, limit the time period in which the license can be used, use another mechanism to license the application, or not impose any licensing restrictions at all. When you create an entitlement, you can include products that are either locked to a device or unlocked from a device, but not both. For more details, see Sentinel EMS User Guide for Sentinel LDK.

Sentinel EMS 6.0 with Sentinel LDK 10.0 | Tutorial: Sentinel LDK Cloud Licensing (CL) with Sentinel EMS - User-Based Licensing
© 2009- THALES. All rights reserved. | Last updated: 15 October 2024 | Support

Tutorial: User-Based Licensing Cloud Licensing with Sentinel LDK CL Service and Sentinel EMS

The Basics

Sentinel EMS

Sentinel LDK Envelope

ToolBox and Sentinel Licensing API

Features

Products

Entitlements

Tutorial Workflow

Initial Setup, License Integration, Application Protection, and Testing

Production and License Fulfillment for a Vendor's Customers

Before You Begin

Create a Catalog

Define a Customer and Administrator User

Generate a License and Push It to the Cloud

Define an End User and Associate a Product

Set an OAuth Client

Integrate Licensing and Protection

End User Starts Using the Application / Test Your Application

Glossary

Tutorial: User-Based Licensing
Cloud Licensing with Sentinel LDK CL Service and Sentinel EMS