iOS PingID SDK Mobile API


Overview

PingID SDK provides the ability to integrate PingID MFA functionality into your mobile applications.

The PingID SDK Mobile API for iOS is declared in the PingID_SDK.framework/Headers/PingID.h header file included in the SDK package. This header file (replicated below) includes descriptions for all functions, parameters and error codes.

For further details on how to integrate PingID SDK into your iOS applications, refer to iOS implementation in the Getting started section.

PingID SDK Mobile API - iOS (PingID.h)

//
//  PingID SDK version 1.1(340)
//
//  Copyright (c) 2017 Ping Identity. All rights reserved.
//
// See LICENSE_SDK.txt for the PingID SDK library licensing information.
//

#import <Foundation/Foundation.h>

@class PIDUserSelectionObject;


#pragma mark - PIDSupportedMfaType
/**
 Supported MFA types
 
 - PIDSupportedMfaTypeAutomatic:            		MFA Supports Remote Notifications with automatic fallback to One Time Passcode
 - PIDSupportedMfaTypeEnforceRemoteNotifications:   MFA Supports Remote Notifications only
 - PIDSupportedMfaTypeDisableRemoteNotifications:   MFA Will not support Remote notifications and will support only One Time Passcode
 */
typedef NS_ENUM(NSUInteger, PIDSupportedMfaType)
{
    PIDSupportedMfaTypeAutomatic            		=   0,
    PIDSupportedMfaTypeEnforceRemoteNotifications   =   1,
    PIDSupportedMfaTypeDisableRemoteNotifications  	=   2
};

#pragma mark - PIDActionType
/**
 Actions types

 - PIDActionTypeNone:       None
 - PIDActionTypeApprove:    Approve the device
 - PIDActionTypeDeny:       Deny the device
 - PIDActionTypeBlock:      Block the device
 */
typedef NS_ENUM(NSUInteger, PIDActionType)
{
    PIDActionTypeNone       =  -1,
    PIDActionTypeApprove    =   0,
    PIDActionTypeDeny       =   1,
    PIDActionTypeBlock      =   2
};

/**
 Trust Levels

 - PIDTrustLevelNone:       None
 - PIDTrustLevelPrimary:    Sets the device as primary
 - PIDTrustLevelTrusted:    Sets the device as trusted
 - PIDTrustLevelIgnored:    Sets the device as ignored
 */
typedef NS_ENUM(NSUInteger, PIDTrustLevel)
{
    PIDTrustLevelNone       =  -1,
    PIDTrustLevelPrimary    =   0,
    PIDTrustLevelTrusted    =   1,
    PIDTrustLevelIgnored    =   2
};
#pragma mark - PIDFlowState

/**
 Describes the flow state

 - PIDFlowStateDone:            No action is needed
 - PIDFlowStateOneTimePasscode: The device can't be reached. Display available trust levels when device is offline.
 - PIDFlowStateTrustLevels:     Present trust levels to select from
 */
typedef NS_ENUM(NSInteger, PIDFlowState)
{
    PIDFlowStateDone                = 0,
    PIDFlowStateOneTimePasscode     = 1,
    PIDFlowStateTrustLevels         = 2,
    PIDFlowStateDeviceIsTrusted     = 3
};


#pragma mark - PIDIgnoreIntervalUnit

/**
 Ignore interval type

 - PIDIgnoreIntervalUnitMinutes:    Minutes
 - PIDIgnoreIntervalUnitHours:      Hours
 - PIDIgnoreIntervalUnitDays:       Days
 - PIDIgnoreIntervalUnitWeeks:      Weeks
 - PIDIgnoreIntervalUnitMonths:     Months
 - PIDIgnoreIntervalUnitYears:      Years
 - PIDIgnoreIntervalUnitAlways:     Always
 */
typedef NS_ENUM(NSUInteger, PIDIgnoreIntervalUnit)
{
    PIDIgnoreIntervalUnitMinutes    =   0,
    PIDIgnoreIntervalUnitHours      =   1,
    PIDIgnoreIntervalUnitDays       =   2,
    PIDIgnoreIntervalUnitWeeks      =   3,
    PIDIgnoreIntervalUnitMonths     =   4,
    PIDIgnoreIntervalUnitYears      =   5,
    PIDIgnoreIntervalUnitAlways     =   6
};

#pragma mark - PIDRemoteNotificationType

/**
 Remote Notification type
 
 - PIDRemoteNotificationTypeDone:     Authentication completed successfully
 - PIDRemoteNotificationTypeAuth:     Authentication currently in progress
 - PIDRemoteNotificationTypeCancel:   Authentication request was canceled
 */
typedef NS_ENUM(NSUInteger, PIDRemoteNotificationType)
{
    PIDRemoteNotificationTypeDone     =  0,
    PIDRemoteNotificationTypeAuth     =  1,
    PIDRemoteNotificationTypeCancel   =  2
};

#pragma mark - PIDDataCenterType

/**
Data Center type
 
 - PIDDataCenterTypeDefault:    Default Data Center
 - PIDDataCenterTypeNA:         North America Data Center
 - PIDDataCenterTypeAU:         Australia Data Center
 - PIDDataCenterTypeEU:         Europe Data Center
 */
typedef NS_ENUM(NSUInteger, PIDDataCenterType)
{
    PIDDataCenterTypeDefault    =   0,
    PIDDataCenterTypeNA         =   1,
    PIDDataCenterTypeAU         =   2,
    PIDDataCenterTypeEU         =   3
};

/**
 PingIDDelegate
 */
@protocol PingIDDelegate <NSObject>

@optional
/**
 Get a new one time passcode once it's created. A new one time passcode will be created on each PingID SDK server request

 @param oneTimePasscode Current one time passcode
 */
- (void)didRefreshOneTimePasscode:(nonnull NSString *)oneTimePasscode;

@end

@interface PingID : NSObject

#pragma mark - Delegate

/**
 PingID delegate
 */
@property (nonatomic, weak) _Nullable id<PingIDDelegate> delegate;

/**
 Set PingID Delegate object

 @param aDelegate The object you'd like to use. A UIViewController object for example
 */
+ (void)setPingIDDelegate:(_Nonnull id<PingIDDelegate>)aDelegate;

#pragma mark - Initializing PingID SDK

/**
 Initializes the PingID singleton instance with supported MFA of type PIDSupportedMfaTypeAutomatic.
 This method will be deprecated in future releases. Please use +[initWithAppID:supportedMfa:] instead.
 
 @param appID An ID string from PingOne admin console.
 */
+ (void)initWithAppID:(nonnull NSString *)appID;

/**
 Initializes the PingID singleton instance.
 
 @param appID An ID string from PingOne admin console.
 @param supportedMfaType The supported MFA type.
 */
+ (void)initWithAppID:(nonnull NSString *)appID supportedMfa:(PIDSupportedMfaType)supportedMfaType;

#pragma mark - Authentications

/**
Send reply to SDK and pair user

 @param selection Should contain PIDActionType or PIDTrustLevel or both. In case of ignore, ignoreIntervalUnit and ignoreInterval may be added. (Both are optional)
 @param completionBlock Used to notify the Customer mobile app about pairing process. NSError contains a more specific error in case of failure.
 */
+ (void)setUserSelection:(nonnull PIDUserSelectionObject *)selection
         completionBlock:(nullable void (^)(NSError * _Nullable error))completionBlock;

/**
 Authenticate user
 
 @param selection Should contain PIDActionType or PIDTrustLevel or both. In case of ignore, ignoreIntervalUnit and ignoreInterval may be added. (Both are optional)
 @param completionBlock Will return NSError in case of an error.
 */
+ (void)setAuthenticationUserSelection:(nonnull PIDUserSelectionObject *)selection
                       completionBlock:(nullable void(^)(NSError * _Nullable error))completionBlock;

/**
 Call this function in order to get an offline one-time passcode.

 @return One-time passcode.
 */
+ (nullable NSString *)getNextOneTimePasscode;

#pragma mark - SDK-to-Server Payload

/**
 Returns an encrypted payload string for any communication needed between Customer mobile app and the PingID SDK server, through the Customer server.
 
 @param error If there is a problem with the method, an error code will be returned. (Optional)
 @return If method is successful, a string will be returned in order to pass to the Customer server. This payload must be sent to the PingID SDK server from the Customer server.
 */
+ (nullable NSString *)generatePayload:(NSError * _Nullable * _Nullable)error;

/**
 Returns an encrypted updated payload string for any communication needed between Customer mobile app and the PingID SDK server, through the Customer server.
 
 @param selection Should contain PIDActionType or PIDTrustLevel or both. In case of ignore, ignoreIntervalUnit and ignoreInterval may be added. (Both are optional)
 @param error If there is a problem with the method, an error code will be returned. (Optional)
 @return If method is successful, a string will be returned in order to pass to the Customer server. This payload must be sent to the PingID SDK server from the Customer server.
 */
+ (nullable NSString *)updateExistingPayloadWithUserSelection:(nonnull PIDUserSelectionObject *)selection error:(NSError * _Nullable * _Nullable)error;

/**
 Every payload received from the Customer server should be sent to the PingID SDK
 
 @param serverPayload Payload from the Customer server
 @param completionBlock May include availableTrustLevels to present to the user. availableTrustLevels is an array of PIDTrustLevel wrapped with NSNumber, for example [@(PIDTrustLevelPrimary),@(PIDTrustLevelTrusted)]
 */
+ (void)setServerPayload:(nonnull NSString *)serverPayload
         completionBlock:(nullable void(^)(PIDFlowState flowState, NSArray * _Nullable availableTrustLevels, NSError * _Nullable error))completionBlock;

/**
This is a mandatory post action method which should be executed once, after receiving an access token from Ping Federate.
@param dataCenter The data center that should be used. 
@param completionBlock May include availableTrustLevels to present to the user. availableTrustLevels is an array of PIDTrustLevel wrapped with NSNumber, for example [@(PIDTrustLevelPrimary),@(PIDTrustLevelTrusted)]
*/
+ (void)postIDPAuthenticationStepWithDataCenter:(PIDDataCenterType)dataCenter
                                completionBlock:(nullable void(^)(PIDFlowState flowState, NSArray * _Nullable availableTrustLevels, NSError * _Nullable error))completionBlock;
#pragma mark - Remote Notifications

/**
 Checks the payload received in remote Notification in order to check its validity against PingID SDK server.
 
 @param userInfo The userInfo received in the AppDelegate application:didReceiveRemoteNotification:fetchCompletionHandler: method.
 @return Returns YES if the remote notification data is PingID related.
 */
+ (BOOL)isRemoteNotificationFromPingID:(nonnull NSDictionary *)userInfo;

/**
 Set device remote notification token. Should be within application:didRegisterForRemoteNotificationsWithDeviceToken:

 @param deviceToken The deviceToken received in the AppDelegate application:didRegisterForRemoteNotificationsWithDeviceToken: method.
 */
+ (void)setRemoteNotificationsDeviceToken:(nullable NSData *)deviceToken;

/**
 Get PingID remote notification categories for iOS 8 & 9. Registering UIUserNotificationSettings more than once results in previous settings being overwritten. PingID provides the needed categories. The developer may add categories.
 @return Returns PingID remote notification categories.
 */
+ (nonnull NSMutableSet *)getPingIDDeprecatedRemoteNotificationsCategories;

/**
 Get PingID remote notification categories for iOS 10. Setting UNNotificationCategory more than once results in previous settings being overwritten. PingID provides the needed categories. The developer may add categories.
 @return Returns PingID remote notification categories.
 */
+ (nonnull NSMutableSet *)getPingIDRemoteNotificationsCategories;

/**
 Handles the remote notification received from PingID. The developer should call isRemoteNotificationFromPingID: before this method in order to check the payload validity.

 @param userInfo The userInfo received in the AppDelegate application:didReceiveRemoteNotification:fetchCompletionHandler: method.
 @param completionBlock Will return NSError in case of an error. sessionInfo may include device details and timeout details. availableTrustLevels is an array of PIDActionType wrapped with NSNumber, for example [@(PIDTrustLevelPrimary),@(PIDTrustLevelTrusted)] (Optional)
 */
+ (void)handleRemoteNotification:(nonnull NSDictionary *)userInfo
                   completion:(nullable void(^)(PIDRemoteNotificationType remoteNotificationType, NSArray * _Nullable availableTrustLevels, NSDictionary * _Nullable sessionInfo, NSError * _Nullable error))completionBlock;

/**
 Tells PingID to perform the custom action specified by a remote notification. Should be within application:handleActionWithIdentifier:forRemoteNotification:

 @param identifier The identifier received in the AppDelegate application:handleActionWithIdentifier:forRemoteNotification: method.
 @param userInfo The userInfo received in the AppDelegate application:handleActionWithIdentifier:forRemoteNotification: method.
 @param completionBlock Will return NSError in case of an error.
 */
+ (void)handleActionWithIdentifier:(nonnull NSString *)identifier forRemoteNotification:(nonnull NSDictionary *)userInfo
                  completionBlock:(nullable void(^)(NSError * _Nullable error))completionBlock;

/**
 The developer can decide if PingID uses sandbox or production APNS

 @param debugMode YES to use sandbox APNS. Defaults to NO
 */
+ (void)setDebugMode:(BOOL)debugMode;


/**
 The developer can decide if the device will stay trusted after app reinstallation. This method should only be called once per SDK initialization. 
 
 @param keep YES to save state. Defaults to NO
 */
+ (void)setKeepTrustedDeviceAfterReinstall:(BOOL)keep;


/**
 Send logs to PingID SDK server

 @param completionBlock will return NSError in case of an error.
 */
+ (void)sendLogs:(nullable void (^)(NSString * _Nullable supportId, NSError * _Nullable error))completionBlock;

/**
 **************** Warning  ****************
 Using this method will remove the trusted connection between the iOS SDK and the PingID SDK 
 server in a one sided manner, where only the iOS side will be removed.
 This method should not be used when logging out of your account.
 */
+(void)removePingIDSDKLocalData;

typedef NS_ENUM(NSUInteger, PIDError)
{
    PIDErrorInternal                    =   -10000,
    PIDErrorWithPairing                 =   -10001,
    PIDErrorAppDisabled                 =   -10002,
    PIDErrorWrongAppID                  =   -10003,
    PIDErrorRemoteNotificationTimeout   =   -10004,
    PIDErrorNoInternetConnection        =   -10005,
    PIDErrorWrongSignature              =   -10006,
    PIDErrorProblemWithPublicKey        =   -10007,
    PIDErrorMissingPermissions          =   -10008,
    PIDErrorReachability                =   -10009,
    PIDErrorServerResponse              =   -10010,
    PIDErrorServerInternal              =   -10011,
    PIDErrorWithServerPayload           =   -10012,
    PIDErrorSelectionIsMissing          =   -10013,
    PIDErrorDeviceTokenIsMissing        =   -10014
};



@end

@interface PIDUserSelectionObject : NSObject

/**
 Create the PIDUserSelectionObject that will be passed to the supported methods. Should contain PIDActionType or PIDTrustLevel or both. In case of ignore, ignoreIntervalUnit and ignoreInterval may be added. (Both are optional)

 @param action Can be any of the PIDActionType
 @param trustLevel Can be any of the PIDTrustLevel 
 @return Returns the PIDUserSelectionObject.
 */
-(nonnull PIDUserSelectionObject *)initWithAction:(PIDActionType)action trustLevel:(PIDTrustLevel)trustLevel;

@property (nonatomic, assign)   PIDIgnoreIntervalUnit ignoreIntervalUnit; //Can be any of the PIDIgnoreIntervalUnit types   (Optional)
@property (nonatomic, assign)   NSInteger ignoreInterval;                 //Units of time                                   (Optional)
@property (readonly)            PIDActionType action;
@property (readonly)            PIDTrustLevel trustLevel;

- (nonnull instancetype)init NS_UNAVAILABLE;

@end

PingID SDK Mobile API error codes

Error Description Failure reason Recovery suggestion
PIDErrorInternal An internal error occurred. An unknown error has occurred. Please contact PingID Support.
PIDErrorWithPairing There was a problem with the pairing process. An unknown error has occurred. Please contact PingID Support.
PIDErrorAppDisabled The current App Id is disabled in the PingOne admin console. The current App Id is disabled in the PingOne admin console. You can enable the app in the PingOne admin console.
PIDErrorRemoteNotificationTimeout Remote notification timeout. The remote notification didn’t reach the device. This could be due to a certificate problem or a connectivity issue. Make sure the certificates in PingOne admin console are valid for both enviroments. Also make sure that you have a working internet connection.
PIDErrorNoInternetConnection There was a problem with your internet connection. There was a problem with your internet connection. Check that you have a working internet connection.
PIDErrorWrongSignature There was a problem verifying the response from the server. An unknown error has occurred. Please contact PingID Support.
PIDErrorReachability There was a problem connecting to the server. There was a problem connecting to the server. Check that you have a working internet connection.
PIDErrorServerResponse There was a problem with the server response. There was a problem with the server response. Please contact PingID Support.
PIDErrorServerInternal There was a problem with the server response. There was a problem with the server response. Please contact PingID Support.
PIDErrorWithServerPayload There was a problem with the server payload. The server payload can’t be decoded. Make sure that you pass the exact payload value you receive from hosting server response to the setServerPayload method.
PIDErrorSelectionIsMissing There was a problem with your PIDUserSelectionObject. One or more mandatory items were not selected. PIDUserSelectionObject must contain at least a trustLevel or an action.
PIDErrorDeviceTokenIsMissing There was a problem finding the device token. One or more mandatory items were not found. PingID SDK must contain the device token in order to support remote notification MFA.