iOS PingOne Mobile SDK API


Overview

The PingOne Mobile SDK provides the ability to integrate PingOne MFA functionality into your mobile applications.

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

The PingOne Mobile SDK package is available for download at https://github.com/pingidentity/pingone-customers-mobile-sdk. Further details for setup and integrating PingOne Mobile SDK into your mobile apps are available in the README file in the iOS folder of the downloadable package.

See Edit an application in the admin guide for the server-side configuration steps.

PingOne Mobile SDK API - iOS (PingOne.h)

//
//  PingOne.h
//  PingOne
//
//  Created by Ping Identity on 3/12/19.
//  Copyright © 2019 Ping Identity. All rights reserved.
//

@objc public enum ErrorCode : NSInteger {

    /// Internal Error.
    case internalError

    /// Device token was missing and is required to complete this action.
    case deviceTokenIsMissing

    /// Remote notification isn't from PingOne.
    case unrecognizedRemoteNotification

    /// There was a server error.
    case serverError

    /// There was a problem with the network.
    case noConnectivity

    /// There was a problem with the pairing key.
    case pairingKey

    /// There was a problem with the bundle id.
    case bundleId

    /// Device may be paired in one regional data center only, and is already paired in another regional data center.
    case pairingKeyDataCenterMismatch

}

/// A Notification Object represents an authentication request via remote notification. It can be approved or denied.
@objc public class NotificationObject : NSObject {

    /// Type that describes the purpose of the notification.
    @objc public enum NotificationType : NSInteger {

        /// Notification was not recognized.
        case none

        /// Notification process has finished. No further action is required.
        case done

        /// Authentication notification that should be presented to the user and followed with the `approve` or `deny` method.
        case authentication
    }

    /// Describes the purpose of the notification.
    @objc final public let notificationType: PingOne.NotificationObject.NotificationType

    /// Approve authentication
    /// - Parameters:
    ///   - withAuthenticationMethod: The `String` is the authentication method that was used to authenticate the user on the authenticating device, for example, fpt (fingerprint), face (facial recognition) etc. Refer to the "amr" (Authentication Method Reference) values in https://tools.ietf.org/html/rfc8176/#section-2 .
    ///   - completionHandler: Will return NSError in case of an error.
    @objc final public func approve(withAuthenticationMethod: String?, completionHandler: @escaping (NSError?) -> Void)

    /// Approve authentication
    ///
    /// - Parameter completionHandler: Will return NSError in case of an error.
    @available(*, deprecated, message: "please use approve(withAuthenticationMethod:completionHandler) instead")
    @objc final public func approve(completionHandler: @escaping (NSError?) -> Void)

    /// Deny authentication
    ///
    /// - Parameter completionHandler: Will return NSError in case of an error.
    @objc final public func deny(completionHandler: @escaping (NSError?) -> Void)
}

/// PairingObject represents a pairing request that can be approved or ignored.
@objc public class PairingObject : NSObject {

    /// Approve pairing
    ///
    /// - Parameter completionHandler: Will return NSError in case of an error.
    @objc final public func approve(completionHandler: @escaping (NSError?) -> Void)
}

@objc public class PingOne : NSObject {

    /// Type that describes the APNS environment.
    @objc public enum APNSDeviceTokenType : NSInteger {

        /// Production environment.
        case production

        /// Sandbox environment.
        case sandbox
    }

    /// Returns a payload string for any communication needed between the customer mobile app and the PingOne server.
    @objc public static func generateMobilePayload() throws -> String

    /// Pair device
    ///
    /// - Parameters:
    ///   - pairingKey:         The `String` value
    ///   - completionHandler:  Will return NSError in case of an error.
    @objc public static func pair(_ pairingKey: String, completionHandler: @escaping (NSError?) -> Void)

    /// When using OpenID Connect, this is a mandatory post action method which should be executed after receiving an ID token from the PingOne server.
    ///
    /// - Parameters:
    ///   - idToken:         The `String` value
    ///   - completionHandler:  Will return NSError in case of an error. Will return PairingObject in case further action is required, such as approving the pairing.
    @objc public static func processIdToken(_ idToken: String, completionHandler: @escaping (PingOne.PairingObject?, NSError?) -> Void)

    ///  Set device remote notification token. Should be within application:didRegisterForRemoteNotificationsWithDeviceToken:
    ///
    /// - Parameters:
    ///   - deviceToken: The `Data` received within application:didRegisterForRemoteNotificationsWithDeviceToken:
    ///   - type: The `APNSDeviceTokenType` case.
    ///   - completionHandler: Will return NSError in case of an error.
    @objc public static func setDeviceToken(_ deviceToken: Data, type: PingOne.PingOne.APNSDeviceTokenType, completionHandler: @escaping (NSError?) -> Void)

    /// Get PingOne remote notification categories. Setting UNNotificationCategory more than once results in previous settings being overwritten.
    /// PingOne provides the needed categories. The developer may add categories.
    /// - Returns: The remote notification categories.
    @objc public static func getUNNotificationCategories() -> Set<UNNotificationCategory>

    /// Process the remote notification received from PingOne.
    ///
    /// - Parameters:
    ///   - userInfo: The `[AnyHashable : Any]` received in the AppDelegate application(_:didReceiveRemoteNotification:fetchCompletionHandler:) method.
    ///   - completionHandler: Will return NSError in case of an error. Will return NotificationObject in case further action is required, such as approving or denying an authentication.
    @objc public static func processRemoteNotification(_ userInfo: [AnyHashable : Any], completionHandler: @escaping (PingOne.NotificationObject?, NSError?) -> Void)

    ///  Tells PingOne server to perform the custom action specified by a remote notification. Should be within userNotificationCenter(_:didReceive:withCompletionHandler:) method.
    ///
    /// - Parameters:
    ///   - identifier: The `String` is the response.actionIdentifier received within userNotificationCenter(_:didReceive:withCompletionHandler:) method.
    ///   - userInfo: The `[AnyHashable : Any]` received within userNotificationCenter(_:didReceive:withCompletionHandler:) method.
    ///   - authenticationMethod: The `String` is the authentication method that was used to authenticate the user on the authenticating device, for example, fpt (fingerprint), face (facial recognition) etc. Refer to the "amr" (Authentication Method Reference) values in https://tools.ietf.org/html/rfc8176/#section-2 .
    ///   - completionHandler: Will return NSError in case of an error. NotificationObject will be returned in case an action is required.
    @objc public static func processRemoteNotificationAction(_ identifier: String, authenticationMethod: String?, forRemoteNotification userInfo: [AnyHashable : Any], completionHandler: @escaping (PingOne.NotificationObject?, NSError?) -> Void)

    ///  Tells PingOne server to perform the custom action specified by a remote notification. Should be within userNotificationCenter(_:didReceive:withCompletionHandler:) method.
    ///
    /// - Parameters:
    ///   - identifier: The `String` is the response.actionIdentifier received within userNotificationCenter(_:didReceive:withCompletionHandler:) method.
    ///   - userInfo: The `[AnyHashable : Any]` received within userNotificationCenter(_:didReceive:withCompletionHandler:) method.
    ///   - completionHandler: Will return NSError in case of an error. NotificationObject will be returned in case an action is required.
    @available(*, deprecated, message: "please use processRemoteNotificationAction(identifier:authenticationMethod:userInfo) instead")
    @objc public static func processRemoteNotificationAction(_ identifier: String, forRemoteNotification userInfo: [AnyHashable : Any], completionHandler: @escaping (PingOne.NotificationObject?, NSError?) -> Void)

    ///  **************** Warning  ****************
    /// Using this method will remove the trusted connection between the iOS SDK and the PingOne server
    /// 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.
    /// This method should only be used in development.
    @objc public static func removePingOneLocalData()

    /// The developer can decide if the device will stay paired after app reinstallation. This method should only be called once.
    ///
    /// - Parameter stayPaired: The `Bool` value. `true` to stay paired. Defaults to `false`.
    @objc public static func setDevicePairedAfterReinstall(_ stayPaired: Bool)
}

PingOne Mobile SDK API error codes

Error Status Description
10000 internalError Internal Error
10001 deviceTokenIsMissing Device token was missing and is required to complete this action
10002 unrecognizedRemoteNotification Remote notification isn’t from PingOne
10003 serverError There was a server error
10004 noConnectivity There was a problem with the network
10005 pairingKey There was a problem with the pairing key
10006 bundleId There was a problem with the bundle ID
10007 pairingKeyDataCenterMismatch Device may be paired in one regional data center only, and is already paired in another regional data center.