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

A função "Restaurar credenciais" do Credential Manager funciona em dispositivos com Android 9 e versões mais recentes, a versão principal 24220000 ou mais recente do Google Play Services (GMS) e a 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, seu 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 nenhuma mudança adicional 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.6.0-rc01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-rc01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-rc01"
}

A restauração 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 "Restaurar credenciais" funciona independente de allowBackup estar definido em manifest.

Visão geral

1. Criar uma chave de restauração: para criar uma chave de restauração, siga estas etapas:
   1. Instanciar o Gerenciador de credenciais: 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 Gerenciador de credenciais 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 para fazer login do usuário.
3. Excluir uma chave de restauração.

Criar uma chave de restauração

Crie a chave de restauração depois que o usuário se autenticar no app, imediatamente após o login ou durante uma inicialização subsequente do app, se ele já estiver conectado.

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 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 objeto CreateRestoreCredentialRequest e chamando o método createCredential() com o objeto CredentialManager.

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
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 estará 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 restaurar 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

O Gerenciador de credenciais 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.
• 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 "Restaurar credenciais" para fazer login do usuário silenciosamente 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.

Você pode buscar a chave de restauração nos seguintes cenários:

• Recomendado: imediatamente após a restauração dos dados do app. Use BackupAgent para configurar o backup do app e concluir a funcionalidade getCredential no callback onRestore para garantir que as credenciais do app sejam restauradas imediatamente após a restauração dos dados do app. Isso evita possíveis atrasos quando os usuários abrem o novo dispositivo pela primeira vez e permite que eles interajam sem esperar que abram seu app.
• No primeiro lançamento do app no dispositivo.

Para enviar notificações a um usuário antes que ele abra o app pela primeira vez em um novo dispositivo, busque a chave de restauração no callback onRestore do BackupAgent. Isso é especialmente relevante para apps de mensagens ou comunicação.

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

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

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

As APIs do Gerenciador de credenciais retornam uma resposta do tipo GetCredentialResponse. Essa resposta 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 conhece 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 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 recuperaçã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)

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)