Аутентификация на носимых устройствах: Credential Manager

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

В этом руководстве приведены инструкции по рекомендуемому методу аутентификации для приложений Wear OS — диспетчеру учетных данных.

Чтобы узнать больше о том, как разработать удобный процесс входа в систему, ознакомьтесь с руководством по UX-дизайну входа в систему .

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

Прежде чем приступить к внедрению, примите во внимание следующие моменты.

Гостевой режим

Не требуйте аутентификации для всех функций. Вместо этого предоставьте пользователю как можно больше функций без необходимости входа в систему.

Пользователи могут обнаружить и установить ваше приложение Wear, не имея опыта использования мобильного приложения, поэтому у них может не быть учётной записи и они могут не знать, какие функции оно предлагает. Убедитесь, что гостевой режим точно отображает возможности вашего приложения.

Некоторые устройства могут оставаться разблокированными дольше.

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

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

val wristDetectionEnabled =
        isWristDetectionAutoLockingEnabled(applicationContext)

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

Менеджер по учетным данным

Credential Manager — рекомендуемый API для аутентификации на Wear OS. Он обеспечивает более безопасную среду для входа пользователей в приложения Wear OS в автономном режиме, без необходимости подключения сопряженного телефона и запоминания пароля.

В этом документе излагается информация, необходимая разработчикам для внедрения решения Credential Manager со стандартными механизмами аутентификации, которые оно размещает, а именно:

• Ключи доступа
• Пароли
• Федеративные удостоверения (например, вход через Google)

В этом руководстве также содержатся инструкции по переносу других приемлемых методов аутентификации Wear OS ( Data Layer Token Sharing и OAuth ) в качестве резервных копий для Credential Manager, а также специальные инструкции по выполнению перехода с устаревшей автономной кнопки входа Google на встроенную версию Credential Manager.

Пароли на Wear OS

Разработчикам настоятельно рекомендуется реализовать пароли в своих реализациях диспетчера учетных данных Wear OS. Пароли — это новый отраслевой стандарт аутентификации конечных пользователей, и они дают им ряд существенных преимуществ .

Пароли проще

• Пользователи могут выбрать учётную запись для входа. Вводить имя пользователя не нужно.
• Пользователи могут пройти аутентификацию, используя блокировку экрана устройства.
• После создания и регистрации ключа доступа пользователь может легко переключиться на новое устройство и сразу же использовать его без необходимости повторной регистрации.

Пароли безопаснее

• Разработчики сохраняют на сервере только открытый ключ, а не пароль, а это значит, что злоумышленникам гораздо сложнее взломать серверы, а в случае взлома придется выполнять гораздо меньше действий по устранению неполадок.
• Пароли обеспечивают защиту от фишинга. Пароли действуют только на зарегистрированных сайтах и ​​в приложениях; пользователя невозможно обманным путём заставить пройти аутентификацию на мошенническом сайте, поскольку верификацию выполняет браузер или операционная система.
• Пароли сокращают необходимость отправки SMS-сообщений, делая аутентификацию более экономичной.

Реализовать пароли

Включает настройку и руководство для всех типов внедрения.

Настраивать

1. Установите целевой уровень API 35 в файле build.gradle вашего модуля приложения:

   android {
       defaultConfig {
           targetSdkVersion(35)
       }
   }
   

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

   androidx.credentials:credentials:1.5.0
   androidx.credentials:credentials-play-services-auth:1.5.0
   

Встроенные методы аутентификации

Поскольку Credential Manager представляет собой унифицированный API, шаги по внедрению для Wear OS такие же, как и для любого другого типа устройства.

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

Действия по добавлению поддержки «Входа с Google» в Credential Manager ориентированы на разработку мобильных приложений, но на Wear OS они аналогичны. Подробнее об этом см. в разделе « Переход от устаревшего «Входа с Google» .

Обратите внимание, что поскольку учетные данные невозможно создать в Wear OS, вам не нужно реализовывать методы создания учетных данных, упомянутые в мобильных инструкциях.

Резервные методы аутентификации

Для приложений Wear OS доступны два других метода аутентификации: OAuth 2.0 (любой из вариантов) и Mobile Auth Token Data Layer Sharing. Хотя эти методы не имеют точек интеграции в API Credential Manager, их можно включить в пользовательский интерфейс Credential Manager в качестве резервных вариантов на случай, если пользователи закроют экран Credential Manager.

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

yourCoroutineScope.launch {
    try {
      val response = credentialManager.getCredential(activity, request)
      signInWithCredential(response.credential)
    } catch (e: GetCredentialCancellationException) {
      navigateToFallbackAuthMethods()
    }
}

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

Совместное использование токенов уровня данных

Приложение-компаньон для телефона может безопасно передавать данные аутентификации в приложение Wear OS с помощью API Wearable Data Layer. Передавайте учётные данные в виде сообщений или элементов данных.

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

Важно: ваше приложение Wear OS должно предлагать как минимум один другой метод аутентификации, поскольку эта опция работает только на сопряженных с Android часах при установленном соответствующем мобильном приложении. Предоставьте альтернативный метод аутентификации для пользователей, у которых нет соответствующего мобильного приложения или чьи устройства Wear OS сопряжены с устройствами iOS.

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

val token = "..." // Auth token to transmit to the Wear OS device.
val dataClient: DataClient = Wearable.getDataClient(context)
val putDataReq: PutDataRequest = PutDataMapRequest.create("/auth").run {
    dataMap.putString("token", token)
    asPutDataRequest()
}
val putDataTask: Task<DataItem> = dataClient.putDataItem(putDataReq)

Прослушивайте события изменения данных в приложении Wear OS, как показано в следующем примере:

val dataClient: DataClient = Wearable.getDataClient(context)
dataClient.addListener{ dataEvents ->
    dataEvents.forEach { event ->
        if (event.type == DataEvent.TYPE_CHANGED) {
            val dataItemPath = event.dataItem.uri.path ?: ""
            if (dataItemPath.startsWith("/auth")) {
                val token = DataMapItem.fromDataItem(event.dataItem).dataMap.getString("token")
                // Display an interstitial screen to notify the user that
                // they're being signed in.
                // Then, store the token and use it in network requests.
            }
        }
    }
}

Дополнительную информацию об использовании Wearable Data Layer см. в разделе Отправка и синхронизация данных на Wear OS .

Использовать OAuth 2.0

Wear OS поддерживает два потока на основе OAuth 2.0, которые описаны в следующих разделах:

• Предоставление кода авторизации с ключом подтверждения для обмена кодами (PKCE), как определено в RFC 7636
• Разрешение на авторизацию устройства (DAG), как определено в RFC 8628

Примечание: Чтобы минимизировать вероятность завершения работы приложения при переходе устройства Wear OS в режим Ambient Mode, включите Always-on с помощью AmbientModeSupport.attach в действии, выполняющем аутентификацию. Подробнее о рекомендациях по использованию режима Ambient Mode см . в статье «Как обеспечить видимость приложения на Wear OS ».

Ключ подтверждения для обмена кодами (PKCE)

Для эффективного использования PKCE используйте RemoteAuthClient . Затем, чтобы выполнить запрос аутентификации из вашего приложения Wear OS к поставщику OAuth, создайте объект OAuthRequest . Этот объект состоит из URL-адреса вашей конечной точки OAuth для получения токена и объекта CodeChallenge .

Следующий код показывает пример создания запроса на аутентификацию:

val request = OAuthRequest.Builder(this.applicationContext)
    .setAuthProviderUrl(Uri.parse("https://...."))
    .setClientId(clientId)
    .setCodeChallenge(codeChallenge)
    .build()

После создания запроса на аутентификацию отправьте его в сопутствующее приложение с помощью метода sendAuthorizationRequest() :

val client = RemoteAuthClient.create(this)
client.sendAuthorizationRequest(request,
    { command -> command?.run() },
    object : RemoteAuthClient.Callback() {
        override fun onAuthorizationResponse(
            request: OAuthRequest,
            response: OAuthResponse
        ) {
            // Extract the token from the response, store it, and use it in
            // network requests.
        }

        override fun onAuthorizationError(errorCode: Int) {
            // Handle any errors.
        }
    }
)

Этот запрос инициирует вызов сопутствующего приложения, которое затем отображает интерфейс авторизации в веб-браузере на мобильном телефоне пользователя. Провайдер OAuth 2.0 аутентифицирует пользователя и получает его согласие на запрошенные разрешения. Ответ отправляется на автоматически сгенерированный URL-адрес перенаправления.

После успешной или неудачной авторизации сервер OAuth 2.0 перенаправляет пользователя на URL-адрес, указанный в запросе. Если пользователь одобряет запрос на доступ, ответ содержит код авторизации. Если пользователь не одобряет запрос, ответ содержит сообщение об ошибке.

Ответ имеет форму строки запроса и выглядит как один из следующих примеров:

  https://wear.googleapis.com/3p_auth/com.your.package.name?code=xyz
  https://wear.googleapis-cn.com/3p_auth/com.your.package.name?code=xyz

Загружается страница, которая перенаправляет пользователя в сопутствующее приложение. Сопутствующее приложение проверяет URL-адрес ответа и передаёт ответ в ваше приложение Wear OS, используя API onAuthorizationResponse .

Затем приложение для часов может обменять код авторизации на токен доступа.

Примечание: После создания OAuthRequest вы можете найти URL-адрес перенаправления, перейдя по адресу redirectUrl .

Грант на авторизацию устройства

При использовании Device Authorization Grant пользователь открывает URI проверки на другом устройстве. Затем сервер авторизации просит его одобрить или отклонить запрос.

Чтобы упростить этот процесс, используйте RemoteActivityHelper для открытия веб-страницы на сопряженном мобильном устройстве пользователя, как показано в следующем примере:

// Request access from the authorization server and receive Device Authorization
// Response.
val verificationUri = "..." // Extracted from the Device Authorization Response.
RemoteActivityHelper.startRemoteActivity(
    this,
    Intent(Intent.ACTION_VIEW)
        .addCategory(Intent.CATEGORY_BROWSABLE)
        .setData(Uri.parse(verificationUri)),
    null
)
// Poll the authorization server to find out if the user completed the user
// authorization step on their mobile device.

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

Переход от устаревшего входа через Google

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

Примечание: Версия Credential Manager для функции «Вход с Google» временно недоступна на устройствах Wear OS под управлением Wear OS 3 (API уровня 30). Если приложение вызывает Credential Manager на устройстве, которое его не поддерживает, поток GetCredential генерирует исключение NoCredentialException , которое обычно указывает на отсутствие доступных учётных данных для вызывающего приложения на устройстве пользователя.

Чтобы решить эту проблему, мы рекомендуем добавить устаревшую версию кнопки в качестве части резервного UX-процесса аутентификации и добавить булеву логику для отключения этой кнопки при использовании на устройствах с Wear OS 4 (уровень API 33) или выше. Это позволит пользователям получить доступ к привычной кнопке «Войти через Google» независимо от возможностей их устройства, а также отобразит единственный допустимый вариант аутентификации.

// Define a basic SDK check.
fun isCredentialManagerAvailable(): Boolean {
 return android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.VANILLA_ICE_CREAM
}

// Elsewhere in the code, use it to selectively disable the legacy option.
Button(
  onClick = {
    if (isCredentialManagerAvailable()) {
      Log.w(TAG, "Devices on API level 35 or higher should use
                  Credential Manager for Sign in with Google")
    } else {
      navigateToSignInWithGoogle()
    }},
  enabled = !isCredentialManagerAvailable(),
  label = { Text(text = stringResource(R.string.sign_in_with_google)) },
  secondaryLabel = { Text(text = "Disabled on API level 35+")
  }
)