Writing a Droplets Java 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 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.
For
details on writing a custom User Manager in C++, see Writing
a Droplets C++ User Manager.
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 Java-based User Managers, this encryption is performed by (1) your JDK's MessageDigest class, getInstance() method; and (2) a base 64 translation file provided with your Droplets SDK. In the Windows version of the Droplets Platform, this file is located at dropletsdkroot\java\examples\usermanagerfixture\src\com\droplets\usermanagerfixture. In the Solaris version it is located at $DROPLETS_HOME/examples/usermanagerfixture/com/droplets/usermanagerfixture. Also in this directory is a sample User Manager file, UserManagerFixture.java, which shows you how to use the JDK's Message Digest class and Droplets' base64.java file for your User Manager encryption.
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.
When developing in Java, your user manager must be a Java class that implements the com.droplets.api.UserManager2 interface. This interface defines the following function:
getPassword2(java.lang.String appName, java.lang.String userName, java.lang.String context, VariableMap connectionVariables)
This
function will be called by the Droplets UI Server whenever a user attempts
authentication by entering a user name and password.
In
addition, your class must implement a default (no-argument) constructor.
This will be used by the Droplets UI Server to construct objects of
your class.
Note that you should not assume anything about the lifecycle and reuse of objects of your UserManager class. In particular, the Droplet Server may create new ones and discard old ones at any time.
Parameters
appName: The name of the application which the user is requesting.
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").
connectionVariables:
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
Java 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.
Return Value
The getPassword2 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 when using the Windows version of the Droplets Server 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-643. password
The password itself, in plaintext4. 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.
Refer
to the sample User Manager file that is included in your Droplets SDK
at dropletsdkx.x/java/examples/UserManagerFixture
for further details on creating a User Manager implementation.
"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 implement three additional methods within the ApplicationFactory class:
- public
boolean hasLoginContext(VariableMap vMap):
Should return "true"
in order to implement context
- public
String getLoginContextName(VariableMap vMap):
Returns the text label for the context drop-down menu (e.g. "Domain
Name")
- public String getLoginContext(VariableMap vMap): 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.
When developing in Java, your user manager must be a Java class that implements the com.droplets.api.UserManagerAuthenticator interface. This interface defines the following function:
The main difference between the arguments of the UserManager interface's getPassword2() method and the UserManagerAuthenticator's authenticate() method is the additional password argument, which passes the decrypted client password to the external authentication.
The authenticate() method returns an int because there are four possible values which can be returned to the Droplets UI Server:
-1: Invalid username
0: Authentication failed, but reason is unknown
Once you've built your Java User Manager with a Java compiler, you're ready to deploy it on the Droplets UI Server. See our Deployment Guide for full details.
Return to Droplets SDK Documentation Home