Beesnest - Personal Application Server

Home Documents Downloads/Code About Contact Me

Beesnest Login System

Most of the special services from the Beesnest system are available just after the user is logged in. Just then the system remembers the last "state" of the user, and the objects she created.

Beesnest has two built-in ways to log in a user. One is the standard HTTP Digest Access Authentication (I will call it DAA), it is documented in RFC 2617. The other is a built-in login process that works with HTML pages (and I will call it the built-in method). Whatever method you use, there are two things you need to set in the configuration file, in order to create a login protected page. You need to set a Group that will hold the users you want to be able to see this file. And you need to let the server know this file is just for this group.

Setting Groups

Groups are groups of users that have access to the same resources. A user can be in more then one Group. To create a Group you need to write all the users of this group under Login-Manager->Groups->My-Group (when My-Group is the group you create). In the configuration file it will look like: <Login-Manager> <Groups> <My-Group> user1 otheruser admin ... More users here ... </My-Group> ... More groups here ... </Groups> ... Other Login Manager configuration here ... </Login-Manager> A group can hold other groups or users (but not both). All the users that are somewhere under a group will have access to pages protected by this group. For example if you set: <Login-Manager> <Groups> <My-Group> <Not-To-Be-Used> user1 otheruser </Not-To-Be-Used> <Admin> admin </Admin> </My-Group> <Groups> <Login-Manager> admin will have access to all the pages protected under My-Group, but user1 will not be able to get pages protected under Admin.

Setting protected files and folders

To set a file or folder as protected you need to bind it to a group. Then only users of this group will be able to get this file (or any file under that folder). To specify a file or folder you need to write it's entire path from the host root. Dot (.) symbols the host root, so to describe a file you should write something like "./my-folder/my-file.html" and a folder will be "./my-folder". "." will protects all the files under this host. The names of files and folder are ALWAYS in lower case letters. The name of the group you want to assign to a file/folder will be written in the configuration file under Login-Manager->Access->Default-Host->./my-folder/my-file.html. Default-Host can be replaced by any other host name you have. An entry in the configuration file will look like: <Login-Manager> <Access> <Default-Host> <./folder/file.shtml> MyGroup </./folder/file.shtml> <./the-entire-folder> OtherGroup </./the-entire-folder> ... Other file or folders for this host here ... </Default-Host> <Other-Host> ... Protected files and folders for Other-Host here ... </Other-Host> ... Other hosts here ... </Access> ... Other Login Manager configuration here ... </Login-Manager>

Digest Access Authentication

To fully understand how Digest Access Authentication works you need to read RFC 2617. There is partly but more "user friendly" explanation at Wikipedia.
In short, DAA is working on the principle of challenge-response. The server sends a "question" to the client. The client can answer this "question" correctly just if it knows the user password. After login, every time the client requests a protected page, it needs to send an appropriate response. If it does not know the response, it will get a new challenge.
There are two important configuration parameters for DAA, Stale and Expire. Stale is the time in seconds that a challenge can be answered. A client can use the same challenge more then once, for different pages. After a Stale period of time, from the initiate of the challenge is passed, the client will get a new challenge. The client, most likely will not prompt the user for a password again. It will use the same password to generate the response to the new challenge. Expire is the time in seconds for an un-answered challenge to expire. If the user does answer the challenge after the Stale period of time, but before the Expire period, the server will send a new challenge, but the client (browser) will not prompt the user for the password again. If the Expire period of time passed, the client will ask again for the password. Even when the Expire time passed, from the server point of view, the user is still logged in. A user is logged out just when he explicitly asked to be logged out.
DAA is safe (as far as login goes) also without SSL encryption.

Built-in Method

The built-in method uses HTML login page to pass the exact same challenge as in DAA. The main different is that here after the first log in, the user keeps his logged in status by getting and returning a one-time random code. This random code is changed in every request for a new page. Once the user "lost" her random code, it will be taken to the login page again. Also here, from the server point of view, the user is logged out just when he explicitly asked to log out. Losing the random code does not log out the user, it just get the server to ask again for the password.
For the Built-in login method there is one important configuration parameter Old-Code-Life. This is the time an old "one-time" random code can still be used (in seconds). This parameter come to solve the problem of browser that asks simultaneity for more then one protected file (Like in page with HTML frames). The first request will have the correct code, but the rest will still use the same code, that has already expired. The server can consider requests, from the same client, with an old code as OK for a period of time. In this case the server will not change again the random code, but will keep the current one. Note that the server remembers just one code back. Sending older codes will not work. Setting Old-Code-Life for a number that is more then zero does compromise somewhat the security of the server. If you do not need it, set it to zero or drop this field altogether.
The built-in login method is safe just if you use SSL to encrypt your pages, as the one-time random code is sent as clear text!
Since I do not yet added SSL to Beesnest (I'm going to do it, but not in the near future), use this method just if the protection of your pages is not critical.

If you use the built-in method, you will need to create your own login page, use SSI (or any script language) on the server side, and Javascript to hash your values on the client side. Don't worry I wrote it already.
Before the server executes the login file it, looks like this
Note that I use md5.js from (thanks Paul Johnston).

How to let Beesnest know which method you use?

If you use the built-in method, set the login page in the configuration files, under Login-Manager->Login-Page. If you use DAA, just live this entry empty. There is also Login-Manager->Denied-Page entry. Put there the file you want a user to see if he cannot get a protected page. Both settings are for all of the hosts, and relative to the host root.

How To Log out?

With both methods, in order to log out just send to the server the variable BN_Logout with value yes.
For example: http://localhost/index.html?BN_Logout=yes

Note: With DAA, if this page will not be a protected page, the user will be logged out from Beesnest, but the browser will still see this user as logged in.

The built-in login system uses many special request variables. For more information see Beesnest Special Variables.

Home Documents Downloads/Code About Contact Me