Table of Contents

• Purpose
• Usage
• Use Cases
  • Intranet web application
  • Cloud application licensed to enterprises
  • Cloud application licensed to individuals

Purpose

Note: To use the elm client web user control API, you will need to follow the same installation steps as that of the server API. Read the instructions for installations here

The web user control API is used to provide advanced control over a user's access to your web application. You can use this API for both intranet web applications and cloud-based web applications.

In the case of an intranet web application, where your server-based application is deployed in your customer's enterprise network, you should use this API in conjunction with the server control manager API.

For a cloud application, where the server instance is controlled by you as the software vendor, the user control manager API may be used independently or in conjuction with the server control manager API, depending on the type of application and your intended licensing mechanism.

The web user and server control manager APIs, as of v4.0, do not support component checkout APIs.

Usage

Authentication

A cloud-based, or intranet-based server application is expected to handle user authentication on it own. For speed and security sake, elm does not provide user authentication functionality. What elm provides is session management and control. elm allows web applications to leverage its advanced session control configuration to restrict user access to your web application.

API Calls

// From configuration:
var keyFile = PublicKeyFile.Create(WebConfigurationManager.AppSettings["PublicKey"]);

// From a resource string:
var keyFile = PublicKeyFile.Create(Resources.PublicKey);

// From an external file:
var keyFile = PublicKeyFile.ReadFrom(filePath);

Before you can make API calls, you need to create a UserControlManager:

var controlManager = new UserControlManager(
    <ProductId>,
    <InstanceId>, 
    keyFile,
    controlStrategy: <strategyObject>,
    savedState: <stateObject>);

How you specify InstanceId and savedState arguments depends on your use case. Three different use cases are described in the next section.

Once you have a controlManager object, you call the RegisterAsync method when a new user signs up:

var result = await controlManager.RegisterAsync(userInfo, userIdentity);
if (!result.Success) {
    // Not registered, deny access or try again.
}

Once registration succeeds, or when an existing user signs in, call the ValidateSessionAsync method to verify that the user is authorized to use the application and start a new session. Needless to say, you should only call the ValidateSessionAsync method after user authentication succeeds on your server.

var validity = await controlManager.ValidateSessionAsync(userIdentity);
if (validity.IsValid) {
    // Allow access
}
else {
    // Deny access
}

Use Cases

In a traditional web application, such as a banking portal, the bank does not restrict the number of devices from which a user accesses the portal, or how many simultaneous sessions they might have open. elm is used when the application vendor wants to restrict such parameters. For example, a web-based service licensed to enterprise users should protect against customers who pay for one user seat and then share the user name and password between multiple employees. elm allows your to enforce such restrictions without you having to track and manage user count and sessions yourself.

Intranet web application

For intranet-deployed web applications, the UserControlManager must be used in conjuntion with the server control manager API. The InstanceId passed to the UserControlManager constrcutor should match the instance identity obtained from the ServerControlManager calls. This will uniquely identify the license on the elm server and use the corresponding licensing restrictions.

For this use case, it is recommended that the server maintain a persistent instance of the control managers rather than create control managers when needed and disposing them when the calls are completed.

Cloud application licensed to enterprises

elm identifies the license associated with a user using the InstanceId passed in to the UserControlManager constructor. However, cloud applications have only one instance by definition. Therefore, a ServerControlManager must be used to obtain this InstanceId before a UserControlManager is created.

One mechanism to do this is to map the user in your application database to the corresponding license in elm. When a user signs in, you can use the ServerControlManager API to obtain the InstanceId and use that InstanceId in the UserControlManager API calls.

elm currently does not expose any API calls to create licenses when a new enterprise user signs up. This support is planned in the product roadmap.

Cloud application licensed to individuals

The use of elm for this scenario has limited benefits since it is impractical to create and manage licenses for each individual who signs up for a public web application. However, it still works when the number of users is expected to be small and when elm's advanced session control strategies are needed.

Where the benefits of using elm's session conrtol strategies outweigh the cost of developing those strategies in your own application, it is recommended that the server be licensed with only one license and the instance id of the server be hardcoded in the call to the UserControlManager constructor. You will need to perform a one-time registration call to the elm server to obtain an instance id.