API WebOTP

API WebOTP предоставляет упрощённый пользовательский интерфейс для веб-приложений, чтобы проверить, принадлежит ли номер телефона пользователю при его использовании в качестве фактора входа. WebOTP — это расширение API управления учётными данными.

Проверка выполняется в двухэтапном процессе:

1. Клиент приложения запрашивает одноразовый пароль (OTP), который извлекается из специально отформатированного SMS-сообщения, отправленного сервером приложения.
2. JavaScript используется для ввода OTP в форму проверки на клиенте приложения и отправки её обратно на сервер для проверки соответствия исходному сообщению SMS.

Номера телефонов часто используются для идентификации пользователя приложения. SMS часто используется для проверки принадлежности номера пользователю. SMS обычно содержит OTP, который пользователь должен скопировать и вставить в форму приложения, чтобы подтвердить владение номером. Это несколько неудобный пользовательский интерфейс.

Примеры использования OTP:

• Повышение безопасности входа с использованием номера телефона как дополнительного фактора (например, для двухфакторной аутентификации (2FA) или многофакторной аутентификации (MFA)).
• Проверка чувствительных действий, таких как платежи.

API WebOTP позволяет веб-приложениям ускорить этот процесс проверки, копируя OTP из SMS и автоматически передавая его приложению после предоставления пользователем согласия (большинство платформ с нативными API имеют эквивалентный API).

Обратите внимание, что OTP привязан к домену отправки. Это полезное ограничение безопасности для проверки того, что OTP поступает из надёжного источника, что может смягчить риск фишинговых атак во время повседневной повторной аутентификации.

SMS-OTP полезны для проверки номеров телефонов, и использование SMS для второго фактора безусловно лучше, чем отсутствие второго фактора. В некоторых регионах другие идентификаторы, такие как адреса электронной почты и аутентификаторы, не широко используются, поэтому SMS-OTP очень распространены.

Однако SMS не являются очень надёжными. Злоумышленники могут подделать SMS и перехватить номер телефона человека. Операторы связи могут повторно использовать номера телефонов для новых пользователей после закрытия учётной записи.

Поэтому рекомендуется использовать более надёжный метод аутентификации, если это возможно, например, решение на основе API веб-аутентификации, включающее пароль и ключ безопасности или ключ доступа.

Процесс происходит следующим образом:

1. В момент, когда требуется проверка номера телефона, клиент приложения попросит пользователя ввести свой номер телефона в форму, которая затем отправляется на сервер приложения.
2. Затем клиент приложения вызывает navigator.credentials.get() с параметром otp, указывающим тип transport "sms". Это запускает запрос OTP в подлежащей системе, источником которого будет специально отформатированное SMS-сообщение (содержащее OTP и домен приложения), полученное от сервера приложения. Вызов get() основан на Promise и ожидает получения SMS-сообщения.
3. Сервер приложения отправляет SMS-сообщение на указанный номер телефона. Это необходимо сделать сразу после шага 2.
4. При получении SMS-сообщения на устройстве, при условии, что оно содержит домен приложения, браузер запросит у пользователя согласие на получение/использование OTP. Например, Chrome отобразит диалоговое окно, спрашивающее разрешение на получение OTP из SMS; другие браузеры могут обрабатывать его по-разному. Если пользователь даст согласие, вызов get() выполнится с объектом OTPCredential, содержащим OTP.
5. Затем OTP можно использовать как угодно. Типичное использование — установить его в качестве значения поля формы проверки на клиенте приложения, а затем отправить форму, сделав процесс максимально бесшовным.
6. Сервер приложения затем проверит, соответствует ли отправленный обратно OTP тому, что он первоначально отправил в SMS, и, если да, завершит процесс (например, войдёт пользователя в систему).

Типичное SMS-сообщение выглядит следующим образом:

Your verification code is 123456.

@www.example.com #123456

• Первая строка и вторая пустая строка являются необязательными и предназначены для удобочитаемости.
• Последняя строка обязательна. Если имеются другие строки, она должна быть последней и состоять из:
  • Части домена URL-адреса веб-сайта, вызвавшего API, предваряемой символом @.
  • Следующей за ней пробел.
  • Следующей за ней OTP, предваряемый символом решётки (#).

Если метод get() вызывается сторонним сайтом, встроенным в <iframe>, структура SMS должна быть следующей:

Your verification code is 123456.

@top-level.example.com #123456 @embedded.com

В этом случае последняя строка должна состоять из:

• Части домена верхнего уровня, предваряемой символом @.
• Следующей за ней пробел.
• Следующей за ней OTP, предваряемый символом решётки (#).
• Следующей за ней пробел.
• Следующей за ней частью домена встроенного домена, предваряемой символом @.

Доступность WebOTP может быть контролируема с помощью Политики разрешений, определяющей директиву otp-credentials. Эта директива имеет значение по умолчанию в списке разрешений "self", что означает, что по умолчанию эти методы могут использоваться в контекстах документов верхнего уровня.

Вы можете указать директиву, разрешающую использование WebOTP в определённом домене с другим происхождением (например, внутри <iframe>) так:

Permissions-Policy: otp-credentials=(self "https://embedded.com")

Или вы можете указать её напрямую на <iframe> так:

<iframe src="https://embedded.com/..." allow="otp-credentials"> ... </iframe>

OTPCredential

Возвращается, когда вызов WebOTP get() выполняется; включает свойство code, содержащее полученный OTP.

CredentialsContainer.get(), параметр otp

Вызов get() с параметром otp инструктирует пользовательский агент попытаться получить OTP из приложения SMS подлежащей системы.

В этом примере, когда приходит SMS-сообщение и пользователь предоставляет разрешение, возвращается объект OTPCredential с OTP. Этот пароль затем предварительно заполняется в поле формы проверки, и форма отправляется.

Попробуйте эту демонстрацию с помощью телефона.

Поле формы включает атрибут autocomplete со значением one-time-code. Это не требуется для работы API WebOTP, но стоит добавить. В результате Safari будет предлагать пользователю заполнить это поле OTP автоматически, когда будет получено правильно отформатированное SMS-сообщение, даже если API WebOTP не полностью поддерживается в Safari.

<input type="text" autocomplete="one-time-code" inputmode="numeric" />

JavaScript выглядит следующим образом:

// Detect feature support via OTPCredential availability
if ("OTPCredential" in window) {
  window.addEventListener("DOMContentLoaded", (e) => {
    const input = document.querySelector('input[autocomplete="one-time-code"]');
    if (!input) return;
    // Set up an AbortController to use with the OTP request
    const ac = new AbortController();
    const form = input.closest("form");
    if (form) {
      // Abort the OTP request if the user attempts to submit the form manually
      form.addEventListener("submit", (e) => {
        ac.abort();
      });
    }
    // Request the OTP via get()
    navigator.credentials
      .get({
        otp: { transport: ["sms"] },
        signal: ac.signal,
      })
      .then((otp) => {
        // When the OTP is received by the app client, enter it into the form
        // input and submit the form automatically
        input.value = otp.code;
        if (form) form.submit();
      })
      .catch((err) => {
        console.error(err);
      });
  });
}

Ещё одно хорошее применение AbortController — отмена запроса get() после определённого промежутка времени:

setTimeout(() => {
  // abort after 30 seconds
  ac.abort();
}, 30 * 1000);

Если пользователь отвлекается или переходит на другую страницу, разумно отменить запрос, чтобы ему не было предложено диалоговое окно с запросом разрешения, которое больше не актуально.

• Проверка номеров телефонов в сети с помощью WebOTP на developer.chrome.com (2023)
• Заполнение форм OTP в фреймах с другим происхождением с помощью API WebOTP