This step type pairs an MFA device with the user account during MFA enrollment. The step returns either the ENROLLED or SKIPPED result.

Step properties used with flow definitions

Configuration schema property Description
useDefaultPolicy A boolean that when set to true specifies that the environment’s default device authentication policy is used during MFA evaluation. This is a required property.
deviceAuthenticationPolicy.id A string that specifies the ID device authentication policy to use during authentication. This is a required property.
template.variant A string that specifies the notification template variant used for authentication.
Input property Description
user.id A string that specifies the user ID of the user account from the identity provider. This is a required property.
user.email A string that specifies the user’s email address.
user.mobilePhone A string that specifies the user’s mobile phone number.
webauthn.compatibility A string that specifies the webauthn compatibility.
template.locale A string that specifies the notification template locale.
template.variables An object that specifies the notification template variables.

The following properties are returned for the ENROLLED result.

Output property Description
device.id A string that specifies the device ID.
device.type A string that specifies the device type. Options are MOBILE, EMAIL, SMS, VOICE, TOTP, PLATFORM, and SECURITY_KEY.

The following properties are returned for the SKIPPED result.

Output property Description
There are no output properties for the SKIPPED result.

Step properties used with flow executions

Properties for the DEVICE_ENROLLMENT_REQUIRED flow state

Flow state Description
DEVICE_ENROLLMENT_REQUIRED A flow status that prompts the user to either enroll a device or skip the enrollment process.
Flow state response schema property Description
email A string that specifies the user email provided in the step inputs.
mobilePhone A string that specifies the user mobile phone number provided in the step inputs.
allowedtypes An array that specifies the allowed device types for pairing. Options are MOBILE, EMAIL, SMS, VOICE, TOTP, PLATFORM, and SECURITY_KEY.
mfaSettings An object that specifies the environment’s MFA settings.
applications An array that specifies the environment applications.

Properties for the ACTIVATION_REQUIRED flow state

Flow state Description
ACTIVATION_REQUIRED A flow status that prompts the user to activate the offline device to finalize the enrollment process.
Flow state response schema property Description
device An object that specifies the user device pending for activation. The device properties shown depend on the device type.

Properties for the PAIRING_REQUIRED flow state

Flow state Description
PAIRING_REQUIRED A flow status that prompts the user to pair the mobile device to finalize the mobile enrollment process. The client will have to poll the HAL self link (/{envID}/flowExecutions/{flowExecutionID}) to verify the pairing.
Flow state response schema property Description
device An object that specifies the user device pending for activation. The device properties shown depend on the device type.
pairingKey.code A string that specifies the mobile pairing key code, used to finalize the mobile enrollment process.

Properties for the MOBILE_PAIRING_FAILURE flow state

Flow state Description
MOBILE_PAIRING_FAILURE A flow status that results when mobile pairing has failed. This status returns the error code and the mobile pairing error details.
Flow state response schema property Description
error An object that specifies the error details.
error.code A string that specifies the error code.
error.message A string that specifies the error message.

Flow execution actions

Device create device.create action

Links Description
device.create The link to initiate an action to specify an MFA device to associate with the user. The action must provide a value for the type property and specify application/vnd.pingidentity.device.create+json as the custom content type in the request.
Parameters Description
type A string that specifies the device type. Options are MOBILE, EMAIL, SMS, VOICE, TOTP, PLATFORM, and SECURITY_KEY. This is a required property.
nickname A string that specifies the device nickname.
email A string that specifies the user’s email address.
phone A string that specifies the user’s phone number.
application.id A string that specifies the associated application ID, which is required for pairing with devices of type MOBILE.
rp.id A string that specifies an RP ID, which is based on a host’s domain name.
rp.name A string that specifies a human-readable name for the user account.

Device activate device.activate action

Links Description
device.activate The link to initiate an action to activate an MFA device. The action must specify application/vnd.pingidentity.device.activate+json as the custom content type in the request.
Parameters Description
otp A string that specifies the one-time passcode.
attestation A string that specifies the FIDO2 attestation.
origin A string that specifies the calling service.

Device skip device.skipEnrollment action

Links Description
device.skipEnrollment The link to skip device enrollment. This action can be used only if device registration is configured to allow skipping. The action must specify the application/vnd.pingidentity.device.skipEnrollment+json as the custom content type in the request.
Parameters Description
There are no parameters required for the device.skipPairing action.

Device delete device.delete action

Links Description
device.delete The link to delete the device registration process. This action must specify the application/vnd.pingidentity.device.delete+json as the custom content type in the request.
Parameters Description
There are no parameters required for the device.delete action.

Resend OTP otp.resend action

Links Description
otp.resend The link to resend the OTP to complere the device registration process for SMS, email, and voice devices. This action must specify the application/vnd.pingidentity.otp.resend+json as the custom content type in the request.
Parameters Description
There are no parameters required for the otp.resend action.