Custom iOS App Guide

By default IAMPASS will send authentication requests to the reference IAMPASS mobile application. IAMPASS Applications can be configured to send authentication requests to custom mobile applications. In this case the custom application is responsible for: * Registering the mobile device with IAMPASS * Collecting the required authentication data in response to authentication requests.


The easiest way to integrate IAMPASS into your application is to use CocoaPods. To integrate IAMPASS into your xCode project using CocoaPods, specify it in your podfile.:

pod 'IAMPASSiOS', '~>0.0.65'


The IAMPASSiOS framework reference documentation can be found here

Getting Started

Create an IAMPASS Account and Application

The first stage in integrating IAMPASS into your applicaton is to create an IAMPASS Application as described here.

Save the application id and application secret for your IAMPASS Application you will need them to communicate with IAMPASS.

Add the IAMPASSiOS framework to your project

To integrate IAMPASSiOS into your xCode project using CocoaPods, specify it in your podfile.:


Application Configuration

Enable Push Notifications

IAMPASS uses Push Notifications to notify users of Authentication Requests. Add the Push Notifications entitlement to your application.

Configure IAMPASS Notifications Credentials

In order to send Push Notifications to your application you need to configure your IAMPASS: IAMPASS needs to be able to authenticate with the APNS servers. The easiest way to do this is to use Token Based Authentication. You can obtain the token information using the instructions here.

  • Open the IAMPASS Console

  • Select you application and click the Details button.

  • In the details page click the settings icon and select Notification Settings.

  • On the Notifications Settings page click the Edit button for iOS.

  • On the Apple iOS Notification Settings page select Custom iOS app from the dropdown.

  • Select token for the authentication method.

  • Enter the values obtained from the Apple Developer Portal

Alternatively you can use the certificate based authentication. * Download the APNS certificates for your application from the Apple Developer Portal. * Import the certificate and private key into KeyChain (both development and production keys). * Export the certificate and private key from KeyChain as .p12 files. * Open the IAMPASS Console * Select your application and click the Details button.

  • In the details page click the settings icon and select Notification Settings.

  • On the Notifications Settings page click the Edit button for iOS.

  • On the Apple iOS Notification Settings page select Custom iOS app from the dropdown.

  • Select certificate for the authentication method.

  • Update the credentials with your APNS certificate and Private Key.

  • Repeat the process for iOS Sandbox using your development credentials.

IAMPASS will now route your users authentication requests to your iOS application.

Applications Entitlements

IAMPASS use Camera and Bluetooth services on your user’s mobile device. You must add the following entries to your application’s info.plist.





uses Bluetooth to verify proximity


uses Bluetooth to verify proximity


uses the camera to capture images required for facial recognition.


uses FaceID to verify that you can unlock your phone.


will not use any of your stored images.

Background Modes

Add the Background Modes entitlement to your application in xCode. Enable the following modes:

  • Acts as a Bluetooth LE accessory

  • Remote Notifications


Key Concepts

When a system uses IAMPASS to authenticate its users:
  • A notification is sent to the users registered device.

  • The registered device collects the required information and send it to IAMPASS.

  • IAMPASS processes the collected data and makes an authentication decision.

A custom IAMPASS mobile device is responsible for:
  • Registering the user’s device.

  • Processing notifications from IAMPASS.

  • Collecting the required data.

Registering Users

IAMPASS does not manage your users or replace your sign up flow. You register your user with IAMPASS by providing a token that you can relate back to your user See Getting Started for information about user management. There are 2 common registration flows: * User registers using your mobile application. * User registers externally (in a web browser for example).

You must wait until your application has completed the Push Notification registration process before registering devices

Mobile Application Registration

The IAMPASS iOS framework provides an interface for registering users and their mobile device. See the IAMPASS example application on GitHub for details.

External Registration

IAMPASS generates custom registration links for associating a device with a user. The external client application can get the registration link and share it with the mobile application. It is the client’s responsibility to share these links with the mobile application. Alternatively, the mobile application can provide an interface for the user to enter their username and obtain a registration link. The IAMPASS iOS framework provides a method to get a registration link for the user

// user_id: client generated identifer for the client applications user.
// display_name: A readable name for the user (user_id may be a random token)
// MY_APPLICATION_ID: The ID of the IAMPASS application (from IAMPASS Console)
// MY_APPLICATION_SECRET: The Application Secret of the IAMPASS application (from IAMPASS Console)

// Create an IAMPASS Management API instance using credentials for client application
let management_api = ManagementAPI(application_id: MY_APPLICATION_ID,application_secret: MY_APPLICATION_SECRET)

management_api.get_registration_link(user_id: user, display_name: user) { (reg_link) in
            // reg_link: URL that can be used to register the device.
        } failure: { (error) in
            // Failed to get registration link.

Whichever method is used to obtain the registration link, the link can now be used to register the device

IPUser.registerDevice(identifier: user_id, registration_link: reg_link, notification_token: NOTIFICATION_TOKEN) { (identifier, device) in
            // Device registered
            // identifier: identifier for user (same as value passed to registerDevice)
            // device: IPUser that contains user and device information required for subequent IAMPASS calls.
        } failure: { (identifier, error) in
            // identifier: identifier for user (same as value passed to registerDevice)
            // error: Error indicating failure reason

Storing Device Information

The client application should store the IPUser instance returned by device registration. IPUser implements the Codeable interface and can be persisted using Swift encoding (JSONEncoder for example). The iOS UserDefaults can be used to store the data, however the iOS KeyChain main be a more secure option.


After a user has been registered IAMPASS may have to collect some training data. After registration check the training_required property of IPUser to determine if IAMPASS needs to perform training.

if registeredUser.training_required{
    // Perform training...

The IAMPASS iOS framework provides a default UI for performing training. The example code below shows a view controller that presents the training UI.

func doTrainingForUser(identifier: Any, user: IPUser) {
    // It is important that the code to display UI components happens
    // on the main thread.
    DispatchQueue.main.async {

        // Get the ViewController to use to present the UI.
        // If this code is part of a ViewController, just use self.
        let presentingVC = getViewController()

        // Create the IAMPASS training view controller.
        if let vc = IPTrainingViewController.create(user: user, identifier: identifier, success: { sender, identifier, device in
            // The training process completed successfuly so save the user information.
            if let id = identifier as? String{

                //TODO: Save the user data.

            // sender is the training UI view controller, so dismiss it.
            sender.dismiss(animated: true)
        }, failure: { sender, identifier, device, error in
            // TODO: Training failed - provide user feedback.
            sender.dismiss(animated: true)
            // Present the training UI.
            vc.modalPresentationStyle = .fullScreen
            vc.modalTransitionStyle = .crossDissolve
            presentingVC.present(vc, animated: true, completion: nil)


If you prefer to use Storyboards and Segues you can create a new IPTrainingViewController derived class and instantiate an instance in Interface Builder.

Updating Device Information

Every time your application starts up or the user changes Notification Settings, you should update the device stored IPUser. Use the update method of IPUser to update the device information. When the device is updated IAMPASS may need to perform training. See training for information about training.

// Class implements IPTrainingDelegate, which processes training results.
class MainViewController : UIViewController, IPTrainingDelegate{

    // Update the stored mobile device.
    func updateDevice()->Void{
        let device = self.get_device()
        let user_id = self.get_user_id()

       device.update(identifier: user_id, notification_token: NOTIFICATION_TOKEN) { (identifier, updated_device) in
           print("Updated Device")

           // Save the device
           self.save_device(identifier: user_id, device: device)
           if mobile_device.training_required{
               DispatchQueue.main.async {
       } failure: { (identifier, error) in
           print("Update error")



Handling Authentication Requests

IAMPASS delivers authentication requests to mobile applications using Push Notifications. The notification title and description use string IDs so the client application must have the following strings in its string resource.

/*Content of the login notification*/
"NOTIFICATION_TITLE" = "IAMPASS AuthenticationRequest";
"NOTIFICATION_BODY" = "TAP TO ACCEPT or clear to cancel.";

You can change the values of the strings but the keys must exist.

When a mobile application receives a Push Notification it should pass it to the IAMPASS iOS framework, which will decode the payload and carry out the required authentication steps.

func application(
      _ application: UIApplication,
      didReceiveRemoteNotification userInfo: [AnyHashable: Any],
      fetchCompletionHandler completionHandler:
      @escaping (UIBackgroundFetchResult) -> Void
    ) {

        // IAMPASS authentcation request notifications contain data to identify the user the request targets.
        // We have to provide the notification handler with a list of user data that is stored on this device so that it can determine whether the notification should be handled.

        // Do we have a user?
        // Need to implent getRegisteredUser
        if let user = self.getRegisteredUser(){
            let registeredUser = [user]
            let  notificationHandler = IPNotificationHandler()
            notificationHandler.processNotification(userInfo: userInfo, registeredUsers: registeredUser) { request, user in
                // This is an authentication request for a user of this device so show the authentication UI.
                let vc = IPAuthenticationViewController.create(request: request, device: user) { sender in
                    // Authentication was successful
                    sender.dismiss(animated: false) {
                        // We send a notification now that the UI has been cleaned up so that interested
                        // parties (ViewController) can update their state.
               AUTHENTICATION_UI_COMPLETE_MESSAGE, object: nil)
                } failure: { sender, error in
                    // Authentication failed.
                    sender.dismiss(animated: false){
                        // We send a notification now that the UI has been cleaned up so that interested
                        // parties (ViewController) can update their state.
               AUTHENTICATION_UI_COMPLETE_MESSAGE, object: nil)
                vc?.modalPresentationStyle = .fullScreen
                vc?.modalTransitionStyle = .crossDissolve

                self.topViewController()?.present(vc!, animated: true)

            } onStatusChanged: { status in
                // The notification is a session status change notification.
            } onError: { error in
                // There was an error handling the notification.
            } onIgnore: {
                // The notification is an IAMPASS notification but should be ignored.
            } defaultHandler: { userInfo in
                // The notification is not an IAMPASS notification.
                // The application should continue with its normal notification handling.




The IAMPASS iOS framework uses system logging to display diagnostic information.