AuthMethodInterface

Type

Interface

Namespace

craft\auth\methods

Extends

craft\base\ComponentInterface

Implemented by

craft\auth\methods\BaseAuthMethod, craft\auth\methods\RecoveryCodes, craft\auth\methods\TOTP

Since

5.0.0

AuthMethodInterface defines the common interface to be implemented by authentication methods used for 2-step verification.

A base implementation is provided by craft\auth\methods\BaseAuthMethod.

View source

Public Methods

Method	Description
description()	Returns the description of this authentication method.
displayName()	Returns the display name of this class.
extraFields()	Returns the list of additional fields that can be returned by toArray() in addition to those listed in fields().
fields()	Returns the list of fields that should be returned by default by toArray() when no specific fields are specified.
getActionMenuItems()	Returns action menu items for the authentication method, when active.
getAuthFormHtml()	Returns the HTML for the authentication method’s authentication form.
getSetupHtml()	Returns the HTML for the authentication method’s setup slideout.
instance()	Returns static class instance, which can be used to obtain meta information.
isActive()	Returns whether the authentication method is active for the user.
isSelectable()	Returns whether the component should be selectable in component Type selects.
remove()	Removes the authentication method for the current user.
setUser()	Sets the user that is being verified.
toArray()	Converts the object into an array.
verify()	Authenticates the user.

description()

Returns the description of this authentication method.

View source

Returns

string

getActionMenuItems()

Returns action menu items for the authentication method, when active.

See craft\helpers\Cp::disclosureMenu() for documentation on supported item properties.

View source

Returns

array

getAuthFormHtml()

Returns the HTML for the authentication method’s authentication form.

Before returning the HTML, ensure an asset bundle is registered which defines a JavaScript class for handling your form. The class should be registered via Craft.registerAuthFormHandler().

Acme.VoiceAuthForm = Garnish.Base.extend({
  init(form, onSuccess, showError) {
    this.addListener(form, 'submit', (ev) => {
      ev.preventDefault();
      const data = {
        voiceSignature: '...',
      };
      Craft.sendActionRequest('acme/auth/verify-voice', {data})
        .then(() => {
          onSuccess();
        })
        .catch(({response}) => {
          showError(response.data.message);
        });
    });
  },
}, {
  METHOD: 'acme\\auth\\VoiceAuth',
});

Craft.registerAuthFormHandler(Acme.VoiceAuthForm.METHOD, Acme.VoiceAuthForm);

The class should send a request to a controller action, which collects the form data and passes it to craft\services\Auth::verify(). That in turn will call your verify() method, passing it the same arguments.

If your verify() method returns true, craft\services\Auth::verify() will log the user in before returning the result.

use Craft;
use yii\web\Response;

protected array|bool|int $allowAnonymous = [
    'verify-voice' => self::ALLOW_ANONYMOUS_LIVE | self::ALLOW_ANONYMOUS_OFFLINE,
];

public function actionVerifyVoice(): Response
{
    $this->requirePostRequest();
    $this->requireAcceptsJson();

    $voiceSignature = $this->request->getRequiredBodyParam('voiceSignature');
    $success = Craft::$app->auth->verify(VoiceAuth::class, $voiceSignature);

    if (!$success) {
        return $this->asFailure('Voice verification failed.');
    }

    return $this->asSuccess('Voice verification successful.');
}

View source

Returns

string

getSetupHtml()

Returns the HTML for the authentication method’s setup slideout.

Once the method is enabled for the user, call the slideout’s showSuccess() method to display a success message, and call Craft.authMethodSetup.refresh() to refresh the method’s info and actions in the main window.

Craft::$app->view->registerJsWithVars(fn($containerId, $class) => <<<JS
  // ...
  Craft.Slideout.instances[$containerId].showSuccess();
  Craft.authMethodSetup.refresh();
JS, [
    $containerId,
    static::class
]);

View source

Arguments

• $containerId (string) – The ID of the setup slideout’s container element

Returns

string

isActive()

Returns whether the authentication method is active for the user.

View source

Returns

boolean

remove()

Removes the authentication method for the current user.

View source

setUser()

Sets the user that is being verified.

This will be called once during initialization.

View source

Arguments

• $user (craft\elements\User)

verify()

Authenticates the user.

This will be called from craft\services\Auth::verify(), which can be passed any number of arguments which will be forwarded onto this method. (See getAuthFormHtml() for a full walkthrough of how it works.)

View source

Arguments

• $args (mixed) – ,... Any arguments passed to craft\services\Auth::verify()

Returns

boolean – Whether the user should be authenticated.