Documentation

Horde_Auth_Sql extends Horde_Auth_Base
in package

The Horde_Auth_Sql class provides a SQL implementation of the Horde authentication system.

The table structure for the Auth system needs to be created with the shipped migration scripts. See "horde-db-migrate-component --help" for details.

Tags
author

Chuck Hagenbuch chuck@horde.org

category

Horde

copyright

1999-2017 Horde LLC

license

http://www.horde.org/licenses/lgpl21 LGPL-2.1

Table of Contents

$_capabilities  : array<string|int, mixed>
An array of capabilities, so that the driver can report which operations it supports and which it doesn't.
$_credentials  : array<string|int, mixed>
The credentials currently being authenticated.
$_db  : Horde_Db_Adapter
Handle for the current database connection.
$_error  : array<string|int, mixed>
Authentication error information.
$_history_api  : Horde_History
History object.
$_lock_api  : Horde_Lock
Lock object.
$_logger  : Horde_Log_Logger
Logger object.
$_params  : array<string|int, mixed>
Hash containing parameters needed for the drivers.
__construct()  : mixed
Constructor
addUser()  : mixed
Add a set of authentication credentials.
authenticate()  : bool
Finds out if a set of login credentials are valid, and if requested, mark the user as logged in in the current session.
exists()  : bool
Checks if a userId exists in the system.
getCredential()  : mixed
Returns internal credential value(s).
getError()  : mixed
Returns the error type or message for an invalid authentication.
getParam()  : string
Returns the named parameter for the current auth driver.
hasCapability()  : bool
Queries the current driver to find out if it supports the given capability.
isLocked()  : bool|array<string|int, mixed>
Returns whether a user is currently locked.
listUsers()  : array<string|int, mixed>
List all users in the system.
lockUser()  : mixed
Locks a user indefinitely or for a specified time.
removeUser()  : mixed
Delete a set of authentication credentials.
resetPassword()  : string
Reset a user's password. Used for example when the user does not remember the existing password.
searchUsers()  : array<string|int, mixed>
Searches the users for a substring.
setCredential()  : mixed
Sets an internal credential value.
setError()  : mixed
Sets the error message for an invalid authentication.
transparent()  : bool
Automatic authentication.
unlockUser()  : mixed
Unlocks a user and optionally resets the bad login count.
updateUser()  : mixed
Update a set of authentication credentials.
validateAuth()  : bool
Checks for triggers that may invalidate the current auth.
_authenticate()  : mixed
Find out if a set of login credentials are valid.
_badLogin()  : mixed
Handles a bad login.
_comparePasswords()  : bool
Compare an encrypted password to a plaintext string to see if they match.
_resetBadLogins()  : mixed
Resets the bad login counter.
_sort()  : array<string|int, mixed>
Basic sort implementation.
_calc_expiration()  : int
Calculate a timestamp and return it along with the field name

Properties

$_capabilities

An array of capabilities, so that the driver can report which operations it supports and which it doesn't.

protected array<string|int, mixed> $_capabilities = array('add' => \true, 'list' => \true, 'remove' => \true, 'resetpassword' => \true, 'update' => \true, 'authenticate' => \true)

$_credentials

The credentials currently being authenticated.

protected array<string|int, mixed> $_credentials = array('change' => \false, 'credentials' => array(), 'expire' => \null, 'userId' => '')

$_db

Handle for the current database connection.

protected Horde_Db_Adapter $_db

$_error

Authentication error information.

protected array<string|int, mixed> $_error

$_history_api

History object.

protected Horde_History $_history_api

$_lock_api

Lock object.

protected Horde_Lock $_lock_api

$_logger

Logger object.

protected Horde_Log_Logger $_logger

$_params

Hash containing parameters needed for the drivers.

protected array<string|int, mixed> $_params = array()

Methods

__construct()

Constructor

public __construct([array<string|int, mixed> $params = array() ]) : mixed
Parameters
$params : array<string|int, mixed> = array()

Parameters: 'db' - (Horde_Db_Adapter) [REQUIRED] Database object.

'encryption' - (string) The encryption to use to store the password in
               the table (e.g. plain, crypt, md5-hex, md5-base64, smd5,
               sha, ssha, aprmd5).
               DEFAULT: 'md5-hex'
'hard_expiration_field' - (string) The name of the field containing a
                          date after which the account is no longer
                          valid and the user will not be able to log in
                          at all.
                          DEFAULT: none
'password_field' - (string) The name of the password field in the auth
                   table.
                   DEFAULT: 'user_pass'
'show_encryption' - (boolean) Whether or not to prepend the encryption
                    in the password field.
                    DEFAULT: false
'soft_expiration_field' - (string) The name of the field containing a
                          date after which the system will request the
                          user change his or her password.
                          DEFAULT: none
'table' - (string) The name of the SQL table to use in 'database'.
          DEFAULT: 'horde_users'
'username_field' - (string) The name of the username field in the auth
                   table.
                   DEFAULT: 'user_uid'
Tags
throws
InvalidArgumentException
Return values
mixed —

addUser()

Add a set of authentication credentials.

public addUser(string $userId, array<string|int, mixed> $credentials) : mixed
Parameters
$userId : string

The userId to add.

$credentials : array<string|int, mixed>

The credentials to add.

Tags
throws
Horde_Auth_Exception
Return values
mixed —

authenticate()

Finds out if a set of login credentials are valid, and if requested, mark the user as logged in in the current session.

public authenticate(string $userId, array<string|int, mixed> $credentials[, bool $login = true ]) : bool
Parameters
$userId : string

The userId to check.

$credentials : array<string|int, mixed>

The credentials to check.

$login : bool = true

Whether to log the user in. If false, we'll only test the credentials and won't modify the current session. Defaults to true.

Return values
bool —

Whether or not the credentials are valid.

exists()

Checks if a userId exists in the system.

public exists(string $userId) : bool
Parameters
$userId : string

User ID for which to check

Return values
bool —

Whether or not the userId already exists.

getCredential()

Returns internal credential value(s).

public getCredential([mixed $name = null ]) : mixed
Parameters
$name : mixed = null

The credential value to get. If null, will return the entire credential list. Valid names:

  • 'change': (boolean) Do credentials need to be changed?
  • 'credentials': (array) The credentials needed to authenticate.
  • 'expire': (integer) UNIX timestamp of the credential expiration date.
  • 'userId': (string) The user ID.
Return values
mixed —

The credential information, or null if the credential doesn't exist.

getError()

Returns the error type or message for an invalid authentication.

public getError([bool $msg = false ]) : mixed
Parameters
$msg : bool = false

If true, returns the message string (if set).

Return values
mixed —

Error type, error message (if $msg is true) or false if entry doesn't exist.

getParam()

Returns the named parameter for the current auth driver.

public getParam(string $param) : string
Parameters
$param : string

The parameter to fetch.

Return values
string —

The parameter's value, or null if it doesn't exist.

hasCapability()

Queries the current driver to find out if it supports the given capability.

public hasCapability(string $capability) : bool
Parameters
$capability : string

The capability to test for.

Return values
bool —

Whether or not the capability is supported.

isLocked()

Returns whether a user is currently locked.

public isLocked(string $userId[, bool $show_details = false ]) : bool|array<string|int, mixed>
Parameters
$userId : string

The user to check.

$show_details : bool = false

Return timeout too?

Tags
throws
Horde_Auth_Exception
Return values
bool|array<string|int, mixed> —

If $show_details is a true, an array with 'locked' and 'lock_timeout' values. Whether the user is locked, otherwise.

listUsers()

List all users in the system.

public listUsers([bool $sort = false ]) : array<string|int, mixed>
Parameters
$sort : bool = false

Sort the users?

Tags
throws
Horde_Auth_Exception
Return values
array<string|int, mixed> —

The array of userIds.

lockUser()

Locks a user indefinitely or for a specified time.

public lockUser(string $userId, int $time) : mixed
Parameters
$userId : string

The user to lock.

$time : int

The duration in minutes, 0 = permanent.

Tags
throws
Horde_Auth_Exception
Return values
mixed —

removeUser()

Delete a set of authentication credentials.

public removeUser(string $userId) : mixed
Parameters
$userId : string

The userId to delete.

Tags
throws
Horde_Auth_Exception
Return values
mixed —

resetPassword()

Reset a user's password. Used for example when the user does not remember the existing password.

public resetPassword(string $userId) : string
Parameters
$userId : string

The user id for which to reset the password.

Tags
throws
Horde_Auth_Exception
Return values
string —

The new password on success.

searchUsers()

Searches the users for a substring.

public searchUsers(string $search) : array<string|int, mixed>
Parameters
$search : string

The search term.

Tags
since

Horde_Auth 2.2.0

Return values
array<string|int, mixed> —

A list of all matching users.

setCredential()

Sets an internal credential value.

public setCredential(string $type, mixed $value) : mixed
Parameters
$type : string

The credential name to set. See getCredential() for the list of valid credentials/types.

$value : mixed

The credential value to set.

Return values
mixed —

setError()

Sets the error message for an invalid authentication.

public setError(string $type[, string $msg = null ]) : mixed
Parameters
$type : string

The type of error (Horde_Auth::REASON_* constant).

$msg : string = null

The error message/reason for invalid authentication.

Return values
mixed —

transparent()

Automatic authentication.

public transparent() : bool

Transparent authentication should set 'userId', 'credentials', or 'params' in $this->_credentials as needed - these values will be used to set the credentials in the session.

Transparent authentication should normally never throw an error - false should be returned.

Tags
throws
Horde_Auth_Exception
Return values
bool —

Whether transparent login is supported.

unlockUser()

Unlocks a user and optionally resets the bad login count.

public unlockUser(string $userId[, bool $resetBadLogins = false ]) : mixed
Parameters
$userId : string

The user to unlock.

$resetBadLogins : bool = false

Reset bad login counter?

Tags
throws
Horde_Auth_Exception
Return values
mixed —

updateUser()

Update a set of authentication credentials.

public updateUser(string $oldID, string $newID, array<string|int, mixed> $credentials) : mixed
Parameters
$oldID : string

The old userId.

$newID : string

The new userId.

$credentials : array<string|int, mixed>

The new credentials

Tags
throws
Horde_Auth_Exception
Return values
mixed —

validateAuth()

Checks for triggers that may invalidate the current auth.

public validateAuth() : bool

These triggers are independent of the credentials.

Return values
bool —

True if the results of authenticate() are still valid.

_authenticate()

Find out if a set of login credentials are valid.

protected _authenticate(string $userId, array<string|int, mixed> $credentials) : mixed
Parameters
$userId : string

The userId to check.

$credentials : array<string|int, mixed>

The credentials to use.

Tags
throws
Horde_Auth_Exception
Return values
mixed —

_badLogin()

Handles a bad login.

protected _badLogin(string $userId) : mixed
Parameters
$userId : string

The user with a bad login.

Tags
throws
Horde_Auth_Exception
Return values
mixed —

_comparePasswords()

Compare an encrypted password to a plaintext string to see if they match.

protected _comparePasswords(string $encrypted, string $plaintext) : bool
Parameters
$encrypted : string

The crypted password to compare against.

$plaintext : string

The plaintext password to verify.

Return values
bool —

True if matched, false otherwise.

_resetBadLogins()

Resets the bad login counter.

protected _resetBadLogins(string $userId) : mixed
Parameters
$userId : string

The user to reset.

Tags
throws
Horde_Auth_Exception
Return values
mixed —

_sort()

Basic sort implementation.

protected _sort(array<string|int, mixed> $users, bool $sort) : array<string|int, mixed>

If the backend has listUsers and doesn't have a native sorting option, fall back to this method.

Parameters
$users : array<string|int, mixed>

An array of usernames.

$sort : bool

Whether to sort or not.

Return values
array<string|int, mixed> —

the users, sorted or not

_calc_expiration()

Calculate a timestamp and return it along with the field name

private _calc_expiration(string $type) : int
Parameters
$type : string

The timestamp parameter.

Return values
int —

'timestamp' intended field value or null

Search results