Class Authentication

Generic authentication interface.

Core\Object implements Core\Chainable

Core\Set implements Core\Accessor

Core\Authentication

Direct known subclasses

Core\Authentication\Driver\ldap, Core\Authentication\Driver\sspi, Core\Authentication\Driver\storage

Abstract
Namespace: Core
Package: Core\Authentication
Since: 3.0
Requires: PHP 5.3
Version: 2.1
Located at Authentication.inc.php

Methods summary

`protected`	# `__construct( Core\URI $uri )` Parameters `$uri` Authentication driver description from factory. Throws `Core\Exception\InvalidArgument` Target object for auto-chaining does not implement `Core\Chainable`. `Core\Exception\MissingParameter` A mandatory parameter is missing. `Core\Exception\Parameter` Invalid value for enumeration parameter. Since 3.0
`abstract protected Core\Authentication_Token\|false`	# `_validate( array $credentials )` Driver implementation of user credentials verification. Driver implementation of user credentials verification. Parameters `$credentials` Associative array of user credentials. Contains at least the following entries: string `user` The username to verify. string `password` The provided password or password hash to verify. string `domain` The domain name to verify credentials for. Returns `Core\Authentication_Token`\|false Token instance for the specified user on success, otherwise `false`. Set the status and status message properties to provide additional information on why authentication failed. If the back-end encounters a fatal error, it might throw an exception. Remark Drivers must set the status property and should set the status message property to provide extended status information. Since 3.0 See self::$status self::$statusMessage
`protected boolean`	# `_validatePassword( array $credentials, string $backendPassword )` Performs validation step for standardised authentication methods. Performs validation step for standardised authentication methods. This method simplifies the authentication process for back-ends with full control and access to the user password storage system. Passwords are automatically encoded using the configured encoder and compared in their encoded form. Parameters `$credentials` Associative array of user credentials. Accesses the following fields: callable `callback` Optional callback used to calculate a password hash from given credentials and back-end password. Primarily used by authentication automation helpers. string `password` Password to validate. `$backendPassword` The password retrieved from the authentication back-end. Returns boolean `true`, if user credentials match, otherwise `false`. Remark This method automatically updates the status code property. Since 3.0
`public static Core\Authentication`	# `autocreate( Core\URI $uri )` Authentication driver factory. Authentication driver factory. Parameters `$uri` Authentication driver description. Returns `Core\Authentication` New authentication driver instance. Throws `Core\Exception\InvalidDriver` The driver description scheme refers to an unknown driver. Since 3.0
`public boolean`	# `chain( Core\Chainable $object, array $flags = null )` Adds or replaces a successive authentication layer. Adds or replaces a successive authentication layer. Parameters `$object` Successive authentication instance to set. `$flags` The following optional chain flags are supported: bool `replace` If set to `true`, the current successor is replaced by the new object. Otherwise the new object is appended to the successor chain. Returns boolean `true` on success, otherwise an exception is thrown. Throws `Core\Exception\InvalidArgument` Class of provided object is not supported. Since 3.0 Overrides `Core\Object::chain`
`public Core\Authentication_Token\|false`	# `perform( Core\URI $methodURI, string $realm = null, string $message = null )` Performs an automated authentication step (e.g. HTTP Basic and Digest). Performs an automated authentication step (e.g. HTTP Basic and Digest). All authentication data is retrieved from the corresponding authentication method, which most likely involes user interaction. Parameters `$methodURI` Authentication automation driver description. `$realm` Optional name of authentication realm. Depending on the authentication method, the realm is displayed to the user and set to a driver-dependent default if not provided. `$message` Optional message presented to the user if an authentication step has been cancelled or was interrupted. Returns `Core\Authentication_Token`\|false Authentication token for the specified user on success, otherwise `false`. Since 3.0 Uses static::verify()
`public Core\Authentication_Token\|false`	# `verify( array $credentials )` Verifies user credentials against the full chain of authentication drivers. Verifies user credentials against the full chain of authentication drivers. Parameters `$credentials` Associative array of user credentials to verify. Expects the following fields: string `user` The username to verify. string `password` The provided password or password hash to verify. string `domain` The domain name to verify credentials for. Returns `Core\Authentication_Token`\|false Authentication token for the specified user on success, otherwise `false`. In case of a fatal back-end error, an exception may be thrown. Throws `Core\Exception\Loader` Failed to load the `Core\Hash` module. Since 3.0 Uses `Core\Hash`

Methods inherited from Core\Set

__get(), __isset()

Methods inherited from Core\Object

__autocreateFactory(), __call(), __processParameters(), __toString(), attachMethod(), getValueForKey(), getValueForKeyPath(), getValueForUndefinedKey(), hash(), issetValueForKey(), setValueForKey(), setValueForKeyPath(), setValueForUndefinedKey(), uuid()

Constants summary

`string`	`AllowEmptyPasswordParameter` Configuration parameter name to control whether empty password are allowed. Defaults to `true`. Configuration parameter name to control whether empty password are allowed. Defaults to `true`. If disabled, authentication attempts using empty passwords will fail prior to invocation of the actual driver back-end. Since 3.0	# `'allow-empty-password'`
`string`	`AllowEmptyUsernameParameter` Configuration parameter name to control whether empty user names are allowed. Defaults to `false`. Configuration parameter name to control whether empty user names are allowed. Defaults to `false`. If disabled, authentication attempts using empty user names will fail prior to invocation of the actual driver back-end. Since 3.0	# `'allow-empty-username'`
`string`	`FieldSelectorParameter` Configuration parameter name of PCRE describing additionally available data fields. Defaults to `null`. Configuration parameter name of PCRE describing additionally available data fields. Defaults to `null`. Since 3.0	# `'field-selector'`
`string`	`PasswordEncryptionParameter` Configuration parameter name of encoder URI string for passwords. Defaults to `passthrough:`. A decoder, if required by the back-end, is derived from the selected encoder. Configuration parameter name of encoder URI string for passwords. Defaults to `passthrough:`. A decoder, if required by the back-end, is derived from the selected encoder. Remark Only supported by drivers that verify passwords by themselves (ie. do not let an external back-end perform the actual verification). Since 3.0 See Encoder::resolveDecoder()	# `'password-encryption'`
`integer`	`Success` Verification status code for valid user credentials. Verification status code for valid user credentials. Since 3.0	# `0x0`
`integer`	`InvalidCredentials` Verification status code for invalid user credentials. Usually indicates that the password used is invalid. Verification status code for invalid user credentials. Usually indicates that the password used is invalid. Since 3.0	# `0x1`
`integer`	`UnknownIdentifier` Verification status code for an unknown user identifier. E.g. the user does not exist in the given domain. Verification status code for an unknown user identifier. E.g. the user does not exist in the given domain. Since 3.0	# `0x2`
`integer`	`TemporaryFailure` Verification status code for a temporary back-end failure. E.g. an authentication server timeout. Verification status code for a temporary back-end failure. E.g. an authentication server timeout. Since 3.1	# `0x3`

Constants inherited from Core\Object

AnyParameterType, AutochainParameterType, AutocreateParameterType, BooleanParameterType, CharParameterType, EnumParameterType, IntegerParameterType, RealParameterType, StringParameterType, UserParameterType

Properties summary

`protected array`	`$_v_parameters` Authentication configuration parameters. Authentication configuration parameters. Since 3.0	#
`protected integer`	`$_v_status` Status code of last user credentials verification. Drivers must set the status code after each performed verification. Status code of last user credentials verification. Drivers must set the status code after each performed verification. Remark The default value is undefined. A status code is only valid for the last performed credentials verification. Since 3.0	# `-1`
`protected string`	`$_v_statusMessage` Optional credentials verification status message. Drivers should set this to a corresponding error message with further information on the cause on authentication failures to pass-through back-end error messages. May also contain further details on success. The value is initially set to `null` during each verification. Optional credentials verification status message. Drivers should set this to a corresponding error message with further information on the cause on authentication failures to pass-through back-end error messages. May also contain further details on success. The value is initially set to `null` during each verification. Remark The default value is `null`. A status message is only valid for the last performed credentials verification. The status message contains the driver class name, followed by a colon and space, and the actual message contents. E.g. drivers usually use the following code fragment to set a status message: `$this->_v_statusMessage = __CLASS__ . ': ' . \rtrim($backendMessage, '.');` This enables front-ends to parse error messages and extrapolate driver class names. The backend message must not end in a dot. Since 3.1	#
`protected Core\Authentication`	`$_v_successor` Subsequent (chained) authentication layer instance, if any. Subsequent (chained) authentication layer instance, if any. Since 3.0	#

Magic properties

`public read-only array`	`$parameters` Authentication configuration parameters.
`public read-only integer`	`$status` Status code of last user credentials verification. Only defined after first completed credentials verification. For authentication chains, the status code of the last invoked instance in the chain is propagated to all predecessors. In case of an error, chain execution is stopped preliminarily and the status code will reflect the code of the first failed authentication instance.
`public read-only string`	`$statusMessage` Status message of last user credentials verification. Defaults to `null`. For authentication chains, the status message of the last invoked instance in the chain is propagated to all predecessors. In case of an error, chain execution is stopped preliminarily and the status message will reflect the reason of the first failed authentication instance.
`public read-only Core\Authentication`	`$successor` Subsequent (chained) authentication driver instance, if any. Defaults to `null`.

Magic properties inherited from Core\Object

$hash, $uuid

Namespaces

Classes

Interfaces

Exceptions

Constants

Class Authentication

Direct known subclasses

Methods summary

Parameters

Throws

Since

Parameters

Returns

Remark

Since

See

Parameters

Returns

Remark

Since

Parameters

Returns

Throws

Since

Parameters

Returns

Throws

Since

Overrides

Parameters

Returns

Since

Uses

Parameters

Returns

Throws

Since

Uses

Methods inherited from Core\Set

Methods inherited from Core\Object

Constants summary

Since

Since

Since

Remark

Since

See

Since

Since

Since

Since

Constants inherited from Core\Object

Properties summary

Since

Remark

Since

Remark

Since

Since

Magic properties

Magic properties inherited from Core\Object