Skip to main content

Tap to Log In: API

Tap to Log In is an authentication method available to HYPR when using the FIDO UAF protocol. It is an alternative method to push notification authentication or QR code authentication. Push notification authentication has security issues as it is prone to push attacks. Typically, QR code authentication is favored instead for this reason. However, there are use cases where there is a limited UI and a QR code cannot be displayed (e.g., a telephone IVR system). In this case, Tap To Log Inis the best approach. Like push and QR, it is an out-of-band (OOB) mechanism where the service begins the authentication flow and waits for action by the user. The user must explicitly open the UAF app andtap a Login button (which then requires them to perform a FIDO biometric authentication) before the process completes.

Prerequisites​

  1. In your HYPR tenant, create a new RP application with the following settings:

    StepChoice
    Decentralized channelWeb
    IdP ProviderCustom Solution
    Push notificationsNo
    Name(A name for the external service)

  2. In the new RP app, create an access token to be used by an external service that wishes to perform authentication. Grant the token the following permissions:

    • User Management

    • Device Registration

    • Authentication

    • Reporting

  3. You will need a mobile device that is either running the HYPR Mobile App or another app that is using the appropriate HYPR SDK.

User Registration​

A user and their device must first be registered before they can authenticate with HYPR. Typically this is done by generating a magic link for a user which takes them to a page in the HYPR tenant where they can scan a QR code with the HYPR-enabled app on their mobile device. This link can then be delivered to the user (e.g., via email or instant messaging).

Authentication​

An external service must call two endpoints to complete the authentication process. The first endpoint starts an authentication session;  the second endpoint checks the status of the authentication. This second call can be performed over and over again every few seconds (polling) until the authentication is successful, times out, or some other error occurs.

Begin Authentication Session​

Request​

To initiate an authentication flow, the server must perform the following POST request, passing the HYPR access token as a Bearer token in the Authorization request header:

POST {{HYPR_BASE_URL}}/rp/api/oob/client/authentication/requests
Authorization: Bearer {{HYPR_ACCESS_TOKEN}}

The following JSON body must also be passed in the request:

{
 "appId":"{{HYPR_RP_APP_ID}}",
 "namedUser":"{{HYPR_USERNAME}}",
 "machineId":"{{UAF_MACHINE_ID}}",
 "machine":"{{UAF_MACHINE_NAME}}",
 "sessionNonce":"{{sessionNonce}}",
 "deviceNonce":"{{deviceNonce}}",
 "serviceNonce":"{{serviceNonce}}",
 "serviceHmac":"{{serviceHmac}}"
}

  • appId: The camel case identifier of the RP app taken from the URL when viewing the app in the Control Center

  • namedUser: The username of the user that was previously registered

  • machineId: An arbitrary identifier for the calling service

  • machine: A friendly name of the service

  • sessionNonce, deviceNonce, serviceNonce, serviceHmac: These are all unique nonce values that must have the following characteristics:

    • Random and unique

    • Exactly 64 characters in length

    • Hexadecimal format

Normally serviceHmac must be calculated using a SHA256 HMAC algorithm, but this is not necessary for this use case.

Response​

If successful, this will result in an HTTP 200 response containing the following JSON body:

{
 "status": {
 "responseCode": 200,
 "responseMessage": "Device Authentication Started"
  },
 "response": {
 "requestId": "{{sessionId}}"
  }
}

Extract the sessionId from the response via the response.requestId value.

Check Authentication Session Status​

Request​

With the sessionId that was returned from previous call, the server can then perform the following GET request to the HYPR server to poll for status:

GET {{HYPR\_BASE\_URL}}/rp/api/oob/client/authentication/requests/{{sessionId}}
Authorization: Bearer {{HYPR\_ACCESS\_TOKEN}}

Response​

If successful, this will result in an HTTP 200 response containing the following JSON body:

{
  "requestId":"{{requestId}}",
  "namedUser":"{{username}}",
  "machine":"{{machineName}}",
  "device":{
     ...
  },
  "state":[
    {
      "value":"REQUEST_SENT",
      "message":"",
      "timestamp":1703076816
    }
  ]
}

The state array will contain a list of states (identified by the value field in each) as the user progresses through the authentication process. The first state will always be REQUEST_SENT.

The server should continue to call this endpoint every 3–5 seconds, looking for one of the following as a last state in the array to know that the OOB authentication flow has finished:

StateMeaning
COMPLETEDThe authentication completed successfully.
FAILEDAn error occurred during the authentication process.
CANCELEDThe user canceled the authentication in the UAF app.

You may also see these intermediate states within the array before any of the above appear:

  • INITIATED

  • INITIATED_RESPONSE

If the user does not respond at all, eventually the above call will result in an HTTP 400 response containing the following JSON body:

{
  "type": "/static/docs/com/hypr/server/rp/errorhandling/oob/OOBAuthRequestNotFoundProblem.html",
  "title": "The request could not be found.",
  "status": 400,
  "detail": "Please contact HYPR customer support and report this issue. ExceptionId: {{exceptionId}}",
  "errorCode": 1201013
}

Authentication Flow​

The above flow can be visualized with the following sequence diagrams:

Start Authentication​

The first flow is the initial user interaction with the limited UI application, where they are prompted to enter their user ID (e.g., entering a series of digits into a telephone prompt) and the OOB authentication flow begins. The user is then prompted to open their mobile device.

Complete Authentication​

The second flow shows the user completing the authentication flow using their mobile device, which returns control back to the limited UI application:

Additional Considerations​

Passing a Confirmation Code​

The security of both Tap To Log In and push notification authentication can be improved by passing an additional message that appears in the HYPR Mobile App/SDK on the mobile device. This can be used, for example, to generate a code (i.e., one-time password/OTP) within the limited UI application and then prompt for that same code when the user completes the normal FIDO authentication. When the user completes the FIDO authentication on the mobile device, they would see a UI that looks like this:

   

To pass the above message and confirmation code, append the following JSON to the original authentication request:

{
 "transactionText":"Please sign into the IVR",
 "transactionType":"(this can be anything)",
  "extras":{
 "amount": {code}
  }
}