iOS Authenticator SDK Integration

Adding the Authenticator SDK to your iOS Project

To add the Authenticator SDK to your iOS project, follow these instructions:

  1. Add WhiteLabel.bundle and WhiteLabel.framework to your project.
  2. You should see WhiteLabel.bundle under the Copy Bundle Resources section of your target’s Build Phases.
  3. Under Link Binary With Libraries, you should see WhiteLabel.framework.

After the Authenticator SDK has been successfully added, you will need to link the following frameworks to your project:

  • Foundation.Framework
  • LocalAuthentication.Framework
  • CoreMedia
  • CoreVideo
  • ImageIO
  • CoreGraphics
  • Security
  • CoreData
  • CoreLocation
  • CoreBluetooth
  • AVFoundation
  • UIKit
  • MobileCoreServices
  • ExternalAccessory

Next, under your target’s Build Settings -> Other Links Flags, ensure that you add the -ObjC flag.

Initializing the Authenticator SDK

First, import the Authenticator framework to your delegate and then initialize WhiteLabelManager:

Example:

#import <WhiteLabel/WhiteLabelManager.h>

Next, initialize the shared client:

Prototype:

- (void)init:(NSString*)sdkKey;

Example:

[[WhiteLabelManager sharedClient] init:@"abcDEfgHIjkLMNOPqrsTuVwxYZ01234567890"];

The SDK key (sdkKey) for your directory can be found within Dashboard inside the directory details page which can be accessed from your Organization details page.

Register For APN Token

In order to identify the device as well as to receive push notifications from the Platform (more on that later), you need to register for an Apple Push Notification token. To register for a notification token, make this call:

[[UIApplication sharedApplication] registerForRemoteNotifications];

Next, in the AppDelegate callback function didRegisterForRemoteNotificationsWithDeviceToken, make a call to the WhiteLabelManager to register the device’s token with the Authenticator SDK via SetNotificationToken like this:

Prototype:

- (void)setNotificationToken(NSData *)deviceToken;

Example of callback and registering the token with the Authenticator SDK:

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
    {
    [[WhiteLabelManager sharedClient] setNotificationToken:deviceToken];
    }

Adding Location Request to info.plist

Next, open your project’s priority list file (usually info.plist). Right-click a row in the info.plist and click Add Row, enter NSLocationWhenInUseUsageDescription and NSLocationAlwaysUsageDescription as the key and leave the Value section blank. This will prompt the User for access to their location when geo-fencing is enabled.

Configuration Options - Optional

With WhiteLabelConfigurator, you can modify various aesthetic and security configuration options for the Auth Modal by modifying the WhiteLabelConfigurator sharedConfig object with the following calls:

Background Color

The default color of the Auth Modal background is near-black (hex #1E1E29, RGB 30,30,41). To change this to a different color, modify the Configurator and pass in a custom UIColor object with this call:

Prototype:

- (void)setModalBackgroundColor:(UIColor*)modalBackgroundColor;

Example:

[[WhiteLabelConfigurator sharedConfig] setModalBackgroundColor:[UIColor redColor];

Background Alpha (Transparency)

The default alpha value for the Auth Modal background is .85 (85% opacity). To modify the alpha value, modify the Configurator with the following call:

Prototype:

- (void)setModalAlpha:(float)alpha;

Example:

[[WhiteLabelConfigurator sharedConfig] setModalAlpha:.7];

Text Color

The default text color in the Auth Modal is white (hex #FFFFFF, RGB 255,255,255). To change the text color, modify the Configurator and pass in a custom UIColor object with this call:

Prototype:

- (void)setModalTextColor:(UIColor*)primaryTextColor;

Example:

[[WhiteLabelConfigurator sharedConfig] setModalTextColor:[UIColor blackColor]];

Secondary Text Color

The default secondary text color (used in all text input fields) is near-black (hex #2E2E2E; RGB 46,46,46). To change the secondary text color, modify the configurator and pass in a custom UIColor object with this call:

Prototype:

- (void)setSecondaryTextColor:(UIColor*)secondaryTextColor;

Example:

[[WhiteLabelConfigurator sharedConfig] setSecondaryTextColor:[UIColor whiteColor]];

UI Theme Color

The Auth Modal includes various user interface graphics that can be set to either a dark (black) or light (white) theme to ensure they’re visible with your background color choice. To set the UI theme (default is light), modify the Configurator with one of the following calls:

Prototype:

// Light
- (void)setLightTheme;

// Dark
- (void)setDarkTheme;

Example:

// Light
[[WhiteLabelConfigurator sharedConfig] setLightTheme;

// Dark
[[WhiteLabelConfigurator sharedConfig] setDarkTheme;

Secondary Theme Color

The secondary theme color is the color used in interface elements such as buttons and form inputs. While the alpha for these elements is determined by the SDK, the alpha differs depending on the element and its current state. The default secondary theme color is determined from the UI Theme Color (above), but you can explicitly define a color by modifying the Configurator with a custom UIColor object using this call:

Prototype:

- (void)setSecondaryColor:(UIColor*)secondaryColor;

Example:

[[WhiteLabelConfigurator sharedConfig] setSecondaryColor:[UIColor redColor]];

Custom Launcher Image

The default user interaction to approve an Auth Request from your service is to slide an approval slider upwards. The default launcher has a LaunchKey icon within it, but you can replace this icon with your own image (e.g. your company logo or avatar). Your launcher image should be a square PNG file (93x93 pixels @2x). To set a custom launcher image, modify the Configurator with this call:

Prototype:

- (void)setLauncherImage:(NSString*)launcherImage;

Example:

[[WhiteLabelConfigurator sharedConfig] setLauncherImage:@“image_string”];

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.

To bundle the LaunchKey SSL public keys in your project, drag and drop the LaunchKey public key certs (.cer files) to your project’s Supporting Files folder. To verify that these have been properly added to your project, go to Build Phases, and under Copy Bundle Resources, you should see the .cer files listed accordingly.

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.

Prototype:

// Turn OFF
- (void)turnOffSSLPinning;

// Turn ON
- (void)turnOnSSLPinning;

Example:

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

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

Interacting with the Auth Modal

The Auth Modal is what your directory users will interact with inside your Mobile App to link/un-link their device, authenticate and respond to auth requests from your service, and configure various settings. The modal lives hidden from view within your Mobile App and slides into view as necessary. The Auth Modal consists of three primary views:

Linking View:In this view (used only once during initial setup), the end user can scan a QR linking code or manually enter a 7-character alphanumeric code to link their mobile device and register their User with your directory.
Settings View:This view is where your Users will manage various security settings related to the Auth Modal (e.g. enabling authentication factors, un-linking devices, etc.)
Auth Request View:This is the view where your Users will authenticate and respond to Auth Requests

To interact with these views:

Display Linking View

use this view in the device linking process to give your User the ability to scan a QR linking code or manually enter a 7-character alphanumeric linking code.

Note

Your Mobile App can also link the user’s device from within your own custom view using a method exposed by the SDK. To do this, read Performing Auth Modal Actions Directly In Your App - Optional.

To display the Linking View in the Auth Modal, make the following call:

Prototype:

- (void)showLinkView:(UIViewController*)parentViewController withLinked:(linkedBlock)linked withFailure:(failureBlock)failure;

Example:

[[WhiteLabelManager sharedClient] showLinkView:self withLinked:^{

    } withFailure:^(NSString *errorMessage, NSString *errorCode) {

    }];

This will toggle the Auth Modal to appear in your Mobile App, allowing the end user to either scan the QR linking code or manually enter the 7-character alphanumeric code that your service will present to them. The withLinked callback will be called if the User has successfully linked their device (see next).

To determine whether a User has been successfully linked or not, call:

Prototype:

- (BOOL)isAccountActive;

Example:

[[WhiteLabelManager sharedClient] isAccountActive];

Display Settings View

The Authenticator SDK provides the User with certain auth-related settings through the Auth Modal (e.g. enable/configure authentication factors, log out, un-link device). To display the Settings View in the Auth Modal, make the following call:

Prototype:

- (void)showSettingsView:(UIViewController*)parentViewController withUnLinked:(unlinkedBlock)unlinked;

Example:

[[WhiteLabelManager sharedClient] showSettingsView:self withUnLinked:^{

    }];

The withUnLinked callback will be called if the User has unlinked their device from your directory.

Display Auth Request View

To give your Users the ability to authenticate and respond to pending Auth Requests from your service, make a call to:

Prototype:

- (void)showPendingAuthentication:(UIViewController*)parentViewController withSuccess:(successBlock)success withFailure:(failureBlock)failure;

Example:

[[WhiteLabelManager sharedClient] showPendingAuthentication:self withSuccess:^{

    } withFailure:^(NSString *errorMessage, NSString *errorCode) {

    }];

Note

The Request View will only be displayed if isAccountActive returns true, meaning the User has successfully has linked their device.

Configure Push Notifications - Optional

Although optional, we recommend using push notifications in your Mobile App to provide a better user experience. With push notifications, the Platform will push alerts to your User’s device to notify them of pending Auth Requests from your service. Additionally, your Mobile App can check for these notifications and automatically display the Request View to the User. To use this feature, follow these steps:

Warning

Push notifications are dependent upon the proper function of the Apple Push Notification system and your user’s mobile carrier. Slowdowns, outages, or other problems may affect the speed and ability of your user’s mobile device to receive push notifications. Therefore, in addition to push requests, it’s highly recommended that you provide a manual option for your user to check for pending Auth Requests within your mobile app.

Obtain APN Certificate from Apple Developer Portal

In order for the LaunchKey Platform to be able to send push notifications to your Mobile App on your behalf, you must first obtain an Apple Push Notification Certificate. To do this:

  1. Log into the Apple Developer Portal at https://developer.apple.com and click on the Certificates, Identifiers & Profiles section. (This assumes you have already setup push notifications for your mobile app)
  2. Under the Certificates section, find the Production Push Notification certificate you created for your mobile app (this should be the certificate you use in production for your mobile app) and click the Download link to download the certificate to your Mac.
  3. Once downloaded, double-click on the certificate file to add it to your Keychain’s Certificate section.
  4. Open Keychain Access, find the Push Notification certificate that you just added, then right-click the certificate and choose Export "Apple Development iOS Push Services …"
  5. When prompted, save this certificate with a .p12 file extension and leave the password field empty. Move on to the next step.

Add APN Certificate to directory

Next, add the APN certificate to your directory settings in Dashboard:

  1. Log into Dashboard and click on the Organizations link.
  2. Click on your Organization, scroll down to the directories section and click on the group you want to authorize push notifications for.
  3. Finally, scroll down to the Push Notification Credentials section, and under iOS Certificate upload your APN certificate.

Intercepting Push Notifications For Auth Requests - Optional

If you’re using push notifications, your Mobile App will receive a push notification regarding the pending Auth Request. Your Mobile App should intercept this notification in order to trigger the Request View of the Auth Modal. You can intercept the push notification via the didReceiveRemoteNotification callback in the AppDelegate:

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo { }

In the didReceiveRemoteNotification callback, your Mobile App should trigger the Request View in order to display the pending Auth Request to your User.

Performing Auth Modal Actions Directly In Your App - Optional

The Authenticator SDK exposes certain methods involving User logout, device link/User register, and device un-link, so that your Mobile App can perform these actions outside of the Auth Modal. With this capability, you can use your own buttons, interfaces, and views for these actions instead of relying on the Auth Modal.

User Logout

To log out all active sessions for the current User, call:

Prototype:

- (void)logOut:(successBlock)success withFailure:(failureBlock)failure;

Example:

[[WhiteLabelManager sharedClient] logOut:^{

    } withFailure:^(NSString *errorMessage, NSString *errorCode) {

    }];

Done

The Authenticator SDK has now been configured and added to your iOS project. The final step is to integrate the LaunchKey Platform API within your service using one of the SDKs.

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