Adapter

Abstract authentication adapter.

This class is the base class for all of the supplied authentication adapters. This class takes care of the password hash generation and session management, including the autologin function.

Available options are:

encryption.hash - default: sha256

The hash algorithm to use to encrypt passwords. This can be a a single algorith, such as sha256, sha1 or any other algorithm supported by the PHP hash() function. You can use the hash_algos() function to get a list of available algorithms. Any unsupported algorithms are silently ignored.

This option can also be an array of algorithms. In which case each one will be applied in the order specified. During each iteration the hash will be appended with the original password (this helps prevent hash collisions) along with any salt value (see below) before being hashed with the next algorithm.

The default is sha256 for security. Please note that this breaks backwards compatibility with the 1.0 version of this module.

Configuration Directives

encryption.count - default: 1

For extra obfuscation, it's possible to "hash the hash" this many times. This is the old method we used to add extra security to the hash, except we now also append the original password to the hash before hashing it. (too much hash?). In the case where the encryption.hash is a list of algorithms, each one of these will be applied as above for each count. So for example, if you have a list of 3 algorithms and the count is 3, your password will be hashed 9 times.

encryption.salt - default: null

For more security a salt value can be set which will be appended to each password when being hashed. If the password is being hashed multiple times then the salt is appended to the hash + password.

This is now more often used as a cache timeout value because on logon, certain data is obtained for a user and stored in cache. Sometimes obtaining this data can be processor intensive so we don't want to do it on every page load. Instead we do it, cache it, and then only do it again once this time passes.

Example Config (application.json)

{
    "development": {
        "encryption": {
            "hash": [ "md5", "sha1", "sha256" ],
            "salt": "mysupersecretsalt"
        },
        "autologin": {
            "period": 365,
            "hash": "sha1"
        },
        "timeout": 28800
    }
}

Properties

options

The configuration options.

protected array $options

storage

protected Storage $storage

identity

public string $identity

credential

public string $credential

extra

Extra data fields to store from the user record.

protected array $extra

noCredentialHashing

private bool $noCredentialHashing

Methods

__construct

Construct the adapter.

public __construct(array $config = []): void

Parameters

Parameter	Type	Description
$config	array	The configuration options

setIdentity

Sets the identity for the authentication adapter.

public setIdentity(string $identity): void

Parameters

Parameter	Type	Description
$identity	string	the identity to be set

setCredential

Sets the credential for authentication.

public setCredential(string $credential): void

Parameters

Parameter	Type	Description
$credential	string	the credential to be set

getIdentity

Retrieves the identity of the current user.

public getIdentity(): ?string

getCredentialHash

Get the encrypted hash of a credential/password.

public getCredentialHash(?string $credential): ?string

This method uses the "encryption" options from the application configuration to generate a password hash based on the supplied password. If no password is supplied then the currently set credential is used.

NOTE: Keep in mind that if no credential is set, or it's null, or an empty string, this will still return a valid hash of that empty value using the defined encryption hash chain.

Parameters

Parameter	Type	Description
$credential	string

authenticate

Authenticates a user based on the provided identity and credential.

public authenticate(?string $identity, ?string $credential, bool $autologin = false): mixed

Parameters

Parameter	Type	Description
$identity	string	The identity of the user (e.g., username or email).
$credential	string	The credential of the user (e.g., password).
$autologin	bool	whether to enable autologin

authenticateRequest

Authenticates an HTTP request using Basic Authentication.

public authenticateRequest(Request $request): bool

This method checks if the request contains a valid 'Authorization' header with Basic Authentication credentials. It decodes the credentials and verifies them using the authenticate method.

Parameters

Parameter	Type	Description
$request	Request	the HTTP request to authenticate

authenticated

Checks if the user is authenticated.

public authenticated(): bool

This method verifies if the storage is not empty and contains an 'identity' key. If the storage is empty or does not have the 'identity' key, it clears the storage and returns false. Otherwise, it returns true indicating the user is authenticated.

check

Check that the supplied password is correct for the current identity.

public check(string $credential): bool

This is useful for checking an account password before allowing something important to be updated. This does the same steps as authenticate() but doesn't actually do the authentication.

Parameters

Parameter	Type	Description
$credential	string

clear

Clears the authentication storage.

public clear(): bool

This method checks if the storage is empty. If it is not empty, it clears the storage and returns true. If the storage is already empty, it returns false.

unauthorised

Helper method that sets the basic auth header and throws an unauthorised exception.

public unauthorised(): void

disableCredentialHashing

Toggles on/off the internal credential hashing algorithm.

public disableCredentialHashing(bool $value = true): void

This is useful is you want to authenticate with an already hashed credential.

WARNING: This should NOT normally be used. And if it IS used, it should only be used to authenticate credentials supplied internally by the application itself, and not provided by a user/client/etc. Disabling password hash essentially turns this all into clear text credentials.

Parameters

Parameter	Type	Description
$value	bool

get

Retrieves a value from the storage based on the provided key.

public get(string $key): mixed

Parameters

Parameter	Type	Description
$key	string	the key used to retrieve the value from the storage

set

Sets a value in the storage with the specified key.

public set(string $key, mixed $value): void

Parameters

Parameter	Type	Description
$key	string	the key under which the value will be stored
$value	mixed	the value to be stored

has

Checks if a given key exists in the storage.

public has(string $key): bool

Parameters

Parameter	Type	Description
$key	string	the key to check for existence in the storage

public (string $key): void

Parameters

Parameter	Type	Description
$key	string

offsetExists

public offsetExists(mixed $offset): bool

Parameters

Parameter	Type	Description
$offset	mixed

offsetGet

public offsetGet(mixed $offset): mixed

Parameters

Parameter	Type	Description
$offset	mixed

offsetSet

public offsetSet(mixed $offset, mixed $value): void

Parameters

Parameter	Type	Description
$offset	mixed
$value	mixed

offsetUnset

public offsetUnset(mixed $offset): void

Parameters

Parameter	Type	Description
$offset	mixed

getAuthData

Retrieves authentication data from the storage.

public getAuthData(): void

getToken

Returns the storage session token.

public getToken(): void

setStorageAdapter

Sets the storage adapter for authentication.

public setStorageAdapter(string $storage, array $options = []): bool

Parameters

Parameter	Type	Description
$storage	string	the name of the storage adapter to use
$options	array	optional configuration options for the storage adapter

getIdentifier

Generates a hashed identifier for the given identity string.

protected getIdentifier(string $identity): ?string

This method takes an identity string and returns its SHA-1 hash. If the identity string is empty or null, the method returns null.

Parameters

Parameter	Type	Description
$identity	string	the identity string to be hashed

setDataFields

Set the extra data fields.

protected setDataFields(array $fields): void

Parameters

Parameter	Type	Description
$fields	array	The extra data fields

authenticationSuccess

Overload function called when a user is successfully authenticated.

protected authenticationSuccess(string $identity, array $data): void

This can occur when calling authenticate() or authenticated() where a session has been saved. This default method does nothing but can be overridden.

Parameters

Parameter	Type	Description
$identity	string	The identity that was successfully authenticated
$data	array	The data returned from the authentication query

authenticationFailure

Overload function called when a user fails authentication.

protected authenticationFailure(string $identity, array $data): void

This can occur when calling authenticate() or authenticated() where a session has been saved. This default method does nothing but can be overridden.

Parameters

Parameter	Type	Description
$identity	string	the identity that failed authentication
$data	array	the data returned from the authentication query

---

Generated by Hazaar API Doc Generator