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

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

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

Функция восстановления учетных данных в Credential Manager работает на устройствах под управлением Android 9 и выше, с ядром Google Play Services (GMS) версии 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"
}

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

Обзор

  1. Создание ключа восстановления : Для создания ключа восстановления выполните следующие шаги:
    1. Создание экземпляра Credential Manager : Создайте объект 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 : Параметры создания учетных данных, отправляемые сервером приложений в формате API веб-аутентификации для PublicKeyCredentialCreationOptionsJSON .

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

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

Обработайте ответ о создании учетных данных.

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 надежно вызывается для любого типа восстановления резервных копий. Это позволяет избежать потенциальных задержек при первом открытии пользователями нового устройства и позволяет им взаимодействовать с приложением, не дожидаясь его открытия. Например, это позволяет вашему приложению отправлять пользователю уведомления до первого открытия приложения на новом устройстве, что особенно актуально для приложений обмена сообщениями или связи.
// 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)