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.
Workflow
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.
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}}",
"mfaEmail":"{{mfaEmail}}”,
"mfaPhone":"{{mfaPhone}}",
"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 ",
"tags":"",
"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
Get URL
Refer to the API Secure MFA page for help documentation specific for the API.
https://api.kount.com/secure-mfa/status/{mfaId}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.
- Open the Decision Manager tab on the left navigation pane.
- Select the desired profile or click the edit icon to view the Edit Profile page.
- 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).
Use Cases
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.
- Go to Decision Manager.
- 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).
- Create a new Profile.
- Set the condition userType to equal MFAONLY.
- Set MFA to On for this Profile.
- Name the Profile Explicit MFA (the customer can use any name that is fitting for them) and save it.
- Make sure the Profile is in the number one position within the list of Profiles.
- Click on the Policies tab.
- Click Create Policy.
- Set condition to userType equals MFAONLY then Challenge.
- Change the Profile to Explicit MFA.
- Name the Policy Send MFA.
- Click Save Policy.