Models, objects, and error codes
When using the PingOne MFA IdP Adapter through the PingFederate authentication API, the adapter uses the following state models, action models, objects, and error codes.
State models
Status | Response Model | Action | Description | ||
---|---|---|---|---|---|
|
|
|
Indicates that authentication is required. This state is the first state returned from the adapter. |
||
|
|
|
Indicates that authentication is required. This state is the first state returned from the adapter. |
||
|
|
|
Indicates that device selection is required, and the user has more than one device. |
||
|
|
|
Indicates that OTP is required. This state is returned when the user is prompted to provide an OTP. The OTP is one of the following:
|
||
|
|
|
Indicates that a push was sent to the user.
|
||
|
|
|
Indicates a push timeout state. |
||
|
|
|
Indicates that the user has rejected the push. |
||
|
|
|
Indicates a successful MFA. The API client must call |
||
|
See |
|
Indicates a dead end. The API client can proceed in the flow by calling |
||
|
The PingOne ID token. |
|
Indicates that mobile pairing is required. |
||
|
This state has no model. |
|
The user must set up a device for multi-factor authentication. |
||
|
|
|
The user must select a device type for multi-factor authentication to proceed. |
||
|
|
|
Device integrity validation failed. The device integrity check determined that the device is jailbroken (iOS) or rooted (Android). |
||
|
This state has no model. |
|
The user must submit an email address for multi-factor authentication. |
||
|
This state has no model. |
|
The user must submit a phone number for multi-factor authentication. |
||
|
This state has no model. |
|
The user must submit a phone number for multi-factor authentication. |
||
|
|
|
The user must activate their mobile device to complete the device pairing. |
||
|
|
|
The user must submit their authenticator activation code to complete the device pairing. |
||
|
|
|
The user must submit their email activation code to complete the device pairing. |
||
|
|
|
The user must submit their SMS activation code to complete the device pairing. |
||
|
|
|
The user must submit their voice activation code to complete the device pairing. |
||
|
|
|
The user must pair their biometrics with the browser to complete the device pairing. |
||
|
|
|
The user must pair their security key with the browser to complete the device pairing. |
||
|
|
|
The user must complete multi-factor authentication via authentication code. |
||
|
|
|
The user must select the one-time device from the list to proceed ahead with authentication flow. |
||
|
|
|
Indicates that OTP is required. This state is returned when the user is prompted to provide an OTP. The OTP is one of the following: Sent to the user in an SMS, voice call, or email. |
||
|
This state has no model. |
|
The user must provide the server name where the fetch originates. |
||
|
This state has no model. |
|
The user can either add a device nickname or skip adding a device nickname. |
Action models
Action | Request Model | Errors | Description |
---|---|---|---|
|
|
|
Starts an authentication flow. The mobile payload is required in cases of mobile app access. The presence or absence of the mobile payload determines whether the flow is a mobile or web authentication, respectively. You cannot switch midway between mobile and web authentication flows. |
|
|
|
Starts an authentication with the specified deviceId. For example:
If there is already an authentication in progress, this authentication will be canceled. This action is available only when the user has at least one device, and can also be used as an authentication retry. A mobile payload is required if a user requests access from an untrusted mobile app, and needs to select of one of the user’s trusted devices to approve or deny access. |
|
|
|
Sets the user’s default authentication device. For example:
If there is already an authentication in progress, this authentication will be canceled. This action is available only when the user has at least one device, and can also be used as an authentication retry. A mobile payload is required if a user requests access from an untrusted mobile app, and needs to select of one of the user’s trusted devices to approve or deny access. |
|
|
|
Validates the provided OTP. |
|
This action has no model. |
|
This action returns the authentication code request status. |
|
This action has no model. |
This action has no errors. |
This action cancels the current authentication step. |
|
This action has no model. |
This action has no errors. |
This action continues the current authentication flow. |
|
This action has no model. |
This action has no errors. |
Initiates the multi-factor authentication pairing process. |
|
This action has no model. |
|
Skip the multi-factor authentication pairing process. |
|
|
|
Select a device pairing method to pair as a new multi-factor authentication device. |
|
This action has no model. |
This action has no errors. |
Cancel the multi-factor authentication pairing process. |
|
|
|
Pair an email address for use as a new multi-factor authentication device. |
|
|
|
Pair a phone number for use as a new multi-factor authentication device. |
|
|
|
Pair a phone number for use as a new multi-factor authentication device. |
|
|
|
Submit the email activation code to complete the device pairing. |
|
|
|
Submit the SMS activation code to complete the device pairing. |
|
|
|
Submit the voice activation code to complete the device pairing. |
|
|
|
Activate an authenticator for use as a new multi-factor authentication device. Submit the authenticator activation code to complete the device pairing. |
|
|
|
|
|
|
|
|
|
|
|
Starts the One-Time Device OTP authentication flow for the selected device. |
|
This action has no model. |
|
Resend the OTP to the previously selected device. |
|
|
|
Continue with biometric device authentication. |
|
|
|
Give a unique nickname to a device. |
|
This action has no model. |
This action has no errors. |
Skip updating the device nickname during the device pairing flow. |
|
|
|
Remove a device. See the |
Objects
Parameter name | Type | Description |
---|---|---|
|
String |
Unique identifier of a trusted device in the PingOne MFA server. |
|
String |
Model of the device. For example, "iPhone 5S". This parameter is empty for OTP devices (SMS, voice, email, TOTP). |
|
String |
Model of the device, for example, "iPhone 5S". This parameter is empty for OTP devices (SMS, voice, email, TOTP). |
|
String |
The device’s nickname. |
|
String |
The ID of the customer mobile application. |
|
String |
The device’s operating system version. |
|
String |
The device’s application version. |
|
String |
The device’s masked email address/phone number. |
|
boolean |
Indicates whether the device is usable. |
|
String |
The type of One-Time Device. Possible values - SMS, voice, email. |
|
String |
The device’s masked email address/phone number. |
|
String |
Random ID to identify the device within the response. |
Parameter name | Type | Description |
---|---|---|
|
String |
The user’s PingOne user ID or username that was mapped into the adapter. |
Parameter name | Type | Description |
---|---|---|
|
String |
The resource’s identifier. |
Parameter name | Type | Description |
---|---|---|
|
String |
The type of the device. |
|
String |
The name of the native application associated with this device, if the device is a mobile application. For other device types, this attribute is omitted. |
|
String |
The ID of the native application associated with this device, if the device is a mobile application. For other device types, this attribute is omitted. |
|
String |
Specifies the server name/relying party that is initiating the request. This is required to initiate pairing requests of security key/biometrics devices. If not provided, the PingFederate domain is used. |
|
String |
Identifies the server name/relying party that is initiating the request. This is required to initiate pairing requests of security key/biometrics devices. If not provided, the string |
|
String |
User agent of device initiating the pairing request. This is applicable only for platform/biometrics device pairing requests. It is passed to PingOne so it can accurately capture additional platform information of the device. |
Parameter name | Type | Description |
---|---|---|
|
String |
The relying party identifier. |
|
String |
The relying party’s human-readable display name. |
Parameter Name | Type | Description |
---|---|---|
|
String |
A string that specifices the code request ID. |
|
String |
A string that specifies a universal link such as https://www.example.com/pingonesdk?authentication_code={{generated token}}). This property can also set a link to a schema application such as pingoneapp://pingonesdk?authentication_code={{generated token}}). If a universal link or schema application link is not set, the response does not include the pingonesdk?authentication_code={{generated token}} portion of the URL. |
|
String |
An enumeration that specifies whether the mobile device must verify that the user approves the authentication with the scanned code. Options are |
|
String |
A date that specifies the expiration time of authentication code. |
|
String |
A date that specifies when the resource was last updated. |
|
String |
A date that specifies when the resource was created. |
|
Application |
Mobile application info. |
|
ClientContext |
Provides relevant information to the mobile application that can be shown to application users. |
|
LifeTime |
Specifies the length of time for this authentication code to be valid. |
|
String |
A string that specifies the status of the authentication code. Options are |
|
String |
A string that specifies the ID of a mobile application for which the code is valid; only the specified mobile application can scan the QR code. |
|
String |
Client information header. |
|
String |
Client information body |
|
Integer |
Specifies the length of time for this authentication code to be valid. |
|
String |
A string that specifies the time unit for the |
There may be values such as SMS message, email configuration type and others, that you want the client to pass to PingFederate for step-up authentication and transaction approval. However, these values cannot be sent using the PingFederate Authentication API, due to security reasons. See Transaction approval setup for details on the available parameters and the instructions for sending them to PingFederate. |
Error codes
An error code is returned if the call flow state has not reached a dead end, and the user can still authenticate with a device. In cases where a flow reaches a dead end, the MFA_FAILED
state is returned with a corresponding code.
Error code | Message | HTTP status |
---|---|---|
|
One or more validation errors occurred. |
|
|
The request could not be completed. There was an issue processing the request. |
|
|
The requested resource was not found. |
|
Error code | Message | userMessageKey | Parent code |
---|---|---|---|
|
An invalid or expired passcode was provided. |
|
|
|
The passcode has expired. |
|
|
|
An invalid device was provided. |
|
|
|
The user performed too many unsuccessful passcode attempts. |
|
|
|
The user performed too many unsuccessful TOTP passcode attempts. |
|
|
|
The user has resent the passcode the maximum number of times. |
|
|
|
Failed to send the push message. |
|
|
|
An invalid mobile payload was provided. |
|
|
|
An invalid device pairing method was provided. |
|
|
|
The request could not be completed. One or more validation errors were in the request. |
|
|
|
An invalid email address was provided. |
|
|
|
An invalid phone number was provided. |
|
|
|
Reached maximum number of allowed methods limit. |
|
|
Error code | Message | userMessageKey |
---|---|---|
|
Server error. |
|
|
Service unavailable. |
|
This error code can also be returned if this is not a dead end. |
The user has re-sent the passcode the maximum number of times. |
|
|
Failed to send the push message. |
|
|
Mobile payload is valid but the extra push verification did not arrive. |
|
|
The user has no usable devices for the requested authentication policy. |
|
|
The user does not have MFA enabled. |
|
|
The user is not enabled in PingOne or does not exist. |
|
|
Device integrity validation failed. |
|