Model

About 6 min

Model

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\Model
Parent class: \Hazaar\Auth\Adapter
This class is an Abstract class

Methods

create

Create a new user record.

public create(string $identity, string $credential, array&lt;string,mixed&gt; $data = []): bool

Parameters:

Parameter	Type	Description
`$identity`	string	The user identity/username
`$credential`	string	The user credential/password
`$data`	array<string,mixed>	Additional data to store with the user record

update

Update a user record.

public update(string $identity, ?string $credential = null, array&lt;string,mixed&gt; $data = []): bool

Use this method to set the user's password and/or update any additional data stored with the user record.

Parameters:

Parameter	Type	Description
`$identity`	string	The user identity/username
`$credential`	?string
`$data`	array<string,mixed>	The data to update

delete

Delete a user record.

public delete(string $identity): bool

Parameters:

Parameter	Type	Description
`$identity`	string	The user identity/username

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&lt;string,mixed&gt;

Return Value:

the authentication data

getToken

Returns the storage session token.

public getToken(): array&lt;string,string&gt;

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&lt;string,mixed&gt;|\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