Autenticação em wearables: Gerenciador de credenciais

Os apps para Wear OS podem ser executados de forma independente, sem um app complementar. Isso significa que um app para Wear OS precisa 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 sobre o método de autenticação recomendado para apps para Wear OS, o Credential Manager.

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, forneç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 ficar 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 o normal.

Se o app exigir um nível mais alto de segurança, como ao mostrar dados potencialmente sensíveis ou particulares, verifique primeiro se a detecção de pulso está ativada:

fun isWristDetectionAutoLockingEnabled(context: Context): Boolean {
    // Use the keyguard manager to check for the presence of a lock mechanism
    val keyguardManager = context.getSystemService<KeyguardManager>()
    val isSecured = keyguardManager?.isDeviceSecure == true

    // Use OEM-specific system settings to verify that on-body autolock is enabled.
    val isWristDetectionOn = android.provider.Settings.Global.getInt(
        context.contentResolver, PIXEL_WRIST_AUTOLOCK_SETTING_STATE,
        0
    ) == 1

    return isSecured && isWristDetectionOn
}

Se o valor de retorno desse método for false, peça para o usuário fazer login em uma conta no seu app antes de mostrar conteúdo específico para ele.

Credential Manager

O Credential Manager é a API recomendada para autenticação no Wear OS. Ele oferece um ambiente mais seguro para os usuários fazerem 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 que os desenvolvedores precisam para implementar 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 o recurso 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 tokens da camada de dados e OAuth) como backups para o Gerenciador de credenciais, além de instruções especiais para lidar com a transição do botão de login do Google independente, que foi descontinuado, para a versão incorporada do Gerenciador de credenciais.

Limitações e diferenças do Wear OS

Os desenvolvedores precisam estar cientes das seguintes limitações e diferenças no Wear OS:

  • O Credential Manager está disponível no Wear OS 3 e versões mais recentes.
  • Não é possível criar credenciais no Wear OS
  • Não há suporte para restaurar credenciais nem para fluxos de login híbridos.
  • Somente provedores de credenciais com integrações do Wear OS podem ser reutilizados em dispositivos móveis.

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 trazem vários benefícios significativos para os usuários.

As chaves de acesso são mais fáceis de usar

  • Os usuários podem selecionar uma conta para fazer login. Não é necessário digitar um nome de usuário.
  • Os usuários podem se autenticar usando o bloqueio de tela do dispositivo.
  • Depois que uma chave de acesso é criada e registrada, o usuário pode mudar de 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, o que significa que há muito menos valor para um usuário de má-fé invadir servidores e muito menos limpeza a ser feita em caso de violação.
  • As chaves de acesso oferecem proteção contra phishing. As chaves de acesso funcionam apenas nos sites e apps registrados. Um usuário não pode ser enganado para se autenticar 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.

Configuração

  1. Defina o nível desejado da API como 35 no arquivo build.gradle do módulo do aplicativo:

    android {
        defaultConfig {
            targetSdk(35)
        }
    }
    
  2. Adicione as seguintes linhas ao arquivo build.gradle do app ou módulo, usando a versão estável mais recente da referência de versões do androidx.credentials.

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

Métodos de autenticação integrados

Como o Gerenciador de credenciais é 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 e implementar o suporte a chaves de acesso e senhas.

As etapas para adicionar o suporte ao recurso Fazer login com o Google ao Gerenciador de credenciais são voltadas para o desenvolvimento para dispositivos móveis, mas são as mesmas no Wear OS.

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 para Wear OS: OAuth 2.0 (qualquer variante) e compartilhamento de camada de dados de token de autenticação para dispositivos móveis. 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 lidar com a ação do usuário de dispensar a tela do Credential Manager, capture uma GetCredentialCancellationException como parte da lógica GetCredential e navegue até sua própria interface de autenticação personalizada.

try {
    val getCredentialResponse: GetCredentialResponse =
        credentialManager.getCredential(activity, createGetCredentialRequest())
    return authenticate(getCredentialResponse.credential)
} catch (_: GetCredentialCancellationException) {
    navigateToSecondaryAuthentication()
}

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 ao 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, como mostrado neste exemplo:

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

Detecte eventos de mudança de dados no app para Wear OS, conforme mostrado neste exemplo:

class AuthDataListenerService : WearableListenerService() {
    override fun onDataChanged(dataEvents: DataEventBuffer) {
        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.
                    handleSignInSequence(token)
                }
            }
        }
    }

    /** placeholder sign in handler. */
    fun handleSignInSequence(token: String?) {}
}

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 Proof Key for Code Exchange (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 solicitar a autenticação no 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 oauthRequest = OAuthRequest.Builder(context)
    .setAuthProviderUrl(uri)
    .setCodeChallenge(codeChallenge)
    .setClientId(CLIENT_ID)
    .build()

Depois de criar a solicitação de autenticação, faça o envio dela ao app complementar usando o método sendAuthorizationRequest():

RemoteAuthClient.create(context).sendAuthorizationRequest(
    request = oauthRequest,
    executor = { command -> command?.run() },
    clientCallback = object : RemoteAuthClient.Callback() {
        override fun onAuthorizationResponse(
            request: OAuthRequest,
            response: OAuthResponse
        ) {
            // Extract the token from the response, store it, and use it in requests.
            continuation.resume(parseCodeFromResponse(response))
        }
        override fun onAuthorizationError(request: OAuthRequest, errorCode: Int) {
            // Handle Errors
            continuation.resume(Result.failure(IOException("Authorization failed")))
        }
    }
)

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. 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.
private fun verifyDeviceAuthGrant(verificationUri: String) {
    RemoteActivityHelper(context).startRemoteActivity(
        Intent(Intent.ACTION_VIEW).apply {
            addCategory(Intent.CATEGORY_BROWSABLE)
            data = Uri.parse(verificationUri)
        },
        null
    )
}

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.