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.

Compatibilidade de versões

O recurso "Restaurar credenciais" do Gerenciador de credenciais funciona em dispositivos com o Android 9 e versões mais recentes, o Google Play Services (GMS) Core versão 24220000 ou mais recente e a biblioteca androidx.credentials versão 1.5.0 ou mais recente.

Pré-requisitos

Configure um servidor de 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 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"
}

O recurso "Restaurar credenciais" está disponível na versão 1.5.0 e mais recentes da biblioteca androidx.credentials. No entanto, recomendamos usar as versões estáveis mais recentes das dependências sempre que possível.

Visão geral

  1. Criar uma chave de restauração: para criar uma chave de restauração, siga estas etapas:
    1. Instanciar o Credential Manager: crie um CredentialManager objeto.
    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 no 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 seu app.
    4. Processar a resposta de criação de credenciais: envie as credenciais do app cliente para o servidor de apps para processamento e processe todas as exceções.
  2. 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 no servidor de apps.
    2. Receber a chave de restauração: solicite a chave de restauração do Gerenciador de credenciais quando o usuário configurar um novo dispositivo. Isso permite que o usuário faça login sem outras informações.
    3. Processar a resposta de recuperação de credenciais: envie a chave de restauração do app cliente para o servidor de apps para fazer 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 do 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 da Activity principal).
  • Quando o usuário estiver fazendo login ou concluindo um novo fluxo de registro de conta.

Para otimizar a performance 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 credenciais no armazenamento local, como has_synced_restore_credential, para acompanhar 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 de apps 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 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 CreateRestoreCredentialRequest objeto e chamando o createCredential() método com o CredentialManager objeto.

// 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 precisa ser armazenada em backup na nuvem. Por padrão, essa flag é true. Esse campo tem estes valores:

      • true: (recomendado) esse valor ativa 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 ativados, como um bloqueio de tela.
      • false: esse valor salva a chave localmente e não na nuvem. A chave não estará disponível no novo dispositivo se o usuário escolher restaurar da nuvem.

Processar a resposta de criação de credenciais

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

Envie a chave pública do app para o servidor de parte confiável. Essa chave pública é semelhante à chave pública gerada ao criar 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 the orientações para chaves de acesso.

Durante o processo de criação de chaves 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 a E2eeUnavailableException explicitamente chamando createCredential com isCloudBackupEnabled definido como true. Se E2eeUnavailableException for gerada, 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 recurso "Restaurar credenciais" para fazer login do usuário de forma silenciosa 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:

  • 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 onRestore método, 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 que ele abra o app pela primeira vez no novo dispositivo, o que é particularmente relevante para apps de mensagens ou comunicações.
// 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.

Processar a resposta de login

Envie a chave pública do app para o servidor de parte confiável, que pode ser usada para fazer login do usuário. No lado do servidor, essa ação é semelhante ao 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 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 reconhece a atividade do usuário. Portanto, 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 solicitado a fazer login novamente.

A desinstalação de um app é interpretada como uma intenção de excluir a chave de restauração correspondente desse 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)