How to Set Up Multi-factor Authentication in Control

Control has an integrated secure Multi-factor Authentication (MFA) so that customers can reduce their integration effort and have an all-in-one location for login security.


In the following workflow diagram, the end user logs into a customer site. In this example, the end user received a Challenge decision and is asked to perform an MFA. The end user successfully clicks on the link and is allowed to gain access to the customer’s site.

Integrated MFA Workflow

Login API

There are two additions to the Login API to facilitate MFA:

  • mfaEmail
  • mfaPhone

One or both fields are needed if an MFA message is to be sent by Kount on behalf of the customer.

When the customer receives the response from the API Login and Kount has sent an MFA request to the end user, the API response body contains the mfaId and mfaType. The customer uses these values to poll the MFA status API and tell when the MFA was sent.

Login API Post Body

   "clientId" : "{{clientID}}",
   "loginURL" : "{{loginURL}}",
   "sessionId" : "{{sessionID}}",
   "userId" : "{{userId}}",
   "username" : "{{userLogin}}",
   "userPassword" : "{{userPassword}}",
   "userCreationDate" : "{{userCreationDate}}",
   "userIp": "{{ipAddress}}",
   "userType": "{{userType}}"

Login API Response Body

   "decision": "Challenge",
   "deviceId": "udmfi5tr6ejd0kf4idfktpfdkemdheee6", 
   "matchedToDevice": "Device not found",
   "mfaEnabled": true,
   "mfaId": "41ba6a8b-071f-4310-9162-14bd42f7559d",
   "mfaType": "sms",
   "sessionId": " ffkcdlvkxldlcfflf009sjfjkefjjkj3 ",
   "userProfile": "Send MFA"

MFA Status API

The MFA Status API is used to find when/if an end user clicks on the secure MFA link sent.

  • Standard JWT Bearer Auth
  • X-Correlation-ID must be added to the header with a GUID
  • MFA link times out at five minutes
  • Poll every five seconds for status update


Refer to the API Secure MFA page for help documentation specific for the API.{mfaId}
Note: mfaId is taken from the Login API Response Body.

MFA Status Response Body

"correlationId": "fd4c7ace-f409-42cc-bd94-e716a1a53a09",
"createdAt": "1644875221",
"lastUpdated": "1644875261",
"mfaId": "5c547a91-9b15-4707-95c0-73d5016eee8b",
"mfaStatus": "FAILED_TO_SEND",
"mfaType": "email",
"sessionId": "b52b67bb17924161af67e5e6514ad6b5",
"userId": "sven1234"

Customer Admin MFA Tab

MFA: This is a Client Administration page and is viewable when Kount has turned MFA on for a Client on Customer Success page.

Global MFA: This turns MFA on/off globally for a client. If this setting is unchecked, MFA will not be sent for that type. This is true even if the customer has configured MFA within Profiles. This setting allows customers to turn MFA off for everything within the system (by unchecking both options). If both email and SMS are checked, the MFA will be sent to email unless the email is invalid or not available.

Auto Trust Device: When On, the device will automatically be trusted for a user when that user succeeds on a successful MFA challenge.

Target URL: The URL that a customer is directed to after clicking the MFA link.


Managing Profiles

In Kount Control, profiles can be viewed and edited to incorporate MFA on the Decision Manager page.


The MFA Enabled indicator shows the global state of the customer’s integrated MFA. The color of the MFA Enabled indicator changes depending on where the MFA feature is in the approval cycle if activated at all.

  • Green: Customer Success has been configured AND either email or SMS text messages has been turned on globally.
  • Grey: MFA has been setup by a Kount Employee for the customer, but neither email nor SMS text messages have been turned on globally.
  • Missing: If Kount has not turned on the feature in the Customer Success tab.

The Profile MFA shows the MFA status (On/Off) and allows the client to set MFA at a profile level. The default state of Profile MFA is Off. The user can click on the edit icon to change the Profile MFA settings.

Turning MFA On/Off for a profile

Challenge MFA allows users to turn on/off MFA for the selected profile.

  1. Open the Decision Manager tab on the left navigation pane.
  2. Select the desired profile or click the edit icon to view the Edit Profile page.
  3. On the Edit Profile page under Tags, you can toggle Challenge MFA to On or Off.
  • When toggled on, the profile triggers a challenge during the login request, then the end user with receive MFA to their email or phone based on global settings selected on MFA page and the MFA information included in the Login API.
  • When toggled off, logins where this profile is chosen, will not receive MFA (even if there is a challenge).
  • Select Save Profile to save changes.
  • Use Cases

    Creating an MFA Call Outside the Typical Login Workflow

    There are instances when an MFA must be re-sent without invoking policies again. For example, the end-user was too slow when clicking the link and it has now timed out.

    The solution is to create a Profile that looks for a pass-in value from the customer. When that pass-in value is received on a Login API call, a challenge is sent to the end-user.

    1. Go to Decision Manager.
    2. During the Login API call, set userType to equal MFAONLY (the value can be set by the customer as long as it is consistent throughout).
    3. Create a new Profile.
      1. Set the condition userType to equal MFAONLY.
      2. Set MFA to On for this Profile.
      3. Name the Profile Explicit MFA (the customer can use any name that is fitting for them) and save it.
    4. Make sure the Profile is in the number one position within the list of Profiles.
    5. Click on the Policies tab.
    6. Click Create Policy.
      1. Set condition to userType equals MFAONLY then Challenge.
      2. Change the Profile to Explicit MFA.
      3. Name the Policy Send MFA.
    7. Click Save Policy.
    Creating a Customer Selected MFA Type

    In some cases, a you might want to give end-users the choice of email or SMS MFA when logging in.

    During the login process, a challenge rule is triggered causing the need for the end-user to need to complete a step-up MFA. The customer asks the end-user what type of MFA the end-user would like to complete, SMS or email. After choosing, the user is sent the appropriate challenge to complete.

    Steps within Control

    1. Complete steps in Creating an MFA Call Outside the Typical Login Workflow.
    2. Make sure that other Profiles do not have MFA turned on.

    Steps required for API calls and responses

    1. When an end-user enters the proper credentials, send a Login API to Kount (typical use-case).
    2. If the Login API returns a Challenge present a choice to the end-user for MFA type desired.
    3. After the end-user enters their choice, send a new Login API call.
      1. Set userType to MFAONLY.
        • If the end-user chooses email, populate mfaEmail with the end-user’s email.
        • If the end-user chooses SMS, populate the mfaSMS with the end-user’s cell phone number.
    Creating a Login Call that Bypasses MFA

    You want to bypass challenge when MFA was successful for the account. This would be the same as Creating an MFA Call Outside the Typical Login Workflow except the pass-in value would be to allow you to log in without a challenge (and there would not be any block or challenge policies assigned to this Profile).

    1. During the Login API call, set userType to equal NOMFA (the value can be set by the customer as long as it is consistent throughout).
    2. Create a new Profile
      1. Set the condition userType to equal NOMFA.
      2. Set MFA to On for this Profile.
      3. Name the Profile Explicit MFA (the customer can use any name that is fitting for them) and save it.
    3. Make sure the Profile is after MFAONLY and before any other Profiles that might invoke a challenge or a block.
    Note: Do not add any policies to the Profile NOMFA. This means that any login API call with a NOMFA userType will receive an Accept response.
    Was this article helpful?
    0 out of 0 found this helpful