Contents
This document walks you through integrating LaunchKey with iOS apps.
The Authenticator SDK supports iOS 8.0 and up.
Before integrating the LaunchKey Authenticator SDK with your app, an administrator must complete the following steps:
You are now ready to integrate the LaunchKey SDK into your mobile apps.
Follow these steps to integrate the LaunchKey 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
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:
Import Authenticator.framework to your app delegate or, for Swift projects, your Bridging-Header.h file:
#import <Authenticator/AuthenticatorManager.h>
Initialize the AuthenticatorManager shared client with your Authenticator SDK Key:
// 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.
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
}
})
This completes the core integration. Continue on to the next section for advanced integration options.
Now that the LaunchKey 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 LaunchKey integration.
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.
The following examples set the delay to 24 hours.
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 LaunchKey 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 LaunchKey Platform API can be interrupted if SSL pinning is not properly configured.
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
}
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 DevicesViewController to manage device actions. The Authenticator SDK provides a default view
to display linked devices and provides methods that you can use to implement a custom view.
First, import DevicesViewController.h and IOADevice.h:
#import <Authenticator/DevicesViewController.h>
#import <Authenticator/IOADevice.h>
Then, 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)
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)")
}
}
}
Use SessionsViewController to manage session-related tasks. The Authenticator SDK provides a default
view to display sessions and provides methods that you can use to implement a custom view of Sessions as well.
First, import SessionsViewController.h and IOASession.h:
#import <Authenticator/SessionsViewController.h>
#import <Authenticator/IOASession.h>
Then, 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.
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.
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 LaunchKey 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.
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.
| 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 | 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 | 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 | 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) |
|
In order to customize UI elements, import the following:
#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
These code examples (Objective-C and Swift) walk you through the customizable elements and how you can set them in the AppDelegate callback of your Application.
If you want to set custom fonts, determine whether the fonts are supported by Xcode, then:
NSString values to the setFont callFonts provided by application. In this row, include all of the font names in an array.Objective-C:
// Include Info buttons in the Security screens
[[AuthenticatorConfigurator sharedConfig] enableInfo:YES];
// Include table headers
[[AuthenticatorConfigurator sharedConfig] enableHeaderViews:YES];
// Enable notification prompt if disabled
[[AuthenticatorConfigurator sharedConfig] enableNotificationPrompt:YES];
// Disable Back Bar Button Item from being shown (available in v3.0.5 and up)
[[AuthenticatorConfigurator sharedConfig] enableBackBarButtonItem:NO];
// Disable view controller animation when transitioning (available in v3.0.5 and up)
[[AuthenticatorConfigurator sharedConfig] enableViewControllerTransitionAnimation:NO];
// Set custom font
[[AuthenticatorConfigurator sharedConfig] setFont:@"Roboto"];
UINavigationBar *navigationBarAppearance = [UINavigationBar appearance];
// Define colors to use
UIColor *mainColor = [UIColor colorWithRed:(0.0/255.0) green:(150.0/255.0) blue:(136.0/255.0) alpha:1.0];
UIColor *accentColor = [UIColor colorWithRed:(61.0/255.0) green:(188.0/255.0) blue:(212.0/255.0) alpha:1.0];
UIColor *redColor = [UIColor colorWithRed:(255.0/255.0) green:(64.0/255.0) blue:(129.0/255.0) alpha:1.0];
// Set bar tint color of navigation bar
[navigationBarAppearance setBarTintColor:mainColor];
// To set title text color of navigation bar
NSDictionary *textAttributes = [NSDictionary dictionaryWithObjectsAndKeys:[UIColor whiteColor], NSForegroundColorAttributeName, nil];
[navigationBarAppearance setTitleTextAttributes:textAttributes];
// To set appearance for normal bar button items
NSDictionary *textAttributes2 = [NSDictionary dictionaryWithObjectsAndKeys:[UIColor whiteColor], NSForegroundColorAttributeName, nil];
[[UIBarButtonItem appearanceWhenContainedIn:[UINavigationBar class], nil]
setTitleTextAttributes:textAttributes2
forState:UIControlStateNormal];
// Set tint color of UISwitch
[[UISwitch appearance] setOnTintColor:redColor];
// Set tint color of bar button items
[[UIBarButtonItem appearanceWhenContainedIn:[UINavigationBar class], nil] setTintColor:[UIColor whiteColor]];
// Set tint color of Navigation Bar
[[UINavigationBar appearance] setTintColor:[UIColor whiteColor]];
// Set text color labels contained in table views
[[UILabel appearanceWhenContainedIn:[UITableViewCell class], nil] setTextColor:[UIColor blackColor]];
// Set text color of labels in Security View and Add Bluetooth Proximity View (available in v3.0.5 and up)
[IOALabel appearance].textColor = [UIColor whiteColor];
// Set UIAppearance colors for PIN Code
[[PinCodeButton appearance] setTitleColor:accentColor forState:UIControlStateNormal];
[PinCodeButton appearance].highlihgtedStateColor = [UIColor whiteColor];
[PinCodeButton appearance].backgroundColor = [UIColor colorWithRed:(245.0/255.0) green:(245.0/255.0) blue:(245.0/255.0) alpha:1.0];
[[PinCodeButton appearance] setPinCodeButtonAsCircle:YES];
// Set color of letters in PIN Code (available in v3.0.5 and up)
[PinCodeButton appearance].lettersColor = [UIColor blackColor];
// Set color and width of border for PIN Code (available in v4.1.0 and up)
[[PinCodeButton appearance] setBorderColor:accentColor];
[[PinCodeButton appearance] setBorderWidth:1.0f];
// Set color of bullets in the PIN Code view when verifying and removing PIN Code (available in v4.1.0 and up)
[PinCodeButton appearance].bulletColor = accentColor;
// Set UIAppearance colors for the AuthenticatorButton
[[AuthenticatorButton appearance] setTitleColor:[UIColor whiteColor] forState:UIControlStateNormal];
[AuthenticatorButton appearance].backgroundColor = redColor;
// Set the style of negative actions (available in v4.0.0 and up)
[AuthenticatorButton appearance].negativeActionTextColor = [UIColor whiteColor];
[AuthenticatorButton appearance].negativeActionBackgroundColor = redColor;
// Set UIAppearance colors for Circle Code
[CircleCodeImageView appearance].defaultColor = [UIColor darkGrayColor];
[CircleCodeImageView appearance].highlightColor = redColor;
// Set UIAppearance colors for UIButtons inside TableViewCells
[[UIButton appearanceWhenContainedIn:[UITableViewCell class], nil] setTintColor:redColor];
// Set UIAppearance colors for the Authorization slider
[AuthorizationSliderButton appearance].backgroundColor = [UIColor grayColor];
[AuthorizationSliderButton appearance].highlihgtedStateColor = [UIColor lightGrayColor];
[[AuthorizationSliderButton appearance] setTintColor:[UIColor whiteColor]];
[AuthorizationSlider appearance].topColor = [UIColor whiteColor];
[AuthorizationSlider appearance].bottomColor = [UIColor darkGrayColor];
// Set background color of controls
[[AuthenticatorConfigurator sharedConfig] setControlsBackgroundColor:[UIColor clearColor]];
// Set visibility of images for security factors
[[AuthenticatorConfigurator sharedConfig] enableSecurityFactorImages:YES];
// Set color of UITableView separator color
[[UITableView appearance] setSeparatorColor:[UIColor clearColor]];
// Set custom images for security factors
[SecurityFactorTableViewCell appearance].imagePINCodeFactor = [UIImage imageNamed:@"Image1"];
[SecurityFactorTableViewCell appearance].imageCircleCodeFactor = [UIImage imageNamed:@"Image2"];
[SecurityFactorTableViewCell appearance].imageBluetoothFactor = [UIImage imageNamed:@"Image3"];
[SecurityFactorTableViewCell appearance].imageGeofencingFactor = [UIImage imageNamed:@"Image4"];
[SecurityFactorTableViewCell appearance].imageFingerprintFactor = [UIImage imageNamed:@"Image5"];
// Set custom images for images in auth requests
[AuthRequestContainer appearance].imageAuthRequestGeofence = [UIImage imageNamed:@"Image1"];
[AuthRequestContainer appearance].imageAuthRequestBluetooth = [UIImage imageNamed:@"Image2"];
// Set color of IOATextField (in manual linking view) placeholder text color (available in v4.4.0 and up)
[IOATextField appearance].placeholderTextColor = [UIColor lightGrayColor];
// Set color of geofence circle (available in v4.4.0 and up)
[[AuthenticatorConfigurator sharedConfig] setGeofenceCircleColor:accentColor];
// Set colors of TableView Header background and text (available in v4.4.0 and up)
[[AuthenticatorConfigurator sharedConfig] setTableViewHeaderBackgroundColor:[UIColor clearColor]];
[[AuthenticatorConfigurator sharedConfig] setTableViewHeaderTextColor:accentColor];
// Set colors of text throughout Security Views (available in v4.4.0 and up)
[[AuthenticatorConfigurator sharedConfig] setSecurityViewsTextColor:[UIColor blackColor]];
// Set tint color of factor images in Security View (available in v4.4.0 and up)
[[AuthenticatorConfigurator sharedConfig] setSecurityFactorImageTintColor:[UIColor blackColor]];
// To set background color
self.window.backgroundColor = [UIColor whiteColor];
Swift:
// Include Info button
AuthenticatorConfigurator.sharedConfig().enableInfo(false)
// Include table headers
AuthenticatorConfigurator.sharedConfig().enableHeaderViews(true)
// Set custom font
AuthenticatorConfigurator.sharedConfig().setFont("Roboto")
// Enable notification prompt if disabled
AuthenticatorConfigurator.sharedConfig().enableNotificationPrompt(true)
// Disable Back Bar Button Item from being shown (available in v3.0.5 and up)
AuthenticatorConfigurator.sharedConfig().enableBackBarButtonItem(false)
// Disable view controller animation when transitioning (available in v3.0.5 and up)
AuthenticatorConfigurator.sharedConfig().enableViewControllerTransitionAnimation(false)
// Define colors to use
let mainColor = UIColor(red: 0.0/255, green: 150.0/255, blue: 136.0/255, alpha: 1.0)
let accentColor = UIColor(red: 61.0/255, green: 188.0/255, blue: 212.0/255, alpha: 1.0)
let redColor = UIColor(red: 255.0/255, green: 64.0/255, blue: 129.0/255, alpha: 1.0)
// Set color for Navigation bar
UINavigationBar.appearance().barTintColor = mainColor
UINavigationBar.appearance().titleTextAttributes = [NSForegroundColorAttributeName : UIColor.white]
// Set tint color of UISwitch
UISwitch.appearance().onTintColor = redColor
// Set tint color of bar button items
UIBarButtonItem.appearance().tintColor = UIColor.white
// Set tint color of Navigation Bar
UINavigationBar.appearance().tintColor = UIColor.white
// Set text color of labels in Security View and Add Bluetooth Proximity View (available in v3.0.5 and up)
IOALabel.appearance().textColor = UIColor.white
// Set UIAppearance colors for PIN Code
PinCodeButton.appearance().setTitleColor(accentColor, for: .normal)
PinCodeButton.appearance().highlihgtedStateColor = UIColor.white
PinCodeButton.appearance().backgroundColor = UIColor(red: 232.0/255, green: 232.0/255, blue: 232.0/255, alpha: 1.0)
PinCodeButton.appearance().setPinCodeButtonAsCircle(true)
// Set color of letters in PIN Code (available in v3.0.5 and up)
PinCodeButton.appearance().lettersColor = UIColor.black
// Set color and width of border for PIN Code (available in v4.1.0 and up)
PinCodeButton.appearance().setBorderColor(accentColor)
PinCodeButton.appearance().setBorderWidth(1.0)
// Set color of bullets in the PIN Code view when verifying and removing PIN Code (available in v4.1.0 and up)
PinCodeButton.appearance().bulletColor = accentColor
// Set UIAppearance colors for AuthenticatorButton
AuthenticatorButton.appearance().setTitleColor(UIColor.white, for: .normal)
AuthenticatorButton.appearance().backgroundColor = redColor
// Set the style of negative actions (available in v4.0.0 and up)
AuthenticatorButton.appearance().negativeActionTextColor = UIColor.white
AuthenticatorButton.appearance().negativeActionBackgroundColor = redColor
// Set UIAppearance colors for Circle Code
CircleCodeImageView.appearance().defaultColor = UIColor.gray
CircleCodeImageView.appearance().highlightColor = UIColor.darkGray
// Set UIAppearance colors for UIButtons inside TableViewCells
if #available(iOS 9.0, *)
{
UIButton.appearance(whenContainedInInstancesOf: [UITableViewCell.self]).tintColor = UIColor.red
}
// Set UIAppearance colors for the Authorization slider
AuthorizationSliderButton.appearance().backgroundColor = UIColor.gray
AuthorizationSliderButton.appearance().highlihgtedStateColor = UIColor.lightGray
AuthorizationSliderButton.appearance().tintColor = UIColor.white
AuthorizationSlider.appearance().topColor = UIColor.white
AuthorizationSlider.appearance().bottomColor = UIColor.darkGray
// Set backgrund of controls
AuthenticatorConfigurator.sharedConfig().setControlsBackgroundColor(UIColor.clear)
// Set visibility of images for security factors
AuthenticatorConfigurator.sharedConfig().enableSecurityFactorImages(true)
// Set color of UITableView separator color
UITableView.appearance().separatorColor = UIColor.clear
// Set custom images for security factors
SecurityFactorTableViewCell.appearance().imagePINCodeFactor = UIImage(named:"Image1")
SecurityFactorTableViewCell.appearance().imageCircleCodeFactor = UIImage(named:"Image2")
SecurityFactorTableViewCell.appearance().imageBluetoothFactor = UIImage(named:"Image3")
SecurityFactorTableViewCell.appearance().imageGeofencingFactor = UIImage(named:"Image4")
SecurityFactorTableViewCell.appearance().imageFingerprintFactor = UIImage(named:"Image5")
// Set custom images for images in Auth Request flow
AuthRequestContainer.appearance().imageAuthRequestGeofence = UIImage(named:"Image1")
AuthRequestContainer.appearance().imageAuthRequestBluetooth = UIImage(named:"Image2")
// Set color of IOATextField (in manual linking view) placeholder text color (available in v4.4.0 and up)
IOATextField.appearance().placeholderTextColor = UIColor.lightGray
// Set color of geofence circle (available in v4.4.0 and up)
AuthenticatorConfigurator.sharedConfig().setGeofenceCircleColor(accentColor)
// Set colors of TableView Header background and text (available in v4.4.0 and up)
AuthenticatorConfigurator.sharedConfig().setTableViewHeaderBackgroundColor(UIColor.clear)
AuthenticatorConfigurator.sharedConfig().setTableViewHeaderTextColor(accentColor)
// Set colors of text throughout Security Views (available in v4.4.0 and up)
AuthenticatorConfigurator.sharedConfig().setSecurityViewsTextColor(UIColor.black)
// Set tint color of factor images in Security View (available in v4.4.0 and up)
AuthenticatorConfigurator.sharedConfig().setSecurityFactorImageTintColor(UIColor.black)
// To set background color
self.window?.backgroundColor = UIColor.white
iovation 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 Google performance.
At a high level, the setup steps include:
To identify a device and to receive push notifications from the LaunchKey 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 LaunchKey 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)
-(void)sendMetricsWithCompletion:(completion)completion method in the AuthenticatorManager to help implementers
provide collected metrics to our service whenever necessary.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.
Added support for Local Auth Requests where the app is allowed to generate a localized
Auth Request limited to that authenticator without relying on the LaunchKey Service.
Keep the following in mind when making use of the new LocalAuthManager class:
-(void)enableSecurityChangesWhenUnlinked:(BOOL)enable
is set to true in the AuthenticatorConfigurator object when initializing the SDK.-(void)setTitle:(NSString*)title from the LocalAuthManager class.-(void)setExpiration:(int)expiration from the LocalAuthManager class.LKPolicy object must be passed along to set the
requirements for that request and implementors can build it matching what can be possible with the LaunchKey Service through the
Service SDKs.For example:
Objective-C:
#import <Authenticator/LocalAuthManager.h>
LKPolicy *policy = [LKPolicy new];
// To build LKPolicy by count
policy = [LKPolicy makeWithCountBuilder:^(LKPolicyByCount *builder){
builder.countTotal = 2;
}];
// To build LKPolicy by type
policy = [LKPolicy makeWithTypeBuilder:^(LKPolicyByType *builder){
builder.knowledge = YES;
builder.inherence = NO;
builder.possession = YES;
}];
// Set local auth request title
[[LocalAuthManager sharedManager] setTitle:@"Local Auth Request Title"];
// Set local auth request expiration duration
[[LocalAuthManager sharedManager] setExpiration:150];
// Generate and present local auth request
[[LocalAuthManager sharedManager] presentLocalAuth:self.navigationController withPolicy:policy withCompletion:^(BOOL response, NSError *error)
{
if(response)
NSLog(@"Local auth approved.")
else
NSLog(@"Local auth denied. Local auth error: %@", error);
}];
Swift:
#import <Authenticator/LocalAuthManager.h>
var policy: LKPolicy!
// To build LKPolicy by count
policy = LKPolicy.make(countBuilder: { (builder) in
builder?.countTotal = 2
})
// To build LKPolicy by type
policy = LKPolicy.make(typeBuilder: { (builder) in
builder?.knowledge = true
builder?.inherence = false
builder?.possession = true
})
// Set local auth request title
LocalAuthManager.shared().setTitle("Local Auth Request Title")
// Set local auth request expiration duration
LocalAuthManager.shared().setExpiration(150)
// Generate and present local auth request
LocalAuthManager.shared().presentLocalAuth(self.navigationController, with: policy, withCompletion: { (localAuthResponse, error) in
if(localAuthResponse)
{
print("Local auth approved.")
}
else
{
print("Local auth denied. Local auth error: \(error)")
}
})
AuthenticatorManager class, -(void)handlePushPackage:(NSString*)pushPackage,that takes the push package string provided by our LaunchKey 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")
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 Subscriber's service to handle the response of Auth Requests and then request the LaunchKey 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 LaunchKey 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 LaunchKey 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 LaunchKey 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.
LaunchKey links to user contributed code as a resource to its community. LaunchKey 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 LaunchKey immediately and we will investigate the claim. Submit any issue to LaunchKey support at https://launchkey.com./support. ×