PingOne

Support for authentication code flow

The PingOne MFA Integration Kit supports authentication code flow if a local identity profile (LIP) has been configured. You can find more information about LIPs in Configuring local identity profiles.

Process flow

  1. 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, the policy.action attribute could be "QR code."

    Screen capture of the Policy screen with the Rules window displayed and showing a policy.action attribute defines as "QR Code."

    This allows PingFederate to use the built-in QR code image for the Sign-On page.

    Screen capture of the Sign on window showing QR code as an option.

  2. 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.

    Screen capture of the Authentication Code window showing a QR authentication code.

  3. 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.

  4. If approved and authentication flow is successful, the adapter returns the userID and username in the core contract authentication.code.flow.userid and username respectively along with pingone.mfa.status set to the value com.pingidentity.pingone.mobile_login_authentication_code.

  5. 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

p1mfa.authenticationcode.clientContext.header

clientContext.header

p1mfa.authenticationcode.clientContext.body

clientContext.body

p1mfa.authenticationcode.lifeTime.duration

lifeTime.duration

p1mfa.authenticationcode.lifeTime.timeUnit

lifeTime.timeUnit

p1mfa.authenticationcode.userApproval

userApproval

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"
    }
  }
}