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

Esta página descreve 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

O Restaurador de Credenciais do Credential Manager funciona em dispositivos com Android 9 (nível 28 da API) ou mais recente, versão 24220000 ou mais recente do núcleo do Google Play Services (GMS) e versão 1.5.0 ou mais recente da biblioteca androidx.credentials.

Pré-requisitos

Configure um servidor de terceira parte confiável semelhante ao servidor de 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 restaurar chaves.

Observação: embora a implementação do lado do servidor seja a mesma para chaves de acesso e de recuperação, o app do lado do cliente pode oferecer suporte a chaves de recuperação sem oferecer suporte a chaves de acesso. Como as chaves de restauração funcionam de forma independente do método de autenticação no seu app (por exemplo, senhas ou Fazer login com o Google), não é necessário fazer mudanças adicionais nos métodos de autenticação atuais no código do app.

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"
}

O Restaurador de Credenciais 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.

Observação: o recurso Restaurador de Credenciais funciona independente de allowBackup estar definido no manifesto.

Visão geral

1. Criar uma chave de restauração: para criar uma chave de restauração, siga estas etapas:
   1. Instancie 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 seu servidor de apps.
   3. Crie a chave de restauração: crie uma chave de restauração para a conta do usuário se ele estiver conectado ao seu 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 todas as exceções.
2. Fazer login com uma chave de recuperação: para fazer login com uma chave de recuperaçã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 seu servidor de apps.
   2. Receber a chave de restauração: solicite a chave de restauração do Credential Manager quando o usuário configurar um novo dispositivo. Isso permite que o usuário faça login sem precisar inserir 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 e faça login do usuário.
3. 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 novo fluxo de registro de conta.

Para otimizar o desempenho e evitar o trabalho 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.

Observação: uma chave de restauração está vinculada ao nome de pacote exclusivo de um aplicativo. Se o app principal e os subapps da sua organização tiverem nomes de pacotes diferentes, crie uma chave de restauração separada para cada um.

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 propriedades de configuração adicionais. Para mais informações sobre a implementação do lado do servidor, consulte Orientação 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 encapsulando 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 os seguintes campos:

  • requestJson: as opções de criação de credenciais enviadas pelo servidor de apps no formato da API Web Authentication para PublicKeyCredentialCreationOptionsJSON.

  • isCloudBackupEnabled: campo Boolean para determinar se a chave de restauração deve ser armazenada em backup na nuvem. Por padrão, essa flag é true. Esse campo tem os seguintes valores:

    • true: (recomendado) esse valor permite o backup das chaves de restauração na nuvem se o usuário tiver o Backup do Google e a criptografia de ponta a ponta ativados, como um bloqueio de tela.
    • false: esse valor salva a chave localmente, e não na nuvem. A chave não fica disponível no novo dispositivo se o usuário escolher restaurar da nuvem.
  Atenção: é recomendável definir isCloudBackupEnabled como true. Se o backup na nuvem estiver desativado e o usuário fizer a restauração de um backup na nuvem, a chamada para recuperar a chave de restauração vai falhar. Os usuários que restauram seu 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 de credencial de chave pública no formato JSON.

Envie a chave pública do seu 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 recuperaçã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 o Restaurador de Credenciais seja criado em todos os casos, processe o 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 o Restaurador de Credenciais para fazer login silenciosamente do 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 esta 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:

• No primeiro lançamento 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 de apps 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 conclua a funcionalidade getCredential no callback onRestoreFinished. Não use o método onRestore, porque ele só é chamado 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 de ele abrir o app pela primeira vez no novo dispositivo, o que é particularmente relevante para apps de mensagens ou comunicações.

Se você criar um novo BackupAgent e 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.

Importante: as notificações não são restauradas automaticamente depois que as credenciais de restauração são recuperadas. Se você usa o Firebase para processar notificações, é necessário buscar e enviar o token do Firebase Cloud Messaging (FCM) para o back-end para retomar as mensagens e notificações em segundo plano.

// 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 nesta resposta é explicitamente do tipo RestoreCredential, que contém a chave pública.

Processar a resposta de login

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 a fazer login usando 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 recuperaçã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.

Observação: embora as chaves de restauração e as chaves de acesso usem a mesma implementação de servidor subjacente, diferencie-as ao salvar no banco de dados do servidor do app. Essa distinção é crucial quando existe uma página de gerenciamento de chaves de acesso, porque os usuários podem gerenciar as chaves de acesso criadas por eles diretamente, enquanto as chaves de recuperação são gerenciadas pelo sistema e ficam ocultas na página de gerenciamento de chaves de acesso.

Excluir a chave de restauração

O Credential Manager não tem estado e não sabe 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 de novo.

Observação: o encerramento da sessão de um usuário também pode acontecer remotamente, por exemplo, quando ele muda a senha na Web ou quando a sessão é encerrada remotamente pelo servidor. Se o app detectar uma invalidação de sessão do lado do servidor, exclua a chave de restauração no dispositivo. Um exemplo disso é o servidor retornar um erro HTTP 401 Unauthorized.

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 maneira 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)