Integrating LaunchKey with iOS¶

iOS Version¶

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

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

AuthenticatorConfig Builder Properties¶

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

Objective-C:

AuthenticatorConfig *config = [AuthenticatorConfig makeWithAuthenticatorConfigBuilder:^(AuthenticatorConfigBuilder *builder) {
    builder.SSLPinningEnabled = YES;
    builder.customFont = @"System";
    builder.keyPairSize = keypair_maximum;
    builder.activationDelayWearable = 86400;
    builder.activationDelayGeofence = 86400;
    builder.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?.enableInfoButtons = true
        builder?.enableHeaderViews = true
        builder?.enableNotificationPrompt = true
        builder?.enableSecurityChangesWhenUnlinked = false
        builder?.controlsBackgroundColor = UIColor.clear
        builder?.enableSecurityFactorImages = true
        builder?.geofenceCircleColor = UIColor.blue
        builder?.tableViewHeaderBackgroundColor = UIColor.clear
        builder?.tableViewHeaderTextColor = UIColor.blue
        builder?.securityViewsTextColor = UIColor.black
        builder?.securityFactorImageTintColor = UIColor.black
        builder?.enablePINCode = true
        builder?.enableCircleCode = true
        builder?.enableGeofencing = true
        builder?.enableWearable = true
        builder?.enableFingerprint = true
        builder?.enableFace = true
        builder?.authContentViewBackgroundColor = UIColor.white
        builder?.authTextColor = UIColor.purple
        builder?.authResponseAuthorizedColor = UIColor.green
        builder?.authResponseDeniedColor = UIColor.red
        builder?.authResponseFailedColor = UIColor.orange
        builder?.authResponseDenialReasonSelectedColor = UIColor.blue;
        builder?.authResponseDenialReasonUnselectedColor = UIColor.brown
    }

Activation Delay (v3.0.4 and up)¶

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

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

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

Objective-C:

[[AuthenticatorConfigurator sharedConfig] setActivationDelayProximity:86400];

[[AuthenticatorConfigurator sharedConfig] setActivationDelayGeofence:86400];

Swift:

AuthenticatorConfigurator.sharedConfig().setActivationDelayProximity(86400)

AuthenticatorConfigurator.sharedConfig().setActivationDelayGeofence(86400)

SSL Pinning (Extra Security)¶

The Authenticator SDK uses SSL for network communication to the 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.

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

Objective-C:

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

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

Swift:

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

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

Customizing Device Linking¶

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

Objective-C:

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


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

Swift:

let qrCode = "ABCD123"


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

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

Objective-C:

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

Swift:

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

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.

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

Objective-C:

[[AuthenticatorConfigurator sharedConfig] setKeyPairSize:keypair_maximum];

Swift:

AuthenticatorConfigurator.sharedConfig().setKeyPairSize(keypair_maximum)

Listening To Events via NSNotificationCenter¶

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

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

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

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

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

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

Automatic Linking of a Device¶

If your mobile app is supported by its own backend system, then the backend can generate a valid linking code, directly interacting with the 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.

Overview¶

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

Import Headers¶

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

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

UI Customization Definitions¶

Set Custom Font¶

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

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

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 Apple Push Notification token:

Objective-C:

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

Swift:

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

Registering the Device Token¶

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

Objective-C:

[[AuthenticatorManager sharedClient] setNotificationToken:deviceToken];

Swift:

AuthenticatorManager.sharedClient().setNotificationToken(deviceToken)

Obtaining an Apple Push Notification Certification¶

You must obtain an Apple Push Notification Certification before the 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)

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

What’s new with v4.3¶

• Collection of anonymous metrics to better support the service and understand the behavior of the Authenticator SDK in order to make improvements in newer versions.
• Added a public -(void)sendMetricsWithCompletion:(completion)completion method in the AuthenticatorManager to help implementers provide collected metrics to our service whenever necessary.

What’s new with v4.5¶

• Added support for third-party push notification services by providing a new method in the 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")

What’s new with v4.6¶

• All new Auth Request Flow

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

• Added support for Auth Denial Context

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

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

  Ensuring that Subscribers 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 LaunchKey supports.

• We’ve updated the verification and priority order of the Auth Methods

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

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

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

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

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

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

  KNOWLEDGE

  1. PIN Code
  2. Circle Code

  INHERENCE

  1. Fingerprint Scan
  2. Face Scan
  3. Geofencing

  POSSESSION

  1. Wearable