Multi-Factor Authentication

The Multi-Factor Authentication (MFA) component enables seamless management of the MFA process for your customers. To use this component, you must generate a customer token with upgradable scopes. These scopes will be granted to the customer upon successful verification.

For instance, if your app includes an ACH debit component requiring the following scopes: customers accounts payments counterparties payments-write counterparties-write, you should issue a customer token with the customers accounts payments counterparties customer-token-write scopes while setting payments-write counterparties-write as upgradable scopes.

Request for customer token with upgradable scope

curl -X POST 'https://api.s.unit.sh/customers/8/token'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "customerToken",
    "attributes": {
      "scope": "customers accounts payments counterparties customer-token-write",
      "upgradableScope": "payments-write counterparties-write"
    }
  }
}'

Implementation

Web Components

Add the Multi-Factor Authentication element to your app where you'd like it to be presented. Note this component will use unitVerifiedCustomerToken key in local storage. It's important to clean it when the user logs out from the app.

<unit-elements-multi-factor-authentication
	customer-token=""
	theme=""
	language=""
>
</unit-elements-multi-factor-authentication>

Inputs:

Name	Type	Required	Description
customer-token	string	Yes	Customer token created with upgradable scope.
theme	string	No	A URL that specifies the UI configuration.
language	string	No	A URL that specifies the language configuration.

Events:

Event Name	Description	Detail
unitMultiFactorAuthVerificationTokenCreated	Occurs on load of component and when clicking Resend code	Create Customer Token Verification
unitMultiFactorAuthFinished	Occurs when multi-factor authentication finished successfully, and customer token created	Create Customer Token

React Native SDK

UNMultiFactorAuthenticationComponent props:

Name	Type	Required	Description
theme	string	NO	A URL that specifies the UI configuration.
language	string	NO	A URL that specifies the language configuration.
onLoad	(response: UNComponentsOnLoadResponse<undefined>) => void	NO	Callback for handling onload event, also usable for error handling.
onVerificationTokenCreated	(data: UNCustomerTokenVerification) => void	NO	Occurs on load of component and when clicking Resend code
onAuthenticationFinished	(data: UNMultiFactorAuthenticationFinished) => void	NO	Callback when multi-factor authentication finished successfully, and customer token created

Example:

import React from 'react';
import { UNMultiFactorAuthenticationComponent } from 'react-native-unit-components';

export default function YourComponent {
  return (
    <UNMultiFactorAuthenticationComponent
      onLoad={(response: UNComponentsOnLoadResponse<undefined>) => console.log(response)}
      onVerificationTokenCreated={(data: UNCustomerTokenVerification) => console.log(`Verification token created: ${data}`)}
      onAuthenticationFinished={(data: UNMultiFactorAuthenticationFinished) => console.log(`Authentication finished: ${counterparty}`)}
    />
  );
};

Android SDK

Component name: UNMultiFactorAuthenticationComponent

getMultiFactorAuthenticationComponent parameters:

Name	Type	Required	Description
theme	String	NO	A URL that specifies the UI configuration.
language	String	NO	A URL that specifies the language configuration.
callbacks	UNMultiFactorAuthenticationComponentCallbacks	NO	Component's Callbacks sealed class

UNMultiFactorAuthenticationComponentCallbacks

The callbacks parameter for UNMultiFactorAuthenticationComponent is of the following type:

typealias UNMultiFactorAuthenticationComponentCallbacks = (callback: UNMultiFactorAuthenticationComponentCallback) -> Unit

The UNMultiFactorAuthenticationComponentCallback is sealed class that has the following callbacks that you can receive from a MultiFactorAuthentication component:

sealed class UNMultiFactorAuthenticationComponentCallback {
    data class OnLoad(val onLoadResponse: Result<UNMultiFactorAuthenticationOnLoadResponse>): UNMultiFactorAuthenticationComponentCallback()
    data class OnAuthenticationFinished(val authToken: UNMultiFactorAuthenticationFinished): UNMultiFactorAuthenticationComponentCallback()
    data class OnMFAVerificationTokenCreated(val verification: UNCustomerTokenVerification): UNMultiFactorAuthenticationComponentCallback()
}

To get the MultiFactorAuthentication Component fragment, call the getMultiFactorAuthenticationComponent method of UnitComponentsSdk.manager.ui.views.

Example:

import android.os.Bundle
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import androidx.fragment.app.Fragment
import co.unit.un_components.api.UnitComponentsSdk
import co.unit.un_components.common.builders.UNMultiFactorAuthenticationViewSettingsBuilder
import co.unit.un_components.common.enums.UNMultiFactorAuthenticationComponentCallback
import co.unit.un_components.components.UNMultiFactorAuthenticationComponent

class MultiFactorAuthenticationFragment : Fragment() {
    private var unMultiFactorAuthenticationComponent: UNMultiFactorAuthenticationComponent? = null

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View? {
        val fragmentLayout = inflater.inflate(R.layout.FILE_NAME, container, false)

        // Define your callbacks
        val callbacks: (UNMultiFactorAuthenticationComponentCallback) -> Unit = { callback ->
            when (callback) {
                is UNMultiFactorAuthenticationComponentCallback.OnLoad -> handleUnitOnLoad(callback.onLoadResponse)
                is UNMultiFactorAuthenticationComponentCallback.OnAuthenticationFinished -> handleAuthenticationFinished(callback.authToken)
                is UNMultiFactorAuthenticationComponentCallback.OnMFAVerificationTokenCreated -> handleVerificationCreated(callback.verification)
            }
        }

        // Check if this is a fresh creation or restoration after process death
        unMultiFactorAuthenticationComponent = if (savedInstanceState == null) {
            // Fresh creation - create new component and add to fragment manager
            UnitComponentsSdk.manager.ui.views.getMultiFactorAuthenticationComponent(
                theme = YOUR_THEME_URL,
                language = YOUR_LANGUAGE_URL
            ).also {
                childFragmentManager.beginTransaction()
                    .replace(R.id.CONTAINER_NAME, it as Fragment, FRAGMENT_TAG)
                    .commitNow()
            }
        } else {
            // Restoration after process death - find existing fragment by tag
            childFragmentManager.findFragmentByTag(FRAGMENT_TAG) as? UNMultiFactorAuthenticationComponent
        }

        // Set callbacks after obtaining the component (required for both fresh and restored)
        unMultiFactorAuthenticationComponent?.callbacks = callbacks

        return fragmentLayout
    }

    // ...
    // Event handlers
    // ...

    companion object {
        private const val FRAGMENT_TAG = "mfa_component"
    }
}