Integrating LaunchKey with iOS

This document walks you through integrating LaunchKey with iOS apps.

Setting Up the LaunchKey Service

Before integrating the LaunchKey Authenticator SDK with your app, an administrator must complete the following steps:

  1. From an iOS device, launch the Apple App store.
  2. Search for the LaunchKey Authenticator app, then download and install it.
  3. Run the LaunchKey Authenticator app and tap Get Started.
  4. Complete the Link page. This includes:
    • A username and device name. You will use this username to log into the LaunchKey Admin Center. The device name will appear when you review linked devices.
    • Choose which communication channel you want to use to complete account creation and device registration. You can choose Email and/or SMS. Accept the terms and agreements, then tap Done.
  5. Based on the linking method(s) you chose, you will receive an email and/or text message with a link that you must follow to complete account creation and link your device to the LaunchKey Admin Center.
  6. Now that the device is configured, you must associate it with a service in the LaunchKey Admin Center. From a browser, open the LaunchKey Admin Center at https://admin.launchkey.com/login.
  7. To log in, enter the username that you entered into the LaunchKey Authenticator app when you linked the device.
  8. On the device, authorize the login. If any security factors have been enabled, you will be prompted to complete them before you can complete authorization.
  9. Now that you are in the LaunchKey Admin Center, click the left navigation button and select Organizations. The All Organizations page appears.
  10. Click the New Organization button. The Create New Organization screen appears.
  11. Enter a name for the organization, provide your name and email address (or name and email address of an admin user). Complete the Create New Organization Screen.
  12. The user whose email you entered will receive a confirmation email. Click the confirmation email to complete creation of the organization.
  13. Back in the LaunchKey Admin Center, open the organization you created. Expand the menu button on the left of the screen and select Organizations, then click the organization.
  14. From within the organization, select the Directories tab.
  15. Click the New Directory button to create a new directory. Enter a name for the directory and click the Submit button.
  16. Directory details appear. From here, on the General tab, you can see a Authenticator SDK Keys list. Capture the Authenticator SDK Key. You will need it later when integrating the LaunchKey SDK into your app.
  17. Also on the General tab, under Services, click the NEW SERVICE button. The Create New Service screen appears.
  18. Enter a name and description for the service. Optionally choose an avatar file, read and accept the Terms of Service and click the Create Service button.

You are now ready to integrate the LaunchKey SDK into your mobile apps.

Integrating the iOS SDK into Your App

Follow these steps to integrate the LaunchKey SDK for iOS into your app. This includes examples and instructions for Objective-C and swift.

  1. Download the SDK from https://github.com/iovation/launchkey-ios-authenticator-sdk/releases

  2. 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.

  3. Add the following .plist permissions to your project and provide description values for each:

    • NSLocationWhenInUseUsageDescription
    • NSBluetoothPeripheralUsageDescription
    • NSCameraUsageDescription

    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:

    • NSFaceIDUsageDescription

  4. Import Authenticator.framework to your app delegate or, for Swift projects, your Bridging-Header.h file:

    #import <Authenticator/AuthenticatorManager.h>

  5. Initialize the AuthenticatorManager shared client with your Directory SDK Key:

    // Initialize the SDK Manager
[[AuthenticatorManager sharedClient] initSDK:@"<Directory_SDK_Key>"];

  6. 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
})

  7. 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)")
    }
})

  8. 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
})

  9. 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.

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.

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.

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.

SSL Pinning (Extra Security)

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()

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
}

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()

Displaying Linked Devices

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)")
        }
    }
}

Managing Sessions

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
    }
}

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.

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.

Customizing the User Interface

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 proxy UIAppearance proxy.

Getting Started

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

UI Customization Examples

These examples walk you through the customizable elements and how you can set them in both Objective-C and Swift.

If you will 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 setFont call
  • 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.

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"];
[AuthRequestContainer appearance].imageAuthRequestFingerprint = [UIImage imageNamed:@"Image3"];

// 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")
AuthRequestContainer.appearance().imageAuthRequestFingerprint = UIImage(named:"Image3")

// To set background color
self.window?.backgroundColor = UIColor.white

Adding Push Notifications to Your Integration

Overview

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:

  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 LaunchKey platform, you must register for an Apply Push Notification token:

Objective-C:

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

Swift:

let center = UNUserNotificationCenter.current()
center.requestAuthorization(options:[.badge, .alert, .sound]) { (granted, error) in
}
application.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 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:

  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 LaunchKey Admin Center at https://admin.launchkey.com/login.
  9. Click Organizations and select your organization. Click the White Label tab. Select the White Label 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)

Changes with 4.x

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.

  • 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:

    • Supports offline authentication. For example, it can be used to authenticate an End User before displaying sensitive content.
    • Allows the End User to set up Security factors and authenticate through Local Auth Requests even when unlinked if the new config method -(void)enableSecurityChangesWhenUnlinked:(BOOL)enable is set to true in the AuthenticatorConfigurator object when initializing the SDK.
    • Titles of Local Auth Requests can be set to a custom title (NSString) through -(void)setTitle:(NSString*)title from the LocalAuthManager class.
    • Expiration of Local Auth Requests can be set to a custom value (int) but must be within two and five minutes, two minutes being the default value if not specified through -(void)setExpiration:(int)expiration from the LocalAuthManager class.
    • When generating a Local Auth Request, a 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.
    • Can only be used when there's at least one factor set up, otherwise an error will be returned.

    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)")
    }
})

User Contributed

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. ×