Yi Gu on web.dev

Fill OTP forms within cross-origin iframes with WebOTP API

2021-04-21T00:00:00Z

SMS OTPs (one-time passwords) are commonly used to verify phone numbers, for example as a second step in authentication, or to verify payments on the web. However, switching between the browser and the SMS app, to copy-paste or manually enter the OTP makes it easy to make mistakes and adds friction to the user experience.

The WebOTP API gives websites the ability to programmatically obtain the one-time password from a SMS message and enter it automatically in the form for the users with just one tap without switching the app. The SMS is specially-formatted and bound to the origin, so it mitigates chances for phishing websites to steal the OTP as well.

One use case that has yet to be supported in WebOTP was targeting an origin inside an iframe. This is typically used for payment confirmation, especially with 3D Secure. Having the common format to support cross-origin iframes, WebOTP API now delivers OTPs bound to nested origins starting in Chrome 91.

How WebOTP API works #

WebOTP API itself is simple enough:

…
  const otp = await navigator.credentials.get({
    otp: { transport:['sms'] }
  });
…

The SMS message must be formatted with the origin-bound one-time codes.

Your OTP is: 123456.

@web-otp.glitch.me #12345

Notice that at the last line it contains the origin to be bound to preceded with a @ followed by the OTP preceded with a #.

When the text message arrives, an info bar pops up and prompts the user to verify their phone number. After the user clicks the Verify button, the browser automatically forwards the OTP to the site and resolves the navigator.credentials.get(). The website can then extract the OTP and complete the verification process.

Learn the basics of using WebOTP at Verify phone numbers on the web with the WebOTP API.

Cross-origin iframes use cases #

Entering an OTP in a form within a cross-origin iframe is common in payment scenarios. Some credit card issuers require an additional verification step to check the payer's authenticity. This is called 3D Secure and the form is typically exposed within an iframe on the same page as if it's a part of the payment flow.

For example:

A user visits shop.example to purchase a pair of shoes with a credit card.
After entering the credit card number, the integrated payment provider shows a form from bank.example within an iframe asking the user to verify their phone number for fast checkout.
bank.example sends an SMS that contains an OTP to the user so that they can enter it to verify their identity.

How to use WebOTP API from a cross-origin iframe #

To use WebOTP API from within a cross-origin iframe, you need to do two things:

Annotate both the top-frame origin and the iframe origin in the SMS text message.
Configure permissions policy to allow the cross-origin iframe to receive OTP from the user directly.

WebOTP API within an iframe in action.

You can try the demo yourself at https://web-otp-iframe-demo.stackblitz.io.

Annotate bound-origins to the SMS text message #

When WebOTP API is called from within an iframe, the SMS text message must include the top-frame origin preceded by @ followed by the OTP preceded by # followed by the iframe origin preceded by @.

@shop.example #123456 @bank.exmple

Configure Permissions Policy #

To use WebOTP in a cross-origin iframe, the embedder must grant access to this API via otp-credentials permissions policy to avoid unintended behavior. In general there are two ways to achieve this goal:

via HTTP Header:

Permissions-Policy: otp-credentials=(self "https://bank.example")

via iframe allow attribute:

<iframe src="https://bank.example/…" allow="otp-credentials"></iframe>

See more examples on how to specify a permission policy .

Caveats #

Nesting levels #

At the moment Chrome only supports WebOTP API calls from cross-origin iframes that have no more than one unique origin in its ancestor chain. In the following scenarios:

a.com -> b.com
a.com -> b.com -> b.com
a.com -> a.com -> b.com
a.com -> b.com -> c.com

using WebOTP in b.com is supported but using it in c.com is not.

Note that the following scenario is also not supported because of lack of demand and UX complexities.

a.com -> b.com -> a.com (calls WebOTP API)

Interoperability #

While browser engines other than Chromium do not implement the WebOTP API, Safari shares the same SMS format with its input[autocomplete="one-time-code"] support. In Safari, as soon as an SMS that contains an origin-bound one-time code format arrives with the matched origin, the keyboard suggests to enter the OTP to the input field.

As of April 2021, Safari supports iframe with a unique SMS format using %. However, as the spec discussion concluded to go with @ instead, we hope the implementation of supported SMS format will converge.

Feedback #

Your feedback is invaluable in making WebOTP API better, so go on and try it out and let us know what you think.

Resources #

Photo by rupixen.com on Unsplash

Scroll snapping after layout changes

2020-02-22T00:00:00Z

CSS Scroll Snap allows web developers to create well-controlled scroll experiences by declaring scroll snapping positions. One shortcoming of the current implementation is that scroll snapping does not work well when the layout changes, such as when the viewport is resized or the device is rotated. This shortcoming is fixed in Chrome 81.

Interoperability #

Many browsers have basic support for CSS Scroll Snap. See Can I use CSS Scroll Snap? for more information.

Chrome is currently the only browser to implement scroll snapping after layout changes. Firefox has a ticket open for implementing this and Safari also has an open ticket for re-snapping after a scroller's content changes. For now, you can simulate this behaviour by adding the following code to event listeners to force a snapping to execute:

scroller.scrollBy(0,0);

However, this will not guarantee that the scroller snaps back to the same element.

Background #

CSS Scroll Snap #

The CSS Scroll Snap feature allows web developers to create well-controlled scroll experiences by declaring scroll snapping positions. These positions ensure that scrollable content is properly aligned with its container to overcome the issues of imprecise scrolling. In other words, scroll snapping:

Prevents awkward scroll positions when scrolling.
Creates the effect of paging through content.

Paginated articles and image carousels are two common use cases for scroll snaps.

Example of CSS scroll snap. At the end of scrolling an image's horizontal center is aligned with the horizontal center of the scroll container.

Shortcomings #

Snap positions get lost when resizing a window.

Scroll snapping allows users to effortlessly navigate through content, but its inability to adapt to changes in content and layout blocks some of its potential benefits. As shown in the example above, users have to re-adjust scroll positions whenever resizing a window to find the previously snapped element. Some common scenarios that cause layout change are:

Resizing a window
Rotating a device
Opening DevTools

The first two scenarios make CSS Scroll Snap less appealing for users and the third one is a nightmare for developers when debugging. Developers also need to consider these shortcomings when trying to make a dynamic experience that supports actions such as adding, removing, or moving content.

A common fix for this is to add listeners that execute a programmatic scroll via JavaScript to force snapping to execute whenever any of these mentioned layout changes happen. This workaround can be ineffective when the user expects the scroller to snap back to the same content as before. Any further handling with JavaScript seems to almost defeat the purpose of this CSS feature.

Built-in support for re-snapping after layout changes in Chrome 81 #

The mentioned shortcomings no longer exist in Chrome 81: scrollers will remain snapped even after changing layout. They will re-evaluate scroll positions after changing their layout, and re-snap to the closest snap position if necessary. If the scroller was previously snapped to an element that still exists after the layout change, then the scroller will try to snap back to it. Pay attention to what happens when the layout changes in the following example.

Snap position lost

Rotating a device does not preserve the snap positions in Chrome 80. After scrolling to the slide that says NOPE and changing the device orientation from portrait to landscape, a blank screen is shown, which indicates that the scroll snap position was lost.

Snap position preserved

Rotating a device does preserve the snap positions in Chrome 81. The slide that says NOPE remains in view even though the device orientation changes multiple times.

See the Re-snapping after layout changes specification for more details.

Example: Sticky scrollbars #

With "Snap after layout changes", developers can implement sticky scrollbars with a few lines of CSS:

.container {
  scroll-snap-type: y proximity;
}

.container::after {
  scroll-snap-align: end;
  display: block;
}

Want to learn more? See the following demo chat UI for visuals.

Adding a new message triggers re-snap which makes it stick to the bottom in Chrome 81.

Future work #

All re-snapping scroll effects are currently instant; a potential follow-up is to support re-snapping with smooth scrolling effects. See the specification issue for details.

Feedback #

Your feedback is invaluable in making re-snapping after layout changes better, so go on and try it out and let the Chromium engineers know what you think.