Jump to content

Developer Documentation

core/MFAArea

What it is

The MFAArea extension allows you to protect certain resources within your application behind multi-factor authentication (MFA), if enabled for the site. Commerce uses this, for example, to require MFA when users access certain restricted areas. Using an extension allows administrators to explicitly require or not require MFA for your sensitive pages, giving them greater control and flexibility over the MFA system as a whole.

How to use

The extension defines one method, which allows administrators to enable or disable MFA being required in the area defined.

    /**
     * Is this area available and should show in the ACP configuration?
     *
     * @return    bool
     */
    public function isEnabled()
    {
        return TRUE;
    }

Your application can return a hardcoded boolean value here, or return the result of an operation (e.g. you may want to check if a feature is enabled and only return TRUE if the feature is enabled).

You will also need to add a language string that will be used when configuring MFA in the AdminCP to denote what this extension protects.

'MFA_appkey_ExtensionKey' => "Doing something in my application",

The format of the language key is MFA_ followed by the application directory and an underscore, followed by the extension key you specified when creating the extension (the class and file name).

Finally, in your application controllers where appropriate, you will need to check if the user has passed MFA yet, and if not show the appropriate form. This can often be done in the controller's execute() method, however you will also need to output the real page behind the MFA prompt so you will need to evaluate how your application behaves to determine the best spot to do this.

An example from Commerce is shown here:

    /**
     * Execute
     *
     * @return    void
     */
    public function execute()
    {
        // Removed for brevity
        
        if ( $output = \IPS\MFA\MFAHandler::accessToArea( 'nexus', 'Alternatives', \IPS\Http\Url::internal( 'app=nexus&module=clients&controller=alternatives', 'front', 'clientsalternatives', array(), \IPS\Settings::i()->nexus_https ) ) )
        {
            \IPS\Output::i()->output = \IPS\Theme::i()->getTemplate('clients')->alternatives( TRUE ) . $output;
            return;
        }
        
        parent::execute();
    }

While some other code not relevant to our example has been stripped here, you can see that we check accessToArea() against \IPS\MFA\MFAHandler, passing in the application key and the extension key, as well as a URL the user should be sent to afterwards. If any output is returned, we send the output immediately appended to the rest of the page. Note, however, that the regular page HTML does NOT contain any sensitive data (the TRUE parameter passed to the template results in the page header being output but not the normal body of the page.


  Report Document


×
×
  • Create New...