Writing a Droplets C++ User Manager
  

 

How Droplets Authentication Works
Writing the User Manager
Implementing Context
Working with External Authentication
Deploying the User Manager

The Droplets Platform supports user authentication for its applications through the use of a User Manager class (Java) or DLL (C++) that resides on the Droplets UI Server. The Droplets Platform installation includes a ready-made C++ User Manager DLL (see Deployment documentation for details), but most commercial deployments will want to write their own custom User Manager so that they can integrate the Droplets Platform into their existing authentication mechanism. This document goes over the steps necessary to write and deploy your own Droplets User Manager with C++.

For details on writing a custom User Manager in Java, see Writing a Droplets Java User Manager.

How Droplets Authentication Works

The Droplets Platform can interoperate with your network's existing authentication setup, provided that you write an appropriate User Manager, which resides on the Droplets UI Server. Droplets support industry-standard MD5 challenge/response hashing of passwords, allowing you to authenticate users without ever passing their user information over the Internet. The Droplets API also features a mechanism through which you can support authentication over multiple "contexts", e.g. email domains.

With C++-based User Managers, MD5 hash encryption is performed by two files that are shipped as a part of the Droplet Server installation at DropletSdkRoot\cpp\utilities\include, UtMd5.cpp (MD5 encryption) and UtBase64.cpp (base-64 translation).

If you do not want to allow the Droplets UI Server to have direct access to your authentication database, you can alternately use the Droplets API's UserManagerAuthenticator, which allows the UI Server to query your database with a username and password, and get an integer value back that tells it whether or not the password is valid (and if not, why). The downside is that this requires you to send an encrypted version of the password across the network from client to server.

The graph below outlines the steps involved in a Droplets authentication. We've assumed that the application requires authentication at start-up, but this authentication process can take place at any time during a Droplets session — as defined by the application's business logic.

1. When the user opens a Droplet, their client asks them for a user name (and context, if appropriate) and password. The user name (but not the password) is then sent over the network to the Droplets UI Server, along with the name of the application.

2. The Droplets UI Server passes this user name (and context, if appropriate) and application name to the User Manager (which itself resides on the UI Server).

3. The User Manager looks up the username's associated password in the database; if the user name exists, the User Manager retrieves its associated password (which may or may not already be hashed or encoded).

4. If the user name is found, the User Manager returns its associated password to the UI Server; if not, the User Manager returns null.

5. The UI Server informs the client as to how the password should be encrypted.

6. The client does one of two things, depending upon which type of User Manager you choose. Either it (1) creates an irreversible hash with the user's password, encrypts the hash, and sends it back to the server. This is the most secure method because the users password is never sent over the network; or (2) The second option performs a strong encryption of the user's password and sends that back to the server for decryption.

7. The UI Server informs the client as to whether or not the passwords match. If the passwords match, the user is allowed entry into the application GUI. If they do not match, but the user exists, the Server informs the client of this, and the client presents the user with an "incorrect password" dialog box. If the user does not exist, the client instead presents a "user name not found" dialog box.


Writing the User Manager

When developing in C++, your user manager must be a DLL that will include the following three functions:

extern "C" void * DsUmCreateUserManager2 (void)
extern "C" void DsUmDestroyUserManager (void * ptr)
extern "C" int DsUmGetPassword2 (void * userManager, const char* appName, const char* userName, const char* context, const TDsVariables* vars, char* buffer, int bufferSize)

 

The first two functions are called when you create and destroy a user manager object, respectively. The third function will be called by the Droplets UI Server whenever a user atempts authentication by entering a user name and password.


GetPassword2 Parameters

userManager: The name of the existing User Manager object.

appName: The name of the application for which the user is logging in. If you use the same authenticaiton database for all of your Droplets (i.e., all username/password pairs are the same), you can safely ignore this parameter. If not, this will be necessary to distinguish among the different sets of authentication information stored on your database.

userName: The username which the user has entered within the authentication dialog box.

context: This is used only if you are authenticating for multiple domain names, and should be left blank if you are not. If you are indeed authenticating for multiple domains, this should be the context/domain name (e.g., "vegaselvis.com").

vars: Allows you to pass certain defined variables (key/value format) about client-side context to the server, including operating system, browser type (or standalone), screen width and height and deviation from Greenwich Mean Time. For more information on these variables, see the Droplets C++ API documentation for the Application class' getVariableValue() method. In addition, any custom variables defined in the application's DRP file or the application skin's params.txt file will be available as well.

buffer: The memory space reserved to hold the password string.

bufferSize: The size of the buffer to be created for holding the password.


Return Value

The DsUmGetPassword2 function must return the correct "password data" for the user, or null if the username is invalid. In most cases, this data is NOT simply the password itself. Since the password may not be stored in cleartext on your database, the Droplets Platform permits some flexibility in the format in which your user manager returns password data. By default, the UI Server expects you to return the result of the following algorithm:

1. Construct a string by concatenating three strings: "DcDropletClient" + username + the user's correct password;
2. Compute the MD5 hash of that string;
3. Encode the result in base 64.

You can override this default encryption method by setting the registry value "AuthExpr" underneath your Droplet application's home registry key in HKEY_LOCAL_MACHINE\SOFTWARE\Droplet\DropletServer\Apps\[ApplicationName]. To create a new default that will apply to all applications that do not have a value for "AuthExpr", set "AuthExpr" under HKEY_LOCAL_MACHINE\SOFTWARE\Droplet\DropletServer\Apps\<default>.

In either event, you must set AuthExpr using a simple expression language consisting of the following primitives:

• Strings in double quotes
• The '+' operator for string concatenations
• The variable "user", which will expand to the username
• The variable "password", which will expand to the correct password for the given username
• The function md5(), which can be placed around a string expression, and which means "the base-64 encoded MD5 hash of the input string".

Some examples of AuthExpr values are as follows:

1. user + "XX" + password
The string concatenation of the username, the two-character string "XX" and the password.

2. md5(password)
The password, hashed using MD5, then encoded in base-64

3. password
The password itself, in plaintext

4. md5("DcDropletClient" + user + password)
The string concatenation of "DcDropletClient", the username and the password, all MD5 hashed and then base-64 encoded. This is the default that will be used if no AuthExpr is present in the registry.

Regardless of which algorithm you express in the AuthExpr key, the Droplets Client will apply the same algorithm to the password the user enteres. It will then compare the result to the password data that your function returned. If they match, authentication is successful.


Implementing Context

"Context" represents the context within which the user name should be interpreted. A common way to use context is with alternate domain names. For example, a Web site for the Elvis Presley fan club could offer free email with alternate domains such as "joe@youngelvis.com", "joe@vegaselvis.com" and "joe@elvislives.com", and handle all of them through the same User Manager.

When using context, the authentication dialog box which is presented at the beginning of a session contains three form entries instead of two. In addition to user name ("joe") and password ("bluesuedeshoes"), an additional drop-down box allows the user to select their context ("vegaselvis.com").

In order to implement context, you need to specify three additional functions within your DLL Interface:

  • int DsAppDoesAppHaveLoginContext(const char * name, const TDsVariables* vars, char* contextName) : Should return "true" in order to implement context. The developer who implements this function must specify the label of the context drop-down menu in the login dialog (e.g. "Domain Name:") via this function's contextName parameter.

  • int DsAppGetLoginContextListSize(const char * name, const TDsVariables* vars) : Returns the number of entries in the context drop-down menu within the login dialog window.

  • void DsAppGetLoginContextList(const char * name, const TDsVariables* vars, char* contextList): Returns the list of entries for the context drop-down menu. Must be tab-delimited (e.g. "youngelvis.com\tvegaselvis.com\telvislives.com")

Working with External Authentication

Some deployments require that the Droplets Platform authenticate users via an external application to which it does not have direct access. The Droplets Server queries this application with the username and password, and gets back a value indicating whether or not the password is valid.

In this event, you must instead use the Droplets UserManagerAuthenticator as your User Manager. The difference between UserManagerAuthenticator and UserManager2 is that UserManagerAuthenticator sends an encrypted version of the password across the network from the client to the server. The server then de-encrypts the password and passes it to the application in charge of authentication.

In order to work with external authentication, your user manager must be a DLL that will include the following three functions:

extern "C" void * DsUmCreateUserManagerAuthenticator (const char *appName, TDsUserManagerSettings *settings);
extern "C" void DsUmDestroyUserManager (void * ptr);
extern "C" int DsUmAuthenticate (void* userManager, const char* appName, const char* userName, const char* password, const char* context, const TDsVariables* vars);

The main difference between the arguments of DsUmGetPassword2 and DsUmAuthenticate is that there is no need for a buffer (and thus no buffer or bufferSize arguments), and the addition of the password argument, which passes the client's password to the external authentication.

DsUmAuthenticate returns an int because there are four possible values which can be returned to the Droplets UI Server:

  •    -2: Invalid password
  •    -1: Invalid username
  •     0: Authentication failed, but reason is unknown
  •     1: Authentication succeeds


Deploying the User Manager

Once you've built your User Manager, you're ready to deploy it on the Droplets UI Server. See our Deployment Guide for full details.

 

  Return to Droplets SDK Documentation Home