RapidIdentity Product Guide

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.

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.

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