Pair first device

Note: This page is for developers using the PingID SDK. For information on pairing additional devices with PingID, see Managing your devices in the PingID End User Guide.

In order to build a network of trusted devices, a user needs to pair a first device for that application. Once trusted, that device may be used as an authentication device during logins and transaction approval for a specific application. The first paired device will typically become the user’s primary device, which is their default authentication device. The primary device is also used for authorizing additional devices into the user’s network of trusted devices for an application.

There are two major pairing flow options for pairing a user’s first device:

Pairing a user’s first device: Automatic pairing flow.
Pairing a user’s first device: Manual pairing flow.

Pairing a user’s first device: Automatic pairing flow

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

Registration of a device behind the scenes means that during user authentication, a customer server communicates with the PingID SDK server to generate a token. The token allows pairing the device to the user. The user is not aware of this, and is not required to type or scan anything.

The user is identified on the customer mobile application, usually with a username and password.
The PingID SDK component passes a payload to the customer mobile application.
The customer mobile application sends an authentication request to the customer server, with the username, password and payload.
The customer server performs the first factor authentication, and if it’s successful, it starts the automatic pairing flow using the PingID SDK server:

a) The customer server checks if the user already exists in the PingID SDK server. If not, the user is then created in the PingID SDK server.

b) The customer server creates a registration token for the user, which contains a server payload.
The PingID SDK component parses the server payload and triggers an event in the customer mobile app, with available trust levels that the user can choose for this device:
- Primary: Pair this device as a primary device. This option is available only if the user doesn’t already have a primary device.
- Trusted: Pair this device as a trusted device.
- Ignore: Ignore this device for an interval of time. Ignoring a device means that the device is not paired with PingID SDK, and if allowed to proceed, the user logs in without MFA. If the user asked to ignore for a duration of time, upon their next logins during that period they will not be asked if they wish to pair the device, but will login without MFA.
  
  Note: A customer can prompt the user for a device’s trust level or determine it internally. For example the logic in an app may determine that a user’s first device will be paired as a primary device, and other devices will be paired as trusted devices, as implemented in our demo code (Moderno application).
The customer mobile application prompts the user for the action via a dialog, and the user chooses one.
Based on the user’s choice, the customer mobile application invokes a function in the PingID SDK component, with the trust level chosen by the user/app for this device: Primary, Trusted or Ignore.
The PingID SDK component completes the transaction accordingly, by communicating directly with PingID SDK server.

Pairing a user’s first device: Manual pairing flow

Manual pairing provides a higher or extra level of security for pairing a user’s first device, which initiates the user’s network of trusted devices. Manual pairing requires the user to perform an extra step on their first log in to an application with an embedded PingID SDK component: On their mobile device, the user should enter or scan the pairing key which was provided to them in advance.

Manual pairing has the advantage of flexibility. It allows the customer mobile application the following capabilities:

Separation of the registration and authentication processes.
Management of the logic to determine how the user receives the pairing key (via email, on last invoice, ATM, etc.), and what the user’s pairing key should match. The customer mobile application logic may choose that the pairing key should match one user, or a group of users.

Manual pairing requires development of new flows between the application and server, on the customer server side:

Subflow 1: Obtaining a pairing key.
Subflow 2: Pairing the device with the pairing key.

Subflow 1: Obtaining a pairing key

The example below describes one way of providing the user with the required pairing key, in order to pair a first device when the organization chooses manual pairing.

The user enters their credentials in the login page.
The customer server verifies the credentials.
The customer server checks via the PingID SDK server whether the user has any paired devices.
Since the user does not have any paired devices, the customer server initiates a request to the PingID SDK server to create a pairing key, and displays it to the user for the pairing process, along with instructions on how to install or upgrade the mobile application.

Subflow 2: Pairing the device with the pairing key

The PingID SDK component passes a payload to the customer mobile application.
The customer mobile application sends an authentication request to the customer server, with the username, password and payload.
The customer server performs the first factor authentication, and if successful, communicates with the PingID SDK server.
The customer server receives the PingID SDK server response, and passes it to the customer mobile application.
The customer mobile application prompts the user for a pairing key that they received in advance via another channel.
The user enters the pairing key.
The customer mobile application sends another request to the customer server with the pairing key, username and password.
The customer server sends the pairing key to the PingID SDK server and receives a server payload, which it passes in the response to the customer mobile application.
The customer mobile application passes the server payload to the PingID SDK component.
The PingID SDK component parses the server payload and triggers an event in the customer mobile application, with available trust levels that the user can choose for this device:
- Primary: Pair this device as a primary device. This option is available only if the user doesn’t already have a primary device.
- Trusted: Pair this device as a trusted device.
- Ignore: Ignore this device for an interval of time.
The customer mobile application prompts the user for the action via a dialog, and the user chooses one.
Based on the user’s choice, the customer mobile application invokes a function in the PingID SDK component, with the trust level chosen by the user/app for this device: Primary, Trusted or Ignore.
The PingID SDK component performs the selected action.