|
|
|
|
This page discusses how Unanet creates and uses cookies to validate client requests. Using this information, you could modify this process for the purposes of facilitating a single sign on procedure for your installation. Perhaps using an authentication server such as Kerberos (including Active Directory Server) or Radius.
Following the instructions below, build your own process for creating the cookies outside of the Unanet system -- you can effectively create your own validation process.
Note that if you do create your own validation process the various unanet properties that control password expiration and other characteristics will not be used.
Beginning with version 7.0, Unanet has built-in support for Active Directory and Single Sign-On functionality.
Areas addressed on this page include:
The user's password is not actually stored in the Unanet database. Instead, an MD5 digest of the user's username and password is stored. An MD5 digest is sort of a one-way encryption. Storing this instead of the actual password means that even someone with full access to the Unanet database cannot retrieve users' passwords.
Concatenate the username and the password. The username should have no leading or trailing white space, and should be all upper-case. The password should also have no leading or trailing white space, but the case should be preserved.
Apply the MD5 algorithm to the resulting string to produce the digest. The digest itself is always exactly 32 characters long and case-insensitive. For example, if the username is "JDOE" and the password is "twjI]O", these are concatenated to produce "JDOEtwjI]O". (Optionally, a nonce value may be appended to this string before creating the hash. This nonce value is configured with the unanet.password.nonce property.) Pushing this string through the MD5 algorithm produces the MD5 digest, "685e50636005ccf2a0bd8558b138c6c7".
Creating a new person record
Setting a person's password
Setting your own password
Logging in
A person record is created via an outside means, or you don't care if a person is created without a valid password (that is, you will later supply a valid password through an outside means).
You will not use Unanet to change a person's password.
You will not allow users to use Unanet to change their own passwords. (This option can be removed from the menu.)
You will supply an alternate means of logging in, since the Unanet login method will no longer function. (Also, if a user logs out of Unanet, they will be presented with the non-functional login screen.) This may be addressed in later versions.
You will also need to supply your own method of generating the cookie, as described below. In this case, the value stored in the person.password column in the Unanet database does not even need to be an MD5 digest. It can be anything that your outside methods can generate and understand. Or you could choose to store nothing at all, since it is not used in outside of the above mentioned cases.
The Unanet login may be bypassed entirely if you choose to generate the Unanet cookie yourself. This is useful if you want to authenticate users via some means other than the password digest that is stored in Unanet. For example you might want to authenticate against a Kerberos (including Active Directory) or Radius server. To do this you must be able to create a web page to accomplish the following:
You must create a web page that the users will access, instead of going directly to Unanet.
On this web page, you must have some way of knowing who the user is. Generally, you must do this either by ensuring that they are authenticated prior to accessing this page or providing a means for them to authenticate themselves on this page.
On this web page, you must be able to map the user to the equivalent user on Unanet. The easiest way to do this is to keep the usernames the same on your authentication server and Unanet.
On this web page, you must be able to access the Unanet database. Information about the user's roles and alternate roles will be used to create the cookie.
On this web page, you must be able to set a cookie on the client browser with an appropriate domain and path so that the client it will send it to the Unanet application upon every access.
Finally, on this web page you will probably want to redirect them to the Unanet application.
The cookie is used by Unanet on each client access to validate the user. It contains some clear text information, and an MD5 hash to validate that the information was created by Unanet. The cookie is named unanetAccess, and the value is a URL encoded, vertical bar (|) delimited set of four fields. The four fields are:
Person Key - The primary key for this user in the Unanet database.
Username - The username in the Unanet database.
Roles - A caret (^) delimited set of fields indicating the Unanet roles that the user has. A tilde (~) after a role name indicates that the user has that role as an alternate for someone. If a user has a role both directly and indirectly (as an alternate), then the role name will appear twice in this list, once without the tilde, and once with.
MD5 Digest - An MD5 digest generated from all the preceding information and a system-wide, configurable nonce value.
For example, let's take JDOE from the preceding example.
Let's say that the primary key for his record in Unanet's person table is 204. The first part of the cookie would be:
204
Next we'll add on the Username, remembering to delimit with the vertical bar:
204|JDOE
Now we need to append the user's role(s). Also assume that he is a timesheet user, an expense user, a project manager, an alternate project manager for someone, and an alternate manager. The order of these roles does not matter -- except when used to create or check the validity of the cookie's MD5 digest:
204|JDOE|projectManager^expenseUser^timesheetUser^projectManager~^manager~
Now we will add the nonce value (which is configurable with the unanet.cookie.nonce property), say "q4Z26w&3@1xya", yielding:
204|JDOE|projectManager^expenseUser^timesheetUser^projectManager~^manager~|q4Z26w&3@1xya
Running what we have so far through the MD5 digest function gives us 9ec6de647d37f331d131be1a66598d96 -- so we need to add that to the cookie (without the nonce value -- that is only used to make up the MD5 digest:
204|JDOE|projectManager^expenseUser^timesheetUser^projectManager~^manager~|9ec6de647d37f331d131be1a66598d96
Finally, URL encode this to get the final text that will go into the cookie:
204%7CJDOE%7CprojectManager%5EexpenseUser%5EtimesheetUser%5EprojectManager%7E%5Emanager%7E%7C9ec6de647d37f331d131be1a66598d96
If the cookie cannot be validated then the user will be directed to the login page.
Note: If you change the value of the unanet.password.nonce property, all existing unanet passwords will be voided as well as any credit card numbers stored in any user's person profile records.
