Contents
This document walks you through integrating TruValidate Multifactor Authentication with iOS apps.
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.
Before integrating the TruValidate Multifactor Authentication Authenticator SDK with your app, an administrator must complete the following steps:
You are now ready to integrate the TruValidate Multifactor Authentication SDK into your mobile apps.
Follow these steps to integrate the TruValidate Multifactor Authentication SDK for iOS into your app. This includes examples and instructions for Objective-C and swift.
Download the SDK from https://github.com/iovation/launchkey-ios-authenticator-sdk/releases
Add the Authenticator framework to your project:
If using Authenticator SDK v4.9.0+:
In Xcode 11, add Authenticator.framework
to your project, as an embedded framework. Ensure the framework is visible in your build
target’s Frameworks, Libraries, and Embedded Content with the option Embed & Sign selected.
In Xcode 10 and earlier, ensure the framework is visible in your build target’s Embedded Binaries and Linked Frameworks and Libraries.
If using a version of the Authenticator SDK below v4.9.0:
In Xcode, add Authenticator.bundle
and Authenticator.framework
to your project. Make sure that they are visible
under Copy Bundle Resources in your target’s Build phase. Also ensure that Authenticator.framework
appears
under Link Binary With Libraries.
Add the following .plist permissions to your project and provide description values for each:
If you would like to support Face ID on iPhone X devices and you are using v4.1.0+ of the Auth SDK, please also include the following .plist permission in your project and provide a description value:
If you are using Xcode 11, you must include the following .plist permission and provide a description as well:
If using Authenticator SDK v4.9.0+:
Import the Authenticator as follows:
Objective-C:
#import <Authenticator/Authenticator.h>
Swift:
import Authenticator
If using a version of the Authenticator SDK below v4.9.0:
Import Authenticator.framework
to your app delegate or, for Swift projects, your Bridging-Header.h file:
#import <Authenticator/AuthenticatorManager.h>
We recommend you initialize the SDK once your application has been launched, within the App Delegate, under application:didFinishLaunchingWithOptions.
As of Authenticator SDK v4.6.0 and up, you should initialize the SDK via building a new AuthenticatorConfig
object and setting the Authenticator SDK Key,
along with the other builder properties you desire for the app, which is explained in AuthenticatorConfig Builder Properties section below. For example:
Objective-C:
AuthenticatorConfig *config = [AuthenticatorConfig makeWithAuthenticatorConfigBuilder:^(AuthenticatorConfigBuilder *builder) {
builder.sdkKey = @"<Authenticator_SDK_Key>";
}];
[[AuthenticatorManager sharedClient] initialize:config];
Swift:
let config = AuthenticatorConfig.make {builder in
builder?.sdkKey = "<Authenticator_SDK_Key>"
}
AuthenticatorManager.sharedClient().initialize(config)
If you are using a version of the Authenticator SDK below v4.6.0, you should initialize the AuthenticatorManager shared client with your Authenticator SDK Key as follows::
// Initialize the SDK Manager
[[AuthenticatorManager sharedClient] initSDK:@"<Authenticator_SDK_Key>"];
To enable users to link their devices, specify a linking mechanism. You can enable either QR code scanning by passing a YES or the ability to manually enter their linking code by passing NO.
If using Authenticator SDK v4.7.0+, call the following method:
Objective-C:
[[AuthenticatorManager sharedClient] showLinkingView:self.navigationController withCamera:YES withCompletion:^(NSError *error)
{
if(error == nil)
{
// End-user has been successfully linked
}
else
{
// Check error
}
}];
Swift:
AuthenticatorManager.sharedClient()?.showLinkingView(self.navigationController, withCamera: true, withCompletion: {(error) in
if(error == nil)
{
// End-user has been successfully linked
}
else
{
// Check error
}
})
If using Authenticator SDK v4.6.1 and below, call the following method:
Objective-C:
[[AuthenticatorManager sharedClient] showLinkingView:self.navigationController withCamera:YES withLinked:^{
// Success block
// End-user has been successfully linked
} withFailure:^(NSString *errorMessage, NSString *errorCode) {
// Failure block
// Check error
}];
Swift:
AuthenticatorManager.sharedClient().showLinkingView(self.navigationController, withCamera: true, withLinked: {() in
// Success block
// End-user has been successfully linked
}, withFailure:{(errorMessage, errorCode) in
// Failure block
// Check error
})
To check for and present a pending Auth Request, as of Authenticator SDK v4.2.0+, import the AuthRequestManager.h file:
#import <Authenticator/AuthRequestManager.h>
Then call the following method and if there is an Auth Request, the Auth Request View will be pushed on to the navigation stack:
Objective-C:
// Check For Pending Auth Request
[[AuthRequestManager sharedManager] checkForPendingAuthRequest:self.navigationController withCompletion:^(NSString *message, NSError *error)
{
if(error != nil)
{
// Check error
}
else
{
// Check message to see if response to auth request was successful or if there are no pending auth requests
NSLog(@"Message: %@", message);
}
}];
Swift:
// Check For Pending Auth Request
AuthRequestManager.shared().check(forPendingAuthRequest: self.navigationController, withCompletion: { (message,error) in
if((error) != nil)
{
// Check error
}
else
{
// Check message to see if response to auth request was successful or if there are no pending auth requests
print("\(message)")
}
})
Please note the following class and methods have been deprecated in v4.2.0 of the Authenticator SDK and will be removeed in a future major release. For Authenticator SDK v4.1.1 and below, to create a view where users can view auth requests, first import the AuthRequestViewController.h file:
#import <Authenticator/AuthRequestViewController.h>
Then, initialize AuthRequestViewController and define a Container view where you can embed the auth request view.
Objective-C:
AuthRequestViewController *requestChildView = [[AuthRequestViewController alloc] initWithParentView:self];
[self addChildViewController:requestChildView];
[self.containerView addSubview:requestChildView.view];
[requestChildView didMoveToParentViewController:self];
// Check For Pending Auth Request
[authRequestChildView checkForPendingAuthRequest:self.navigationController withCompletion:^(NSString *message, NSError *error)
{
if(error != nil)
{
// Check error
}
else
{
// Check message to see if response to auth request was successful or if there are no pending auth requests
NSLog(@"Message: %@", message);
}
}];
Swift:
var authRequestView:AuthRequestViewController!
authRequestView = AuthRequestViewController.init(parentView: self)
self.addChildViewController(authRequestView)
containerView.addSubview(authRequestView.view)
authRequestView.didMove(toParentViewController: self)
// Check For Pending Auth Request
authRequestView.check(forPendingAuthRequest: self.navigationController, withCompletion: { (message,error) in
if((error) != nil)
{
// Check error
}
else
{
// Check message to see if response to auth request was successful or if there are no pending auth requests
print("\(message)")
}
})
End-users can choose their own security factors. Services can be set to require users to set a minimum number of factors. Implement the following to enable users to use the Security Factors view and choose their security factors.
Objective-C:
[[AuthenticatorManager sharedClient] showSecurityViewWithNavController:self.navigationController withUnLinked:^{
}];
Swift:
AuthenticatorManager.sharedClient().showSecurityView(withNavController: self.navigationController, withUnLinked: {() in
})
Implement the IOADevice object to unlink either the current device or a remote device.
Objective-C:
[[AuthenticatorManager sharedClient] unlinkDevice:nil withCompletion:^(NSError *error){
if(error != nil)
{
// Check error
}
else
{
// Device has been successfully unlinked
}
}];
Swift:
AuthenticatorManager.sharedClient().unlinkDevice(nil, withCompletion: { (error) in
if((error) != nil)
{
// Check error
}
else
{
// Device has been successfully unlinked
}
})
Remember to set a default background color for your application from within the App Delegate. If this is not set, the background color of the default views inside the Authenticator SDK may be set to transparent.
Objective-C:
// To set background color of all views
self.window.backgroundColor = [UIColor whiteColor];
Swift:
// To set background color of all views
self.window?.backgroundColor = UIColor.white
This completes the core integration. Continue on to the next section for advanced integration options.
Now that the TruValidate Multifactor Authentication(MFA) SDK for iOS is integrated and the basics are working, let’s move on to more advanced integration options. We’ll start by reviewing the technical components that make up advanced MFA integration.
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
}
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)
Warning
Setting the activation delay to 0 can potentially allow anyone to bypass passive security factors. They can do this by adding new, unintended passive factors and setting the verification toggle to only verify when required. If the user then immediately attempts to authenticate, the new passive factor will not be verified. For this reason, we strongly suggest setting the value to a minimum of ten minutes / 600 seconds.
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.
Note
SSL pinning is turned OFF by default.
Warning
SSL pinning should only be enabled if you fully understand the consequences of enabling this feature as connectivity to the TruValidate Multifactor Authentication Platform API can be interrupted if SSL pinning is not properly configured.
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()
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
}
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.
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()
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()
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)")
}
}
}
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
}
}
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)
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.
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.
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
}
})
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.
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
Subclassed Item Name | UI Element Type | Property/Method | Description | Objective-C / Swift Examples |
PinCodeButton | UIButton | highlightedStateColor | UIColor displayed when a PIN Code button is pressed |
|
lettersColor | UIColor set for letters in the PIN Code button (available in v3.0.5 and up) |
|
||
bulletColor | UIColor set for bullets in the PIN Code view when verifying and removing a PIN Code (available in v4.1.0 and up) |
|
||
-setPinCodeButtonAsCircle:(BOOL)asCircle | Method to set the PIN Code Button shape as either a circle (pass YES/true) or square (pass NO/false) |
|
||
-setBorderColor:(UIColor*)borderColor | UIColor set for PIN Code button border (available in v4.1.0 and up) |
|
||
-setBorderWidth:(CGFloat)borderWidth | CGFloat set for PIN Code button width (available in v4.1.0 and up) |
|
||
CircleCodeImageView | UIImageView | defaultColor | Default UIColor set for the Circle Code center and hashmarks |
|
highlightColor | UIColor set for the Circle Code center and sectors when pressed on |
|
||
AuthenticatorButton | UIButton | negativeActionTextColor | UIColor set for the text color of the UIButtons that are representative of negative actions (available in v4.0.0 and up) |
|
negativeActionBackgroundColor | UIColor set for the background color of the UIButtons that are representative of negative actions (available in v4.0.0 and up) |
|
||
AuthorizationSlider deprecated in v4.6.0 | UIImageView | topColor | UIColor representative of the top track of the Authorization Slider |
|
bottomColor | UIColor representative of the bottom track of the Authorization Slider, exposed when the button is dragged upwards |
|
||
AuthorizationSliderButton deprecated in v4.6.0 | UIButton | highlightedStateColor | UIColor displayed when the button of the AuthorizationSlider is pressed |
|
SecurityFactorTableViewCell | UITableViewCell | imagePINCodeFactor | UIImage displayed in the Table of Security Factors for Pin Code |
|
imageCircleCodeFactor | UIImage displayed in the Table of Security Factors for Circle Code |
|
||
imageBluetoothFactor | UIImage displayed in the Table of Security Factors for Bluetooth Proximity |
|
||
imageGeofencingFactor | UIImage displayed in the Table of Security Factors for Geofencing |
|
||
imageFingerprintFactor | UIImage displayed in the Table of Security Factors for Fingerprint/Face Scan |
|
||
AuthRequestContainer | UIView | imageAuthRequestGeofence | UIImage displayed during an Auth Request for Geofencing |
|
imageAuthRequestBluetooth | UIImage displayed during an Auth Request for Bluetooth Proximity |
|
||
IOLabel | UILabel | textColor | UIColor set for the text color of labels in Security View and Add Bluetooth Proximity View (available in v3.0.5 and up) |
|
IOTextField | UITextField | placeholderTextColor | UIColor set for the placeholder text of the IOATextField, in the manual linking view (available in v4.4.0 and up) |
|
AuthenticatorConfigurator This class and all it’s methods are now deprecated. Please build an AuthenticatorConfig object and initalize the SDK with the AuthenticatorManager instead. | NSObject | -setFont:(NSString*)customFont | Method used to set a custom font throughout the SDK views |
|
-enableInfo:(BOOL)enable | Method to enable/disable Info buttons in the Security views |
|
||
-enableHeaderViews:(BOOL)enable | Method to enable/disable TableView Headers |
|
||
-enableSecurityFactorImages:(BOOL)enable | Method to enable/disable Security Factor Images in the TableView of the Security view |
|
||
-setControlsBackgroundColor:(UIColor*)color | Method to set the background color of controls UIView |
|
||
-enableViewControllerTransitionAnimation:(BOOL)enable | Method to enable/disable view controller animation when transitioning (available in v3.0.5 and up) |
|
||
-enableBackBarButtonItem:(BOOL)enable | Method to enable/disable back bar button item from being shown (available in v3.0.5 and up) |
|
||
-setTableViewHeaderBackgroundColor:(UIColor*)color | UIColor set for the TableView Header background (available in v4.4.0 and up) |
|
||
-setTableViewHeaderTextColor:(UIColor*)color | UIColor set for the TableView Header text (available in v4.4.0 and up) |
|
||
-setSecurityViewsTextColor:(UIColor*)color | UIColor set for the text throughout the Security views (available in v4.4.0 and up) |
|
||
-setGeofenceCircleColor:(UIColor*)color | UIColor set for the geofence circle (available in v4.4.0 and up) |
|
||
-setSecurityFactorImageTintColor:(UIColor*)color | UIColor set for the factor images in the TableView of the Security view (available in v4.4.0 and up) |
|
If you want to set custom fonts, determine whether the fonts are supported by Xcode, then:
NSString
values to the customFont
property of the AuthenticatorConfig
builder.Fonts provided by application
. In this row, include all of the font names in an array.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
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:
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()
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)
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:
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)
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")
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.
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.
TransUnion links to user contributed code as a resource to its community. TransUnion does not in any way guarantee or warrant the quality and security of these code bases. User contributed code is supported by the creators. If you do find a link from the site to user contributed code that is malicious or inappropriate in any way, please report that link to TransUnion immediately and we will investigate the claim. Submit any issue to TransUnion support at https://transunion.com/support. ×