Introduction
elm is a web-based licensing system with a simple, full-featured JSON API for making license enforcement requests. A .NET API is available for use in .NET-based desktop and server applications.
API documentation
Web API:
Conceptual overview
Products and licenses
When licensing a software application in elm, the first step is to create a product in the elm web portal. A product is simply a representation of the software being licensed, and all licensing requests made by the software are made within the context of a product.
In order to license a product, the elm portal allows you to generate licenses (and their associated license keys) that define the limits imposed upon users of the product (end-users). elm allows a variety of limitations to be set, including, for example, the overall number of users registered ( named-user licensing), the number of installations of a product (node-locked licensing), and the number of sessions of a product that can run simultaneously (concurrent-use licensing). Limits are set independently for each license and can be changed at any time.
Each license has a license term that defines the period of time in which the license is active. If the license term has expired, all requests for access to a product will be denied. License terms cannot be changed once they are created, but a license can have any number of terms. In order to extend the lifetime of a license, simply create a new term with the new, extended end date.
Product types
When a product is created in elm, a product type must be assigned. The product type determines the supported API calls and licensing schemes.
A desktop product represents a traditional software product installed on the user's desktop.
A "Server" product represents a web-based server product, typically deployed within your customer's intranet. A server product should typically have a corresponding product of type "Web app", which represents the front-end to the server. The server part and the web app part can be separately licensed. For example, the "Server" product is typically node-locked, with a limit on the number of installations, while the corresponding web app product will place restrictions on the number of users that may login to the server, or the number of simultaenous web app sessions supported by the server.
A "Web API" product represents a web-based server product that allows your customers to make API calls. The only type of license supported by a Web API product is an unrestricted license. In other words, there are no restrictions on the number of users or installations since the web API server is typically cloud-based, and there is no concept of a user when your customer makes an API call. The only type of restriction that can be placed on a web API product is via the use of consumable tokens.
Instances
A specific installation of the product is referred to as an instance. When an instance runs for the first time, it registers itself with elm using a license key and a unique instance identity. The identity is simply a collection of name-value pairs containing values that make that instance unique to all other instances of the same product. For desktop applications, this might include hardware information such as the CPU ID and MAC addresses. For server applications it might additionally include the server's virtual directory. The .NET client API has a helper method that generates an instance identity based on the computer's hardware.
Users
An instance of a product has zero or more associated users. For desktop applications, the user of the product is typically the currently-signed-in OS user. For server applications, the "user" may be the account currently signed-in to the web site during a server call. Or, if the server does not have accounts, there may be no user at all.
Users are displayed in the elm portal using a name and email address that is specified when the user is registered.
Like instances, users are identified by a unique user identity that is a collection of name-value pairs. Again, desktop applications might include Active Directory information as the user's identity, whereas server applications might include the id of the user's account in the database. The .NET client API has a helper method that generates a unique user identity based on the currently-signed-in user's Active Directory account information.
Users must be registered against a specific instance of a product.
Sessions
In order to support concurrent-use licensing, elm also includes the ability to manage sessions. A session represents the period of time in which a specific user is using a specific instance of a product.
When a session is started, the session is automatically active for a set period of time, after which the server will consider the session ended. As a result, products are required to periodically extend a session in order to keep the license checked out. A session that has been automatically ended by the server can be extended indefinitely, but a session explicitly ended by the client cannot be extended.
Sessions are identified by a key and an extension token. The extension token is a one-time-use token used to extend the session after it has started.
Features and components
A product can contain multiple features and components.
Features are parts of a product that can be turned on or off for a given license. A typical use case for features is when you sell base and pro licenses to your software. Instead of sending separate installation media to customers who buy the different versions, you can have all your customers install one product, and turn on and off features from the elm portal depending on the edition they paid for. It is important to note though that features cannot have terms (validity periods), and restrictions separate from the license.
Components are different from features in that they can be independently termed, and restricted on top of the base license. Components can be restricted using three different models: sessions, checked-out tokens, and consumable tokens.
- Sessions restrict the number of simultaneous sessions that use the component. Even if your customer's base license is restricted based on number of named users, components can still be restricted using sessions.
- Checked-out tokens allow you to assign a token requirement for each of your components. Components of higher value can be assigned a higher number of tokens than ones of lower value. Your customers can then "rent" a pool of tokens, and whenever they use a component, the corresponding number of tokens will be checked out. When the product session is ended, the tokens will be automatically checked back in to the pool.
- Consumable tokens are similar to checked-out tokens in that you can assign different token requirements to different components. However, your customers buy a pool of tokens instead of renting them. When they use a component in a session, the corresponding number of tokens will be deducted from the pool and never checked back in.
Workflow
When implementing licensing within a software product, the following fundamental processes must be implemented:
Registration is the process of setting up a new product instance and, optionally, user of that instance in elm. When an instance and user are registered, elm will verify that the registration is allowed based on the license configuration and will set up a guid that the instance uses to identify itself with the server on future calls. If a user is also registered, the server will set up a guid for the user as well. If elm detects that an instance is attempting to register for a second time, it will return the first registration. A duplicate registration is not allowed.
Validation is the process of verifying that the current instance is allowed to run and, if there is a user, that the current user is allowed to access the product. An instance can also use validation to ensure that the instance's and user's identity (possibly based on hardware configuration or active directory information) has not changed since the instance was registered. This identity verification is designed to ensure that end-users cannot spoof a product installation or user in order to circumvent licensing restrictions.
Managing a user session is required when a product will support a concurrent-use licensing model. A product will begin a session for a specific user and instance combination and keep the session alive while the product is in use. Beginning a session is performed in conjunction with validation.
Note: Correctly implementing these workflows is critical to ensuring a tamper-proof licensing system. The .NET client APIs are designed to help reduce the amount of work needed to correctly implement these workflows and ensure a seamless licensing experience for the end-user.
License limits
The limitations that can be placed on a license are as follows:
- # of instances
- The number of instances of the product allowed to be registered.
- # of users
- The number of users allowed to register to use the product.
- # of sessions
- The number of sessions allowed to be active simultaneously.
- Users per instance
- The maximum number of users allowed to register on a single instance of a product.
- Instances per user
- The maximum number of instances a single user is allowed to register
- Sessions per user
- The maximum number of sessions a single user is allowed to have open at one time, on any number of instances
- Sessions per instance
- The maximum number of sessions a single instance is allowed to have open at one time, by any number of users
- Sessions per user per instance
- The maximum number of sessions a single user is allowed to have open on a single instance at one time
- Email activation
- A user is required to click an emailed link in order to use a newly-registered instance of a product
FAQs
Click here for a list of frequently asked questions about integrating elm into your application.