SecondFactorVerifier
Piwik\Plugins\Login\
SecondFactorVerifier
Requires the current user to confirm a sensitive action with their second factor, e.g.
Unlike a password confirmation done through PasswordVerifier, a second-factor confirmation is not valid for a period of time: each confirmation is used up by the first request using it, is only valid for the action it was requested for, and only reaches the browser that entered the code. Users without a second factor are not asked for one.
Plugins providing a second factor answer the Login.userRequiresSecondFactorConfirmation and
Login.verifySecondFactor events. Failed codes count towards the brute force detection.
Usage in a controller action, typically after a password confirmation:
$params = ['module' => 'MyPlugin', 'action' => 'mySensitiveAction'];
if (!$secondFactorVerifier->requireSecondFactorConfirmed($params)) {
return;
}
// perform the sensitive action
Methods
The class defines the following methods:
isSecondFactorRequired()— Returns whether the given user has a second factor that has to be confirmed.requireSecondFactorConfirmed()— Returnstrueif the current request carries a confirmation of the user's second factor for the given action, or if the user has no second factor.requestConfirmation()— Records that the current user needs to confirm the given action and returns the id of that request, which the confirmation page needs.hasConfirmationBeenRequested()— Returns whether the given confirmation request is pending for the current user.confirmSecondFactor()— Verifies the given code for the current user and the given confirmation request.
isSecondFactorRequired()
Returns whether the given user has a second factor that has to be confirmed.
Signature
It accepts the following parameter(s):
$login(string) —
It returns a
boolvalue.
requireSecondFactorConfirmed()
Returns true if the current request carries a confirmation of the user's second factor for the given
action, or if the user has no second factor. The confirmation is used up by this call, so the action has
to perform the sensitive operation right away.
Otherwise, the user is redirected to the confirmation page, which redirects back to the action once
confirmed. Returns false if redirects are disabled.
Signature
- It accepts the following parameter(s):
$redirectParams(array) — string|int> $redirectParams The query parameters of the action, includingmoduleandaction. Values are URL encoded when redirecting.
- It returns a
boolvalue.
requestConfirmation()
Records that the current user needs to confirm the given action and returns the id of that request, which the confirmation page needs. Prefer requireSecondFactorConfirmed().
Signature
- It accepts the following parameter(s):
$redirectParams(array) — string|int> $redirectParams
- It returns a
stringvalue.
hasConfirmationBeenRequested()
Returns whether the given confirmation request is pending for the current user.
Signature
It accepts the following parameter(s):
$requestId(string) —
It returns a
boolvalue.
confirmSecondFactor()
Verifies the given code for the current user and the given confirmation request. If it is valid, returns the URL of the action to redirect to. That URL carries a one-time token which lets the action proceed once.
Returns null if the code is not valid or the request is not pending.
Failed attempts count towards the brute force detection.
Signature
It accepts the following parameter(s):
$requestId(string) —$code(string) —
Returns:
string|null—