FAQ

Index

Where do I find the library's documentation?
installCheck.php warns me about using AJAX. Can't I use AJAX with uLogin?
How do I detect if a session has been invalidated for a security reason?
My sessions are sometimes dropped for seemingly no reason. How do I debug it?
My sessions are sometimes dropped because of "User agent mismatch". What do I do?
My sessions do not work, it seems that cookies do not get set. I test my website on the local machine.
How do I add additional user fields to the PDO backend, like name, e-mail etc.?
What is the difference between volatile and persistent nonces?
How do I integrate a CAPTCHA?
How do I make some session data survive session invalidations?
How do I elevate privileges of a logged in user?
Do I need a SQL database to use uLogin?
I want to use e-mail addresses instead of usernames to sign in users. How do I do that?
How do I implement two-factor authentication?
I get a 500 Internal Server Error.
How do I add support for authentication backends not yet supported by uLogin?

Where do I find the library's documentation?

First, start by reading the Usage page and this FAQ. These should cover the general usage and more. If you are interested in each of the configuration options and public functions, look in the sources. Each configuration variable and function is documented, describing their effects, purpose, arguments and return values etc.

installCheck.php warns me about using AJAX. Can't I use AJAX with uLogin?

Sure you can! That warning simply means that you need to pay a bit more attention to your AJAX techniques than simply throwing requests at the server. For example, if you do not initiate multiple requests concurrently, you are always safe. If you do not use UL_PREVENT_REPLAY, you can even issue concurrent requests, as long as they do not write session data. Or, of course, you can just disable all offending features, in which case you have traded security for ease of programming.

How do I detect if a session has been invalidated for a security reason?

So you want to tell a new session from a security event apart? After a session has been started using sses_start() you can use sses_invalidated() to query if the previous session was continued. This function will normally return FALSE, but TRUE if the previous session has been invalidated because of a possible hijacking attempt or if the session idle timeout has expired. If it returns TRUE, data in the old session has been deleted and is not available anymore, except for $_SESSION['nonsensitive'].

My sessions are sometimes dropped for seemingly no reason. How do I debug it?

uLogin includes a debug feature that allows you to trace events that happen during session management. To use it:

Set UL_DEBUG to TRUE.
Call ulLog::ShowDebugConsole(); in a place on your page where it is valid to insert a piece of javascript, for example in HEAD.

Now when you load your page, a popup window will open describing what happened to your session. If it got invalidated, it will also tell you the reason.

My sessions are sometimes dropped because of "User agent mismatch". What do I do?

Make sure that you include a DOCTYPE on every page, and make sure that you consistently use the same DOCTYPE everywhere.

My sessions do not work, it seems that cookies do not get set. I test my website on the local machine.

Set UL_DOMAIN to "localhost". Do not forget to update UL_DOMAIN to its real value when you deploy your website.

How do I add additional user fields to the PDO backend, like name, e-mail etc.?

There are two ways to go about this:

Create a second table with your required user fields, and associate user fields with login data based on the user id (uid), which is the id field in the logins table. This is the recommended solution for multiple reasons: First, if you update uLogin to a newer version in the future, you will not have to change your code to stay compatible. Second, this approach clearly separates the authentication table from the rest of your data, meaning you can use a database user in the rest of your web application that does not require access to logins. So if your web application is ever breached, the attacker still won't be able to get a list of the authentication data.
A second solution, much inferior by the way, would be to create a new database backend to uLogin to fit your needs. Refer to the question in the FAQ asking about custom backends.

What is the difference between volatile and persistent nonces?

Volatile nonces are stored in session variables and are only valid as long as the current session is alive or until the nonce expires.
Persistent nonces are stored in a database table and stay valid even if the user logs out or the session ends. They can, of course, also expire.
When creating a nonce, you select between volatile and persistent by the boolean $persistent parameter to Nonce::Create, which defaults to volatile (false). You should create volatile nonces whenever you can, but persistent nonces are useful if the nonce needs to survive sessions or a browser close, like for e-mail activations, remember-me function and so on.

How do I integrate a CAPTCHA?

Simply create a nonce with the value of the text of the CAPTCHA. Upon verification check it as you would any other nonce.

How do I make some session data survive session invalidations?

If uLogin thinks that there might have been an attack or breach on the current session, it will delete all data in the session to protect the legitim user. This would normally make it impossible to, for example, store the previous URL before invalidating the session, so that after a re-login the user can continue where he left off. To support such scenarios, uLogin will leave the contents of $_SESSION["nonsensitive"] alone and will not delete that variable. You can store anything you want there, but as the name suggests you better make sure that you only store nonsensitive data there to prevent information leak in case of an attack on the session.

How do I elevate privileges of a logged in user?

The typical use case would be that a user is already logged in, but is about to perform some action that requires elevated privileges, such as changing password, e-mail or transferring 1M dollars. In this case an application should re-authenticate the user before the operation, even though the user is already logged in. For this, simply use uLogin::Login just as if the user was about to log in normally. The system will re-authenticate the user without logging him/her out, and the boolean return value will tell you if the authentication was successfull.

Do I need a SQL database to use uLogin?

No, even though it is highly recommended, it is not strictly needed. Note however, that uLogin uses a database for user- and ip-blocks, persistent nonces, logs and secure session data storage, which means you will need to deactivate these features in the configuration files.

I want to use e-mail addresses instead of usernames to sign in users. How do I do that?

No problem. uLogin mostly authenticates users based on two text strings, where in "uLogin-terminology" one is called the username and the other the password. What uLogin calls the username however, need not necessarily be the "nickname" in your web application. It can be an e-mail address or anything else you desire.

How do I implement two-factor authentication?

Because the authentication backends of uLogin can be selected at runtime, it is easy to implement a two-factor authentication system. Simply create a login page that authenticates using a password, and if that login succeeds, redirect the user to a second login page where you authenticate against a second factor. Alternatively. you can also construct a second instance of uLogin with the second backend on the same page, performing two authentications in one request. uLogin comes with a backend for Duo Security to use as a second factor authenticator. The uLogin download provides a working example for two-factor authentication.

I get a 500 Internal Server Error.

There is most probably something wrong with your setup. Please check your server logs which will contain a more detailed explanation and reason for the 500 error. As an example, if you are running Apache2 on Debian, you'll need to look in /var/log/apache2/error.log.

How do I add support for authentication backends not yet supported by uLogin?

Choose unique directory and class names for your backend and create them. For example, create ulogin/my_directory and ulogin/my_directory/MyLoginBackend.inc.php.
Using include.inc.php from an existing backend as a template create a new include.inc.php file in your new directory. This file should define and register an autoload function with unique name (eg. ulogin_mybackend_autoload()) which maps your new classname to the full absolute file path it is defined in.
In ulogin/my_directory/MyLoginBackend.inc.php override the LoginBackend class defined in ulogin/LoginBackend.inc.php.
Finally, set UL_AUTH_BACKEND to the name of your new class to make it the default backend.
If you have created a general purpose backend that could be useful to other people too, please consider donating it to the project so that others can make use of it too.

uLogin PHP Authentication Library

Index