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

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

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

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

Предварительные требования

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

Зависимости

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

Котлин 

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-rc01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-rc01")
}

Круто 

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-rc01"
}

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

Обзор

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

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

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

Создать менеджер учетных данных

Используйте контекст активности вашего приложения для создания объекта CredentialManager .

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

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

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

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

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

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
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 , но на устройстве пользователя отсутствует резервное копирование данных или сквозное шифрование, например, блокировка экрана.
  • IllegalArgumentException : Это исключение возникает, если createRestoreRequest пуст, не является допустимым JSON-объектом или не содержит допустимого user.id , соответствующего спецификациям WebAuthn.

Войдите в систему с помощью ключа восстановления.

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

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

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

Получите ключ восстановления

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

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

  • ( Рекомендуется ) Сразу после восстановления данных приложения. Используйте BackupAgent для настройки резервного копирования вашего приложения и выполните функцию getCredential в функции обратного вызова onRestore , чтобы гарантировать немедленное восстановление учетных данных приложения после восстановления данных приложения. Это позволит избежать потенциальных задержек при первом открытии пользователями нового устройства и даст возможность взаимодействовать с приложением, не дожидаясь его открытия.
  • При первом запуске приложения на устройстве.

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

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

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

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

API-интерфейсы менеджера учетных данных возвращают ответ типа GetCredentialResponse . Этот ответ содержит открытый ключ.

Обработайте ответ на запрос авторизации.

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

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

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

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

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

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

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

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

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)