lithium\security\Auth

Extends lithium\core\Adaptable
class

The Auth class provides a common interface to authenticate user credentials from different sources against different storage backends in a uniform way. As with most other adapter-driven classes in the framework, Auth allows you to specify one or more named configurations, including an adapter, which can be referenced by name in your application.

Auth is responsible for managing session state for each configuration, and exposes a set of methods which adapters can implement: set(), check() and clear(). You can read more about each method below. Beyond these methods, Auth makes very few assumptions about how your application authenticates users. Each adapter accepts a set of credentials, and returns an array of user information on success, and false on failure. On successful authentication attempts, the data returned from the credential check is written to the session, which is automatically accessed on subsequent checks (though manual re-checking can be forced on a per-instance basis).

To be secure by default (and if you don't override it), a password field is never stored in the session adapter. This prevents a possible password hash to be leaked in a cookie (for example). You can also be very specific on what you want to store in the session:

Auth::config([
  'default' => [
     'session' => [
       'persist' => ['username', 'email']
     ]
  ]
]);

You can also pass an optional persist param to the check method to override this default.

For additional information on configuring and working with Auth, see the Form adapter.

Source

class Auth extends \lithium\core\Adaptable {

	/**
	 * Stores configurations for various authentication adapters.
	 *
	 * @var object `Collection` of authentication configurations.
	 */
	protected static $_configurations = [];

	/**
	 * Libraries::locate() compatible path to adapters for this class.
	 *
	 * @see lithium\core\Libraries::locate()
	 * @var string Dot-delimited path.
	 */
	protected static $_adapters = 'adapter.security.auth';

	/**
	 * Dynamic class dependencies.
	 *
	 * @var array Associative array of class names & their namespaces.
	 */
	protected static $_classes = [
		'session' => 'lithium\storage\Session'
	];

	/**
	 * Called when an adapter configuration is first accessed, this method sets the default
	 * configuration for session handling. While each configuration can use its own session class
	 * and options, this method initializes them to the default dependencies written into the class.
	 * For the session key name, the default value is set to the name of the configuration.
	 *
	 * @param string $name The name of the adapter configuration being accessed.
	 * @param array $config The user-specified configuration.
	 * @return array Returns an array that merges the user-specified configuration with the
	 *         generated default values.
	 */
	protected static function _initConfig($name, $config) {
		$defaults = ['session' => [
			'key' => $name,
			'class' => static::$_classes['session'],
			'options' => [],
			'persist' => []
		]];
		$config = parent::_initConfig($name, $config) + $defaults;
		$config['session'] += $defaults['session'];
		return $config;
	}

	/**
	 * Performs an authentication check against the specified configuration, and writes the
	 * resulting user information to the session such that credentials are not required for
	 * subsequent authentication checks, and user information is returned directly from the session.
	 *
	 * @param string $name The name of the `Auth` configuration/adapter to check against.
	 * @param mixed $credentials A container for the authentication credentials used in this check.
	 *              This will vary by adapter, but generally will be an object or array containing
	 *              a user name and password. In the case of the `Form` adapter, it contains a
	 *              `Request` object containing `POST` data with user login information.
	 * @param array $options Additional options used when performing the authentication check. The
	 *              options available will vary by adapter, please consult the documentation for the
	 *              `check()` method of the adapter you intend to use. The global options for this
	 *              method are:
	 *              - `'checkSession'` _boolean_: By default, the session store configured for the
	 *                adapter will always be queried first, to see if an authentication check has
	 *                already been performed during the current user session. If yes, then the
	 *                session data will be returned. By setting `'checkSession'` to `false`,
	 *                session checks are bypassed and the credentials provided are always checked
	 *                against the adapter directly.
	 *              - `'writeSession'` _boolean_: Upon a successful credentials check, the returned
	 *                user information is, by default, written to the session. Set this to `false`
	 *                to disable session writing for this authentication check.
	 *              - `'persist'` _array_: A list of fields that should be stored in the session.
	 *                If no list is provided will store all fields in the session except
	 *                the `'password'` field.
	 * @return array After a successful credential check against the adapter (or a successful
	 *         lookup against the current session), returns an array of user information from the
	 *         storage backend used by the configured adapter.
	 * @filter
	 */
	public static function check($name, $credentials = null, array $options = []) {
		$config = static::config($name);

		$defaults = [
			'checkSession' => true,
			'writeSession' => true,
			'persist' => isset($config['session']['persist']) ? $config['session']['persist'] : static::_config('persist')
		];

		$options += $defaults;
		$params = compact('name', 'credentials', 'options');

		return Filters::run(get_called_class(), __FUNCTION__, $params, function($params) {
			extract($params);
			$config = static::_config($name);

			if ($config === null) {
				throw new ConfigException("Configuration `{$name}` has not been defined.");
			}
			$session = $config['session'];

			if ($options['checkSession']) {
				if ($data = $session['class']::read($session['key'], $session['options'])) {
					return $data;
				}
			}

			if (($credentials) && $data = static::adapter($name)->check($credentials, $options)) {
				if ($options['persist'] && is_array($data)) {
					$data = array_intersect_key($data, array_fill_keys($options['persist'], true));
				} elseif (is_array($data)) {
					unset($data['password']);
				}
				return ($options['writeSession']) ? static::set($name, $data) : $data;
			}
			return false;
		});
	}

	/**
	 * Manually authenticate a user with the given set of data. Rather than checking a user's
	 * credentials, this method allows you to manually specify a user for whom you'd like to
	 * initialize an authenticated session.
	 *
	 * By default, before writing the data to the session, the `set()` method of the named
	 * configuration's adapter receives the data to be written, and has an opportunity to modify
	 * or reject it.
	 *
	 * @param string $name The name of the adapter configuration to.
	 * @param array $data The user data to be written to the session.
	 * @param array $options Any additional session-writing options. These may override any options
	 *              set by the default session configuration for `$name`.
	 * @return array Returns the array of data written to the session, or `false` if the adapter
	 *         rejects the data.
	 * @filter
	 */
	public static function set($name, $data, array $options = []) {
		$params = compact('name', 'data', 'options');

		return Filters::run(get_called_class(), __FUNCTION__, $params, function($params) {
			extract($params);
			$config = static::_config($name);
			$session = $config['session'];

			if ($data = static::adapter($name)->set($data, $options)) {
				$session['class']::write($session['key'], $data, $options + $session['options']);
				return $data;
			}
			return false;
		});
	}

	/**
	 * Removes session information for the given configuration, and allows the configuration's
	 * adapter to perform any associated cleanup tasks.
	 *
	 * @param string $name The name of the `Auth` configuration to clear the login information for.
	 *               Calls the `clear()` method of the given configuration's adapter, and removes
	 *               the information in the session key used by this configuration.
	 * @param array $options Additional options used when clearing the authenticated session. See
	 *              each adapter's `clear()` method for all available options. Global options:
	 *              - `'clearSession'` _boolean_: If `true` (the default), session data for the
	 *                specified configuration is removed, otherwise it is retained.
	 * @return void
	 * @filter
	 */
	public static function clear($name, array $options = []) {
		$defaults = ['clearSession' => true];
		$options += $defaults;

		$params = compact('name', 'options');

		return Filters::run(get_called_class(), __FUNCTION__, $params, function($params) {
			extract($params);
			$config = static::_config($name);
			$session = $config['session'];

			if ($options['clearSession']) {
				$session['class']::delete($session['key'], $session['options']);
			}
			static::adapter($name)->clear($options);
		});
	}
}