Os apps para Wear OS podem ser executados sem um app complementar. Isso significa que eles precisam gerenciar a autenticação por conta própria ao acessar dados da Internet. No entanto, o tamanho de tela pequeno do smartwatch e os recursos de entrada reduzidos limitam as opções de autenticação que um app para Wear OS pode usar.
Este guia fornece instruções sobre o método de autenticação recomendado para apps para Wear OS, o Gerenciador de credenciais.
Para saber mais sobre como criar uma boa experiência de login, consulte o guia de UX de login.
Considerações preliminares
Antes de iniciar a implementação, considere os seguintes pontos.
Modo convidado
Não exija autenticação para todas as funcionalidades. Em vez disso, ofereça o máximo de recursos possível ao usuário sem exigir que ele faça login.
Os usuários podem descobrir e instalar o app para Wear sem ter usado o app para dispositivos móveis. Assim, podem não ter uma conta e não saber quais recursos ele oferece. Confira se a função do modo visitante apresenta corretamente os recursos do app.
Alguns dispositivos podem permanecer desbloqueados por mais tempo
Em dispositivos com suporte ao Wear OS 5 ou mais recente, o sistema detecta se o usuário está usando o dispositivo no pulso. Se o usuário desativar a detecção do pulso e retirar o dispositivo do pulso, o sistema manterá o dispositivo desbloqueado por um período mais longo do que o normal.
Se o app exigir um nível mais alto de segurança, como ao mostrar dados potencialmente sensíveis ou particulares, primeiro verifique se a detecção de pulso está ativada:
val wristDetectionEnabled =
isWristDetectionAutoLockingEnabled(applicationContext)
Se o valor de retorno desse método for false, peça para o usuário fazer login em uma
conta no app antes de mostrar o conteúdo específico do usuário.
Credential Manager
O Gerenciador de credenciais é a API recomendada para autenticação no Wear OS. Ele oferece um ambiente mais seguro para os usuários fazerem login nos apps do Wear OS em uma configuração independente, sem precisar de um smartphone pareado conectado e sem precisar lembrar da senha.
Este documento descreve as informações que os desenvolvedores precisam para implementar uma solução do Gerenciador de credenciais com os mecanismos de autenticação padrão que ele hospeda, que são:
- Chaves de acesso
- Senhas
- Identidades federadas (como o recurso Fazer login com o Google)
Este guia também fornece instruções sobre como migrar os outros métodos de autenticação do Wear OS (compartilhamento de tokens da camada de dados e OAuth) como backups para o Gerenciador de credenciais e instruções especiais para processar a transição do botão de login independente do Google, que foi descontinuado, para a versão integrada do Gerenciador de credenciais.
Chaves de acesso no Wear OS
Os desenvolvedores são fortemente incentivados a implementar chaves de acesso nas implementações do Gerenciador de credenciais do Wear OS. As chaves de acesso são o novo padrão do setor para autenticação do usuário final e têm vários benefícios importantes para os usuários.
As chaves de acesso são mais fáceis
- Os usuários podem selecionar uma conta para fazer login. Não é necessário digitar um nome de usuário.
- Os usuários podem fazer a autenticação usando o bloqueio de tela do dispositivo.
- Depois que uma chave de acesso é criada e registrada, o usuário pode mudar para um novo dispositivo e usá-lo imediatamente sem precisar fazer um novo registro.
As chaves de acesso são mais seguras
- Os desenvolvedores salvam apenas uma chave pública no servidor em vez de uma senha, o que significa que há muito menos valor para um invasor hackear servidores e muito menos limpeza a ser feita no caso de uma violação.
- As chaves de acesso oferecem proteção contra phishing. As chaves de acesso funcionam apenas em sites e apps registrados. Um usuário não pode ser enganado para fazer a autenticação em um site enganoso, porque o navegador ou o SO processa a verificação.
- As chaves de acesso reduzem a necessidade de enviar SMS, tornando a autenticação mais econômica.
Implementar chaves de acesso
Inclui configuração e orientação para todos os tipos de implementação.
Configurar
Defina o nível desejado da API como 35 no arquivo build.gradle do módulo do aplicativo:
android { defaultConfig { targetSdkVersion(35) } }Adicione as linhas a seguir ao arquivo build.gradle do app ou módulo, usando a versão estável mais recente da referência
androidx.credentialsreleases.androidx.credentials:credentials:1.5.0 androidx.credentials:credentials-play-services-auth:1.5.0
Métodos de autenticação integrados
Como o Credential Manager é uma API unificada, as etapas de implementação para o Wear OS são as mesmas de qualquer outro tipo de dispositivo.
Use as instruções para dispositivos móveis para começar a usar e implementar o suporte a chaves de acesso e senhas.
As etapas para adicionar suporte ao recurso Fazer login com o Google ao Gerenciador de credenciais são voltadas para o desenvolvimento de dispositivos móveis, mas são as mesmas no Wear OS. Consulte a seção Como fazer a transição do recurso "Fazer login com o Google" legado para considerações especiais sobre esse caso.
Como as credenciais não podem ser criadas no Wear OS, não é necessário implementar os métodos de criação de credenciais mencionados nas instruções para dispositivos móveis.
Métodos de autenticação alternativos
Há outros dois métodos de autenticação aceitáveis para apps do Wear OS: OAuth 2.0 (qualquer variante) e compartilhamento de camada de dados de token de autenticação móvel. Embora esses métodos não tenham pontos de integração na API Credential Manager, eles podem ser incluídos no fluxo de UX do Gerenciador de credenciais como substitutos caso os usuários desativem a tela do Gerenciador de credenciais.
Para processar a ação do usuário de dispensar a tela do Gerenciador de credenciais, capture um
NoCredentialException como parte da lógica
GetCredential
e navegue até sua própria interface de autenticação personalizada.
yourCoroutineScope.launch {
try {
val response = credentialManager.getCredential(activity, request)
signInWithCredential(response.credential)
} catch (e: GetCredentialCancellationException) {
navigateToFallbackAuthMethods()
}
}
A interface de autenticação personalizada pode fornecer qualquer um dos outros métodos de autenticação aceitáveis descritos no guia de UX de login.
Compartilhamento de tokens da camada de dados
O app complementar do smartphone pode transferir dados de autenticação com segurança para o app para Wear OS usando a API Wearable Data Layer. Transfira credenciais como mensagens ou itens de dados.
Normalmente, esse tipo de autenticação não requer nenhuma ação do usuário. No entanto, evite realizar a autenticação sem informar o usuário que ele está conectado. Informe o usuário usando uma tela dispensável que mostre que a conta está sendo transferida do dispositivo móvel.
Importante:o app para Wear OS precisa oferecer pelo menos um outro método de autenticação, já que essa opção funciona apenas em smartwatches pareados com Android quando o app para dispositivos móveis correspondente está instalado. Forneça um método de autenticação alternativo para usuários que não têm o app para dispositivos móveis correspondente ou que usam um dispositivo Wear OS pareado com um dispositivo iOS.
Transmita tokens usando a camada de dados do app para dispositivos móveis, conforme mostrado no exemplo abaixo:
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)
Detecte eventos de mudança de dados no app para Wear OS, conforme mostrado no exemplo a seguir:
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.
}
}
}
}
Para mais informações sobre como usar a camada de dados de wearables, consulte Enviar e sincronizar dados no Wear OS.
Usar o OAuth 2.0
O Wear OS oferece suporte a dois fluxos baseados em OAuth 2.0, que são descritos nas seções a seguir:
- Concessão de código de autorização com chave de prova para troca de código (PKCE, na sigla em inglês), conforme definido na RFC 7636 (link em inglês)
- Concessão de autorização do dispositivo (DAG, na sigla em inglês), conforme definido na RFC 8628 (link em inglês)
Chave de prova para troca de código (PKCE, na sigla em inglês)
Para usar a PKCE com eficiência, use RemoteAuthClient.
Em seguida, para realizar uma solicitação de autenticação do app para Wear OS a um provedor OAuth,
crie um objeto OAuthRequest. Esse objeto consiste
em um URL para o endpoint de OAuth para receber um token e um
objeto CodeChallenge.
O código a seguir mostra um exemplo de como criar uma solicitação de autenticação:
val request = OAuthRequest.Builder(this.applicationContext)
.setAuthProviderUrl(Uri.parse("https://...."))
.setClientId(clientId)
.setCodeChallenge(codeChallenge)
.build()
Depois de criar a solicitação de autenticação, faça o envio dela ao app complementar usando o
método 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.
}
}
)
Essa solicitação aciona uma chamada para o app complementar, que depois apresenta uma interface de autorização em um navegador da Web no smartphone do usuário. O provedor de OAuth 2.0 autentica o usuário e recebe o consentimento dele para as permissões solicitadas. A resposta é enviada ao URL de redirecionamento gerado automaticamente.
Após o sucesso ou falha da autenticação, o servidor OAuth 2.0 redireciona ao URL especificado na solicitação. Se o usuário aprovar a solicitação de acesso, a resposta vai conter um código de autorização. Se o usuário não aprovar a solicitação, a resposta vai conter uma mensagem de erro.
A resposta está na forma de uma string de consulta e é semelhante a um dos exemplos abaixo:
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
Isso carrega uma página que direciona o usuário ao app complementar, que
verifica o URL da resposta e a redireciona ao app para Wear OS
usando a API onAuthorizationResponse.
O app para smartwatch pode trocar o código de autorização por um token de acesso.
Concessão de autorização do dispositivo
Ao usar a concessão de autorização do dispositivo, o usuário abre o URI de verificação em outro dispositivo. Em seguida, o servidor de autorização pede que ele aprove ou negue a solicitação.
Para facilitar esse processo, use um
RemoteActivityHelper para abrir uma página da Web no
dispositivo móvel pareado do usuário, conforme mostrado no exemplo a seguir:
// 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.
Se você tiver um app iOS, use links universais para interceptar essa intent no app, em vez de depender do navegador para autorizar o token.
Fazer a transição do recurso legado "Fazer login com o Google"
O Gerenciador de credenciais tem um ponto de integração dedicado para um botão do recurso Fazer login com o Google. Antes, esse botão podia ser adicionado em qualquer lugar na UX de autenticação de um app, mas com a inclusão no Gerenciador de credenciais, a opção antiga foi descontinuada.
// 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+")
}
)