Configure push authentication on an iOS mobile device


Introduction

This activity shows you how to configure push authentication on an iOS mobile device. It assumes that you have an Apple developer account and that you have some familiarity with creating and managing iOS mobile applications. For more information about the Apple developer program, see Apple Developer Program.

Part of this activity requires some app configuration steps in your Apple developer program account. These steps must be completed before you start using the PingOne APIs to configure push authentication. In addition, you must also use Apple’s Xcode IDE to complete the device pairing component of this task.

Apple developer workflow tasks

  1. Sign in to your Apple developer program account.

  2. Create an Apple developer key: On the Certificates, Identifiers & Profiles page, in the left navigation panel, click Keys. In the display panel, click Create a key. Make a note of your Apple team ID.

  3. Under Register a New Key, in the Key name field, enter a name for the new key (such as Push Notifications). In the services table, click to enable the Apple Push Notifications service (APNs) service. Click Continue.

  4. Click Download to download your key. Make a note of your Key ID and store in a safe place. You cannot download this key a second time.

  5. Create the application identifier: On the Certificates, Identifiers & Profiles page, in the left navigation panel, click Identifiers. In the display panel, click Register an App ID.

  6. Under Register a New Identifier, click to select the App IDs property. Click Continue.

  7. Under Register an App ID, under Platform, click the iOS, tvOS, watchOS option. In the Description field, enter a short description of your registered app ID. Next to Bundle ID, click to select the explicit option. In the Bundle ID field, enter a bundle ID name (such as com.domainname.appname). Make a note of your Bundle ID. Click Continue.

  8. Under Register an App ID, scroll to the Push Notifictions option and click the checkbox. Click Continue.

  9. Under Confirm your App ID, verify the settings and click Register.

After registering the app ID, you can log out of your Apple developer account.

PingOne workflow steps

This activity uses PingOne for Customers authentication and management APIs and the PingOne iOS Mobile SDK API to enable push authentication for the specified iOS mobile app. For more information, see PingOne iOS Mobile SDK API.

PingOne workflow tasks

This scenario illustrates the following operations supported by the PingOne for Customers APIs:

  • Create a mobile application connection.

  • Create APNs push credentials.

  • Download the PingOne Mobile SDK package.

  • Open the pingone-customers-mobile-sdk/iOS/Sample Code/SampleApp.xcodeproj in XCode and perform the following tasks:

    • Update Bundle Identifier with

    • Switch to your Apple Developer Team and enable Automatic Signing.

    • Connect and unlock your iOS Device

    • Change the build target to your iOS Device

    • Launch the app and allow push notifications. The mobile app prompts for a pairing code.

  • Create the pairing key and enter the code on the mobile app prompt screen.

Workflow order of operations

To enable push authentication on an iOS mobile app, the following tasks must be completed successfully:

  1. Make a POST request to /environment/{environmentId}/applications to create the mobile push application.

  2. Make a POST request to /environments/{environmentId}/applications/{applicationId}/pushCredentials to create the push credentials for the specified mobile application.

  3. Download the PingOne Mobile SDK package.

  4. Open pingone-customers-mobile-sdk/iOS/Sample Code/SampleApp.xcodeproj in XCode to configure and initiate pairing.

  5. Make a POST request to /environments/{envId}/users/{userId}/pairingKeys to create the pairing key for the specified user.

  6. In Xcode, enter the pairing key code on the mobile app prompt screen.

Step 1: Create the mobile application

The POST /environment/{environmentId}/applications endpoint creates the application connection and sets the type property to NATIVE_APP options. To enable push notifications for this mobile application, you must also specify the application’s bundle ID, which you registered with the app ID in your Apple developer program account.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/applications" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
  {
    "name": "MyMobileApp",
    "description": "Mobile app with push authentication",
    "enabled": true,
    "type": "NATIVE_APP",
    "protocol": "OPENID_CONNECT",
    "responseTypes": [
        "TOKEN",
        "ID_TOKEN"
    ],
    "grantTypes": [
        "IMPLICIT"
    ],
    "tokenEndpointAuthMethod": "CLIENT_SECRET_BASIC",
    "postLogoutRedirectUris": [
        "https://example.com"
    ],
    "redirectUris": [
        "https://example.com"
    ],
    "bundleId": "{yourBundleID}"
}
}'

The response returns a 201 Created message and shows the application connection data. Note that the pkceEnforcement property was omitted from the request, and consequently, the value of this property is set automatically to OPTIONAL, which specifies that a PKCE code_challenge parameter is optional, and that any code challenge method is acceptable.

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/9b85c3fa-a380-44bc-ad09-e15a55eec84b"
    },
    "environment": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
    },
    "attributes": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/9b85c3fa-a380-44bc-ad09-e15a55eec84b/attributes"
    },
    "secret": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/9b85c3fa-a380-44bc-ad09-e15a55eec84b/secret"
    },
    "grants": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/9b85c3fa-a380-44bc-ad09-e15a55eec84b/grants"
    }
  },
  "environment": {
    "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
  },
  "id": "9b85c3fa-a380-44bc-ad09-e15a55eec84b",
  "name": "MyMobileApp",
  "description": "Mobile app with push authentication",
  "enabled": true,
  "type": "NATIVE_APP",
  "protocol": "OPENID_CONNECT",
  "createdAt": "2020-01-29T00:02:42.670Z",
  "updatedAt": "2020-01-29T00:02:42.670Z",
  "bundleId": "com.pingidentity.myBundleId",
  "responseTypes": [
    "ID_TOKEN",
    "TOKEN"
  ],
  "grantTypes": [
    "IMPLICIT"
  ],
  "tokenEndpointAuthMethod": "CLIENT_SECRET_BASIC",
  "pkceEnforcement": "OPTIONAL",
  "postLogoutRedirectUris": [
    "https://example.com"
  ],
  "redirectUris": [
    "https://example.com"
  ]
}

Step 2: Create APNS push credentials

Push credentials are required for the purpose of sending push notifications to a native application. Push credentials must be defined for the application. For an iOS mobile application, you must create Apple Push Notification service (APNS) credentials.

You can use the POST /environments/{environmentId}/applications/{applicationId}/pushCredentials endpoint to create the push credentials for the specified application.

curl -X POST "https://api.pingone.com/v1/environments/environments/{environmentId}/applications/{applicationId}/pushCredentials" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d '{
  "type": "APNS",
  "key": "<Your Key ID>",
  "teamId": "<Your Apple Team ID>",
  "token": "<Your Apple Key P8 Body>"
}'

In the request, the type property specifies APNS. The key, teamId, and token properties are information that Apple uses and were created in your Apple developer account. The key is string that Apple uses as an identifier to identify an authentication key. The teamId is a string that Apple uses as an identifier to identify teams. This property is mandatory for APNS. The token is a string that Apple uses as the authentication token signing key to securely connect to APNS. This is a p8 file with a private key format.

Confidential information is not returned in the response. The data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/fe36bb1a-3983-4d6c-af02-e7d50b0ab99a/pushCredentials/eff3f4f1-bf65-4cc5-badb-4bafd9ed0542"
    },
    "environment": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
    },
    "application": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/fe36bb1a-3983-4d6c-af02-e7d50b0ab99a"
    }
  },
  "id": "eff3f4f1-bf65-4cc5-badb-4bafd9ed0542",
  "environment": {
    "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
  },
  "application": {
    "id": "fe36bb1a-3983-4d6c-af02-e7d50b0ab99a"
  },
  "createdAt": "2020-01-29T00:45:51.747Z",
  "updatedAt": "2020-01-29T00:45:51.747Z",
  "type": "APNS"
}

Step 3: Download the PingOne Mobile SDK package

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

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

Step 4: Open the SampleApp.xcodeproj project

Open the pingone-customers-mobile-sdk/iOS/Sample Code/SampleApp.xcodeproj in Xcode, and using the sample application, perform the following tasks:

  • Edit the Bundle Identifier field to specify your bundleId value.

  • Under Signing, enable Automatically manage signing. Next, open the Team menu and select your Apple developer team.

  • Connect and unlock your iOS device.

  • Change the build target to your iOS device.

  • Launch the app and allow push notifications. The mobile app prompts for a pairing code.

Step 5: Create the pairing key

To enable multi-factor authentication through a push notification on a mobile device, the user resource must have a mobile device and an application associated with its user ID. The association is implemented with a pairing key.

The POST /environments/{envId}/users/{userId}/pairingKeys operation adds a pairing key to the specified user resource. The applicationId property value is the PingOne ID of your mobile application that you created in Step 1.

curl -X "POST" "https://api.pingone.com/v1/environments/{envId}/users/{userId}/pairingKeys" \
-H "Content-type: application/json" \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "applications": [
    {
      "id": "9b85c3fa-a380-44bc-ad09-e15a55eec84b"
    }
  ]
}'

The response includes the code property, which is the pairing key needed to enable push authentication on your mobile app. The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-1234-d5ad75dfaaa0/users/8f8a6354-1234-4430-964e-e10d4e5deed3/pairingKeys/30d03ef6-daa5-41a0-98c3-3b08d1a7c617"
    },
    "environment": {
      "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-1234-d5ad75dfaaa0"
    },
    "user": {
      "href": "https://api.pingone.com/v1/environments/f59504de-3c45-4a37-1234-d5ad75dfaaa0/users/8f8a6354-1234-4430-964e-e10d4e5deed3"
    }
  },
  "id": "30d03ef6-daa5-41a0-98c3-3b08d1a7c617",
  "environment": {
    "id": "f59504de-3c45-4a37-1234-d5ad75dfaaa0"
  },
  "code": "01646543025054",
  "status": "UNCLAIMED",
  "applications": [
    {
      "id": "9b85c3fa-a380-44bc-ad09-e15a55eec84b"
    }
  ],
  "user": {
    "id": "8f8a6354-1234-4430-964e-e10d4e5deed3"
  },
  "createdAt": "2019-07-16T19:03:34.658Z",
  "updatedAt": "2019-07-16T19:03:34.658Z",
  "expiresAt": "2019-07-18T19:03:34.657Z"
}

Step 6: Complete pairing

The code property value returned in Step 5 is the key that you must enter in the sample app prompt to complete the pairing.

To complete device pairing:

  1. Return to the sample mobile app in Xcode, and on the pairing screen, enter the code property value in the field provided. From Step 5 above, the code is:

01646543025054

  1. Click Pair to initiate pairing.

  2. After pairing is complete, click OK.