API Documentation
\

\Horde_Auth_Imap

The Horde_Auth_Imap:: class provides an IMAP implementation of the Horde authentication system.

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()
_getOb()
$_capabilities
$_params
$_credentials
$_logger
$_history_api
$_lock_api
$_error
$_imap
N/A
No private methods found
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

$_imap

$_imap : \array()

Imap client objects.

Type

\array()

Methods

__construct()

__construct(array  $params = array())

Constructor.

Parameters

array $params

Optional parameters:

  • admin_password: (string) The password of the administrator. DEFAULT: null
  • admin_user: (string) The name of a user with admin privileges. DEFAULT: null
  • hostspec: (string) The hostname or IP address of the server. DEFAULT: 'localhost'
  • port: (integer) The server port to which we will connect. IMAP is generally 143, while IMAP-SSL is generally 993. DEFAULT: Encryption port default
  • secure: (string) The encryption to use. Either 'none', 'ssl', or 'tls'. DEFAULT: 'none'
  • userhierarchy: (string) The hierarchy where user mailboxes are stored (UTF-8). DEFAULT: 'user.'

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 use.

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)

Updates 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

Lists 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 $userId exists in the system.

Parameters

string $userId

User ID for which to check

Returns

boolean —

Whether or not $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

An array of login credentials. For IMAP, this must contain a password entry.

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

_getOb()

_getOb(string  $user, string  $pass) : \Horde_Imap_Client_Base

Get Horde_Imap_Client object.

Parameters

string $user

Username.
string $pass

Password.

Throws

\Horde_Auth_Exception

Returns

\Horde_Imap_Client_Base —

IMAP client object.