Prompting for MFA

It is a common practice to require that an end user completes multi-factor authentication during workflows within digital banking. Q2’s digital banking platform supports multi-factor authentication out of the box. SDK Extensions are able to take advantage of that functionality with a SDK python decorator to enforce the completion of that workflow.

Access Code Target Selection

Access Code Input

Access Token Input

Python Decorator

For server-side methods that need to be protected by MFA, you can utilize the @mfa_validation_required decorator. This decorator will enforce that the end user has completed the correct MFA workflow before the method is executed.

from q2_sdk.core.http_handlers.tecton_server_handler import Q2TectonServerRequestHandler,mfa_validation_required

class AuthorizedUserHandler(Q2TectonServerRequestHandler):

    @mfa_validation_required()
    async def submit(self):
        """
        This route will be only called when the MFA workflow has been completed
        """

You may also pass a error handler method to the decorator to handle cases when a user exits the MFA flow before completion or where an exception is thrown during the process.

from q2_sdk.core.http_handlers.tecton_server_handler import Q2TectonServerRequestHandler, mfa_validation_required

class AuthorizedUserHandler(Q2TectonServerRequestHandler):

    def handle_mfa_error(self, error):
        template = self.get_template(
            "error.html.jinja2",
            {
                "header": "MyExtension: Error",
                "message": f'MFA Failure - {error}',
            },
        )

        html = self.get_tecton_form(
            "MyExtension",
            custom_template=template,
            # Hide the submit button as there is no form on this route.
            hide_submit_button=True,
        )

        return html

    @mfa_validation_required(error_handler=handle_mfa_error)
    async def submit(self):
        """
        This route will be only called when the MFA workflow has been completed
        """

Warning

The error_handler function must be synchronous — it cannot be defined with async or use await.

MFA Type

Starting with HQ 4.6.0.7032, you can optionally specify the MFA type to use for the validation by passing the mfa_type parameter. This parameter accepts an EdvMfaType enum value:

EdvMfaType.AUTHENTICATION - Used for authentication-related MFA prompts
EdvMfaType.TRANSACTION_AUTH - Used for transaction authorization MFA prompts
EdvMfaType.PATROL_EDV - Default value if not specified

from q2_sdk.core.http_handlers.tecton_server_handler import Q2TectonServerRequestHandler, mfa_validation_required
from q2_sdk.core.http_handlers.tecton_base_handler import EdvMfaType

class AuthorizedUserHandler(Q2TectonServerRequestHandler):

    @mfa_validation_required(mfa_type=EdvMfaType.AUTHENTICATION)
    async def submit(self):
        """
        This route will prompt for Authentication MFA type
        """

    @mfa_validation_required(mfa_type=EdvMfaType.TRANSACTION_AUTH)
    async def authorize_transaction(self):
        """
        This route will prompt for TransactionAuth MFA type
        """

Front-end Handling

The front-end handling to provide the correct MFA workflow for the user is baked in to the online banking platform as of UUX 4.6.1.4 and supports all variations of MFA. This means that you only need the @mfa_validation_required decorator to add MFA to your extension. The SDK, Tecton, and the UUX platform will handle opening the MFA workflow as needed depending on the user’s setup. If you are supporting an older version of UUX, you will need to implement the front-end handling by using the Tecton promptForMFA capabilitity prior to calling your extension method protected by the @mfa_validation_required decorator.

Note

If a request is attempted against an entry point that has the python decorator but has not completed the MFA workflow, an exception will be thrown and the method will not be executed. You can catch this exception and handle it as needed by passing an error handler method to the decorator.

Target List Configuration

The MFA UI Flow presents a list of known delivery targets for that end user. It is important to know that although the targets are pulled from the same list used during login, the configuration about which type of target is allowed is configured separately.

Logon uses the System Properties LogonTacAllowEmailTargets, LogonTacAllowPushTargets, LogonTacAllowSmsTargets, LogonTacAllowVoiceTargets.

Event Driven Validation uses the System Properties EdvTacAllowEmailTargets, EdvTacAllowPushTargets, EdvTacAllowSmsTargets, EdvTacAllowVoiceTargets.

MFA via Audit Decorator

In addition to @mfa_validation_required, MFA can also be triggered through the @create_audit decorator. Rather than enforcing MFA generically, @create_audit prompts for MFA conditionally based on how the corresponding audit action is configured — for example, via Q2 Patrol step-up authentication policies. This is useful when MFA should only be required under certain conditions determined by the audit action setup rather than unconditionally.

For details on defining audit actions and using the @create_audit decorator, see Auditing.