Support for authentication code flow
The PingOne MFA Integration Kit supports authentication code flow if a local identity profile (LIP) has been configured. For more information on LIPs, see Configuring local identity profiles.
Process flow
-
The PingOne MFA adapter invokes authentication code flow if the adapter is invoked using a
policy.action
attribute containing the keyword "QR"( case-insensitive). For example, thepolicy.action
attribute could be "QR code."This allows PingFederate to use the built-in QR code image for the Sign-On page.
-
When the PingOne MFA adapter is invoked in this mode, the adapter automatically takes the user through authentication code-based authentication flow for the configured application ID.
-
This template polls continuously to check for status. If the authentication code expires before user action, a new authentication code is requested automatically and displayed.
-
If approved and authentication flow is successful, the adapter returns the userID and username in the core contract
authentication.code.flow.userid
andusername
respectively along withpingone.mfa.status
set to the valuecom.pingidentity.pingone.mobile_login_authentication_code
. -
If approval is denied (when user approval is required), the adapter fails the authentication flow.
Complex authentication code request
The authentication code-based flow can be invoked to pass additional attributes described in MFA Authentication Code.
{
"application": {
"id": "{{mobileapplicationId}}"
},
"clientContext": {
"header" : "Authentication process",
"body": "Do you want to approve this transaction?"
},
"lifeTime": {
"duration": 5,
"timeUnit": "MINUTES"
},
"userApproval": "REQUIRED"
}
The adapter expects predefined attributes and when found maps the values automatically to corresponding request attribute as described below.
Incoming Attribute Name | Create Authentication Code API Attribute |
---|---|
|
|
|
|
|
|
|
|
|
|
These attributes can be provided through:
-
Chained attributes
-
Signed request object claims
-
Tracked parameters with the adapter using the values in the same order
Successful user approval will transition to MFA_COMPLETED
state. User denial will transition to MFA_FAILED
state.
The bypass authentication setting when configured with the Service Unavailable Failure Mode field does not apply for authentication code flow. The runtime fails hard ifservice becomes unreachable for this flow. |
Authentication API flow
When authN API flow is invoked for useAlternativeAuthenticationSource
action for QR code, the adapter responds with a AUTHENTICATION_CODE_RESPONSE_REQUIRED
state with an authentication code and several other properties as seen below.
{
"id": "XC5Jt",
"pluginTypeId": "j_AGR1E__nc2USbRhZPMQQ",
"status": "AUTHENTICATION_CODE_RESPONSE_REQUIRED",
"authenticationCodeId": "20842db3-b6d6-4d0b-90aa-63c9d9c81ff9",
"code": "JQQ0GYX8",
"uri": "pingonesdkauthentication_code=JQQ0GYX8",
"userApproval": "REQUIRED",
"expiresAt": "2022-05-17T22:35:04.354Z",
"updatedAt": "2022-05-17T22:25:04.349Z",
"createdAt": "2022-05-17T22:25:04.349Z",
"application": {
"id": "264748d1-4e4a-477d-b673-b4f44db45ccf"
},
"clientContext": {
"header": "Approve request",
"body": "1. Do you want to approve this?"
},
"lifeTime": {
"duration": 10,
"timeUnit": "MINUTES"
},
"requestStatus": "UNCLAIMED",
"_links": {
"cancelAuthentication": {
"href": "https://localhost.ping-eng.com:9031/pf-ws/authn/flows/XC5Jt"
},
"self": {
"href": "https://localhost.ping-eng.com:9031/pf-ws/authn/flows/XC5Jt"
},
"poll": {
"href": "https://localhost.ping-eng.com:9031/pf-ws/authn/flows/XC5Jt"
}
}
}