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

Implement automatic pairing of native app as MFA authenticator app

In order to enable automatic pairing of a native 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 Native 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 native authentication, for either push notification or device authorization.)

Developer tasks

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

  1. Get the native 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 native 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 native app requests a native payload from the PingOne Native SDK.
  2. The PingOne Native SDK returns a native payload to the customer native application.
  3. The customer native application sends an authentication request to the PingOne Platform, including the native 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 native device is paired and active, authenticates the native device, and the MFA step succeeds. The flow skips to step 9.
  5. The platform verifies that the native device is paired and active and sends a “silent” push notification to the native application via the APNS/GCM notification service.
  6. The native application passes the “silent” notification to the PingOne Native SDK.
  7. The PingOne Native SDK acknowledges receiving the “silent” push by sending a confirmation directly to the PingOne platform.
  8. The platform authenticates the native device, and the MFA step succeeds.
  9. The customer native application receives an ID token from the PingOne Platform.
  10. The customer native application passes the ID token to the PingOne Native SDK.
  11. The PingOne Native SDK returns null to the customer native 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 Native 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 native authentication, for either manual or automatic authorization.)

Developer tasks

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

  1. Get the native 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.