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:
<![CDATA[
<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:
<![CDATA[
<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:
<![CDATA[
<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
http://pajhome.org.uk/crypt/md5/ (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.
