Как реализовать восстановление учетных данных с помощью Менеджера учетных данных

На этой странице описано, как создать ключ восстановления, войти с его помощью и удалить его.

Совместимость версий

Функция восстановления учетных данных в Менеджере учетных данных работает на устройствах с Android 9 (уровень API 28) и более поздними версиями, сервисами Google Play (GMS) Core версии 24220000 или выше и библиотекой androidx.credentials версии 1.5.0 или выше.

Требования

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

Связанные запросы

Добавьте в файл build.gradle модуля приложения следующие зависимости:

Котлин 

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha03")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha03")
}

Круто 

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha03"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha03"
}

Восстановление учетных данных доступно в библиотеке androidx.credentials версии 1.5.0 и выше. Однако по возможности рекомендуется использовать последние стабильные версии зависимостей.

Обзор

  1. Создайте ключ восстановления. Для этого выполните следующие действия:
    1. Создайте экземпляр Менеджера учетных данных. Создайте объект CredentialManager.
    2. Получите параметры создания учетных данных от сервера приложения. Отправьте клиентскому приложению сведения, необходимые для создания ключа восстановления с сервера приложения.
    3. Создайте ключ восстановления. Создайте ключ восстановления для аккаунта пользователя, если он вошел в ваше приложение.
    4. Обработка ответа о создании учетных данных. Отправьте учетные данные из клиентского приложения на сервер приложения для обработки и обработайте все исключения.
  2. Войти с помощью ключа восстановления. Чтобы войти с помощью ключа восстановления, выполните следующие действия:
    1. Получите параметры извлечения учетных данных с сервера приложения. Отправьте клиентскому приложению сведения, необходимые для получения ключа восстановления с сервера приложения.
    2. Получите ключ восстановления. Запросите ключ восстановления у Менеджера учетных данных, когда пользователь настраивает новое устройство. Это позволяет пользователю войти в систему без дополнительных действий.
    3. Обработка ответа на получение учетных данных. Отправьте ключ восстановления из клиентского приложения на сервер приложения, чтобы выполнить вход пользователя.
  3. Удалить ключ восстановления.

Создайте ключ восстановления

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

  • Если пользователь вошел в аккаунт и ключ восстановления ещё не создан (например, в методе onCreate для основного Activity).
  • Когда пользователь входит в аккаунт или регистрирует новый.

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

Создайте экземпляр Менеджера учетных данных

Используйте контекст действия приложения, чтобы создать экземпляр объекта CredentialManager.

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

Получите параметры создания учетных данных от сервера приложения.

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

Создайте ключ восстановления

Проанализируйте параметры создания открытого ключа, отправленные сервером, и создайте ключ восстановления. Для этого упакуйте параметры в объект CreateRestoreCredentialRequest и вызовите метод createCredential() с объектом CredentialManager.

// createRestoreRequest contains the details sent by the server 
val response = credentialManager.createCredential(context, createRestoreRequest)

Важные сведения о коде

  • Объект CreateRestoreCredentialRequest содержит следующие поля:

    • requestJson – параметры создания учетных данных, отправленные сервером приложения в формате Web Authentication API для PublicKeyCredentialCreationOptionsJSON.

    • isCloudBackupEnabled: поле Boolean, определяющее, нужно ли сохранять ключ восстановления в облаке. По умолчанию для этого параметра задано значение true. Это поле может принимать следующие значения:

      • true: (рекомендуется) это значение позволяет создавать резервные копии ключей восстановления в облаке, если у пользователя включены резервное копирование Google и сквозное шифрование, например блокировка экрана.
      • false – ключ сохраняется локально, а не в облаке. Если пользователь решит восстановить данные из облака, ключ будет недоступен на новом устройстве.

Как обработать ответ на создание учетных данных

Credential Manager API возвращает ответ типа CreateRestoreCredentialResponse. Этот ответ содержит ответ на регистрацию учетных данных открытого ключа в формате JSON.

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

При создании ключа восстановления обработайте следующие исключения:

  • CreateRestoreCredentialDomException. Это исключение возникает, если requestJson недействителен и не соответствует формату WebAuthn для PublicKeyCredentialCreationOptionsJSON.
  • E2eeUnavailableException. Эта ошибка возникает, если для параметра isCloudBackupEnabled задано значение true, но на устройстве пользователя не настроено резервное копирование данных или сквозное шифрование, например блокировка экрана.
    Чтобы учетные данные для восстановления создавались во всех случаях, необходимо явно обработать E2eeUnavailableException, вызвав createCredential с isCloudBackupEnabled, для которого задано значение true. Если возникает ошибка E2eeUnavailableException, перехватите ее и снова вызовите createCredential, задав для isCloudBackupEnabled значение false.
  • IllegalArgumentException. Эта ошибка возникает, если createRestoreRequest пуст или не является действительным объектом JSON, а также если у него нет действительного user.id, соответствующего спецификациям WebAuthn.

Как войти с помощью ключа восстановления

Используйте функцию восстановления учетных данных, чтобы автоматически выполнять вход пользователя во время настройки устройства.

Получите параметры извлечения учетных данных с сервера приложения

Отправьте клиентскому приложению параметры, необходимые для получения ключа восстановления с сервера. Инструкции по входу с помощью ключа доступа приведены в статье Как войти в аккаунт, используя ключ доступа вместо пароля. Дополнительную информацию о реализации на стороне сервера можно найти в руководстве по аутентификации на стороне сервера.

Как получить ключ восстановления

Чтобы получить ключ восстановления на новом устройстве, вызовите метод getCredential() для объекта CredentialManager.

Рекомендуется получать ключ восстановления в обоих следующих сценариях:

  • При первом запуске приложения на устройстве. В этом случае восстановление учетных данных не зависит от восстановления данных приложения.
  • Если резервное копирование и восстановление данных приложения включено, получите ключ восстановления сразу после восстановления данных приложения. Используйте BackupAgent, чтобы настроить резервное копирование приложения, и убедитесь, что вы реализовали функцию getCredential в обратном вызове onRestoreFinished. Не используйте метод onRestore, так как он вызывается только для резервных копий типа "ключ-значение", тогда как onRestoreFinished надежно вызывается для любого типа восстановления резервной копии. Это позволяет избежать задержек при первом запуске нового устройства и дает пользователям возможность взаимодействовать с приложением, не открывая его. Например, приложение может отправлять пользователю уведомления до того, как он впервые откроет его на новом устройстве. Это особенно актуально для приложений для обмена сообщениями и связи.

Если вы создаете новый BackupAgent и ранее у вас было включено резервное копирование с помощью allowBackup="true", задайте логическое значение android:fullBackupOnly="true" в манифесте приложения. Это позволит сохранить настройки резервного копирования и восстановления приложения.

// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

val response = credentialManager.getCredential(context, getRequest)

// Type-check and extract the restore credential
val credential = response.credential as RestoreCredential

API Менеджера учетных данных возвращают ответ типа GetCredentialResponse. Учетные данные, содержащиеся в этом ответе, явно относятся к типу RestoreCredential, который содержит открытый ключ.

Обработка ответа на запрос входа

Отправьте открытый ключ из приложения на сервер проверяющей стороны, чтобы использовать его для входа пользователя. На стороне сервера это действие похоже на вход с помощью ключа доступа. Тот же код, который обрабатывает вход с помощью ключей доступа на сервере, может также обрабатывать вход с помощью ключей восстановления. Подробнее о реализации ключей доступа на стороне сервера…

Удалить ключ восстановления

Менеджер учетных данных не сохраняет состояние и не отслеживает действия пользователя, поэтому он не удаляет ключи восстановления автоматически после использования. Чтобы удалить ключ восстановления, вызовите метод clearCredentialState. В целях безопасности удаляйте ключ каждый раз, когда пользователь выходит из аккаунта. Это гарантирует, что при следующем открытии приложения на том же устройстве пользователь будет выведен из системы и ему будет предложено войти снова.

Удаление приложения интерпретируется как намерение удалить соответствующий ключ восстановления с этого устройства, аналогично намерению пользователя при выходе из системы.

Ключи восстановления удаляются только в следующих случаях:

  • Действия на уровне системы. Пользователь удаляет приложение или его данные.
  • Вызовы на уровне приложения. Удалите ключ программно, вызвав clearCredentialState() при обработке выхода пользователя из аккаунта в коде приложения.

Когда пользователь выходит из приложения, вызовите метод clearCredentialState() для объекта CredentialManager.

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)