iOS implementation


Set up a mobile app using the PingID SDK sample code

Prerequisites

  1. Make sure that you have the following prerequisites, as decribed in Initial account configurations:

    • The Application ID (used in the server side integration).
    • The PingID SDK settings file.
    • The application configuration.
  1. Prepare the iOS push messaging certificates:

    If you intend to use push messaging in your app, verify that you have your push configuration information:

Configure iOS push messaging certificates:

  • iOS Remote Notification:
    • When configuring your PingID SDK application in the PingOne admin web console, you should upload your Apple iOS Push Services Certificate. Find it under “Connect to your application” in the Application Configuration page in the PingOne admin web console.

IDE integration

PingID SDK Demo Application iOS - IDE integration:

In the example app, make sure that you change the following settings in Constants.m:

kCustomerServerUrl  
kAppID

to your customer server URL,and the Application ID, which you retrieved from the PingOne admin web console. Add the PingID SDK component into your existing project.

  • In your Project Navigator, click on your target, and drag PingID_SDK.framework to Embedded Binaries.

  • Check the Copy items if needed checkbox.

  • PingID SDK uses location, if it is available. Make sure to ask for location permissions in your app code before the following call:

    + (void)initAppID:(nonnull NSString *)appID error:(NSError * _Nullable * _Nullable)error;

    If your app doesn’t use location, you will need to add the NSLocationWhenInUseUsageDescription key to your info.plist with a short description, implement CLLocationManager, and ask for location permissions.

  • Setup the Run Script phase.

    • Make sure that the Run Script phase is after the Embed Frameworks phase.

    • Select your application’s Xcode project, then your application target, and then select Build Phases, click “+”, and then New Run Script Build Phase.

    • Paste the following line into the body of the Run Script Build Phase:

      bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/PingID_SDK.framework/strip-frameworks.sh"

Implement the PingID SDK in your code

This section details the implementation steps of the PingID SDK flows and logic, which are described in Multifactor authentication (MFA) methods and User device pairing.

  1. Retrieve the organization account alias from the pingidsdk.properties file.
  1. Configure remote notification: If you intend to use push messaging in your app, you should have your Apple iOS Push Services Certificate ready. Upload the certificate in the PingOne admin console: Go to Setup > Certificates.

  2. Add the PingID SDK component into your existing project:

    • In your Project Navigator, click on your target, and drag PingID_SDK.framework to Embedded Binaries.
    • Check the Copy items if needed checkbox.
  3. Enable location:

    PingID SDK uses location, if it is available. Regardless, add the NSLocationWhenInUseUsageDescription to your info.plist with a short description, implement CLLocationManager, and ask for location permissions.

  4. Setup the Run Script phase:

    • Make sure that the Run Script phase is after the Embed Frameworks phase.

    • Select your application’s Xcode project, then your application target, and then select Build Phases, click +, and then New Run Script Build Phase.

    • Paste the following line into the body of the Run Script Build Phase:bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/PingID_SDK.framework/strip-frameworks.sh"

  5. Integrate the PingID SDK component into your code:

    • Initialize the PingID SDK singleton. Import the framework into your application initialization code :

      #import <PingID_SDK/PingID.h>

    • Call the initWithAppID method, passing the Application ID requested from the admin (from the PingOne admin console) when the application was created.

      • Call the initWithAppID:supportedMfa: method with the required registration mode for pairing (MFA type):

        PingID initWithAppID:##YOUR_APP_ID_HERE## supportedMfa:##PIDSupportedMfaType##;
        Registration mode value Description
        PIDSupportedMfaTypeAutomatic MFA supports remote notifications with automatic fallback to one time passcode.
        PIDSupportedMfaTypeRemoteNotification MFA supports remote notifications only.
        PIDSupportedMfaTypeOneTimePasscode MFA supports one time passcode only, and will not support remote notifications.

        Make sure that this method is called at the beginning of your AppDelegate application::didFinishLaunchingWithOptions: method.

    • Integrate the PingID SDK component into the authentication process.

      • Invoke the generatePayload function on every login attempt.

      • In the login request to the customer server, add a string parameter, for passing the payload from the customer mobile application’s PingID SDK component.

      • In the authentication request, you’ll receive information regarding the result of the PingID SDK multifactor authentication.

  6. Sign the application certificate.

Working with push messages in iOS

This section details the steps needed in order to work with push messages in iOS:

  1. Enable Push Notifications: Go to your Project Navigator’s capabilities tab. Select Push Notifications > Enable.
  1. Create the APNs certificates for your test and production environments. Refer to: Local and Remote Notifications Overview.

  2. Upload the APNs certificates to the PingOne admin console under your app settings. Go to Applications > PingID SDK Applications.

    • Verify that push notifications are working with the above certificates before uploading them to the admin console.
  3. Enable PingID SDK to send silent notifications when needed:

    • Go to your Project Navigator’s capabilities tab.
    • Select Background Mode > Enable.
    • Check Remote notifications.
  4. Register Push: In order to receive push notifications from PingID SDK, use the following code in your didRegisterForRemoteNotificationsWithDeviceToken call:

    + (void)setRemoteNotificationsDeviceToken:(nullable NSData *)deviceToken;

    using the actual deviceToken string, without spaces and brackets.

  5. Handling Push Notifications: PingID SDK will only handle push notifications which were issued by the PingID SDK server. Inside the following method:

    - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler;

    Call:

    + (BOOL)isRemoteNotificationFromPingID:(nonnull NSDictionary *)userInfo;

    with the userInfo NSDictionary. If the notification is not from PingID SDK, it will not be handled.

    If the push was received from PingID SDK, pass the userInfo to:

    + (void)handleRemoteNotification:(nonnull NSDictionary *)userInfo  
                               completion:(nullable void(^)(PIDRemoteNotificationType  
             remoteNotificationType, NSArray * _Nullable availableTrustLevels, NSDictionary * _Nullable  
             sessionInfo, NSError * _Nullable error))completionBlock

    and handle the response accordingly.

    Please note that the handleRemoteNotification method doesn’t handle didReceiveRemoteNotification:fetchCompletionHandler:, and it should be added to your code.

  6. Push Notifications Categories: PingID SDK uses categories for different notifications. If your app already uses categories, you will need to retrieve the PingID SDK categories NSMutableSet, by calling:

    + (nonnull NSMutableSet *)getPingIDRemoteNotificationsCategories;

    and add that to your current categories.

    • iOS 8 and 9:

      NSMutableSet *categories = [PingID getPingIDDeprecatedRemoteNotificationsCategories];
       
      UIUserNotificationSettings *settings = [UIUserNotificationSettings
              settingsForTypes:UIUserNotificationTypeAlert | UIUserNotificationTypeBadge |
              UIUserNotificationTypeSound categories:categories];
      
      [[UIApplication sharedApplication] registerUserNotificationSettings:settings];
      [[UIApplication sharedApplication] registerForRemoteNotifications];
    • iOS 10 and up: (UNUserNotification support):

      UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
              center.delegate = self;
              [center requestAuthorizationWithOptions:(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge) completionHandler:^(BOOL granted, NSError * _Nullable error)
              {
                  if(!error)
                  {
                      // Registering UNNotificationCategory more than once results in previous categories being overwritten. PingID provides the needed categories. The developer may add categories.
                      NSMutableSet *categories = [PingID getPingIDRemoteNotificationsCategories];
                      [[UNUserNotificationCenter currentNotificationCenter] setNotificationCategories:categories];
                      [[UIApplication sharedApplication] registerForRemoteNotifications];
                  }
              }];
  7. Cancel Authentication:

    The handleRemoteNotification:completion method provides a mechanism for your application to take action on authentication cancelation events, by returning PIDRemoteNotificationTypeCancel.

  8. Localization: The following keys are returned by the PingID SDK Remote Notification, with suggested localization:

    "notification_confirm" = "Approve";
    "notification_deny" = "Deny";
    "notification.message" = "You have a new authentication request.";
    "notification.title" = "New Authentication";

Keychain Sharing

Make sure that the first item on your Keychain Groups is YOUR_BUNDLE_ID (your private keychain group). This requirement will ensure that the SDK keychain values are private, and are not shared between apps​: