CredentialsContainer: метод get()

Метод get() интерфейса CredentialsContainer возвращает Promise, который выполняется с одним кредитными данными, которые затем могут быть использованы для аутентификации пользователя на веб-сайте.

Метод принимает один необязательный options аргумент, который может включать:

• Свойство mediation, указывающее, как и нужно ли пользователя спросить об участии в операции. Это управляет, например, может ли сайт беспрепятственно войти в систему пользователя, используя сохраненные учетные данные.
• Свойство signal, позволяющее отменить операцию с помощью AbortController.
• Одно или несколько свойств — password, federated, identity, otp, publicKey — которые указывают на типы учетных данных, которые запрашиваются. Если установлены, значения этих свойств включают все параметры, необходимые браузеру для поиска подходящих учетных данных заданного типа.

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

options Необязательно

Объект, содержащий параметры для запроса. Он может содержать следующие свойства:

mediation Необязательно

Строка, указывающая, требуется ли пользователю вход для каждого посещения приложения. Значение может быть одним из следующих:

• "conditional": Обнаруженные учетные данные представляются пользователю в немодальном диалоговом окне вместе с указанием источника, запрашивающего учетные данные. На практике это означает автоматическое заполнение доступных учетных данных; см. Вход с помощью ключа доступа через автоматическое заполнение формы для получения более подробных сведений о том, как это используется; PublicKeyCredential.isConditionalMediationAvailable() также содержит полезную информацию.

• "optional": Если учетные данные могут быть переданы для данной операции без участия пользователя, они будут, что позволит автоматически повторно аутентифицироваться без участия пользователя. Если требуется участие пользователя, пользовательский агент запросит у пользователя аутентификацию. Это значение предназначено для ситуаций, когда можно быть уверенным, что пользователь не удивится или не запутается, увидев диалоговое окно входа в систему — например, на сайте, который не автоматически входит в систему пользователей, когда пользователь только что нажал кнопку «Вход/Регистрация».

• "required": Пользователь всегда будет просить аутентификацию, даже если предотвращение беспрепятственного доступа (см. CredentialsContainer.preventSilentAccess()) установлено на false. Это значение предназначено для ситуаций, когда требуется принудительная аутентификация пользователя — например, если необходимо повторно аутентифицировать пользователя при выполнении чувствительной операции (например, подтверждения платежа по кредитной карте) или при переключении пользователей.

• "silent": Пользователь не будет просить аутентификацию. Пользовательский агент автоматически повторно аутентифицирует пользователя и войдет в систему, если это возможно. Если требуется согласие, обещание выполнится с null. Это значение предназначено для ситуаций, когда вы хотели бы автоматически войти в систему пользователя при посещении веб-приложения, если это возможно, но если нет, вы не хотите представлять им путающее диалоговое окно входа в систему. Вместо этого вы хотели бы ждать, пока они явно не нажмут кнопку «Вход/Регистрация».

Значение по умолчанию — "optional".

Примечание: В случае запроса федеральной аутентификации (API FedCM) значение mediation optional или silent может привести к попытке автоматического повторного входа. Произошло ли это, сообщается поставщику идентификации (IdP) через параметр is_auto_selected, отправленный IdP при проверке, и поставщику услуг (RP) через свойство IdentityCredential.isAutoSelected. Это полезно для оценки производительности, требований безопасности (IdP может отклонить запросы на автоматическое повторное подключение и всегда требовать проверки пользователя) и общего пользовательского интерфейса (IdP или RP может предоставить разный пользовательский интерфейс для авто- и неавторизованного входа в систему).

signal Необязательно

Объект AbortSignal, который позволяет прервать текущую операцию get(). Прерванная операция может завершиться нормально (обычно, если прерывание было получено после завершения операции) или отклониться с AbortError DOMException.

password Необязательно

Этот параметр запрашивает у браузера извлечь сохраненный пароль в качестве объекта PasswordCredential. Это логическое значение.

identity Необязательно

Этот параметр запрашивает у браузера извлечь федеративные учетные данные для идентификации в виде объекта IdentityCredential с помощью API управления федеративными учетными данными.

Значение этого параметра — объект IdentityCredentialRequestOptions, содержащий подробности конкретных поставщиков идентификаторов, которые хочет использовать веб-сайт.

federated Необязательно

Этот параметр запрашивает у браузера извлечь федеративные учетные данные для идентификации в виде объекта FederatedCredential. Этот интерфейс теперь устарел, и разработчики должны предпочесть использовать параметр identity , если он доступен.

Значение этого параметра — объект со следующими свойствами:

protocols

Массив строк, представляющих протоколы запрашиваемых федеративных поставщиков идентификаторов учетных данных (например, "openidconnect").

providers

Массив строк, представляющих федеративных поставщиков идентификаторов учетных данных (например, "https://www.facebook.com" или "https://accounts.google.com").

otp Необязательно

Этот параметр запрашивает у браузера извлечь одноразовые пароли (OTP) в качестве объекта OTPCredential.

Значение этого параметра — массив строк, который может содержать только строковое значение "sms".

publicKey Необязательно

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

Значение этого параметра — объект PublicKeyCredentialRequestOptions.

Promise, который разрешается одним из следующих подклассов Credential:

• PasswordCredential
• IdentityCredential
• FederatedCredential
• OTPCredential
• PublicKeyCredential

Если одну учетную запись нельзя однозначно получить, обещание разрешается значением null.

AbortError DOMException

Запрос был прерван вызовом метода abort() объекта AbortController, связанного с опцией signal этого метода.

IdentityCredentialError DOMException

При запросе IdentityCredential запрос к конечному пункту утверждения идентичности не смог валидировать аутентификацию и отклонил запрос с сообщением об ошибке, содержащим информацию о причине.

NetworkError DOMException

При запросе IdentityCredential поставщик идентификации (IdP) не ответил в течение 60 секунд, предоставленные учётные данные были недействительными/не найдены, или состояние входа браузера для IdP установлено в "logged-out" (см. Обновление состояния входа с помощью API состояния входа для получения дополнительной информации о состоянии входа FedCM). В последнем случае может быть небольшая задержка при отклонении, чтобы предотвратить утечку состояния входа IdP в RP.

NotAllowedError DOMException

Выбрасывается в одной из следующих ситуаций:

• Использование этого API было заблокировано одним из следующих политик разрешений:

  • identity-credentials-get
  • publickey-credentials-get
  • otp-credentials

• Вызывающий источник — это прозрачный источник.

SecurityError DOMException

Вызывающий домен не является допустимым доменом.

Организации, использующие доверенные стороны, могут вызвать get() с опцией identity для запроса входа пользователей в доверенную сторону через поставщика удостоверений (IdP) с использованием федерации удостоверений. Типичный запрос выглядит следующим образом:

async function signIn() {
  const identityCredential = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://accounts.idp.example/config.json",
          clientId: "********",
          nonce: "******",
        },
      ],
    },
  });
}

Подробнее о работе с этим процессом см. в разделе API федерального управления удостоверениями (FedCM). Этот вызов запустит процесс входа, описанный в потоке входа FedCM.

Аналогичный вызов, включающий расширения context и loginHint, будет выглядеть так:

async function signIn() {
  const identityCredential = await navigator.credentials.get({
    identity: {
      context: "signup",
      providers: [
        {
          configURL: "https://accounts.idp.example/config.json",
          clientId: "********",
          nonce: "******",
          loginHint: "user1@example.com",
        },
      ],
    },
  });
}

Если IdP не может валидировать запрос к конечному пункту утверждения идентичности, он отклонит обещание, возвращаемое из CredentialsContainer.get().

async function signIn() {
  try {
    const identityCredential = await navigator.credentials.get({
      identity: {
        providers: [
          {
            configURL: "https://accounts.idp.example/config.json",
            clientId: "********",
            nonce: "******",
          },
        ],
      },
    });
  } catch (e) {
    // Handle the error in some way, for example provide information
    // to help the user succeed in a future sign-in attempt
    console.error(e);
  }
}

Следующий фрагмент кода демонстрирует типичный вызов get() с опцией WebAuthn publicKey:

const publicKey = {
  challenge: new Uint8Array([139, 66, 181, 87, 7, 203, ...]),
  rpId: "acme.com",
  allowCredentials: [{
    type: "public-key",
    id: new Uint8Array([64, 66, 25, 78, 168, 226, 174, ...])
  }],
  userVerification: "required",
}

navigator.credentials.get({ publicKey })

Успешный вызов get() возвращает обещание, которое разрешается объектом PublicKeyCredential, представляющим удостоверение с открытым ключом, созданное ранее с помощью WebAuthn create() и использованное для аутентификации пользователя. Свойство PublicKeyCredential.response содержит объект AuthenticatorAssertionResponse, предоставляющий доступ к нескольким полезным фрагментам информации, включая данные аутентификатора, подпись и идентификатор пользователя.

navigator.credentials.get({ publicKey }).then((publicKeyCredential) => {
  const response = publicKeyCredential.response;

  // Access authenticator data ArrayBuffer
  const authenticatorData = response.authenticatorData;

  // Access client JSON
  const clientJSON = response.clientDataJSON;

  // Access signature ArrayBuffer
  const signature = response.signature;

  // Access userHandle ArrayBuffer
  const userHandle = response.userHandle;
});

Некоторые из этих данных необходимо хранить на сервере — например, signature для доказательства того, что аутентификатор обладает подлинным закрытым ключом, использованным для создания удостоверения, и userHandle для связи пользователя с удостоверением, попыткой входа и другими данными.

См. Аутентификацию пользователя для получения дополнительной информации о работе общего потока.

Приведенный ниже код запускает процесс разрешения доступа браузера при получении SMS-сообщения. Если разрешение предоставлено, то обещание разрешается с объектом OTPCredential. Значение code затем устанавливается как значение элемента формы <input>, который затем отправляется.

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