Pairing - automatic enrollment

The automatic enrollment flow requires as little as one extra step from the user. The first time the user logs into an application which has an embedded PingOne Mobile SDK component, they are asked if they wish to trust that device. Once they approve, PingOne works behind the scenes, without requiring anything else from the user.

During user authentication, a mobile app communicates with the PingOne platform to generate a token. The token allows pairing the device to the user in the context of a customer application. The user is not required to type or scan anything.

  1. The user is identified on the customer mobile application, usually with a unique user identifier, for example, a username.
  2. The PingOne Mobile SDK returns a mobile payload to the customer mobile application. The payload is a small data package created by the PingOne Mobile SDK component, which is used as part of the device’s authorization.
  3. The customer mobile application sends an authentication request to the PingOne Platform, including the mobile payload.
  4. The customer mobile application receives an ID token.
  5. The customer mobile application passes the ID token to the PingOne Mobile SDK.
  6. The PingOne Mobile SDK returns a pairing object to the customer mobile application, to pair or ignore the device.
  7. The customer mobile application prompts the user for the approve or deny action via a dialog. Based on the user’s choice, the customer mobile application notifies PingOne Mobile SDK.
  8. The PingOne Mobile SDK completes the transaction accordingly, by communicating directly with PingOne Platform.

Implement automatic pairing of mobile app as MFA authenticator app

In order to enable automatic pairing of a mobile app as an MFA authenticator app, there are several tasks that must be coordinated between admin and developers.
In brief, you will do the following:

Follow the detailed steps below:

Supply the relevant details for the admin to do the following in the PingOne admin console:

Admin tasks

  1. Create a native app. See Add an application - Native.
  2. In Edit an application, in the Authenticator tab:
  3. Create a sign-on policy, and add an MFA step. See Add an authentication policy.
  4. In the MFA step, mark the Mobile Applications checkbox, and mark the native application created in step 1.
  5. In the native application’s Policies tab, choose the sign-on policy you created.
  6. In Edit an authentication policy, in the MFA step, under the native application name, mark the Auto Enrollment checkbox. (Note that steps 1-5 are always required for mobile authentication, for either push notification or device authorization.)

Developer tasks

In your mobile application code (also described in the iOS and Android README.md files, see PingOne Mobile SDK for iOS or PingOne Mobile SDK for Android):

  1. Get the mobile payload from the SDK (PingOne.generateMobilePayload())
  2. Pass the received payload of the OIDC request to the authorization service, as the mobilePayload query parameter.
  3. Call processIdToken() with the token you received from PingOne platform.
  4. If automatic pairing is triggered (i.e. the user was not already paired with the device), processIdToken() will return a pairing object with approve() and deny() functions. Calling approve() will pair the user with the device.

Automatic device authorization

During automatic device authorization, a mobile app communicates with the PingOne platform to generate a token. The token allows authenticating the user device in the context of a customer application. The user is not aware of this, and is not required to type or scan anything.

  1. The customer mobile app requests a mobile payload from the PingOne Mobile SDK.
  2. The PingOne Mobile SDK returns a mobile payload to the customer mobile application.
  3. The customer mobile application sends an authentication request to the PingOne Platform, including the mobile payload.
  4. If the platform’s authentication flow (sign-on policy) contains an MFA step, and extra verification is disabled, the platform verifies that the mobile device is paired and active, authenticates the mobile device, and the MFA step succeeds. The flow skips to step 9.
  5. The platform verifies that the mobile device is paired and active and sends a “silent” push notification to the mobile application via the APNS/GCM notification service.
  6. The mobile application passes the “silent” notification to the PingOne Mobile SDK.
  7. The PingOne Mobile SDK acknowledges receiving the “silent” push by sending a confirmation directly to the PingOne platform.
  8. The platform authenticates the mobile device, and the MFA step succeeds.
  9. The customer mobile application receives an ID token from the PingOne Platform.
  10. The customer mobile application passes the ID token to the PingOne Mobile SDK.
  11. The PingOne Mobile SDK returns null to the customer mobile application, indicating that authorization has completed and no further action needs to be taken.

Implement automatic device authorization

Admin tasks

The admin configuration that was implemented for automatic enrollment, is applied to automatic device authorization.

  1. Create a native app, or edit an existing app. See Add an application - Native.
  2. In Edit an application, in the Authenticator tab:
  3. Create a sign-on policy, and add an MFA step. See Add an authentication policy.
  4. In the MFA step, mark the Mobile Applications checkbox, and mark the native application created in step 1.
  5. In the native application’s Policies tab, choose the sign-on policy you created.
  6. In Edit an authentication policy > Add a multi-factor authentication step, in the MFA step, under the native application name, mark the Device Authorization checkbox.
  7. Configure Extra Verification: Leave the Extra Verification checkbox unchecked to disable extra verification, or mark the checkbox to select the Permissive or Restrictive modes. (Note that steps 1-5 are always required for mobile authentication, for either manual or automatic authorization.)

Developer tasks

In your mobile application code (also described in the iOS and Android README.md files, see PingOne Mobile SDK for iOS or PingOne Mobile SDK for Android):

  1. Get the mobile payload from the SDK (PingOne.generateMobilePayload())
  2. Pass the received payload of the OIDC request to the authorization service, as the mobilePayload query parameter.
  3. Call processIdToken() with the token you received from PingOne platform.
  4. If device authorization is triggered (i.e. verification that the user’s device is already paired and active), processIdToken() will return null, indicating that authorization has completed and no further action needs to be taken.