Solar Framework for PHP 5

7.3. Authentication Processing
Prev	Chapter 7. User Authentication, Roles, and Access Control	Next

7.3. Authentication Processing

Jon Elofson

In most other frameworks, you have to create your own page controller to deal with authentication processing. In Solar, this is not the case; instead, the logic for processing login and logout requests is encapsulated into the Solar_Auth_Adapter class. After you configure an adapter so that it knows how to recognize login and logout attempts, the adapter will intercept incoming requests and handle the process automatically.

	Note
	If you want to build a separate authentication controller for some reason, you can, but usually it's not necessary.

7.3.1. Adapters

Solar provides different adapters allowing several methods of authentication. The current adapters shipped with Solar are as follows:

Solar_Auth_Adapter_Htpasswd - Authenticate against a file generated by htpasswd
Solar_Auth_Adapter_Ini - Authenticate against .ini style files
Solar_Auth_Adapter_Ldap - Authenticate against an LDAP server
Solar_Auth_Adapter_None - Authenticate against nothing; defaults all authentication to "failed"
Solar_Auth_Adapter_Post - Authenticate via simple HTTP POST request-and-reply
Solar_Auth_Adapter_Sql - Authenticate against an SQL database table
Solar_Auth_Adapter_Typekey - Authentication adapter for TypeKey

	Note
	Note that these adapters are read-only. They do not create or manage user accounts for you, they only compare the incoming user credentials to the stored credentials.

Solar uses a Solar_Auth factory to create the adapter instance, so you need to configure the factory to create the kind of adapter you want to use for authentication. You can do so in the config file like this:

<?php
$config['Solar_Auth'] = array(
    'adapter'    => 'Solar_Auth_Adapter_Sql',
);

7.3.2. General Adapter Configuration

Now that we have told the factory what adapter to create, we need to configure the adapter itself. All the adapters have the same underlying config settings, although each adapter also has some additional settings specific to itself.

The following are the common underlying config settings for authentication adapters:

expire: (int) The lifetime, in seconds, that an authentication should last. After this period, the user will be forcibly logged out and will have to log in again. Zero is forever. Default is 14400 (4 hours). If this value is greater than the non-zero PHP ini setting for `session.cookie_lifetime`, it will throw an exception.
idle: (int) The maximum allowed idle time in seconds. If the user is idle for longer than this, he will be logged out automatically and will have to log in again. Zero is forever. Default is 1440 (24 minutes). If this value is greater than the the PHP ini setting for `session.gc_maxlifetime`, it will throw an exception.
source: (string) The source array for auth credentials, 'get' (via the for $_GET request vars) or 'post' (via the $_POST request vars). Default is 'post'.
source_handle: (string) Username key in the auth credential source array, default 'handle'.
source_passwd: (string) Password key in the auth credential source array, default 'passwd'.
source_redirect: (string) Element key in the credential array source to indicate where to redirect on successful login or logout, default 'redirect'.
source_process: (string) Element key in the credential array source to indicate how to process the request, default 'process'.
process_login: (string) The source_process element value indicating a login request; default is the 'PROCESS_LOGIN' locale key value, which is 'login'.
process_logout: (string) The source_process element value indicating a logout request; default is the 'PROCESS_LOGOUT' locale key value, which is 'logout'.
login_callback: (callback) A callback to execute as part of the login process, whether or not login was successful.
logout_callback: (callback) A callback to execute as part of the logout process.

Based on the above default settings, we can discern the following:

The adapter will process a login request whenever it sees $_POST['process'] == 'login'. It will use the value $_POST['handle'] as the username, and the value of $_POST['passwd'] as the plaintext password, when it checks the adapter-specific credential store.
The adapter will process a logout request whenever it sees $_POST['process'] == 'logout'.
After a successful login or logout, the adapter will look at the value of $_POST['redirect'] and, if not empty, will issue a redirect to that URI.

7.3.3. Adapter-Specific Configuration

In addition to the common configuration settings above, each adapter has config settings specific to its credential storage backend.

In the above example, we used a Solar_Auth_Adapter_Sql adapter. You can see the combined set of all config options here, Let's look at a few of adapter-specific settings:

sql: (dependency) A Solar_Sql dependency injection. This is what gives the adapter a connection to the SQL database. Default is 'sql', meaning that it will look for a registry entry named sql.
table: (string) The name of the database table with handles (usernames) and passwords. Default is 'members'.
handle_col: (string) The column in the table for handles (usernames). Default is 'handle'.
passwd_col: (string) The column in the table for hashed passwords. Default is 'passwd'.
hash_algo: (string) The hash algorithm used for passwords. Default is 'md5'/
salt: (string) The salt string prefixed to every password before hashing it. Default is empty.

For example, if you want to use a registry entry 'sql' for the database connection, with users.handle and users.password as the table columns, using sha1 hashing for the password, you would make these entries in the config file:

<?php
$config['Solar_Auth_Adapter_Sql'] = array(
    'sql'          => 'sql',
    'table'        => 'users',
    'handle_col'   => 'handle',
    'passwd_col'   => 'password',
    'hash_algo'    => 'sha1'
);

Again, each adapter has its own special config settings, so the API documentation for the adapter you want to use.

7.3.4. Handling Authentication Attempts

Configuration is the hardest part of setting up authentication. Once that part is done correctly, all you need to do is instantiate a Solar_User object, either by creating it yourself or by retrieving it from the registry. The Solar_User instance will automatically instantiate a Solar_Auth object and start the authentication processing for you, handling login and logout attempts automatically.

	Note
	For more information on exactly what's happening behind the scenes, take a look at the code in the `Solar_Auth_Adapter::start()` method.

7.3.5. Usage

Let's say we are using the SQL role adapter to read from roles table with the following information:

# table: members
handle      passwd
--------    ----------
bolivar     ****
andy        ****
sarah       ****
jameel      ****
kornblum    ****

Let's also say that the user 'andy' has just logged in. The Solar_User object, which has a Solar_Auth_Adapter instance inside it, processes the login attempt for us when we instantiate it. We can then use the following Solar_Auth_Adapter methods and properties to find out about Andy authenticated identity. (Remember, we use a Solar_User object instead of instantiating a separate role adapter instance.)

<?php
$user = Solar_Registry::get('user');

// is the current user authenticated (logged in)?
$user->auth->isValid(); // true when logged in, false when not

// what is the handle for the authenticated user?
$user->auth->handle; // 'andy', or null when not logged in

Prev	Up	Next
7.2. The Solar_User Object	Home	7.4. Authentication Forms