Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
350 lines (283 sloc) 11.7 KB
title subhead authors date update hero alt description tags
Verify phone numbers on the web with the Web OTP API
Help users type OTPs received through SMS
agektmr
2019-10-07
2020-03-05
hero.png
A drawing of a woman using OTP to log in to a web app.
Finding, memorizing, and typing OTPs sent via SMS is cumbersome. The Web OTP API simplifies the OTP workflow for users.
post
identity
sms
capabilities
fugu

What is the Web OTP API?

These days, most people in the world own a mobile device and developers are commonly using phone numbers as an identifier for users of their services.

There are a variety of ways to verify phone numbers, but a randomly generated one-time password (OTP) sent by SMS to the number is one of the most common. Sending this code back to the developer's server demonstrates control of the phone number.

{% Aside %} The Web OTP API was originally called the SMS Receiver API. You may still see it named that way in some places. {% endAside %}

This idea is already deployed in many scenarios to achieve:

  • Phone number as an identifier for the user. When signing up for a new service, some websites ask for a phone number instead of an email address and use it as an account identifier.
  • Two step verification. When signing in, a website asks for a one-time code sent via SMS on top of a password or other knowledge factor for extra security.
  • Payment confirmation. When a user is making a payment, asking for a one-time code sent via SMS can help verify the person's intent.

The current process creates friction for users. Finding an OTP within an SMS message, then copying and pasting it to the form is cumbersome, lowering conversion rates in critical user journeys. Easing this has been a long standing request for the web from many of the largest global developers. Android has an API that does exactly this. So does iOS and Safari.

The Web OTP API lets your app receive specially-formatted messages bound to your app's origin. From this, you can programmatically obtain an OTP from an SMS message and verify a phone number for the user more easily.

{% Aside 'warning' %} Attackers can spoof SMS and hijack a person's phone number. Carriers can also recycle phone numbers to new users after an account is closed. While SMS OTP is useful to verify a phone number for the use cases above, we recommend using additional and stronger forms of authentication (such as multiple factors and the Web Authentication API to establish new sessions for these users. {% endAside %}

Current status

The table below explains the current status of the Web OTP API.

Step Status
1. Create explainer Complete
2. Create initial draft of specification In Progress
3. Gather feedback and iterate on design Complete
4. Origin trial Complete
5. Launch Chrome 81

See it in action

Let's say a user wants to verify their phone number with a website. The website sends a text message to the user over SMS and the user enters the OTP from the message to verify the ownership of the phone number.

With the Web OTP API, these steps are as easy as one tap for the user, as demonstrated in the video. As the text message arrives, a bottom sheet pops up and prompts the user to verify their phone number. After clicking the Verify button within the bottom sheet, the browser pastes the OTP into the form and the form is submitted without the user needing to press Continue.

The whole process is diagrammed in the image below.

Web OTP API diagram

Try the demo yourself. It doesn't ask for your phone number or send an SMS to your device, but you can send one from another device by copying the text displayed in the demo. This works because it doesn't matter who the sender is when using the Web OTP API.

  1. Go to https://sms-receiver-demo.glitch.me in Chrome 81 or later.
  2. Select Chrome Stable from the provided list.
  3. Press Copy to copy the text message.
  4. Using your SMS app send it to another phone.
  5. Press Verify.
  6. From the other phone, send yourself the copied text message via SMS.

Did you receive the SMS and see the prompt to enter the code to the input area? That is how the Web OTP API works for users.

{% Aside 'caution' %} If you are using a work profile on your Android device and the SMS Receiver does not seem to be working, try installing and using Chrome on your personal profile instead (i.e. the same profile in which you receive SMS messages). {% endAside %}

Using the Web OTP API

Using the Web OTP API consists of two parts: JavaScript in your web app and formatted message text sent via SMS.

{% Aside %} The Web OTP API requires a secure origin (HTTPS). {% endAside %}

Feature detection

Feature detection is the same as for many other APIs:

if ('sms' in navigator) {
  ...
}

Process the OTP

The Web OTP API itself is simple enough:

const sms = await navigator.sms.receive();

Once a user taps Verify, displayed in the bottom sheet, the promise containing the entire text message will resolve. You can use a regular expression to extract the OTP and verify the user. Notably, you should parse and use the SMS message assuming it could have been altered by an attacker inserting their own SMSes into your app (e.g. following the formatting convention and sending it right after you called navigator.sms.receive()). For example, if a text message contains a six digit verification code following otp=, the code would look like this:

const code = sms.content.match(/^[\s\S]*otp=([0-9]{6})[\s\S]*$/m)[1];

You can now submit the code to the server to verify it.

Formatting the SMS message

The API itself should look simple enough, but a critical part is to format your SMS text message according to a specific convention. The message has to be sent after navigator.sms.receive() is called and must comply with a formatting convention.

The SMS message must be received on the device where navigator.sms.receive() was called.

The message must adhere to the following formatting:

  • The origin part of the URL of the website that invoked the API must be preceded by For: .
  • The URL must contain (for the time being) a query parameter whose value is the application hash of the user's Chrome instance. (These are static strings. See the table below.)
  • The URL must contain a query parameter otp whose value is the OTP.

An example message that can be retrieved by the browser would look like this:

Your OTP is: 123456.

For: https://sms-receiver-demo.glitch.me/?otp=123456&xFJnfg75+8v

The application hash of Chrome instances are static. Use one of these strings for development depending on which Chrome build you will be working with.

Chrome build APK hash string
Chrome Beta xFJnfg75+8v
Chrome Stable EvsSSj4C6vl

Demos

Try various messages with the demo: https://sms-receiver-demo.glitch.me

You may also fork it and create your version: https://glitch.com/edit/#!/sms-receiver-demo.

Problem with the implementation?

Did you find a bug with Chrome's implementation?

  • File a bug at https://new.crbug.com. Include as much detail as you can, simple instructions for reproducing, and set Components to Blink>SMS.

Planning to use the API?

Are you planning to use the Web OTP API? Your public support helps us prioritize features, and shows other browser vendors how critical it is to support them. Send a Tweet to @ChromiumDev with #smsreceiver and let us know where and how you're using it.

FAQ

Why did you not align with Safari's one-time-code?

We explored options similar to Safari's declarative autocomplete="one-time-code". We believe our imperative approach provides a more flexible user experience and reduces friction when verifying a phone number under certain circumstances. The declarative approach is easier to implement for developers, but requires a form field and at least several taps: focus on the input field, select the one-time-code, then submit the form. Our approach (inspired by what native Android apps do) means that people make only a single tap in the browser, inline with the page content.

Is it safe to use SMS as a way to authenticate?

While SMS OTP is useful to verify a phone number when the number is first provided, phone number verification via SMS must be used carefully for re-authentication since phone numbers can be hijacked and recycled by carriers. Web OTP is a convenient re-auth and recovery mechanism, but services should combine it with additional factors, such as a knowledge challenge, or use the Web Authentication API for strong authentication.

Can't we omit the browser's app hash?

We would like to remove it, but it's currently a platform restriction. We are working with the Android team to understand what's the best way to approach it.

Will an SMS message timeout?

Yes. You can use AbortController to abort the request before the timeout expires.

Will the apk hash change for an installed PWA?

No. A PWA's app hash is the same as the browser it runs in.

Can we localize the "For:" string required in the SMS?

Not yet. Ultimately, we are planning to remove it or otherwise allow for localization.

{% Aside %} Find more questions at the FAQ section in the explainer. {% endAside %}

You can’t perform that action at this time.