iOS

Updated February 7th 2017

Secure your iOS app with PixelPin

PixelPin for iOS

You can download the free PixelPin iOS app from the App store and using a supplied interface, can very easily use your PixelPin developer account information to allow people access to your iOS application by authenticating with PixelPin.

This process is secure and implements various types of cryptography in order to ensure the security of the data that passes between your app, the PixelPin app and the PixelPin web server.

The iOS application can work online-only or can cache the data offline. It is recommended that if your app is online only, that you pass 'true' to the login call and ensure that the app is online. This will avoid storing data locally but will have a performance impact over offline mode.

If you do not pass 'true' to the login call, the login data will be cached offline on the device. It is encrypted using a device-specific key but the data is vulnerable on devices that do not have a hardware security module and/or are jailbroken.

Note that you should keep your version of the iOS integration library up-to-date in your own application otherwise there is a risk that logins will be blocked or the user will be encouraged to download the PixelPin management app

Using the Interface

The PixelPin app on the Play store can be downloaded and used stand-alone but you can only interact with it by using the mobile interface archive available from here.

  1. Build and run your app to ensure it works before integrating PixelPin. This is to avoid confusion of compiler errors that might be caused by a conflict in libraries targets.

  2. Download and unzip pixelpin_ios_sdk_x_x.zip to your PC. Drag the PixelPinSDK.Framework folder into your project navigator

  3. Go to your project -> Build Phases, Click + and then New Copy Files Phase

  4. Change destination to Frameworks and then click + and select the PixelPinSDK.framework

  5. The final result should look like this

  6. In Build Phases, click + and add a New Run Script Phase

  7. Use the following code in the script box

  8. Login to PixelPin and from the dashboard, choose Add/Edit Developer Accounts from the dashboard. Add a new account here, if you are not using this account for web, put in anything for the redirect uri.

  9. Make a note of the 3 keys from the developer account

PixelPin with Swift

  1. Import PixelPinSDK into your AppDelegate

  2. Call the following in your application startup method

    PixelPin.initialise(clientId:secret:clientKey:urlScheme:)

  3. When trying to login with PixelPin call

    PixelPin.loginWithEmail(viewController:email:callback:forceOnline:)

  4. You can pass true to forceOnline, which will ignore any offline cached login data and login online only. This is preferred for security reasons since it will not store offline data but will be slower than logging in offline.

  5. Callback is a typealias of

    (response: AnyObject?, error: PixelPinSDK.PixelPinError?) -> Void

  6. Upon successful login, the response will contain the email you tried to log in with, otherwise, nil is returned for failed login

  7. If an error occured, the error parameter will contain a non-nil value. Read PixelPinError for further detail.

PixelPin with Objective-C

  1. Add the following to your AppDelegate

    #import <PixelPinSDK/PixelPinSDK.h>

  2. Call the following with your PixelPin keys in your application start method

    [PixelPinSDK initialise:secret:clientKey:urlScheme:]

  3. When trying to login call

    [PixelPinSDK loginWithEmail:viewController email:theEmail onSuccess:successClosure onError:errorClosure forceOnline:online]

  4. You can pass YES to forceOnline, which will ignore any offline cached login data and login online only. This is preferred for security reasons since it will not store offline data but will be slower than logging in offline.

  5. onSuccess is a closure receiving NSString and returning void, upon successful login the email will be returned, it will not be called if login fails

  6. onError is a closure receiving enum PixelPinError as a parameter, describing the error. Read PixelPinError for further detail.

Interacting with the PixelPin app

In order to handle out-of-date PixelPin SDKs, the iOS app must also interact with the PixelPin app (if it is installed). Carry out the following steps to set this up.

  1. Add LSApplicationQueriesSchemes to Info.plist

  2. Under your project info add URL Type

  3. Either add the following URL handlers, or if you already handle URLs in your app, add the bold text to the existing handlers

    • Swift:
      func application(app: UIApplication, openURL url: NSURL, options: [String: AnyObject]) -> Bool {
          PixelPinSDK.validateResponse(url.absoluteString)
          return true
      }
    • Objective-C:
      - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary *)options {
          [PixelPinSDK validateResponse:[url absoluteString]];
          return YES;
      }

PixelPinError

The following list shows the error codes that might be returned to your app if login fails

  1. NotInitialised: the initialisation function was not called

  2. ValidationError: pixelpin failed to validate your login information

  3. NetworkError: an error occurred while connecting to the server

  4. UnknownUser: PixelPin does not have an account with the provided email

  5. NotValidated: the account you tried to login with was not validated

  6. SdkOutdatedWarning: the login may proceed, but it is suggested that the user either updates the app, or installs the official PixelPin app

  7. SdkOutdated: the sdk is out of date, login will not be possible until updating to a newer version

  8. UserCanceled: user canceled the login

Important notes

If the user does not have a PixelPin account when they attempt to login to your application, they will be offered the chance to register. They will have to register the email address that your app has passed into the PixelPin app (they cannot decide to change it to another one). If they continue this process, they will have to verify the account before control is passed back to your app but the PixelPin interface will verify that the email that was registered matches the one you originally requested.

IMPORTANT: Due to the nature of the security and the fact that our keys need to be updated, both the PixelPin application and the library are subject to updates. It is important that you are aware of these (people with developer accounts will be contacted ahead of time) and that you are able and willing to make updates to your application when these changes occur, otherwise when a public key is eventually retired, your application will stop working.

Due to these reasons and others, you should make sure that the email address on the developer accounts is up to date and checked regularly.