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. 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 para 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 começar a implementação, considere os pontos a seguir.
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 a necessidade de fazer 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 compatíveis com o Wear OS 5 ou versões mais recentes, o sistema detecta se o usuário está usando o dispositivo no pulso. Se o usuário desativar a detecção de pulso e tirar o dispositivo do pulso, o sistema vai manter o dispositivo desbloqueado por mais tempo do que faria normalmente.
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 ao usuário para fazer login em uma
conta no app antes de mostrar 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 que os usuários façam login em aplicativos 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 necessárias para que os desenvolvedores implementem uma solução do Credential Manager com os mecanismos de autenticação padrão que ele hospeda, que são:
- Chaves de acesso
- Senhas
- Identidades federadas (como Fazer login com o Google)
Este guia também fornece instruções sobre como migrar os outros métodos de autenticação aceitáveis do Wear OS (compartilhamento de token da camada de dados e OAuth) como backups para o Credential Manager, além de instruções especiais para lidar com a transição do botão independente de login do Google, agora descontinuado, para a versão incorporada do Credential Manager.
Chaves de acesso no Wear OS
Recomendamos que os desenvolvedores implementem chaves de acesso nas implementações do Credential Manager do Wear OS. As chaves de acesso são o novo padrão do setor para autenticação de usuários finais e oferecem vários benefícios significativos 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 se registrar de novo.
As chaves de acesso são mais seguras
- Os desenvolvedores salvam apenas uma chave pública no servidor, em vez de uma senha. Isso significa que há muito menos valor para um invasor invadir servidores e muito menos limpeza a ser feita em caso de violação.
- As chaves de acesso oferecem proteção resistente a phishing. As chaves de acesso funcionam apenas nos 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 seguintes linhas ao arquivo build.gradle do seu app ou módulo, usando a versão estável mais recente da referência versões do
androidx.credentials.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 direções para dispositivos móveis para começar e implementar o suporte a chaves de acesso e senhas.
As etapas para adicionar suporte ao recurso Fazer login com o Google no Credential Manager são voltadas para o desenvolvimento de dispositivos móveis, mas são as mesmas no Wear OS. Consulte a seção Transição do login legado com o Google para conferir considerações especiais sobre esse caso.
Como não é possível criar credenciais 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á dois outros métodos de autenticação aceitáveis para apps Wear OS: OAuth 2.0 (qualquer variante) e compartilhamento da camada de dados do 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 Credential Manager como substitutos caso os usuários dispensem a tela do Credential Manager.
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()
}
}
Sua 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 token da camada de dados
O app complementar do smartphone pode transferir dados de autenticação com segurança para o app 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, como mostrado neste exemplo:
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 Wear OS, conforme mostrado neste exemplo:
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), 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 fazer uma solicitação de autenticação do seu 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 a falha da autorização, o servidor OAuth 2.0 redireciona para o 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 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. Depois, 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 neste exemplo:
// 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.
Transição do recurso legado Fazer login com o Google
O Credential Manager tem um ponto de integração dedicado para um botão "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 dele 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+")
}
)