Authentication is a way to detect which user is connected. Authorization is authentication extended by a role defining what the user is allowed to do. For authentication the user has to login with its user name and a password. By entering a valid combination tk_self generates a session id and sends this id to the client by means of a cookie. This cookie is different from the one used for anonymous sessions.
Authentication only works with an activated database. When a client connects, tk_self checks for an authentication cookie and, if this cookie is found, the database is accessed for a corresponding entry with information about the user, the role and a timestamp of the last request. If the time between the request and the previous one exceeds the timeout defined by TK_SELF_AUTHORIZATION_TIMEOUT (in seconds), the request is marked as unauthenticated and the cookie will be deleted. In this case the user has to login again.
In tk_self any authenticated user is assigned to a role, so it's authorization. To activate authorization, set TK_SELF_AUTHORIZATION_USE in the /conf/tk_settings.php file to true. Because at this time there is no user registered in the database, TK_SELF_ACTIVATE_ADMIN can be set to true. Now you can login as user admin with password admin. Be shure to set this value to false in production mode!
// for authorization use: define ("TK_SELF_AUTHORIZATION_USE", true); // set true to activate define ("TK_SELF_AUTHORIZATION_TIMEOUT", 600); // timeout for active // authorized sessions define ("TK_SELF_ACTIVATE_ADMIN", false); // for setup only define ("TK_SELF_ADMIN_USERNAME", "admin"); define ("TK_SELF_ADMIN_PASSWORD", "admin"); define ("TK_SELF_ADMIN_ROLE", "admin"); // reserved role for admin user. // available user roles: $TK_SELF_USER_ROLES = "user, admin"; define ("TK_SELF_LOGIN_TPL", "tk_login.tpl"); // template file to login
To enable the login dialog activate the admin pattern in the /conf/tk_urlpatterns.php file
$TK_SELF_URL_PATTERNS = array( // activate the admin-urls, if in tk_settings.php // TK_SELF_AUTHORIZATION_USE is set to true: "^admin/$" => "tk_admin.tk_self_admin", "^admin/(?P<action>[^/]*)$" => "tk_admin.tk_self_admin", "^admin/(?P<action>[^/]*)/(?P<user>[^/]*)$" => "tk_admin.tk_self_admin", ... );
and enter /admin into the browser address field to get the following login-form. Without any user in the database you can't login, but with TK_SELF_ACTIVATE_ADMIN set to true, the hard-coded User: "admin", Password: "admin" combination will allow to login (enter "admin" without the quotation marks).
All user data and authentication session data are stored in a database which have to be set up before use. For the user data and authentication information two independent (and therefore not normalized) relations are used:
CREATE TABLE tk_auth_users ( name text not null, pw text not null, role text, primary key (name) ); CREATE TABLE tk_auth_sids ( name text, role text, sid text, timestamp integer, primary key (sid) );
The above SQL code is for PostgreSQL (in recent versions text is as fast as varchar but more flexible, so you don't need varchar anymore.) If you only have some few users, the primary keys are not really necessary.
These two tables have to be created manually because tk_self has no tools for database administration. The authentication mechanism is implentented by using the PHP-PDO database extension.
When the relations are defined in the database, a valid login will display an initially empty list of registered users. A click on "Add user" will display a form to enter new user data: a user name that have to be unique, a password for this user, and a role the user belongs to. The list of available roles is defined in $TK_SELF_USER_ROLES in the /conf/settings.php file (see above) as a comma-separated list. Feel free to add additional roles.
Once a user is added, he/she/it is displayed in the user list with the choosen role. The role and the password can be modified and the user can be deleted from the list, but it is not possible to modify or delete the user which is actual logged in.
The first user to add should be one with administration rights. The second step should be to set TK_SELF_ACTIVATE_ADMIN in the /conf/tk_settings.php file to false.
From now on you can login with the new created administration account and the admin-admin shortcut is disabled; users without adminstration rights have no access to the user administration page.
The user data and passwords are stored in the database, where the passwords are md5 coded, so you can not read them as clear text by direkt database access. If a user forgot the password, a new one can be created. Just do this by enter the new one in the "change password" field of the user list and click "modify".
md5 may not be a strong hash-value anymore, but it is good enough to hide the passwords from other people which have the rights to access the database. If intruders are able to read the md5 password-hashs then it is too late: they are already in. To be safe use the https-scheme for at least the password transmissions (see also "Security" further down on this page).
From the view-functions you have access to the global $TK_SELF_AUTH object and can call the following methods to decide how a user-related request should be handled:
$TK_SELF_AUTH->is_admin();
$TK_SELF_AUTH->get_user();
$TK_SELF_AUTH->get_role();
$TK_SELF_AUTH->get_sid();
$TK_SELF_AUTH->is_logged_in();
$TK_SELF_AUTH->get_auth_info();
If a template should be rendered for authenticated users only, inside the view-function you can make a check like this:
global $TK_SELF_AUTH; if ($TK_SELF_AUTH->is_logged_in()) { // render requested content } else { $TK_SELF_AUTH->show_login_form(); }
Another way to give the user the ability to login is to create a login-link. This can be done by appending the parameter login=1 to the URL. For logout change the parameter name to logout:
<a href="?login=1">login</a> <a href="?logout=1">logout</a>
The above code fragment links back to the given page after a successfull login and link to the given page for logout.
For authorization the program logic can depend on the return value from calling TK_SELF_AUTH->get_role();.
So far username and password have been transmitted as clear text over the web. This may be ok for some private uses but is really far away from being secure! The best way to protect data from sniffering is to use SSL by means of apache:
<a href="https://www.example.com/?login=1">login</a> <a href="http://www.example.com/?logout=1">logout</a>
To switch the protocol the links have to be full qualified and apache has to be configured for SSL support. Refer to the apache SSL/TLS encryption documentation. After login you should stay in SSL mode until a logout request occurs.
To use a custom login form copy the file /tmpl/tkself/tk_login.tpl, name it i.e. my_login.tpl, and adapt it to your need. To be independent from any template engine the login form is rendered as a PHP file (see PHP-templates). Then change the definition of TK_SELF_LOGIN_TPL in the /conf/settings.php file to the new login form name:
define ("TK_SELF_LOGIN_TPL", "tk_login.tpl"); // template file to login. // Adapt or change it. define ("TK_SELF_LOGIN_TE", "tk_self"); // template-engine to render // the login form.
To be more flexible it is possible to change the template engine to render the login file. The preset value of "tk_self" requires the login-template to be in the /tmpl/tkself directory and renders the file as a PHP-template. By changing the TK_SELF_LOGIN_TE definition to TK_SELF_TE_PHP, TK_SELF_TE_PHPTAL or TK_SELF_TE_SMARTY tk_self will search the corresponding template-directories (/tmpl/php/ etc.) for the template file with the name defined in TK_SELF_LOGIN_TPL, and will render it with the according template engine.
Another way is to leave the TK_SELF_LOGIN_TE definition empty:
define ("TK_SELF_LOGIN_TE", ""); // template-engine to render // the login form.
tk_self will then use the template engine defined by TK_SELF_TEMPLATE_ENGINE.