uLogin PHP Authentication Library

First-time Installation

  1. Download the uLogin files from the Download page. Place the contents of the downloaded archive on your webserver in a directory where the contents of the "ulogin" directory can be easily included. It is preferable to place said contents outside of the webroot and make sure they can only be read by the appropriate user.
  2. Using the SQL statements in the db-init directory, create your database tables. When importing in phpMyAdmin, select the ANSI dialect of SQL. To make the best use of the security featurs of uLogin, you will need an SQL database even if data for user authentication is stored elsewhere (eg. in LDAP). It is easy to use a non-SQL database for authentication, but you will need an SQL-database to enable all features.
  3. Configure uLogin using the configuration files.
    • General configuration is done by editing config/main.inc.php. Each option is described in the file and is provided a good default. However, YOU HAVE TO at least change these options:
      *To generate strong keys for the options marked above, you can use installCheck.php which outputs a few random strings at the end of its page.

    • Edit and customize config/pdo.inc.php to enable all features.
    • If you set UL_AUTH_BACKEND in config/main.inc.php to something different then the pdo backend, edit the corresponding config file of the backend to enable user authentication.
  4. Some configuration variables contain sensitive information that should be kept secret. Make sure to protect these files from unauthorized access. Do not make them world-readable nor writeable by the webserver. If possible, place them outside the docroot of your webserver.
  5. uLogin by default is set up to only allow encrypted connections. At this point make sure that SSL is correctly configured on your server, or disable UL_HTTPS in config/main.inc.php.
  6. Edit installCheck.php and ensure that it includes uLogin's configuration and sources (2 includes in total) from the correct paths where you've installed them. Then call installCheck.php in your browser to test your installation. If something is wrong, repeat the previous steps until this page returns no errors and preferably no warnings. Warnings may stay but you should review them to make sure that they pose no problems.
  7. Install a cronjob to periodically clean up the database tables. A script that you can run is provided in cron/cleanup.php. If you have logging in uLogin enabled (which is the default setting), it is highly recommended to install a cronjob to keep your log within limits.
  8. Refer to the provided example.php to see uLogin in action and learn about its API's usage.
  9. When your website is ready to go online, delete installCheck.php and make sure UL_DEBUG is disabled in config/main.inc.php.

Installation for OpenID

OpenID support requires external code. To finish installation for OpenID, visit the LightOpenID website, download its distribution and place the openid.php in their archive into the openid/lightopenid/ folder.

Installation for Duo Security

Duo Security, in combination with other backends in uLogin, enables you to implement real two-factor authentication. Follow these steps to set up DuoSec validation:

To get two-factor authentication you should not use DuoSec alone. Pre-validate your users using another uLogin backend first and if that authentication succeeds, proceed with DuoSec. The download provides a working example for two-factor authentication.

Setting up your source for uLogin

To enable multi-site setups, uLogin's configuration and sources are separated and need to be included separately on each page that uses the library. This allows a single library instance that can be included multiple times in different projects, where each project includes a different configuration. To use uLogin on a webpage:

  1. Make sure that UL_INC_DIR is set correctly in config/main.inc.php, pointing to the directory that has the *.inc-php source files.
  2. Each project that uses uLogin needs its own database tables. You can initialize a new database using the files in the init-db directory found in the distribution.
  3. Include the configuration before the sources. For example: require_once('path_to_config/all.inc.php');.
  4. Include the main source file after the config. For example: require_once('path_to_ulogin/main.inc.php');.

Secure sessions

Your basic entry point for user authentication will be the uLogin class provided by the library. But logging in a user is not enough to provide security. One also needs to make sure that the credentials of a logged-in user cannot be stolen or misused. This calls for a way to make user sessions more secure than the default PHP implementation. Luckily, uLogin provides this secured session functionality in the form of a drop-in replacement.

After including uLogin at the beginning of your PHP script, all you have to do to make use of secured sessions is to replace the standard PHP session_* function calls. All the important session-related PHP functions have equivalent counterparts in uLogin, with the same functionality and similar naming. So all you have to do is a simple string replace and you do not have to rearrange or restructure your existing code.

session_start becomes sses_start
session_destroy becomes sses_destroy
session_regenerate_id becomes sses_regenerate_id
session_write_close becomes sses_write_close
The rest of the function calls stay the same.

By simply replacing the function calls as mentioned above, you already gain protection against most of the session-related security features. To further improve protection on shared hosts where all session data is often stored in a common world-readable location, uLogin by default stores your session data in a database table. This also lets your website be used in load-balancing and other distributed situations, provided that the database server is accessed over the network. Database-based session storage is already set up for use if you've followed the Installation instructions, so there is no need to do anything to make use of this. However, should you decide to "downgrade" to the standard PHP session storage, edit UL_SESSION_BACKEND as documented in config/main.inc.php.


To perform user authentication you use instances of the uLogin class. The constructor accepts three optional arguments, in the order: a callback function handle that will be called when an authentication process successfully finishes, a callback function handle that will be called when an authentication process fails, and a backend instance. All arguments are optional, but supplying the two callbacks is highly recommended to transparently work with all kinds of backends. If a backend (3rd argument) is not specified in the constructor, the default will be taken from the UL_AUTH_BACKEND configuration option.

To start the user authentication process, you need to make a call to uLogin::Authenticate($username, $password).

Note that we talk about an authentication process. The reason is that the actual authentication might be a complex series of events, possibly involving multiple end-user browser requests. This means that some backends, when uLogin::Authenticate is called, redirect the user to an external page. When authentication finishes, the user is returned to the same page where uLogin::Authenticate was first called.

So you start the authentication process by calling uLogin::Authenticate, which might not return (in the case of a redirect). How do you tell the end of authentication and its result? You do it by (1) supplying the two callbacks to the uLogin constructor and (2) by checking for being logged in between the constructor and uLogin::Authenticate. Here is some pseudo-code for how a backend-ignorant uLogin webpage might look like:


function loginSuccessful($uid,$pwd,$ulogin) {
	// mark the user as logged in.
	$_SESSION['loggedIn'] = true;
function loginFailed($uid,$pwd,$ulogin) {
	// show error or something

$ul = new uLogin('loginSuccessful', 'loginFailed');

if (@$_SESSION['loggedIn']===true) {
	// show protected content
} else {
	$ul->Authenticate($user, $password);

For a fully functional, working example please see the demo attached in the uLogin download.

Besides the method described above there are also other possiblities to structure code written for uLogin, like checking the return value of uLogin::Authenticate (which depending on the backend might not be possible), or checking the result of the authentication process using uLogin::AuthResult and uLogin::IsAuthSuccess(). However, these methods should be secondary and are not recommended unless you have a good reason to use them.

Backend property matrix

Backend Required PHP modules Authenticate Create or remove Password change Store profile User blocks Remember-me Redirects user Uid != Usern. Last logon
LDAP ldap
OpenID curl
SSH2 ssh2

Copyright (c) 2011-2012, Karoly Pados

Kindly hosted by