Class CookieAuthenticator

Cookie Authenticator

Authenticates an identity based on a cookie data.

You must enable encrypted cookies with EncryptedCookieMiddleware before using CookieAuthenticator. Without encryption remember-me cookie values can be tampered with.

Namespace: Authentication\Authenticator

Property Summary

$_config protected

array<string, mixed>

Runtime config
$_configInitialized protected

bool

Whether the config property has already been configured with defaults
$_defaultConfig protected

array<string, mixed>
Default config for this object.
- fields The fields to use to identify a user by.
$_identifier protected

?IdentifierInterface

Identifier instance.
$_needsPasswordRehash protected

bool

Whether the user authenticated by this class requires their password to be rehashed with another algorithm.
$_passwordHasher protected

?PasswordHasherInterface

Password hasher instance.

Method Summary

__construct() public

Constructor
_authenticateLegacyToken() protected

Validates a legacy two-part [username, passwordHashedToken] token.
_authenticateToken() protected

Validates a three-part [username, expires, hmac] token.
_checkUrl() protected

Checks the Login URL
_configDelete() protected

Deletes a single config key.
_configRead() protected

Reads a config key.
_configWrite() protected

Writes a config key.
_createCookie() protected

Creates a cookie instance with configured defaults.
_createLegacyPlainToken() protected

Recreates the plain part of a legacy cookie token.
_createToken() protected

Creates a full cookie token serialized as a JSON string.
_expiryTimestamp() protected

Converts the cookie.expires config value to a timestamp.
_getUrlChecker() protected

Gets the login URL checker
_hmacKey() protected

Returns the HMAC key for token creation and verification.
_legacyHashWithinLimits() protected

Checks a legacy token hash uses a bounded work factor.
authenticate() public

Authenticate a user based on the request information.
clearIdentity() public

Clears the identity data
configShallow() public

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.
deleteConfig() public

Deletes a config key.
getConfig() public

Returns the config.
getConfigOrFail() public

Returns the config for this specific key.
getIdentifier() public

Gets the identifier, loading a default Password identifier if none configured.
getPasswordHasher() public

Return the password hasher built from the passwordHasher config.
needsPasswordRehash() public

Returns whether or not the password stored in the repository for the logged in user requires to be rehashed with another algorithm
persistIdentity() public

Persists the users data
setConfig() public

Sets the config.
setIdentifier() public

Sets the identifier.
setPasswordHasher() public

Sets password hasher object.

Method Detail

__construct() ¶ public

__construct(Authentication\Identifier\IdentifierInterface|null $identifier = null, array<string, mixed> $config = [])

Constructor

Parameters

Authentication\Identifier\IdentifierInterface|null $identifier optional: Identifier instance.
array<string, mixed> $config optional: Configuration settings.

_authenticateLegacyToken() ¶ protected

_authenticateLegacyToken(array $token): Authentication\Authenticator\ResultInterface

Validates a legacy two-part [username, passwordHashedToken] token.

Legitimate legacy tokens were created with password_hash(), so any hash that is not a known password_hash() algorithm is rejected before it can reach password_verify(). This blocks forged crypt()-format hashes (e.g. DES, which truncates its input to 8 bytes) while all real legacy cookies keep working.

Parameters

array $token: The decoded token parts.

Returns

Authentication\Authenticator\ResultInterface

_authenticateToken() ¶ protected

_authenticateToken(array $token): Authentication\Authenticator\ResultInterface

Validates a three-part [username, expires, hmac] token.

Checks part types, then expiry (before touching the identifier), then locates the user and verifies the HMAC of username + password hash + expires in constant time.

Parameters

array $token: The decoded token parts.

Returns

Authentication\Authenticator\ResultInterface

_checkUrl() ¶ protected

_checkUrl(Psr\Http\Message\ServerRequestInterface $request): bool

Checks the Login URL

Parameters

Psr\Http\Message\ServerRequestInterface $request: The request that contains login information.

Returns

bool

_configDelete() ¶ protected

_configDelete(string $key): void

Deletes a single config key.

Parameters

string $key: Key to delete.

Returns

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_configRead() ¶ protected

_configRead(string|null $key): $key is null ? array : mixed

Reads a config key.

Parameters

string|null $key: Key to read.

Returns

$key is null ? array : mixed

_configWrite() ¶ protected

_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void

Writes a config key.

Parameters

array<string, mixed>|string $key: Key to write to.
mixed $value: Value to write.
string|bool $merge optional: True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Returns

void

Throws

Cake\Core\Exception\CakeException
if attempting to clobber existing config

_createCookie() ¶ protected

_createCookie(mixed $value): Cake\Http\Cookie\CookieInterface

Creates a cookie instance with configured defaults.

Parameters

mixed $value: Cookie value.

Returns

Cake\Http\Cookie\CookieInterface

_createLegacyPlainToken() ¶ protected

_createLegacyPlainToken(ArrayAccess<string, mixed>|array<string, mixed> $identity): string

Recreates the plain part of a legacy cookie token.

This must match the pre-HMAC token construction byte for byte, including the legacy salt config semantics, or existing cookies would not survive the grace period.

Parameters

ArrayAccess<string, mixed>|array<string, mixed> $identity: Identity data.

Returns

string

_createToken() ¶ protected

_createToken(ArrayAccess<string, mixed>|array<string, mixed> $identity): string

Creates a full cookie token serialized as a JSON string.

Cookie token consists of the username, an expiry timestamp, and an HMAC-SHA256 of username + password hash + expires.

Parameters

ArrayAccess<string, mixed>|array<string, mixed> $identity: Identity data.

Returns

string

Throws

JsonException

_expiryTimestamp() ¶ protected

_expiryTimestamp(): int

Converts the cookie.expires config value to a timestamp.

Supported values: DateTimeInterface instances, numeric UNIX timestamps (consistent with Cake\Http\Cookie\Cookie), and strtotime() compatible strings such as the +7 days default.

Returns

int

Timestamp the token will expire at.

_getUrlChecker() ¶ protected

_getUrlChecker(): Authentication\UrlChecker\UrlCheckerInterface

Gets the login URL checker

Returns

Authentication\UrlChecker\UrlCheckerInterface

_hmacKey() ¶ protected

_hmacKey(): string

Returns the HMAC key for token creation and verification.

The salt config is used as the key when it is a string. Any other value falls back to the application salt — the HMAC key cannot be disabled.

Returns

string

_legacyHashWithinLimits() ¶ protected

_legacyHashWithinLimits(array $info): bool

Checks a legacy token hash uses a bounded work factor.

A forged legacy token could embed a valid bcrypt/argon2 hash with an arbitrarily large cost, turning password_verify() into a CPU or memory exhaustion vector. Legitimately issued cookies use the PASSWORD_DEFAULT parameters, so bounding the work factor rejects abusive hashes without affecting real tokens. Bounds come from the legacyHashLimits config.

Parameters

array $info: Result of password_get_info() for the token hash.

Returns

bool

authenticate() ¶ public

authenticate(Psr\Http\Message\ServerRequestInterface $request): Authentication\Authenticator\ResultInterface

Authenticate a user based on the request information.

Parameters

Psr\Http\Message\ServerRequestInterface $request

Returns

Authentication\Authenticator\ResultInterface

clearIdentity() ¶ public

clearIdentity(Psr\Http\Message\ServerRequestInterface $request, Psr\Http\Message\ResponseInterface $response): array{request: \Psr\Http\Message\ServerRequestInterface, response: \Psr\Http\Message\ResponseInterface}

Clears the identity data

Parameters

Psr\Http\Message\ServerRequestInterface $request
Psr\Http\Message\ResponseInterface $response

Returns

array{request: \Psr\Http\Message\ServerRequestInterface, response: \Psr\Http\Message\ResponseInterface}

configShallow() ¶ public

configShallow(array<string, mixed>|string $key, mixed|null $value = null): $this

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

array<string, mixed>|string $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.

Returns

$this

deleteConfig() ¶ public

deleteConfig(string $key): $this

Deletes a config key.

Parameters

string $key: Key to delete. It can be a dot separated string to delete nested keys.

Returns

$this

getConfig() ¶ public

getConfig(string|null $key = null, mixed $default = null): $key is null ? array : mixed

Returns the config.

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

string|null $key optional: The key to get or null for the whole config.
mixed $default optional: The return value when the key does not exist.

Returns

$key is null ? array : mixed

Configuration data at the named key or null if the key does not exist.

getConfigOrFail() ¶ public

getConfigOrFail(string $key): mixed

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters

string $key: The key to get.

Returns

mixed

Configuration data at the named key

Throws

InvalidArgumentException

getIdentifier() ¶ public

getIdentifier(): Authentication\Identifier\IdentifierInterface

Gets the identifier, loading a default Password identifier if none configured.

This is done lazily to allow configuration to be fully set before creating the identifier.

Returns

Authentication\Identifier\IdentifierInterface

getPasswordHasher() ¶ public

getPasswordHasher(): Authentication\PasswordHasher\PasswordHasherInterface

Return the password hasher built from the passwordHasher config.

Overrides the trait accessor so the config option is honored.

Returns

Authentication\PasswordHasher\PasswordHasherInterface

needsPasswordRehash() ¶ public

needsPasswordRehash(): bool

Returns whether or not the password stored in the repository for the logged in user requires to be rehashed with another algorithm

Returns

bool

persistIdentity() ¶ public

persistIdentity(Psr\Http\Message\ServerRequestInterface $request, Psr\Http\Message\ResponseInterface $response, ArrayAccess<string, mixed>|array<string, mixed> $identity): array{request: \Psr\Http\Message\ServerRequestInterface, response: \Psr\Http\Message\ResponseInterface}

Persists the users data

Parameters

Psr\Http\Message\ServerRequestInterface $request
Psr\Http\Message\ResponseInterface $response
ArrayAccess<string, mixed>|array<string, mixed> $identity

Returns

array{request: \Psr\Http\Message\ServerRequestInterface, response: \Psr\Http\Message\ResponseInterface}

setConfig() ¶ public

setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this

Sets the config.

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

array<string, mixed>|string $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.
bool $merge optional: Whether to recursively merge or overwrite existing config, defaults to true.

Returns

$this

Throws

Cake\Core\Exception\CakeException
When trying to set a key that is invalid.

setIdentifier() ¶ public

setIdentifier(Authentication\Identifier\IdentifierInterface $identifier): $this

Sets the identifier.

Parameters

Authentication\Identifier\IdentifierInterface $identifier: IdentifierInterface instance.

Returns

$this

setPasswordHasher() ¶ public

setPasswordHasher(Authentication\PasswordHasher\PasswordHasherInterface $passwordHasher): $this

Sets password hasher object.

Parameters

Authentication\PasswordHasher\PasswordHasherInterface $passwordHasher: Password hasher instance.

Returns

$this

Property Detail

`$_config` ¶ protected

Runtime config

Type

array<string, mixed>

`$_configInitialized` ¶ protected

Whether the config property has already been configured with defaults

Type

bool

`$_defaultConfig` ¶ protected

Default config for this object.

fields The fields to use to identify a user by.

Type

array<string, mixed>

`$_identifier` ¶ protected

Identifier instance.

Type

?IdentifierInterface

`$_needsPasswordRehash` ¶ protected

Whether the user authenticated by this class requires their password to be rehashed with another algorithm.

Type

bool

`$_passwordHasher` ¶ protected

Password hasher instance.

Type

?PasswordHasherInterface

Namespaces

Class CookieAuthenticator

Property Summary

Method Summary

__construct() public

_authenticateLegacyToken() protected

_authenticateToken() protected

_checkUrl() protected

_configDelete() protected

_configRead() protected

_configWrite() protected

_createCookie() protected

_createLegacyPlainToken() protected

_createToken() protected

_expiryTimestamp() protected

_getUrlChecker() protected

_hmacKey() protected

_legacyHashWithinLimits() protected

authenticate() public

clearIdentity() public

configShallow() public

deleteConfig() public

getConfig() public

getConfigOrFail() public

getIdentifier() public

getPasswordHasher() public

needsPasswordRehash() public

persistIdentity() public

setConfig() public

setIdentifier() public

setPasswordHasher() public

Method Detail

__construct() ¶ public

Parameters

_authenticateLegacyToken() ¶ protected

Parameters

Returns

_authenticateToken() ¶ protected

Parameters

Returns

_checkUrl() ¶ protected

Parameters

Returns

_configDelete() ¶ protected

Parameters

Returns

Throws

_configRead() ¶ protected

Parameters

Returns

_configWrite() ¶ protected

Parameters

Returns

Throws

_createCookie() ¶ protected

Parameters

Returns

_createLegacyPlainToken() ¶ protected

Parameters

Returns

_createToken() ¶ protected

Parameters

Returns

Throws

_expiryTimestamp() ¶ protected

Returns

_getUrlChecker() ¶ protected

Returns

_hmacKey() ¶ protected

Returns

_legacyHashWithinLimits() ¶ protected

Parameters

Returns

authenticate() ¶ public

Parameters

Returns

clearIdentity() ¶ public

Parameters

Returns

configShallow() ¶ public

`$_config` ¶ protected

`$_configInitialized` ¶ protected

`$_defaultConfig` ¶ protected

`$_identifier` ¶ protected

`$_needsPasswordRehash` ¶ protected

`$_passwordHasher` ¶ protected