使用 WebOTP API 在网页上验证电话号码

帮助用户了解通过短信接收的动态密码

什么是 WebOTP API?

如今,世界上大多数人都拥有移动设备,开发者通常使用电话号码作为其服务用户的标识符。

验证电话号码的方法有多种,但通过短信发送的随机生成的动态密码 (OTP) 是最常见的方式之一。将此代码发送回开发者的服务器演示了对电话号码的控制。

这一理念已在许多场景中部署,以实现以下目标:

  • 电话号码作为用户标识符。注册新服务时,某些网站会要求您提供电话号码而不是电子邮件地址,并将其用作帐号标识符。
  • 两步验证。登录时,网站会要求在提供密码或其他验证凭据的情况下通过短信发送一次性验证码,以进一步提高安全性。
  • 付款确认。在用户付款时,请求通过短信发送的一次性验证码有助于验证用户的意图。

当前流程会给用户带来不便。在短信中查找动态密码,然后将其复制并粘贴到表单中非常繁琐,这会降低关键用户历程中的转化率。长久以来,许多大型全球开发者对 Web 平台都要求简化此机制。Android 的API 可以做到这一点iOSSafari 也是如此。

WebOTP API 可让您的应用接收绑定到应用网域的特殊格式的消息。然后,您可以通过编程方式从短信中获取动态密码,并更轻松地验证用户的电话号码。

查看实际案例

假设某位用户想在某个网站验证自己的电话号码。网站通过短信向用户发送短信,然后用户需输入短信中的动态密码以验证电话号码的所有权。

如视频所示,借助 WebOTP API,用户只需点按一下,即可轻松完成这些步骤。收到短信后,系统会弹出一个底部动作条,并提示用户验证电话号码。点击底部动作条上的验证按钮后,浏览器会将动态密码粘贴到表单中并提交表单,无需用户按继续

整个流程如下图所示。

WebOTP API 示意图

亲自体验演示。它不会要求您提供电话号码或向您的设备发送短信,但您可以通过复制演示中显示的文本,从其他设备发送一个。这是因为在使用 WebOTP API 时,发送者是谁无关紧要。

  1. 在 Android 设备上的 Chrome 84 或更高版本中,转到 https://web-otp.glitch.me
  2. 用另一部手机向您的手机发送以下短信。
Your OTP is: 123456.

@web-otp.glitch.me #12345

您是否收到了短信并看到了在输入区域输入验证码的提示? 这就是 WebOTP API 为用户运行的方式。

WebOTP API 的使用包括三个部分:

  • 添加了适当注解的 <input> 标记
  • Web 应用中的 JavaScript
  • 通过短信发送的带有格式的消息文字。

我先介绍 <input> 标记。

<input> 标记添加注解

WebOTP 本身无需任何 HTML 注释即可运行,但为了实现跨浏览器兼容性,我强烈建议您在您希望用户输入动态密码的 <input> 标记中添加 autocomplete="one-time-code"

这样一来,Safari 14 或更高版本在用户收到采用设置短信格式中所述的格式(即使不支持 WebOTP)的短信时,也能建议用户使用动态密码自动填充 <input> 字段。

HTML

<form>
  <input autocomplete="one-time-code" required/>
  <input type="submit">
</form>

使用 WebOTP API

由于 WebOTP 很简单,因此只需复制并粘贴以下代码即可。我还是会告诉你怎么做。

JavaScript

if ('OTPCredential' in window) {
  window.addEventListener('DOMContentLoaded', e => {
    const input = document.querySelector('input[autocomplete="one-time-code"]');
    if (!input) return;
    const ac = new AbortController();
    const form = input.closest('form');
    if (form) {
      form.addEventListener('submit', e => {
        ac.abort();
      });
    }
    navigator.credentials.get({
      otp: { transport:['sms'] },
      signal: ac.signal
    }).then(otp => {
      input.value = otp.code;
      if (form) form.submit();
    }).catch(err => {
      console.log(err);
    });
  });
}

功能检测

特征检测与许多其他 API 的特征检测相同。监听 DOMContentLoaded 事件会等待 DOM 树准备好进行查询。

JavaScript

if ('OTPCredential' in window) {
  window.addEventListener('DOMContentLoaded', e => {
    const input = document.querySelector('input[autocomplete="one-time-code"]');
    if (!input) return;
    …
    const form = input.closest('form');
    …
  });
}

处理动态密码

WebOTP API 本身非常简单。请使用 navigator.credentials.get() 获取动态密码。WebOTP 向该方法添加了一个新的 otp 选项。它只有一个属性:transport,其值必须是字符串为 'sms' 的数组。

JavaScript

    …
    navigator.credentials.get({
      otp: { transport:['sms'] }
      …
    }).then(otp => {
    …

这会在收到短信时触发浏览器的权限流程。如果已授予权限,返回的 promise 会使用 OTPCredential 对象进行解析。

获取的 OTPCredential 对象的内容

{
  code: "123456" // Obtained OTP
  type: "otp"  // `type` is always "otp"
}

接下来,将动态密码值传递给 <input> 字段。直接提交表单可以省去要求用户点按按钮的步骤。

JavaScript

    …
    navigator.credentials.get({
      otp: { transport:['sms'] }
      …
    }).then(otp => {
      input.value = otp.code;
      if (form) form.submit();
    }).catch(err => {
      console.error(err);
    });
    …

取消消息

如果用户手动输入动态密码并提交表单,您可以在 options 对象中使用 AbortController 实例来取消 get() 调用。

JavaScript

    …
    const ac = new AbortController();
    …
    if (form) {
      form.addEventListener('submit', e => {
        ac.abort();
      });
    }
    …
    navigator.credentials.get({
      otp: { transport:['sms'] },
      signal: ac.signal
    }).then(otp => {
    …

设置短信的格式

API 本身应该足够简单,但在使用之前应了解一些事项。此消息必须在调用 navigator.credentials.get() 后发送,并且必须在调用 get() 的设备上接收。最后,该消息必须遵循以下格式:

  • 消息以人类可读的文本开头(可选),其中包含 4 到 10 个字符的字母数字字符串,并且至少包含一个数字,放在网址和动态密码的最后一行。
  • 调用该 API 的网站网址的网域部分必须以 @ 开头。
  • 该网址必须包含井号(“#”),后跟动态密码。

例如:

Your OTP is: 123456.

@www.example.com #123456

以下是反面示例:

短信文字格式错误示例 原因
Here is your code for @example.com #123456 @ 应为最后一行的第一个字符。
Your code for @example.com is #123456 @ 应为最后一行的第一个字符。
Your verification code is 123456

@example.com\t#123456
@host#code 之间应有一个空格。
Your verification code is 123456

@example.com  #123456
@host#code 之间应有一个空格。
Your verification code is 123456

@ftp://example.com #123456
不能包含网址架构。
Your verification code is 123456

@https://example.com #123456
不能包含网址架构。
Your verification code is 123456

@example.com:8080 #123456
不能包含端口。
Your verification code is 123456

@example.com/foobar #123456
路径无法包含在内。
Your verification code is 123456

@example .com #123456
网域中没有空格。
Your verification code is 123456

@domain-forbiden-chars-#%/:<>?@[] #123456
域名中没有禁用字符
@example.com #123456

Mambo Jumbo
@host#code 应为最后一行。
@example.com #123456

App hash #oudf08lkjsdf834
@host#code 应为最后一行。
Your verification code is 123456

@example.com 123456
缺少 #
Your verification code is 123456

example.com #123456
缺少 @
Hi mom, did you receive my last text 缺少 @#

样本歌曲

通过演示试用各种消息:https://web-otp.glitch.me

您也可以为其创建分支并创建您自己的版本:https://glitch.com/edit/#!/web-otp

从跨源 iframe 中使用 WebOTP

向跨源 iframe 中输入短信动态密码通常用于付款确认,尤其是在使用 3D Secure 时。WebOTP API 采用支持跨源 iframe 的通用格式,可提供绑定到嵌套源的动态密码。例如:

  • 某用户访问了 shop.example,并用信用卡购买了一双鞋。
  • 输入信用卡号后,集成的付款服务机构会在 iframe 中显示 bank.example 的表单,要求用户验证其电话号码以便快速结账。
  • bank.example 会向用户发送包含动态密码的短信,以便用户输入该密码以验证身份。

如需在跨源 iframe 中使用 WebOTP API,您需要执行以下两项操作:

  • 在短信中同时标注顶部框架来源和 iframe 来源。
  • 配置权限政策,以允许跨源 iframe 直接从用户接收动态密码。
iframe 中的 WebOTP API 的实际运用。

您可以访问 https://web-otp-iframe-demo.stackblitz.io 试用演示版。

为短信的绑定源添加注解

从 iframe 中调用 WebOTP API 时,短信必须包含顶部帧来源,后跟 @,后跟动态密码(后跟 #),以及 iframe 来源(以 @ 开头)。

Your verification code is 123456

@shop.example #123456 @bank.exmple

配置权限政策

如需在跨源 iframe 中使用 WebOTP,嵌入者必须通过 OTP 凭据权限政策授予对此 API 的访问权限,以避免意外行为。一般来说,可以通过两种方法实现这一目标:

通过 HTTP 标头

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

通过 iframe allow 属性

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

查看有关如何指定权限政策的更多示例

在桌面设备上使用 WebOTP

在 Chrome 中,WebOTP 支持监听在其他设备上收到的短信,以协助用户在桌面设备上完成电话号码验证。

桌面设备上的 WebOTP API。

此功能要求用户在桌面版 Chrome 和 Android Chrome 上登录同一 Google 账号。

开发者只需在其桌面版网站上实现 WebOTP API(与在移动网站上相同),无需任何特殊技巧。

如需了解详情,请参阅在桌面设备上使用 WebOTP API 验证电话号码

常见问题解答

虽然我发送的是格式正确的邮件,但仍然没有显示该对话框。哪里出问题了?

测试该 API 时,请注意以下几点:

  • 如果发送者的电话号码包含在接收者的联系人列表中,则由于底层 SMS User Consent API 的设计,系统不会触发此 API。
  • 如果您在 Android 设备上使用工作资料,但 WebOTP 不起作用,请尝试改为在您的个人资料(即您用来接收短信的那个资料)上安装并使用 Chrome。

请再次查看格式,看看您的短信格式是否正确。

此 API 是否兼容不同的浏览器?

Chromium 和 WebKit 已就短信格式达成共识,并且 Apple 宣布从 iOS 14 和 macOS Big Sur 开始支持 Safari。虽然 Safari 不支持 WebOTP JavaScript API,但为 input 元素添加 autocomplete=["one-time-code"] 注释后,如果短信符合格式要求,默认键盘会自动提示您输入动态密码。

使用短信作为身份验证方式安全吗?

虽然短信动态密码对于在首次提供电话号码时对电话号码进行验证非常有用,但在重新进行身份验证时必须小心谨慎,因为运营商可能会劫持和回收电话号码。WebOTP 是一种方便的重新身份验证和恢复机制,但服务应将其与额外因素(例如知识验证)相结合,或使用 Web Authentication API 实现强身份验证。

在哪里报告 Chrome 实现中的错误?

您是否发现了 Chrome 实现方面的错误?

  • https://new.crbug.com 上提交 bug。请提供尽可能详细的信息、简单的重现说明,并将 Components 设为 Blink>WebOTP

我如何才能使用这项功能?

您打算使用 WebOTP API 吗?您公开提供的支持可以帮助我们确定功能的优先级,还能向其他浏览器供应商表明支持这些功能的重要性。请使用 # 标签 #WebOTP@ChromiumDev 发送一条推文,并告诉我们您使用该产品的位置和方式。

资源