---

Basic

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
    }
}

• Full name: \Hazaar\Auth\Adapter\Basic
• Parent class: \Hazaar\Auth\Adapter

Methods

__construct

Construct the helper.

public __construct(?\Hazaar\Map $config = null): mixed

Parameters:

Parameter	Type	Description
$config	?\Hazaar\Map	The configuration options

---

queryAuth

Set the identity.

public queryAuth(string $identity, string[] $extra = []): array<string,mixed>|bool

Parameters:

Parameter	Type	Description
$identity	string	The identity
$extra	string[]	Extra data to return with the authentication

Return Value:

The result

---

Inherited methods

__construct

Construct the adapter.

public __construct(array|\Hazaar\Map $config = []): mixed

Parameters:

Parameter	Type	Description
$config	array|\Hazaar\Map	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(): null|string

Return Value:

the identity of the user, or null if not set

---

getCredentialHash

Get the encrypted hash of a credential/password.

public getCredentialHash(?string $credential = null): ?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(null|string $identity = null, null|string $credential = null, bool $autologin = false): mixed

Parameters:

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

Return Value:

returns true if authentication is successful, false otherwise

---

authenticateRequest

Authenticates an HTTP request using Basic Authentication.

public authenticateRequest(\Hazaar\Application\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	\Hazaar\Application\Request	the HTTP request to authenticate

Return Value:

returns true if the request is authenticated successfully, false otherwise

Throws:

if the authentication fails

• Unauthorised

---

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.

Return Value:

true if the user is authenticated, false otherwise

---

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.

Return Value:

returns true if the storage was cleared, false if the storage was already empty

---

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

Return Value:

the value associated with the provided key

---

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

Return Value:

returns true if the key exists, false otherwise

---

unset

public unset(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(): array<string,mixed>

Return Value:

the authentication data

---

getToken

Returns the storage session token.

public getToken(): array<string,string>

Return Value:

Storage token will be an array with at least a 'token' key and optionally a 'refresh' key

---

setStorageAdapter

Sets the storage adapter for authentication.

public setStorageAdapter(string $storage, array<string,mixed>|\Hazaar\Map $options = []): bool

Parameters:

Parameter	Type	Description
$storage	string	the name of the storage adapter to use
$options	array<string,mixed>|\Hazaar\Map	optional configuration options for the storage adapter

Return Value:

returns true if the storage adapter was successfully set

Throws:

if the specified storage adapter class does not exist

• UnknownStorageAdapter

---

getIdentifier

Generates a hashed identifier for the given identity string.

protected getIdentifier(string $identity): null|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

Return Value:

the SHA-1 hash of the identity string, or null if the identity is empty

---

setDataFields

Set the extra data fields.

protected setDataFields(string[] $fields): void

Parameters:

Parameter	Type	Description
$fields	string[]	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

---

---

Automatically generated on 2024-11-14