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
        """

The decorator can also be used to enforce MFA based on event-driven validation (Patrol). When providing an audit action name, an audit event will be created when the extension method is called. The response to the audit event creation can trigger the MFA workflow for EDV validation or block the method as needed.

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

class AuthorizedUserHandler(Q2TectonServerRequestHandler):

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

When using an audit action name, the decorator creates audit details with basic information such as the extension name and routing key. You can also provide an audit details object to include additional context in the audit event. The audit details parameter accepts a string, dictionary, or a lambda that returns a dictionary. If you use a lambda, it will be executed when the audit event is created, allowing you to include dynamic information from your handler in the audit details.

from q2_sdk.core.http_handlers.tecton_client_handler import Q2TectonClientRequestHandler, mfa_validation_required

class AuthorizedUserHandler(Q2TectonClientRequestHandler):

    @mfa_validation_required(
        audit_action_name="CustomAuditAction", 
        audit_details="Example details"
    )
    async def string_details(self):
        """
        """

    @mfa_validation_required(
        audit_action_name="CustomAuditAction", 
        audit_details={"key": "value"}
    )
    async def dict_details(self):
        """
        """

    @mfa_validation_required(
        audit_action_name="CustomAuditAction", 
        audit_details=lambda self: {"detailItem": self.form_fields.detail_item, "firstName": self.online_user.first_name}
    )
    async def lambda_details(self):
        """
        """

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.

Tecton promptForMFA

The Tecton promptForMFA capability is a JavaScript API that allows you to prompt the end user for MFA. The SDK and the UUX platform use this API internally to kick off the MFA workflow on the front-end, but you can also use it directly in your extension code

tecton.sources.promptForMFA().then((response) => {
    return tecton.sources.requestExtensionData("create_transaction", {
        toAccount: 123123,
        fromAccount: 64521,
        amount: "5.00",
        memo: "My Transaction"
    });
}).catch(() => {
    tecton.actions.showModal({
        title: "Transaction Failed"
        msg: "Multi Factor Authentication is required to complete this transaction.",
        modalType: "Error",
    });
});

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.

Where logon uses the System Properties LogonTacAllowEmailTargets, LogonTacAllowPushTargets, LogonTacAllowSmsTargets, LogonTacAllowVoiceTargets.

promptForMFA uses the System Properties EdvTacAllowEmailTargets, EdvTacAllowPushTargets, EdvTacAllowSmsTargets, EdvTacAllowVoiceTargets.