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.

Authentication

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:

sses_start();

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
PDO	PDO
LDAP	ldap
OpenID	curl
SSH2	ssh2
DuoSec