O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Implementar a restauração de credenciais com o Gerenciador de credenciais

Nesta página, descrevemos como criar, fazer login e excluir uma chave de restauração.

Habilidades do Android

Ver no GitHub

Restaurar credenciais

Use uma habilidade do Android para implementar fluxos de backup e restauração de credenciais usando o Gerenciador de credenciais.

Para instalar a habilidade na CLI do Android, execute:

android skills add restore-credentials

Compatibilidade de versões

A restauração de credenciais do Gerenciador de credenciais funciona em dispositivos com o Android 9 (nível 28 da API) e versões mais recentes, o Google Play Services (GMS) versão principal 24220000 ou mais recente e a versão 1.5.0 ou mais recente da biblioteca androidx.credentials.

Pré-requisitos

Configure um servidor de parte confiável semelhante ao servidor para chaves de acesso. Se você já tiver um servidor configurado para processar a autenticação com chaves de acesso, use a mesma implementação do lado do servidor para as chaves de restauração.

Dependências

Adicione as seguintes dependências ao arquivo build.gradle do módulo do app:

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha02")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha02"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha02"
}

A Restore Credentials está disponível na versão 1.5.0 e mais recentes da biblioteca androidx.credentials. No entanto, é recomendável usar as versões estáveis mais recentes das dependências sempre que possível.

Visão geral

Criar uma chave de restauração: para criar uma chave de restauração, siga estas etapas:
1. Instanciar o Credential Manager: crie um objeto CredentialManager.
2. Receber opções de criação de credenciais do servidor de apps: envie ao app cliente os detalhes necessários para criar a chave de restauração do servidor de apps.
3. Criar a chave de restauração: crie uma chave de restauração para a conta do usuário se ele estiver conectado ao app.
4. Processar a resposta de criação de credenciais: envie as credenciais do app cliente para o servidor do app para processamento e processe as exceções.
Fazer login com uma chave de restauração: para fazer login com uma chave de restauração, siga estas etapas:
1. Receber opções de recuperação de credenciais do servidor de apps: envie ao app cliente os detalhes necessários para recuperar a chave de restauração do servidor de apps.
2. Receber a chave de restauração: solicite a chave de restauração ao Gerenciador de credenciais quando o usuário configurar um novo dispositivo. Isso permite que o usuário faça login sem precisar de mais informações.
3. Processar a resposta de recuperação de credenciais: envie a chave de restauração do app cliente para o servidor do app para fazer login do usuário.
Excluir uma chave de restauração.

Criar uma chave de restauração

O app precisa abranger todos os casos de login de um usuário para garantir que os usuários ativos tenham uma chave de restauração criada. Crie a chave de restauração nos seguintes cenários:

Se o usuário estiver conectado e uma chave de restauração ainda não tiver sido criada (como no método onCreate para o Activity principal).
Quando o usuário está fazendo login ou concluindo um fluxo de registro de nova conta.

Para otimizar o desempenho e evitar a sobrecarga de criar ou verificar uma credencial de restauração em cada login, defina uma flag boolean ou um carimbo de data/hora de criação de credencial no armazenamento local, como has_synced_restore_credential, para rastrear se a chave já foi criada.

Instanciar o Credential Manager

Use o contexto de atividade do app para instanciar um objeto CredentialManager.

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

Receber opções de criação de credenciais do servidor de apps

Use uma biblioteca compatível com FIDO no servidor do app para enviar ao app cliente as informações necessárias para criar a credencial de restauração, como informações sobre o usuário, o app e outras propriedades de configuração. Para mais informações sobre a implementação do lado do servidor, consulte as orientações do lado do servidor.

Criar a chave de restauração

Depois de analisar as opções de criação de chave pública enviadas pelo servidor, crie uma chave de restauração agrupando essas opções em um objeto CreateRestoreCredentialRequest e chamando o método createCredential() com o objeto CredentialManager.

// createRestoreRequest contains the details sent by the server 
val response = credentialManager.createCredential(context, createRestoreRequest)

Pontos principais sobre o código

O objeto CreateRestoreCredentialRequest contém estes campos:
- requestJson: as opções de criação de credenciais enviadas pelo servidor do app no formato da API Web Authentication para PublicKeyCredentialCreationOptionsJSON.
- isCloudBackupEnabled: campo Boolean para determinar se a chave de restauração precisa ser armazenada em backup na nuvem. Por padrão, essa flag é true. Esse campo tem estes valores:
  - true: (recomendado) esse valor permite o backup de chaves de restauração na nuvem se o usuário tiver o Backup do Google e a criptografia de ponta a ponta, como um bloqueio de tela, ativados.
  - false: esse valor salva a chave localmente, e não na nuvem. A chave não vai estar disponível no novo dispositivo se o usuário optar por restaurar da nuvem.
Cuidado: recomendamos definir isCloudBackupEnabled como true. Se o backup em nuvem estiver desativado e o usuário fizer uma restauração usando um backup em nuvem, a chamada para recuperar a chave de restauração vai falhar. Os usuários que restauram o app com um backup na nuvem não recebem a chave de restauração e não fazem login automaticamente.

Processar a resposta de criação de credenciais

A API Credential Manager retorna uma resposta do tipo CreateRestoreCredentialResponse. Essa resposta contém a resposta de registro da credencial de chave pública no formato JSON.

Envie a chave pública do app para o servidor da parte confiável. Essa chave pública é semelhante à gerada quando você cria uma chave de acesso. O mesmo código que processa a criação de chaves de acesso no servidor também pode processar a criação de chaves de restauração. Para mais informações sobre a implementação do lado do servidor, consulte as orientações para chaves de acesso.

Durante o processo de criação da chave de restauração, processe estas exceções:

CreateRestoreCredentialDomException: essa exceção ocorre se requestJson for inválido e não seguir o formato WebAuthn para PublicKeyCredentialCreationOptionsJSON.
E2eeUnavailableException: essa exceção ocorre se isCloudBackupEnabled for true, mas o dispositivo do usuário não tiver backup de dados ou criptografia de ponta a ponta, como um bloqueio de tela.
Para garantir que as credenciais de restauração sejam criadas em todos os casos, é necessário processar E2eeUnavailableException explicitamente chamando createCredential com isCloudBackupEnabled definido como true. Se E2eeUnavailableException for gerado, capture e chame createCredential novamente com isCloudBackupEnabled definido como false.
IllegalArgumentException: essa exceção ocorre se createRestoreRequest estiver vazio ou não for um JSON válido ou se não tiver um user.id válido que esteja em conformidade com as especificações do WebAuthn.

Fazer login com uma chave de restauração

Use as credenciais de restauração para fazer login silenciosamente no usuário durante o processo de configuração do dispositivo.

Receber opções de recuperação de credenciais do servidor de apps

Envie ao app cliente as opções necessárias para receber a chave de restauração do servidor. Para orientações semelhantes sobre chaves de acesso para essa etapa, consulte Fazer login com uma chave de acesso. Para mais informações sobre a implementação do lado do servidor, consulte o guia de autenticação do lado do servidor.

Receber a chave de restauração

Para receber a chave de restauração no novo dispositivo, chame o método getCredential() no objeto CredentialManager.

Recomendamos buscar a chave de restauração nos dois cenários a seguir:

Na primeira inicialização do app no dispositivo. A restauração de credenciais nesse cenário é independente da restauração dos dados do app.
Se o backup e a restauração de dados do app estiverem ativados, receba a chave de restauração imediatamente após a restauração dos dados do app. Use BackupAgent para configurar o backup do app e garantir que você conclua a funcionalidade getCredential no callback onRestoreFinished. Não use o método onRestore, porque ele é chamado apenas para backups de chave-valor, enquanto onRestoreFinished é chamado de forma confiável para qualquer tipo de restauração de backup. Isso evita possíveis atrasos quando os usuários abrem o novo dispositivo pela primeira vez e permite que eles interajam com o app sem esperar que ele seja aberto. Por exemplo, isso permite que o app envie notificações ao usuário antes que ele o abra pela primeira vez no novo dispositivo, o que é particularmente relevante para apps de mensagens ou comunicações.

Se você criar um novo BackupAgent e já tiver ativado o backup com allowBackup="true", defina o valor booleano android:fullBackupOnly="true" no manifesto do app. Isso garante que o comportamento de backup e restauração do app seja mantido.

// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

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

val response = credentialManager.getCredential(context, getRequest)

// Type-check and extract the restore credential
val credential = response.credential as RestoreCredential

As APIs do Gerenciador de credenciais retornam uma resposta do tipo GetCredentialResponse. A credencial contida nessa resposta é explicitamente do tipo RestoreCredential, que contém a chave pública.

Envie a chave pública do app para o servidor da parte confiável, que pode ser usada para fazer login do usuário. No lado do servidor, essa ação é semelhante ao login com uma chave de acesso. O mesmo código que processa o login com chaves de acesso no servidor também pode processar logins com chaves de restauração. Para mais informações sobre a implementação do lado do servidor para chaves de acesso, consulte Fazer login com uma chave de acesso.

Excluir a chave de restauração

O Credential Manager não tem estado e não tem conhecimento da atividade do usuário. Por isso, ele não exclui automaticamente as chaves de restauração após o uso. Para excluir uma chave de restauração, chame o método clearCredentialState. Por segurança, exclua a chave sempre que um usuário sair. Isso garante que, na próxima vez que o usuário abrir o app no mesmo dispositivo, ele será desconectado e precisará fazer login novamente.

A desinstalação de um app é interpretada como uma intenção de excluir a chave de restauração correspondente do dispositivo, semelhante à intenção do usuário ao sair.

As chaves de restauração são removidas apenas nas seguintes situações:

Ações no nível do sistema: os usuários desinstalam o app ou limpam os dados dele.
Chamadas no nível do app: exclua a chave de forma programática chamando clearCredentialState() ao processar a saída do usuário no código do app.

Quando o usuário sair do app, chame o método clearCredentialState() no objeto CredentialManager.

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

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)