Integrating TruValidate Multifactor Authentication with iOS

iOS Version

The minimum iOS version supported for Authenticator SDK v4.6.0 and up is iOS 9.

The minimum iOS version supported for Authenticator SDK v3.0.0 is iOS 8.

AuthenticatorConfig Builder Properties

As of Authenticator SDK v4.6.0 and up, you can build an AuthenticatorConfig object, which is the updated way to set some of the following advanced integration options, as well as some color configurations. Essentially, the AuthenticatorConfig object replaces the deprecated AuthenticatorConfigurator class and all it’s available methods. The following are code snippets to display all the builder options available via the AuthenticatorConfig object:

Objective-C:

AuthenticatorConfig *config = [AuthenticatorConfig makeWithAuthenticatorConfigBuilder:^(AuthenticatorConfigBuilder *builder) {
    builder.SSLPinningEnabled = YES;
    builder.customFont = @"System";
    builder.keyPairSize = keypair_maximum;
    builder.activationDelayWearable = 86400;
    builder.activationDelayGeofence = 86400;
    builder.thresholdAuthFailure = thresholdAuthFailureDefault; // available as of v4.7.0
    builder.thresholdAutoUnlink = thresholdAutoUnlinkDefault; // available as of v4.7.0
    builder.thresholdAutoUnlinkWarning = thresholdWarningUnlinkMin; // available as of v4.7.0
    builder.enableInfoButtons = YES;
    builder.enableHeaderViews = YES;
    builder.enableNotificationPrompt = YES;
    builder.enableSecurityChangesWhenUnlinked = NO;
    builder.controlsBackgroundColor = [UIColor clearColor];
    builder.geofenceCircleColor = [UIColor blueColor];
    builder.tableViewHeaderBackgroundColor = [UIColor clearColor];
    builder.tableViewHeaderTextColor = [UIColor blueColor];
    builder.securityViewsTextColor = [UIColor blackColor];
    builder.securityFactorImageTintColor = [UIColor blackColor];
    builder.enablePINCode = YES;
    builder.enableCircleCode = YES;
    builder.enableGeofencing = YES;
    builder.enableWearable = YES;
    builder.enableFingerprint = YES;
    builder.enableFace = YES;
    builder.authContentViewBackgroundColor = [UIColor whiteColor];
    builder.authTextColor = [UIColor purpleColor];
    builder.authResponseAuthorizedColor = [UIColor greenColor];
    builder.authResponseDeniedColor = [UIColor redColor];
    builder.authResponseFailedColor = [UIColor orangeColor];
    builder.authResponseDenialReasonSelectedColor = [UIColor blueColor];
    builder.authResponseDenialReasonUnselectedColor = [UIColor brownColor];
}];

Swift:

let config = AuthenticatorConfig.make {builder in
        builder?.sslPinningEnabled = true
        builder?.customFont = "System"
        builder?.keyPairSize = keypair_maximum
        builder?.activationDelayGeofence = 86400
        builder?.activationDelayWearable = 86400
        builder?.thresholdAuthFailure = thresholdAuthFailureDefault  // available as of v4.7.0
        builder?.thresholdAutoUnlink = thresholdAutoUnlinkDefault  // available as of v4.7.0
        builder?.thresholdAutoUnlinkWarning = thresholdWarningUnlinkMin  // available as of v4.7.0
        builder?.enableInfoButtons = true
        builder?.enableHeaderViews = true
        builder?.enableNotificationPrompt = true
        builder?.enableSecurityChangesWhenUnlinked = false
        builder?.controlsBackgroundColor = UIColor.clear
        builder?.enableSecurityFactorImages = true
        builder?.geofenceCircleColor = UIColor.blue
        builder?.tableViewHeaderBackgroundColor = UIColor.clear
        builder?.tableViewHeaderTextColor = UIColor.blue
        builder?.securityViewsTextColor = UIColor.black
        builder?.securityFactorImageTintColor = UIColor.black
        builder?.enablePINCode = true
        builder?.enableCircleCode = true
        builder?.enableGeofencing = true
        builder?.enableWearable = true
        builder?.enableFingerprint = true
        builder?.enableFace = true
        builder?.authContentViewBackgroundColor = UIColor.white
        builder?.authTextColor = UIColor.purple
        builder?.authResponseAuthorizedColor = UIColor.green
        builder?.authResponseDeniedColor = UIColor.red
        builder?.authResponseFailedColor = UIColor.orange
        builder?.authResponseDenialReasonSelectedColor = UIColor.blue;
        builder?.authResponseDenialReasonUnselectedColor = UIColor.brown
    }

Activation Delay (v3.0.4 and up)

The Authenticator SDK allows you to set an activation delay for passive security factors, such as geo-fences or Bluetooth proximity devices. This is the time it takes for the SDK to add or remove a passive factor. The delay also applies when an end-user toggles the verification setting for a security factor, which changes how the factor is verified during auth requests, for example only when required, or always.

You can set the delay for a range of time between 0 seconds to 24 hours. Provide the value in seconds, for example set it to 864000 to for a delay of 24 hours.

As of Authenticator SDK v4.6.0 and up, please reference the code examples in the AuthenticatorConfig Builder Properties section above. If using a version of the SDK below v4.6.0, please use the following examples for reference.

Objective-C:

[[AuthenticatorConfigurator sharedConfig] setActivationDelayProximity:86400];

[[AuthenticatorConfigurator sharedConfig] setActivationDelayGeofence:86400];

Swift:

AuthenticatorConfigurator.sharedConfig().setActivationDelayProximity(86400)

AuthenticatorConfigurator.sharedConfig().setActivationDelayGeofence(86400)

SSL Pinning (Extra Security)

The Authenticator SDK uses SSL for network communication to the TruValidate Multifactor Authentication Platform API to ensure secure data transmission. However, to protect against eavesdropping and ensure that man-in-the-middle attacks cannot occur over this connection, you should enable SSL pinning which will verify the hostname and SSL certificate returned from the Platform API handshake exactly matches those that are bundled in your Mobile App. If the certificate cannot be verified, all connections to the Platform API are terminated.

As of Authenticator SDK v4.6.0 and up, please reference the code examples in the AuthenticatorConfig Builder Properties section above. If using a version of the SDK below v4.6.0, please use the following examples for reference.

Objective-C:

// Turn OFF
[[AuthenticatorConfigurator sharedConfig] turnOffSSLPinning];

// Turn ON
[[AuthenticatorConfigurator sharedConfig] turnOnSSLPinning];

Swift:

// Turn OFF
AuthenticatorConfigurator.sharedConfig().turnOffSSLPinning()

// Turn ON
AuthenticatorConfigurator.sharedConfig().turnOnSSLPinning()

Customizing Device Linking

You can customize your implementation of device linking. To do this, pass a valid linking code to the following call. Include a device name if necessary, or pass nil as the device name and the SDK will populate the device name based on the current OS device name. If you want to enable the end-user to override the device name, set deviceNameOverride to YES.

Objective-C:

NSString *qrCode = @"ABCD123";
BOOL deviceNameOverride = YES;


[[AuthenticatorManager sharedClient] linkUser:qrCode withDeviceName:deviceName deviceNameOverride:deviceNameOverride withCompletion:^(NSError *error)
{
    if(error!=nil)
    {
        // Check error
    }
    else
    {
        // End-user has successfully linked
    }
}];

Swift:

let qrCode = "ABCD123"


AuthenticatorManager.sharedClient().linkUser(qrCode, withDeviceName:nil, deviceNameOverride:true, withCompletion: { (error) in
    if((error) != nil)
    {
        // Check error
    }
    else
    {
        // End-user has successfully linked
    }
})

Then to determine whether an end-user has been successfully linked, call isAccountActive.

Objective-C:

if([[AuthenticatorManager sharedClient] isAccountActive])
{
    // End-user's device is linked
}

Swift:

if(AuthenticatorManager.sharedClient().isAccountActive())
{
    // End-user's device is linked
}

Configurable Thresholds (v4.7.0 and up)

We have added support for a few different thresholds that can be configured via the AuthenticatorConfig Builder. The thresholds are defined as follows:

• Authentication Failure Threshold

  The threshold at which failed authentication attempts result in a “Failure:Authentication” response. This feature is limited to PIN Code and Circle Code and work on a per Auth Request basis. The new default failure threshold for these auth methods will be 5 attempts. For code examples, please reference the code examples in the AuthenticatorConfig Builder Properties section above.

• Auto-Unlink Threshold

  The threshold at which failed authentication attempts result in the unlinking of the authenticator. This feature applies to every single authentication method. The default (and maximum) value for this threshold is 10 attempts. The minimum value for this threshold is 2 attempts. For code examples, please reference the code examples in the AuthenticatorConfig Builder Properties section above.

• Auto-Unlink Warning Threshold

  The threshold after which successive failed authentication attempts displays a warning to the End User (regarding the potential for their authenticator to be auto-unlinked). This feature applies to every single authentication method. The default value for this threshold is 2 attempts less than the auto-unlink threshold. The maximum value for this threshold is 1 less than the auto-unlink threshold. The minimum value for this threshold is 0, which means no auto-unlink warning is displayed. For code examples, please reference the code examples in the AuthenticatorConfig Builder Properties section above.

Verifying Current Security Factors

Use getSecurityInfo, available in the AuthenticatorManager, to return an NSArray to list out the factors, types, and whether they are active.

Objective-C:

NSArray *securityFactorArray = [[AuthenticatorManager sharedClient] getSecurityInfo];

Swift:

let securityFactorArray = AuthenticatorManager.sharedClient().getSecurityInfo()

Third-Party Library Info (v4.0.0 and up)

Use getThirdPartyLibraryInfo, available in the AuthenticatorManager, to return an NSArray that lists out all Third Party Libraries included within the Authenticator SDK (name, version, license, and url).

Objective-C:

NSArray *thirdPartyLibraries = [[AuthenticatorManager sharedClient] getThirdPartyLibraryInfo];

Swift:

let thirdPartyLibraries = AuthenticatorManager.sharedClient().getThirdPartyLibraryInfo()

Displaying Linked Devices

As of Authenticator SDK v4.8.0 and up, use LKDeviceManager to manage device actions. You can also use these methods to implement a custom view. Use DevicesViewController to bring up the default Devices view available from the Authenticator SDK.

If you are using a version of the Authenticator SDK below v4.8.0, use DevicesViewController to manage device actions or bring up the default Devices view available from the Authenticator SDK.

First, import DevicesViewController.h, LKDeviceManager.h, and IOADevice.h:

#import <Authenticator/DevicesViewController.h>
#import <Authenticator/LKDeviceManager.h>
#import <Authenticator/IOADevice.h>

To display the default Devices view, initialize DevicesViewController and display the default view in a container view.

Objective-C:

DevicesViewController *devicesChildView = [[DevicesViewController alloc] initWithParentView:self];

[self addChildViewController:devicesChildView];
[self.containerView addSubview:devicesChildView.view];
[devicesChildView didMoveToParentViewController:self];

Swift:

var devicesChildView:DevicesViewController!
devicesChildView = DevicesViewController.init(parentView: self)

self.addChildViewController(devicesChildView)
containerView.addSubview(devicesChildView.view)
devicesChildView.didMove(toParentViewController: self)

If using Authenticator SDK v4.8.0 and up, use the following methods to perform device-related tasks.

Objective-C:

NSArray *devicesArray;

// Get the current IOADevice object
IOADevice *currentDevice = [LKDeviceManager currentDevice];
NSLog(@"current device name = %@", currentDevice.name);


// Call getDevices to get a NSArray of IOADevice objects
[LKDeviceManager getDevices:^(NSArray* array, NSError *error)
{
    if(error)
    {
        // Check error
        NSLog(@"error: %@", error);
    }
    else
    {
        devicesArray = array;
        for(IOADevice *deviceObject in devicesArray)
        {
            NSLog(@"device name: %@", deviceObject.name);
            NSLog(@"device status: %lu", (unsigned long)deviceObject.status);
            NSLog(@"device uuid: %@", deviceObject.UUID);
            NSLog(@"device type: %@", deviceObject.type);
        }
    }
}];

Swift:

var devicesArray = [IOADevice]()

// Call getDevices to get a NSArray of IOADevice objects
LKDeviceManager.getDevices { (array, error) in
    if((error) != nil)
    {
        // Check error
        print("\(error)")
    }
    else
    {
        devicesArray = array!
        for item in devicesArray
        {
            let deviceObject = item
            print("device name: \(deviceObject.name)")
        }
    }
}

If using a version of the Authenticator SDK below v4.8.0, use the following methods to perform device-related tasks.

Objective-C:

DevicesViewController *devicesView;
NSArray *devicesArray;

devicesView = [[DevicesViewController alloc] initWithParentView:self];

// Get the current IOADevice object
IOADevice *currentDevice = [devicesView currentDevice];
NSLog(@"current device name = %@", currentDevice.name);


// Call getDevices to get a NSArray of IOADevice objects
[devicesView getDevices:^(NSArray* array, NSError *error)
{
    if(error)
    {
        // Check error
        NSLog(@"error: %@", error);
    }
    else
    {
        devicesArray = array;
        for(IOADevice *deviceObject in devicesArray)
        {
            NSLog(@"device name: %@", deviceObject.name);
            NSLog(@"device status: %lu", (unsigned long)deviceObject.status);
            NSLog(@"device uuid: %@", deviceObject.UUID);
            NSLog(@"device type: %@", deviceObject.type);
        }
    }
}];

Swift:

var devicesArray = [IOADevice]()
var devicesChildView:DevicesViewController!
devicesChildView = DevicesViewController.init(parentView: self)

// Call getDevices to get a NSArray of IOADevice objects
devicesChildView.getDevices { (array, error) in
    if((error) != nil)
    {
        // Check error
        print("\(error)")
    }
    else
    {
        devicesArray = array!
        for item in devicesArray
        {
            let deviceObject = item
            print("device name: \(deviceObject.name)")
        }
    }
}

Managing Sessions

As of Authenticator SDK v4.8.0 and up, use LKSessionManager to manage session-related tasks. You can also use these methods to implement a custom view. Use SessionsViewController to bring up the default Sessions view available from the Authenticator SDK.

If you are using a version of the Authenticator SDK below v4.8.0, use SessionsViewController to manage session-related tasks or bring up the default Sessions view available from the Authenticator SDK.

First, import SessionsViewController.h, LKSessionManager.h, and IOASession.h:

#import <Authenticator/SessionsViewController.h>
#import <Authenticator/LKSessionManager.h>
#import <Authenticator/IOASession.h>

To display the default Sessions view, initialize SessionsViewController and display the default view in a container view.

Objective-C:

SessionsViewController *sessionsChildView = [[SessionsViewController alloc] initWithParentView:self];

[self addChildViewController:sessionsChildView];
[self.containerView addSubview:sessionsChildView.view];
[sessionsChildView didMoveToParentViewController:self];

Swift:

var sessionsChildView:SessionsViewController!
sessionsChildView = SessionsViewController.init(parentView: self)

self.addChildViewController(sessionsChildView)
containerView.addSubview(sessionsChildView.view)
sessionsChildView.didMove(toParentViewController: self)

You can use the following methods to manage session-related tasks and create a custom Sessions View if needed. Call -getSessions to get a NSArray of all the currently active IOASession objects. Each IOASession object contains four properties so that you can easily create a custom designed view of Sessions: serviceName, serviceID, serviceIcon, and dateCreated.

If using Authenticator SDK v4.8.0 and up, use the following methods to manage session-related tasks.

Objective-C:

NSArray *sessionsArray;

// Call getSessions to get a NSArray of all the IOASession objects
[LKSessionManager getSessions:^(NSArray* array, NSError *error)
{
    if(error)
    {
        NSLog(@"error: %@", error);
    }
    else
    {
        sessionsArray = array;
        for(IOASession *sessionObject in sessionsArray)
        NSLog(@"session name: %@", sessionObject.serviceName);
    }
}];


// End a specific session
IOASession *sessionObject = [sessionsArray objectAtIndex:indexPath.row];
[LKSessionManager endSession:sessionObject completion:nil];


// End all sessions
[LKSessionManager endAllSessions:^(NSError *error)
{
    if(error != nil)
    {
        // Check error
        NSLog(@"Error: %@", error);
    }
    else
    {
        // All sessions have been successfully cleared
    }
}];

Swift:

var sessionsArray = [IOASession]()

// Call getSessions to get a NSArray of all the IOASessions objects
LKSessionManager.getSessions { (array, error) in
    if((error) != nil)
    {
        // Check error
        print("\(error)")
    }
    else
    {
        sessionsArray = array!
        for item in sessionsArray
        {
            let sessionObject = item
            print("session name: \(sessionObject.serviceName)")
        }
    }
}


// End a specific session
LKSessionManager.end(sessionsArray[row], completion: nil)

// End All sessions
LKSessionManager.endAllSessions{(error) in
    if((error) != nil)
    {
        // Check error
        print("\(error)")
    }
    else
    {
        // All sessions have been successfully cleared
    }
}

If using a version of the Authenticator SDK below v4.8.0, use the following methods to manage session-related tasks.

Objective-C:

SessionsViewController *sessionsView;
NSArray *sessionsArray;
sessionsView = [[SessionsViewController alloc] initWithParentView:self];

// Call getSessions to get a NSArray of all the IOASession objects
[sessionsView getSessions:^(NSArray* array, NSError *error)
{
    if(error)
    {
        NSLog(@"error: %@", error);
    }
    else
    {
        sessionsArray = array;
        for(IOASession *sessionObject in sessionsArray)
        NSLog(@"session name: %@", sessionObject.serviceName);
    }
}];


// End a specific session
IOASession *sessionObject = [sessionsArray objectAtIndex:indexPath.row];
[sessionsView clearSession:sessionObject];


// End all sessions
[sessionsView endAllSessions:^(NSError *error)
{
    if(error != nil)
    {
        // Check error
        NSLog(@"Error: %@", error);
    }
    else
    {
        // All sessions have been successfully cleared
    }
}];

Swift:

var sessionsArray = [IOASession]()
var sessionsView:SessionsViewController!


// Call getSessions to get a NSArray of all the IOASessions objects
sessionsView.getSessions { (array, error) in

    if((error) != nil)
    {
        // Check error
        print("\(error)")
    }
    else
    {
        sessionsArray = array!
        for item in sessionsArray
        {
            let sessionObject = item
            print("session name: \(sessionObject.serviceName)")
        }
    }
}


// End a specific session
sessionsView.clear(sessionsArray[row])

// End All sessions
    sessionsView.endAllSessions{(error) in
    if((error) != nil)
    {
        // Check error
        print("\(error)")
    }
    else
    {
        // All sessions have been successfully cleared
    }
}

Setting Key Pair Size

Linking a device creates a key pair. You can use AuthenticatorConfigurator to set its size. The size can be between 2048-4096 bits; if the value is outside of the range, it is set to the nearest valid value, or it will be invalid. By default, if you do not set a key pair size, it is 4096. There are constants available in AuthenticatorConfigurator for common key pair sizes. NOTE Set the key pair size before initializing the SDK.

As of Authenticator SDK v4.6.0 and up, please reference the code examples in the AuthenticatorConfig Builder Properties section above. If using a version of the SDK below v4.6.0, please use the following examples for reference.

Objective-C:

[[AuthenticatorConfigurator sharedConfig] setKeyPairSize:keypair_maximum];

Swift:

AuthenticatorConfigurator.sharedConfig().setKeyPairSize(keypair_maximum)

Listening To Events via NSNotificationCenter

There are specific events that you can add observers to so that you can implement your own UI. Here are a list of observers you can add:

requestReceived: Add an observer for requestReceived to be notified when an auth request has been received. You can call -checkForPendingAuthRequest to bring up the auth request once the notification has been broadcasted.

deviceUnlinked: Add an observer for deviceUnlinked to be notified when the device has been unlinked successfully or when the API returns an error indicating the device is unlinked.

requestApproved: Add an observer for requestApproved to be notified when an auth request has been approved.

requestDenied: Add an observer for requestDenied to be notified when an auth request has been denied.

DeviceKeyPairGenerated: Add an observer for DeviceKeyPairGenerated to be notified once the key pair generation has been completed.

Automatic Linking of a Device

If your mobile app is supported by its own backend system, then the backend can generate a valid linking code, directly interacting with the TruValidate Multifactor Authentication API, and pass it down to the mobile app. This process can be triggered only when the end user has successfully provided traditional credentials to your system which would allow for the device to be automatically linked on their behalf.

This is a scenario that would require deeper integration which would otherwise have the end user type/scan the code themselves instead.

Metrics (v4.3.0 and up)

We have added collection of anonymous metrics to better support the service and understand the behavior of the Authenticator SDK in order to make improvements in newer versions. In order to help implementors provide collected metrics to our service whenever necessary, there is a public method added to the AuthenticatorManager that can be used as follows:

Objective-C:

[[AuthenticatorManager sharedClient] sendMetricsWithCompletion:^(NSError *error)
{
    if(error == nil)
    {
        // Metrics were successfully sent
    }
    else
    {
        // Check error
    }
}];

Swift:

AuthenticatorManager.sharedClient().sendMetrics(completion: { (error) in
    if(error == nil)
    {
        // Metrics were successfully sent
    }
    else
    {
        // Check error
    }
})

Overview

You can customize a number of user interface (UI) elements in the Security and Auth Request views by setting colors using the UIAppearance proxy settings. The Authenticator has subclassed some UI elements so that they can be modified via the UIAppearance proxy as well. Please see this Apple document for further explanation on how to use the UIAppearance proxy. Any UI element that is not subclassed means it can be customized via the proxy and any property of a subclassed item that is not listed in the table below also means it can be customized through default methods of the proxy.

Import Headers

In order to customize UI elements, import the following subclassed UI elements:

#import <Authenticator/PinCodeButton.h>
#import <Authenticator/CircleCodeImageView.h>
#import <Authenticator/AuthenticatorButton.h>
#import <Authenticator/AuthorizationSliderButton.h>
#import <Authenticator/AuthorizationSlider.h>
#import <Authenticator/SecurityFactorTableViewCell.h>
#import <Authenticator/AuthRequestContainer.h>
#import <Authenticator/IOALabel.h> // Available in v3.0.5 and up
#import <Authenticator/IOATextField.h> // Available in v4.4.0 and up
#import <Authenticator/AuthResponseButton.h> // Available in v4.6.0 and up
#import <Authenticator/AuthResponseNegativeButton.h> // Available in v4.6.0 and up
#import <Authenticator/AuthResponseExpirationTimerView.h> // Available in v4.6.0 and up

UI Customization Definitions

Set Custom Font

If you want to set custom fonts, determine whether the fonts are supported by Xcode, then:

• If they are supported, pass the font names as NSString values to the customFont property of the AuthenticatorConfig builder.
• If not, import the font files to your project, include them in the targets, and add them to the .plist under a new row called Fonts provided by application. In this row, include all of the font names in an array.

Dark Mode

Dark Mode on devices running iOS 13+ is natively supported by Xcode 11. Your application can define colors that our views in the SDK will honor for applications running in Dark Mode. In order to support Dark Mode, you must define colors either through the UIAppearance proxy or by setting the color properties and building our AuthenticatorConfig object. Default colors and dark mode colors must be defined, or you can use the newly added dynamic system colors that ensures proper contrast automatically. Please see this Apple Human Interface Guideline for further explanation on Dark Mode.

For example, you can define the background and fill colors of the AuthResponseButton as such, and the tint of the colors will adapt to the current system interface.

Objective-C:

[AuthResponseButton appearance].backgroundColor = [UIColor systemBlueColor];
[AuthResponseButton appearance].fillColor = [UIColor systemPurpleColor];

Swift:

AuthResponseButton.appearance().backgroundColor = UIColor.systemBlue
AuthResponseButton.appearance().fillColor = UIColor.systemPurple

Overview

TransUnion recommends adding push notifications to your integrations in order to provide a better experience for end users. We also recommend providing a mechanism to manually review notifications, because push notifications depend on many interrelated systems to work, such as mobile carrier availability and Apple performance.

At a high level, the setup steps include:

1. Register for an Apple Push Notification token.
2. Register the token with the SDK.
3. Obtain an Apple Push Notification Certificate.
4. Set up interception of push notifications.

Registering for an Apple Push Notification Token

To identify a device and to receive push notifications from the TruValidate Multifactor Authentication platform, you must register for an Apple Push Notification token:

Objective-C:

[[UIApplication sharedApplication] registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:(UIUserNotificationTypeSound | UIUserNotificationTypeAlert | UIUserNotificationTypeBadge) categories:nil]];
[[UIApplication sharedApplication] registerForRemoteNotifications];

Swift:

let userNotifications = UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
UIApplication.shared.registerUserNotificationSettings(userNotifications)
UIApplication.shared.registerForRemoteNotifications()

Registering the Device Token

You must register the device token with the Authenticator SDK using the didRegisterForRemoteNotificationsWithDeviceToken function in the AppDelegate callback.

Objective-C:

[[AuthenticatorManager sharedClient] setNotificationToken:deviceToken];

Swift:

AuthenticatorManager.sharedClient().setNotificationToken(deviceToken)

Obtaining an Apple Push Notification Certification

You must obtain an Apple Push Notification Certification before the TruValidate Multifactor Authentication platform can send push notifications to your mobile app. These instructions assume that you have already set up push notifications for your app. To do this:

1. Log in to the Apple Developer Portal at: https://developer.apple.com
2. Click the Certifications, IDs & Profiles section.
3. Under Certificates, locate the Production Push Notification certificate that you create for your app (the same certificate that you use in production now for your app). Download the certificate.
4. Double-click the local certificate file to add it to your keychain’s Certificate section.
5. Open Keychain Access.
6. Select Certificates and click the arrow beside the certificate you just downloaded. This displays the associated key. Select both the certificate and key, right-click and choose Export 2 items.
7. Save the certificate with a .p12 file extension and leave the password field empty.
8. Log in to TruValidate Multifactor Authentication Admin Center at https://admin.launchkey.com/login.
9. Click Organizations and select your organization. Click the Directories tab. Select the Directory for which you want to authorize push notifications.
10. Select the Push Notifications tab and upload your certificate under the iOS section.

Setting Up Interception of Push Notifications

In order to intercept push notifications, use the didReceiveRemoteNotification callback in the AppDelegate. Pass the userInfo to the following call and add the requestReceived observer.

Objective-C:

[[AuthenticatorManager sharedClient] handleRemoteNotification:userInfo];

Swift:

AuthenticatorManager.sharedClient().handleRemoteNotification(userInfo)

Third-Party Push Notification Services (v4.5.0 and up)

We have added support for third-party push notification services by providing a new method in the AuthenticatorManager class that takes the push package string provided by our TruValidate Multifactor Authentication API and parses the string to generate the appropriate push notification NSNotification (either requestReceived or deviceUnlinked).

For example:

Objective-C:

[[AuthenticatorManager sharedClient] handlePushPackage:@"push_package_string"];

Swift:

AuthenticatorManager.sharedClient().handlePushPackage("push_package_string")

What’s new with v4.2

• Knowledge factors are not mutually exclusive anymore. The behavior changed to support more than one knowledge factor at a time if the End User decides to set more than one up.

What’s new with v4.3

• Collection of anonymous metrics to better support the service and understand the behavior of the Authenticator SDK in order to make improvements in newer versions. Please reference the Metrics (v4.3.0 and up) section above for further integration details.

What’s new with v4.5

• Added support for third-party push notification services. Please reference the Third-Party Push Notification Services (v4.5.0 and up) section above for further integration details.

What’s new with v4.6

• All new Auth Request Flow

  The Auth request flow now has tap and holdable Authorize and Deny buttons, a visible expiration timer and request details. These new features allow users to get all the info they need to make the right decision the first time.

• Added support for Auth Denial Context

  This feature provides Customers with context as to why an end user denied a request, thereby enabling the Customer to take more appropriate action.

• Added the ability for Customers to receive a response when a request fails due to an end user unable to verify an auth method.

  Ensuring that Customer know whenever user authentication fails during a request is important for identifying fraud, assessing future risk, troubleshooting with end users, and distinguishing between the many different response scenarios that TruValidate Multifactor Authentication supports.

• The verification and priority order of the Auth Methods has been updated

  When an auth request gets sent, the order in which the methods are verified is the same for both Android and iOS.

  • The order displayed to the End User for verification is as follows:

    1. Wearable
    2. Geofencing
    3. PIN Code
    4. Circle Code
    5. Face Scan
    6. Fingerprint Scan

  • The priority of the Auth Methods when the policy is requesting by AMOUNT is as follows:

    1. Fingerprint Scan
    2. Face Scan
    3. PIN Code
    4. Circle Code
    5. Wearable
    6. Geofencing

  • The priority of the Auth Methods when the policy is requesting them by TYPE is as follows:

    KNOWLEDGE

    1. PIN Code
    2. Circle Code

    INHERENCE

    1. Fingerprint Scan
    2. Face Scan
    3. Geofencing

    POSSESSION

    1. Wearable

What’s new with v4.7

• Added support for a configurable Auth Failure threshold via the AuthenticatorConfig Builder. Please reference the Configurable Thresholds (v4.7.0 and up) section above for further integration details.
• Added support for a configurable Auto-Unlink threshold via the AuthenticatorConfig Builder. Please reference the Configurable Thresholds (v4.7.0 and up) section above for further integration details.
• Added support for a configurable Auto-Unlink Warning threshold via the AuthenticatorConfig Builder. Please reference the Configurable Thresholds (v4.7.0 and up) section above for further integration details.

What’s new with v4.8

• Added LKDeviceManager to manage device actions. Please reference the Displaying Linked Devices section above for further integration details.
• Added LKSessionManager to manage session-related actions. Please reference the Managing Sessions section above for further integration details.
• Deprecated the LocalAuthManager class and methods.

What’s new with v4.9

• Updated Authenticator SDK to be built as a dynamic framework. Please reference the Integrating the iOS SDK into Your App section (Step #2) above for further integration details.
• Updated Auth Request behavior to ensure that End Users can always capture denial context, even when they fail the Auth Request due to Policy or Configuration.
• Added support for generating and sending the FraudForce Blackbox to the TruValidate Multifactor Authentication API, if a supported version of the FraudForce SDK is included at the app-level (the minimum FraudForce SDK version supported is v5.0.3). To add the FraudForce SDK to your mobile app, you must include it as an embedded framework. Please reference the FraudForce SDK GitHub page for further integration details. Note: If submitting an app with Auth SDK v4.9.0 and without the FraudForce SDK, the app should uncheck “Include bitcode for iOS content” in order for the app to be successfully submitted to App Store Connect.

Best Practices

• Display an active Session after authorizing an Auth Request

  There’s no direct correlation between an Auth Request and an active Session. It is up to the Customer’s service to handle the response of Auth Requests and then request the TruValidate Multifactor Authentication API to start a Session if desired. There is a bit of a delay between the End User responding to an Auth Request and your service as an implementer handling the response, so it is recommended to add a short delay of a few seconds to retrieve the list of active Sessions after responding to an Auth Request.

• Update device token for Push Notifications

  Always make sure to update a new/changed device token meant for Push Notifications in order for the TruValidate Multifactor Authentication service to keep an updated record and notify the End Users of pending Auth Requests. We recommend always registering the device token with the Authenticator SDK with -(void)setNotificationToken:(NSData *)deviceToken.

• Keep the Authenticator SDK up to date

  Updates will include improvements, security patches, and/or new features that will enhance the user experience of End Users if the release increases its minor version. Should a major version be released, keep an eye on the docs on how to migrate over to utilize the latest Authenticator SDK.

• Keep SSL Pinning enabled

  SSL Pinning could prove troublesome if proxies are inherent to an application or service but can enhance the security of a product by preventing Man-in-the-Middle attacks.

• Do NOT allow restore from backups

  In order to prevent any potential issues that can arise from using a backup of your mobile application, we recommend not allowing your mobile application to be restored from a backup.

• Configure Portrait mode only for device orientation

  The Authenticator SDK is currently optimized for Portrait mode only. We recommend configuring your mobile application to be in Portrait mode only in order for the UI to stay consistent when interacting with security factors during setup or in the middle of an Auth Request. Support for Landscape device orientation may come in the future but is NOT part of the product roadmap at this point.

• Listen for important events

  In the main view/home view of your mobile application, ensure that you are listening to important events like receiving an Auth Request or the unlinking of a device, etc. in order to keep the UI, and the End Users, updated.

• Always provide ability to manually refresh data

  While we rely heavily on Push Notifications to notify the End User of pending Auth Requests in a timely manner, it is important to remember that is still an external service outside the scope of the TruValidate Multifactor Authentication service, and delays or drops of Push Notifications can happen at times. Allowing the End User to check pending Auth Requests and refresh the list of active Sessions or linked authenticators will come a long way during these few instances.

• Issues with an authenticator communicating with your service

  Always check the TruValidate Multifactor Authentication Admin Center and ensure all keys are matching the ones on your end–including the Authenticator SDK key used to initialize the AuthenticatorManager shared client.

• Protect sensitive data on-screen

  We recommend protecting any sensitive data that is on-screen when a device goes into “App Switcher” mode. Include [[UIApplication sharedApplication] ignoreSnapshotOnNextApplicationLaunch] in the - (void)applicationWillResignActive:(UIApplication *)application method of the App Delegate and add an image view as a subview on top of the current view. You can remove tihs subview in the - (void)applicationDidBecomeActive:(UIApplication *)application method of the App Delegate.

• Require security factors at all times

  If you’re certain your Service will always require at least one security factor, then it is possible for the implementing app to be aware of how many factors have been set and have its own UI update and guide the user towards the Security view to set one up.

  Use getSecurityInfo, available in the AuthenticatorManager, and based on the array returned, update the UI accordingly.