With Verify V2 just being released for General Availability, we wanted to dive a bit deeper into our Silent Authentication capability! In this article, we’ll talk you through how it works, along with some useful tools and tips for implementation.

How Does Silent Authentication Work?

Silent Authentication is a channel in the Verify API that allows you to complete authentication without a 2FA code. Once a user has entered their login credentials, it proves their identity by checking their SIM information against their carrier's records to ensure that their phone number is active and genuine. Once a request has been verified, you can continuously authenticate the user until either the request expires or the user cancels it.

In short, it’s an authentication method that uses a mobile phone's Subscriber Identity Module (SIM) to prove a user's identity without user input.

You can read more about how silent authentication works in our previous blog post or the developer docs; the rest of this article will talk you through some useful tips and features that you may want to consider when implementing silent authentication.

Force a Mobile Data Connection

Silent Authentication is not just reliant on the user having a mobile phone - it also needs a cellular network connection. If the request is sent over Wi-Fi, it will throw an error. To help with this, we’ve provided iOS and Android SDKs that can help you to make an HTTP request over cellular even when on WiFi:

Android

The Android SDK is available on GitHub, where you can find information on permissions, compatibility, and examples of how to integrate silent auth into your applications:

import com.vonage.silentauth.VGSilentAuthClient
// instantiate the sdk during app startup
VGSilentAuthClient.initializeSdk(this.applicationContext)
val resp: JSONObject = VGSilentAuthClient.getInstance().openWithDataCellular(URL(endpoint), false)
 if (resp.optString("error") != "") {
    // error
} else {
    val status = resp.optInt("http_status")
    if (status == 200) {
        // 200 OK
    } else {
        // error
    }
}

iOS

The iOS SDK is also available on GitHub, where you can find information on installation, compatibility, and usage examples:

import VonageClientSDKSilentAuth
let client = VGSilentAuthClient()
client.openWithDataCellular(url: url, debug: true) { response in
    if (response["error"]) != nil {
      // Handle error
    } else {
      let status = resp["http_status"] as! Int
      if (status == 200) {
          // Handle response
      } else {
        // Handle error
      }
    }
}

Silent Authentication Sandbox

Testing silent authentication can be difficult. To test a successful verification, code must be run from an application running on a phone over a mobile network, which can be tricky to set up. To help with this, Vonage has provided a sandbox that bypasses the check with the carrier. Instead, you’ll use the data returned in your callbacks to complete the check yourself, removing the need for a mobile network connection.

To do this, add "sandbox": "true" to your workflow:

This will bypass the carrier and send your request to the sandbox.

The complete guide on using the silent authentication sandbox can be found here.

Whether using the sandbox or not, you will get a response containing both your request_idand the check_url:

{
  "request_id": "31eaf23d-b2db-4c42-9d1d-e847e75ab330",
  "check_url": "https://api.nexmo.com/v2/verify/31eaf23d-b2db-4c42-9d1d-e847e75ab330/silent-auth/redirect"
}

To continue, you'll need to send a GET request to the check_url. This will result in several HTTP302 responses which your client will need to follow, the amount depending on what carrier routing is required based on the device's location.

HTTP/1.1 302 Found
Location: https://eu.api.silentauth.com/phone_check/v0.2/checks/31eaf23d-b2db-4c42-9d1d-e847e75ab330/redirect

HTTP/1.1 302 Found
Location: https://sandbox.redirect.m-auth.com/callback/sandbox?id=31eaf23d-b2db-4c42-9d1d-e847e75ab330

Once you've followed the redirects, you'll get an HTTP200 which takes us to the final step. You'll get back a code in the response, which needs to be submitted the the check-code endpoint:

{
  "request_id": "31eaf23d-b2db-4c42-9d1d-e847e75ab330",
  "code": "si9sfG"
}

This code functions exactly the same as taking a code delivered via another channel. Send the code to the API endpoint:

POST /https://api.nexmo.com/v2/verify/31eaf23d-b2db-4c42-9d1d-e847e75ab330 HTTP/1.1
Content-Type: application/json

{
  "code": "si9sfG"
}

and you will have your final response. If successful:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "request_id": "31eaf23d-b2db-4c42-9d1d-e847e75ab330",
  "status": "completed"
}

And if the verification fails:

HTTP/1.1 409 CONFLICT
Content-Type: application/json

{
  "title": "Network error",
  "detail": "The Silent Auth request could not be completed due to formatting or the carrier is not supported."
}

The complete guide on using the silent authentication sandbox can be found here.

Fallback to Other Channels

There are several situations where silent authentication may not work, for example, if the user is:

• On a desktop device

• Out of their network’s coverage

• On a Wi-Fi connection instead of their cellular network

In these cases, you have the option to fallback to other channels. You can do this by configuring the workflow in your request; in this example, silent auth will be attempted first. If that fails, an SMS will be sent:

Read more about workflows and the available channels here.

Conclusion

Hopefully, you have found this roundup of hints and tips useful, and it’ll help you with your future projects using Silent Authentication! You can sign up for an account to start using Verify now, follow our Twitter Developer Account to keep updated and check out our developer docs for more information.