RapidIdentity Product Guide: New UI

PingMe Authentication

Here is an example response from the server indicating that PingME authentication is required as the next step:

HTTP/1.1 200 OK 
Content-Type: application/json
{
  "type": "pingMe",
  "id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
  "step": {
    "type": "chooseIdentity",
    "identities": [
      {
        "username": "username1",
        "domain": "DOMAIN1"
      },
      {
        "username": "username2",
        "domain": "DOMAIN2"
      }
    ]
  }
}

Note the value of the type property is pingMe and the step object has a type property value of chooseIdentity.

The identities array will contain one or more identities associated with this user which they can choose to use for this authentication step.  An identity object consists of two properties: username and domain. The username property will always be present but the domain property might not.  When displaying the identity choice to the user, if a domain value is present, it should be displayed in standard Windows format: domain\username.

Currently, the first step for PingME authentication will always be chooseIdentity even if the authenticating user can use a single identity. We could go a few different ways with this.

  1. The UI could just immediately begin the authentication process by sending a chooseIdentity request to the server with the single identity without user interaction

  2. The UI could present a button that the user should click when they are ready for RapidFederation to send the authentication request to their device

  3. The server could be changed to skip the initial chooseIdentity step and automatically send the authentication request (perhaps this could be a configurable setting in the policy).

To begin authentication, the user must choose an identity to use and the following request should be issued:

POST /idp/ws/rest/authn HTTP/1.1 
Content-Type: application/json 
Accept: application/json
{
  "type": "pingMe",
  "id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
  "step": {
    "type": "chooseIdentity",
    "identity": {
      "username": "username1",
      "domain": "DOMAIN1"
    }
  }
}

If everything is good so far, the server sends back a response indicating that authentication is underway:

HTTP/1.1 200 OK 
Content-Type: application/json
{
  "type": "pingMe",
  "id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
  "step": {
    "type": "authenticating"
  }
}

At this point, the user should receive the push notification on their device and they can Approve or Deny the request. However, while that's happening, the UI should display a spinner and poll the server in the background every few seconds to find out if the authentication has succeeded or failed.

POST /idp/ws/rest/authn HTTP/1.1 
Content-Type: application/json 
Accept: application/json
{
  "type": "pingMe",
  "id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
  "step": {
    "type": "pollAuthentication"
  }
}

RapidFederation will continue to respond to pollAuthentication requests with authenticating responses until the 2FA ONE server sends back a response or 120 seconds has elapsed.

I have been told that the 2FA ONE server will always return a response within a minute, but we give it up to two minutes

If the user approved the push request on their device and RapidFederation successfully receives that response, then the authentication flow will continue to the next step.

Authentication Failure

If authentication fails because the user denied the push request on their device or the request times out without a response from the user, then authentication has failed.  In this case the response from the server will resemble the following:

HTTP/1.1 200 OK 
Content-Type: application/json
{
  "type": "pingMe",
  "id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
  "error": {
    "type": "simple",
    "message": "2FA ONE PingME Authentication Failed"
  },
  "step": {
    "type": "chooseIdentity",
    "authenticationRetries": 2,
    "identities": [
      {
        "username": "username1",
        "domain": "DOMAIN1"
      },
      {
        "username": "username2",
        "domain": "DOMAIN2"
      }
    ]
  }
}

Please note that the response contains a standard simple type error object with a message with should be displayed to the user.  Additionally, the chooseIdentity step contains a new property authenticationRetries which indicates how many more PingME authentication attempts may be made before authentication fails altogether.

Since this response step type is chooseIdentity, this gives the user the opportunity to use a different identity for the next authentication attempt.

Useful WSDLs for the RapidIdentity MFA server:

https://host/ONEService/ValidateService.asmx

https://host/ONEService/SyncService.asmx