Credentials

Credentials — это виртуальный аутентификатор WebAuthn, область действия которого ограничена BrowserContext. Он позволяет тестам регистрировать ключи доступа (passkey) и обрабатывать процедуры navigator.credentials.create() / navigator.credentials.get() на странице без реального аутентификатора или аппаратного ключа безопасности.

Существует три распространённых способа его использования:

Использование: предварительное добавление известных учётных данных

BrowserContext context = browser.newContext();

// Ключ доступа, который ваш бэкенд уже подготовил для тестового пользователя.
context.credentials().create("example.com", new Credentials.CreateOptions()
    .setId(knownCredentialId) // base64url
    .setUserHandle(knownUserHandle) // base64url
    .setPrivateKey(knownPrivateKey) // base64url PKCS#8 (DER)
    .setPublicKey(knownPublicKey)); // base64url SPKI (DER)
context.credentials().install();

Page page = context.newPage();
page.navigate("https://example.com/login");
// На вызов navigator.credentials.get() со страницы возвращается предварительно добавленный ключ доступа.

Использование: получение учётных данных и их повторное использование

// Подготовительный тест: разрешаем приложению зарегистрировать ключ доступа, а затем сохраняем его.
BrowserContext context = browser.newContext();
context.credentials().install();

Page page = context.newPage();
page.navigate("https://example.com/register");
page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Create a passkey")).click();

// Получаем ключ доступа, зарегистрированный страницей, — он включает закрытый ключ.
VirtualCredential credential = context.credentials().get(
    new Credentials.GetOptions().setRpId("example.com")).get(0);
Files.writeString(Paths.get("playwright/.auth/passkey.json"), new Gson().toJson(credential));

// Последующий тест: предварительно добавляем сохранённый ключ доступа, чтобы он уже был зарегистрирован в приложении.
VirtualCredential credential = new Gson().fromJson(
    Files.readString(Paths.get("playwright/.auth/passkey.json")), VirtualCredential.class);
BrowserContext context = browser.newContext();
context.credentials().create(credential.rpId, new Credentials.CreateOptions()
    .setId(credential.id)
    .setUserHandle(credential.userHandle)
    .setPrivateKey(credential.privateKey)
    .setPublicKey(credential.publicKey)
    .setSignCount(credential.signCount));
context.credentials().install();

Page page = context.newPage();
page.navigate("https://example.com/login");
// navigator.credentials.get() возвращает сохранённый ключ доступа — вход выполнен.

Использование: сохранение учётных данных в состоянии хранилища и последующее восстановление

Примеры сохранения и восстановления состояния хранилища приведены в руководстве по аутентификации.

Значения по умолчанию

Методы

create

Добавлено в: v1.61

credentials.create

Предварительно добавляет виртуальные учётные данные WebAuthn и возвращает их.

Если указан только rpId, генерирует новую пару ключей ECDSA P-256, идентификатор учётных данных и идентификатор пользователя (user handle). Добавленные учётные данные являются обнаруживаемыми (резидентными), поэтому страница может получать их как в сценариях с вводом имени пользователя перед использованием ключа доступа, так и в сценариях использования ключа доступа без ввода имени пользователя. Возвращаемый объект содержит закрытый и открытый ключи, поэтому его можно сохранить на диск и предварительно добавить в последующем тесте.

Чтобы импортировать известные учётные данные, укажите все четыре параметра одновременно: setId, setUserHandle, setPrivateKey и setPublicKey. Также передайте setSignCount, чтобы продолжить отсчёт со значения счётчика подписей, которое доверяющая сторона уже получила.

Вызовите Credentials.install() перед переходом на страницу, использующую WebAuthn.

Использование

Credentials.create(rpId);
Credentials.create(rpId, options);

Аргументы

rpId String #

Идентификатор доверяющей стороны (обычно фактический домен сайта).
options Credentials.CreateOptions (необязательно)
- setId String (необязательно)#
  
  Идентификатор учётных данных в кодировке base64url. Если не указан, генерируется автоматически.
- setPrivateKey String (необязательно)#
  
  Закрытый ключ в формате PKCS#8 (DER), закодированный в base64url. Если не указан, генерируется автоматически.
- setPublicKey String (необязательно)#
  
  Открытый ключ в формате SPKI (DER), закодированный в base64url. Если не указан, генерируется автоматически.
- setSignCount int (необязательно) Добавлено в: v1.64#
  
  Начальное значение счётчика подписей. Счётчик увеличивается на единицу при каждом успешном подтверждении аутентификации через navigator.credentials.get(), поэтому первое подтверждение сообщает значение signCount + 1. По умолчанию — 0.
- setUserHandle String (необязательно)#
  
  Идентификатор пользователя (user handle) в кодировке base64url. Если не указан, генерируется автоматически.

Возвращает

Create#
- id String
  
  Идентификатор учётных данных в кодировке base64url.
- rpId String
  
  Идентификатор доверяющей стороны.
- userHandle String
  
  Идентификатор пользователя (user handle) в кодировке base64url.
- privateKey String
  
  Закрытый ключ в формате PKCS#8 (DER), закодированный в base64url.
- publicKey String
  
  Открытый ключ в формате SPKI (DER), закодированный в base64url.
- signCount int
  
  Счётчик подписей: значение, переданное доверяющей стороне в последнем подтверждении аутентификации.

delete

Добавлено в: v1.61

credentials.delete

Удаляет учётные данные из аутентификатора по их идентификатору. Работает с любыми учётными данными, которые в данный момент хранятся в аутентификаторе, — как с предварительно добавленными через Credentials.create(), так и с теми, которые страница зарегистрировала самостоятельно вызовом navigator.credentials.create().

Использование

Credentials.delete(id);

Аргументы

id String #

Идентификатор учётных данных в кодировке base64url.

Возвращает

void #

get

Добавлено в: v1.61

credentials.get

Возвращает все учётные данные, которые в данный момент хранятся в аутентификаторе, с возможностью фильтрации по setRpId или setId. Сюда входят как учётные данные, предварительно добавленные через Credentials.create(), так и учётные данные, которые страница зарегистрировала самостоятельно вызовом navigator.credentials.create().

Каждый возвращаемый объект учётных данных содержит закрытый и открытый ключи, а также текущее значение счётчика подписей. Поэтому ключ доступа, только что зарегистрированный приложением, можно сохранить и предварительно добавить в последующем тесте с помощью Credentials.create() — см. второй пример в обзоре класса.

Использование

Credentials.get();
Credentials.get(options);

Аргументы

options Credentials.GetOptions (необязательно)
- setId String (необязательно)#
  
  Возвращать только учётные данные с этим идентификатором в кодировке base64url.
- setRpId String (необязательно)#
  
  Возвращать только учётные данные для указанного идентификатора доверяющей стороны.

Возвращает

List<Get>#
- id String
- rpId String
- userHandle String
- privateKey String
- publicKey String
- signCount int

install

Добавлено в: v1.61

credentials.install

Устанавливает виртуальный аутентификатор WebAuthn в контекст, переопределяя navigator.credentials.create() и navigator.credentials.get() на всех текущих и будущих страницах. Вызовите этот метод до первого обращения страницы к navigator.credentials.

Обязательный вызов: пока не вызван Credentials.install(), перехват не выполняется и страница использует встроенную реализацию WebAuthn платформы (либо WebAuthn остаётся недоступным, если такой реализации нет). Предварительное добавление учётных данных через Credentials.create() без установки аутентификатора заполняет его, но страница никогда не получит доступ к этим учётным данным.

Использование

Credentials.install();

Возвращает

void #

Методы​

create​

delete​

get​

install​

Методы

create

delete

get

install