Silent Authentication

Silent Authentication uses a mobile phone's Subscriber Identity Module (SIM) to prove a user's identity, without any user input. This guide will explain what it is, how it works, and how it can be used with Verify.

What is Silent Authentication?

Once a user has entered their login credentials, Silent Authentication proves a user's identity by checking information from their SIM against their carrier's records to ensure that their phone number is active and genuine. Once a request has been verified, you are able to continuously authenticate the user until either the request expires or it is cancelled by the user. As with any authentication method, there are advantages and disadvantages to this approach:

Advantages

• Minimal user input - Silent Authentication is very user friendly; once the user has entered their credentials, the authentication process happens in the background. There are no OTP codes to input, making the process as frictionless as possible.
• No phishing - By moving authentication directly between the carrier and the mobile device, the threat of phishing via SMS is removed.

Disadvantages

• The user must own a mobile device - Silent Authentication needs the user to authenticate from a mobile device, which they may not always have.
• A cellular network connection is required - Silent Authentication relies on a verified GSM response from the device to prove its credentials, which is not sent if the user is connected to Wi-Fi. The user must therefore trigger the authentication request using cellular data. You can use our mobile libraries to help force a mobile connection.

Using Silent Authentication with Verify

Silent Authentication is available in V2 of the Verify API, and can work both synchronously and asynchronously (using webhooks).

Network API Registration

If you intend to use Verify's Silent Authentication in production heavily, it will require the registration of your application with Vonage and its mobile operator partners. Vonage’s Network API Registration service automates the registration process through a common dashboard interface and sends the information to the operators for approval. Vonage’s Customer Dashboard portal is the single source for registration across all participating operators.

For detailed instructions on how to do this, click here.

Synchronous Implementation

1. To start the silent authentication process, make a Silent Authentication request to Verify with the user's number and your JWT:

In this example, the workflow specifies that Verify will first attempt to use Silent Authentication. If for any reason the request fails, it will then fallback to SMS OTP.

2. Provided the number is supported and the request succeeds, you will receive a HTTP 202 response with your request_id reference and a check_url:

3. Until the request expires or is cancelled, check_url can be used to perform a Silent Authentication check. Upon receiving this response, you need to make a
   GET
   request to the check_url from the mobile device you are trying to authenticate.

4. Once you've made the
   GET
   request, you'll receive a number of HTTP 302 redirects depending on the territory and carrier the target device is using:

Following the redirects will result in either a HTTP 200 or HTTP 409 response depending on whether the request is valid. If there is a problem with the network, you'll see a response like this:

A full list of potential error codes can be found in the API Specification.

If the request is valid, you will receive an HTTP 200 response containing your request_id and a code:

5. The final step is to send the code to be checked:

If the code is valid, you will receive a final response with the status completed:

Or, if there is an error, you will see 'Invalid Code':

At this point, your silent authentication verification is complete.

Asynchronous Implementation

An asynchronous implementation is very similar to the synchronous method; instead of using the device client to make a series of calls, every part of the workflow is included in webhook callbacks to a URL you define instead.

1. To begin, go to the developer dashboard to create your application:

   • Ensure that Verify is enabled under 'Capabilities'.
   • Configure the Status URL to receive callback events.
   • Generate a JWT using the Application ID and private key of the application.

2. To start the silent authentication process, make a Silent Authentication request to Verify with the user's number and your JWT:

In this example, the workflow specifies that Verify will first attempt to use Silent Authentication. If for any reason the request fails, it will then fallback to SMS OTP.

3. You will receive callbacks to the URL specified in your application settings informing you of the progress of the request. It is possible that the request will fail at this point, for example if there is an error in the network. Again, if you have another channel specified in your request, Verify will fallback to it. If the request is successful the first response will contain a check_url:

Until the request expires or is cancelled, check_url will be used to perform a Silent Authentication check. Upon receiving this callback, you need to make a

request to the check_url from the mobile device you are trying to authenticate.

4. Once you've made the
   GET
   request, you'll receive a number of HTTP 302 redirects depending on the territory and carrier the target device is using:

Following the redirects will result in either a HTTP 200 or HTTP 409 response depending on whether the request is valid. If there is a problem with the network, you'll see a response like this:

A full list of potential error codes can be found in the API Specification.

If the request is valid, you will receive an HTTP 200 response containing your request_id and a code:

5. The final step is to send the code to be checked:

If the code is valid, you will receive a callback with the status completed:

Or, if there is an error, you will see 'Invalid Code':

6. You will then receive a final callback with the result of the check. If successful, you will see a callback with "status": "completed":

If unsuccessful, for example if the user has been rejected, this will be indicated in the status field:

Android and iOS Libraries

Vonage have provided two Libraries that you can use in your applications to help you make a HTTP request over a cellular network, even when on WiFi. These are available through GitHub:

• Android
• iOS

Click through for more details, including installation and compatibility information along with usage examples.

Available Territories

Silent Authentication is only available in certain territories - a full list can be found here.