PingOne MFA Mobile SDK

Overview

PingOne MFA Mobile SDK is a set of components and services targeted at enabling organizations to include multifactor authentication (MFA) into native applications. This solution leverages Ping Identity’s expertise in MFA technology, as a component that can be embedded easily and quickly into a new or existing application.

Release notes can be found here.

Documentation

Reference documentation is available for PingOne MFA Mobile SDK, describing its capabilities, features, installation and setup, integration with mobile apps, deployment and more:

Content

Prerequisites
Configure iOS push messaging on the PingOne Portal
Compatibility
Installation
1. Installing with the Swift Package Manager
2. Manual downloading from the Ping Identity Assets
Working with push messages in iOS
Register device token on PingOne server
Handling Push Notifications
Localization
Kechain Sharing

1. Prerequisites

Prepare the iOS push messaging mandatory data from Apple Developer portal:

Key ID
Team ID
Token .p8 file
Bundle ID

Refer to: Establishing a Token-Based Connection to APNs.

2. Configure iOS push messaging on the PingOne Portal

When configuring your PingOne SDK application in the PingOne admin web console (Connections > Applications > {NATIVE application} > Edit > Authenticator), you should upload your .p8 token and fill in the Key ID, Team ID and Bundle ID. See Edit an application in the administration guide.

Beginning with iOS 15, users can define focus modes. In a defined focus mode, all notifications are blocked except those from apps that you choose to allow or notifications that are defined as "time-sensitive".

If you want notifications from the app that you are developing with the PingOne Mobile SDK to be defined as "time-sensitive", follow these steps:

In the Xcode project, select your target -> tap the Signing & Capabilities tab -> add the Time Sensitive Notifications capability.
Make sure to update your app Identifier in the Apple developer account to support Time Sensitive Notifications.
After the identifier is updated, you need to update the app provision profiles as well.

For more information, see the Apple documentation on managing identifiers and adding capabilities to your app.

3. Compatibility

Note: PingOne SDK supports the following software versions:

Xcode 14 and above.
iOS 12.0 and above.

4. Installation

You can use either of the following methods to add the PingOne SDK component to your existing project:

Install with the Swift Package Manager
Install from the Ping Identity Assets

4.1 Installing with the Swift Package Manager

Select File → Add Packages… in Xcode’s menu bar.
Search for the PingOne SDK using the repo's URL: https://github.com/pingidentity/pingone-mobile-sdk-ios.git
Set the Dependency Rule to Branch with value main, and make sure that Add to Project is set to your project.
Select Add Package.
Verify that the package was downloaded in your project.

4.2 Manual downloading from the Ping Identity Assets

Download the latest version 1.10.0.
Unzip the PingOneSDK.xcframework zipped file and drag it into your project.
In your Project Navigator, click on your target, and drag PingOneSDK.xcframework to Frameworks, Libraries, and Embedded Content.
Check the Copy items if needed checkbox.
Integrate the PingOneSDK component into your code:
- Import the framework into your application initialization code:
  import PingOneSDK

5. Working with push messages in iOS

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

Enable Push Notifications: Go to your Project Navigator’s capabilities tab. Select Push Notifications > Enable.
Enable Remote Notifications: Go to your Project Navigator’s capabilities tab. Turn on Background Modes > Remote notifications.
Enable Push Notifications in your Apple Developer Account > Certificates, Identifiers & Profiles > Identifiers > Capabilities > Push Notifications > Enable.
Enter your app’s Deployment Details settings in your Apple Developer Account > Certificates, Identifiers & Profiles > Identifiers > Your App ID. These details are now mandatory prerequisites for Apple to register your device for push notifications.

6. Register device token on PingOne server

In order to receive push notifications from PingOne SDK, use the following code in your didRegisterForRemoteNotificationsWithDeviceToken call, passing the deviceToken as is:

@objc public static func setDeviceToken(_ deviceToken: Data, type: APNSDeviceTokenType, completionHandler: @escaping (_ error: NSError?) -> Void)

7. Handling Push Notifications

PingOne SDK will only handle push notifications which were issued by the PingOne SDK server. For other push notifications, NSError with the code 10002, unrecognizedRemoteNotification will be returned.

The APNSDeviceTokenType should be set like this:

var deviceTokenType : PingOne.APNSDeviceTokenType = .production
#if DEBUG
deviceTokenType = .sandbox
#endif

Inside the following AppDelegate method:

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

Call:

@objc public static func processRemoteNotification(_ userInfo: [AnyHashable : Any], completionHandler: @escaping (_ notificationObject: NotificationObject?, _ error: NSError?) -> Void)

and pass it the userInfo as is.

8. Localization

The following keys are returned by the PingOne SDK Remote Notification, with suggested localization:

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

Note: An example of these keys is provided in the sample app, in the Localizable.strings file.

9. Keychain Sharing

Note: This step is required only if your app uses 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:

Disclaimer

THE SAMPLE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SAMPLE CODE OR THE USE OR OTHER DEALINGS IN THE SAMPLE CODE. FURTHERMORE, THIS SAMPLE CODE IS NOT COMMERCIALLY SUPPORTED BY PING IDENTITY BUT QUESTIONS MAY BE ADDRESSED TO PING'S SUPPORT CENTER OR MAY BE OTHERWISE ADDRESSED IN THE RELATED DOCUMENTATION.

Any questions or issues should go to the support center, or may be discussed in the Ping Identity developer communities.

pingidentity / pingone-mobile-sdk-ios