API Documentation
\

\Horde_Auth_Sql

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.

Summary

Methods
Properties
Constants
__construct()
authenticate()
validateAuth()
addUser()
lockUser()
unlockUser()
isLocked()
updateUser()
removeUser()
listUsers()
searchUsers()
exists()
transparent()
resetPassword()
hasCapability()
getParam()
getCredential()
setCredential()
setError()
getError()
No public properties found
No constants found
_sort()
_authenticate()
_badLogin()
_resetBadLogins()
_comparePasswords()
$_capabilities
$_params
$_credentials
$_logger
$_history_api
$_lock_api
$_error
$_db
N/A
_calc_expiration()
No private properties found
N/A

Properties

$_capabilities

$_capabilities : array

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

Type

array

$_params

$_params : array

Hash containing parameters needed for the drivers.

Type

array

$_credentials

$_credentials : array

The credentials currently being authenticated.

Type

array

$_logger

$_logger : \Horde_Log_Logger

Logger object.

Type

\Horde_Log_Logger

$_history_api

$_history_api : \Horde_History

History object.

Type

\Horde_History

$_lock_api

$_lock_api : \Horde_Lock

Lock object.

Type

\Horde_Lock

$_error

$_error : array

Authentication error information.

Type

array

$_db

$_db : \Horde_Db_Adapter

Handle for the current database connection.

Type

\Horde_Db_Adapter

Methods

__construct()

__construct(array  $params = array())

Constructor

Parameters

array $params

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'

Throws

\InvalidArgumentException

authenticate()

authenticate(string  $userId, array  $credentials, boolean  $login = true) : boolean

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

Parameters

string $userId

The userId to check.
array $credentials

The credentials to check.
boolean $login

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

Returns

boolean —

Whether or not the credentials are valid.

validateAuth()

validateAuth() : boolean

Checks for triggers that may invalidate the current auth.

These triggers are independent of the credentials.

Returns

boolean —

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

addUser()

addUser(string  $userId, array  $credentials)

Add a set of authentication credentials.

Parameters

string $userId

The userId to add.
array $credentials

The credentials to add.

Throws

\Horde_Auth_Exception

lockUser()

lockUser(string  $userId, integer  $time)

Locks a user indefinitely or for a specified time.

Parameters

string $userId

The user to lock.
integer $time

The duration in minutes, 0 = permanent.

Throws

\Horde_Auth_Exception

unlockUser()

unlockUser(string  $userId, boolean  $resetBadLogins = false)

Unlocks a user and optionally resets the bad login count.

Parameters

string $userId

The user to unlock.
boolean $resetBadLogins

Reset bad login counter?

Throws

\Horde_Auth_Exception

isLocked()

isLocked(string  $userId, boolean  $show_details = false) : boolean|array

Returns whether a user is currently locked.

Parameters

string $userId

The user to check.
boolean $show_details

Return timeout too?

Throws

\Horde_Auth_Exception

Returns

boolean|array —

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

updateUser()

updateUser(string  $oldID, string  $newID, array  $credentials)

Update a set of authentication credentials.

Parameters

string $oldID

The old userId.
string $newID

The new userId.
array $credentials

The new credentials

Throws

\Horde_Auth_Exception

removeUser()

removeUser(string  $userId)

Delete a set of authentication credentials.

Parameters

string $userId

The userId to delete.

Throws

\Horde_Auth_Exception

listUsers()

listUsers(boolean  $sort = false) : array

List all users in the system.

Parameters

boolean $sort

Sort the users?

Throws

\Horde_Auth_Exception

Returns

array —

The array of userIds.

searchUsers()

searchUsers(string  $search) : array

Searches the users for a substring.

Parameters

string $search

The search term.

Returns

array —

A list of all matching users.

exists()

exists(string  $userId) : boolean

Checks if a userId exists in the system.

Parameters

string $userId

User ID for which to check

Returns

boolean —

Whether or not the userId already exists.

transparent()

transparent() : boolean

Automatic authentication.

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.

Throws

\Horde_Auth_Exception

Returns

boolean —

Whether transparent login is supported.

resetPassword()

resetPassword(string  $userId) : string

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

Parameters

string $userId

The user id for which to reset the password.

Throws

\Horde_Auth_Exception

Returns

string —

The new password on success.

hasCapability()

hasCapability(string  $capability) : boolean

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

Parameters

string $capability

The capability to test for.

Returns

boolean —

Whether or not the capability is supported.

getParam()

getParam(string  $param) : string

Returns the named parameter for the current auth driver.

Parameters

string $param

The parameter to fetch.

Returns

string —

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

getCredential()

getCredential(mixed  $name = null) : mixed

Returns internal credential value(s).

Parameters

mixed $name

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.

Returns

mixed —

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

setCredential()

setCredential(string  $type, mixed  $value)

Sets an internal credential value.

Parameters

string $type

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

The credential value to set.

setError()

setError(string  $type, string  $msg = null)

Sets the error message for an invalid authentication.

Parameters

string $type

The type of error (HordeAuth::REASON* constant).
string $msg

The error message/reason for invalid authentication.

getError()

getError(boolean  $msg = false) : mixed

Returns the error type or message for an invalid authentication.

Parameters

boolean $msg

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

Returns

mixed —

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

_sort()

_sort(array  $users, boolean  $sort) : array

Basic sort implementation.

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

Parameters

array $users

An array of usernames.
boolean $sort

Whether to sort or not.

Returns

array —

the users, sorted or not

_authenticate()

_authenticate(string  $userId, array  $credentials)

Find out if a set of login credentials are valid.

On failure, Horde_Auth_Exception should pass a message string (if any) in the message field, and the HordeAuth::REASON* constant in the code field (defaults to Horde_Auth::REASON_MESSAGE).

Parameters

string $userId

The userId to check.
array $credentials

The credentials to use.

Throws

\Horde_Auth_Exception

_badLogin()

_badLogin(string  $userId)

Handles a bad login.

Parameters

string $userId

The user with a bad login.

Throws

\Horde_Auth_Exception

_resetBadLogins()

_resetBadLogins(string  $userId)

Resets the bad login counter.

Parameters

string $userId

The user to reset.

Throws

\Horde_Auth_Exception

_comparePasswords()

_comparePasswords(string  $encrypted, string  $plaintext) : boolean

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

Parameters

string $encrypted

The crypted password to compare against.
string $plaintext

The plaintext password to verify.

Returns

boolean —

True if matched, false otherwise.

_calc_expiration()

_calc_expiration(string  $type) : integer

Calculate a timestamp and return it along with the field name

Parameters

string $type

The timestamp parameter.

Returns

integer —

'timestamp' intended field value or null