Autenticar usuários com o recurso "Fazer login com o Google"

O recurso Fazer login com o Google ajuda a integrar rapidamente a autenticação do usuário ao seu app Android. Os usuários podem usar a Conta do Google para fazer login no app, dar consentimento e compartilhar com segurança as informações do perfil com o app. A biblioteca Credential Manager Jetpack do Android facilita essa integração, oferecendo uma experiência consistente em todos os dispositivos Android usando uma única API.

Este documento orienta você sobre como implementar o recurso Fazer login com o Google em apps Android, como configurar a interface do botão Fazer login com o Google e como configurar experiências de cadastro e login com um toque otimizadas para apps. Para uma migração suave do dispositivo, o recurso "Fazer login com o Google" oferece suporte ao login automático, e a natureza multiplataforma em dispositivos Android, iOS e na Web ajuda a fornecer acesso de login para seu app em qualquer dispositivo.

Para configurar o recurso "Fazer login com o Google", siga estas duas etapas principais:

Configure o recurso "Fazer login com o Google" como uma opção para a interface da página inferior do Gerenciador de credenciais. Isso pode ser configurado para solicitar automaticamente que o usuário faça login. Se você implementou chaves de acesso ou senhas, é possível solicitar todos os tipos de credencial relevantes simultaneamente para que o usuário não precise se lembrar da opção que usou anteriormente para fazer login.

Página inferior do Gerenciador de credenciais
Figura 1. A interface de usuário de seleção de credenciais da página inferior do Gerenciador de credenciais

Adicione o botão "Fazer login com o Google" à interface do app. O botão "Fazer login com o Google" oferece uma maneira simplificada de os usuários usarem as próprias Contas do Google para se inscreverem ou fazerem login em apps Android. Os usuários clicarão no botão "Fazer login com o Google" se dispensarem a interface da página inferior ou se quiserem usar explicitamente a Conta do Google para se inscrever e fazer login. Para os desenvolvedores, isso significa uma integração mais fácil do usuário e menos atrito durante a inscrição.

Animação mostrando o fluxo de "Fazer login com o Google"
Figura 2. A interface do botão "Fazer login com o Google" do Gerenciador de credenciais

Este documento explica como integrar o botão "Fazer login com o Google" e a caixa de diálogo da página inferior à API Credential Manager usando a biblioteca auxiliar do ID do Google.

Configurar seu projeto do Console de APIs do Google

  1. Abra o projeto no Console de APIs ou crie um se ainda não tiver um.
  2. Na página de consentimento do OAuth, verifique se todas as informações estão completas e corretas.
    1. Confira se o app tem um nome, um logotipo e uma página inicial corretamente atribuídos. Esses valores serão apresentados aos usuários na tela de consentimento do recurso "Fazer login com o Google" na inscrição e na tela Apps e serviços de terceiros.
    2. Verifique se você especificou os URLs da Política de Privacidade e dos Termos de Serviço do seu app.
  3. Na página "Credenciais", crie um ID do cliente Android para o app, se ainda não tiver um. Você precisa especificar o nome do pacote do app e a assinatura SHA-1.
    1. Acesse a página Credenciais.
    2. Clique em Criar credenciais > ID do cliente OAuth.
    3. Selecione o tipo de aplicativo Android.
  4. Na página "Credenciais", crie um novo ID do cliente para "Aplicativo da Web", se ainda não tiver feito isso. Por enquanto, ignore os campos "Origens JavaScript autorizadas" e "URIs de redirecionamento autorizados". Esse ID do cliente será usado para identificar seu servidor de back-end quando ele se comunicar com os serviços de autenticação do Google.
    1. Acesse a página Credenciais.
    2. Clique em Criar credenciais > ID do cliente OAuth.
    3. Selecione o tipo de aplicativo da Web.

Declarar dependências

No arquivo build.gradle do módulo, declare as dependências usando a versão mais recente do Gerenciador de credenciais:

dependencies {
  // ... other dependencies

  implementation "androidx.credentials:credentials:<latest version>"
  implementation "androidx.credentials:credentials-play-services-auth:<latest version>"
  implementation "com.google.android.libraries.identity.googleid:googleid:<latest version>"
}

Instanciar uma solicitação de login do Google

Para iniciar a implementação, instancie uma solicitação de login do Google. Use GetGoogleIdOption para extrair o token de ID do Google de um usuário.

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(WEB_CLIENT_ID)
  .setAutoSelectEnabled(true)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Primeiro, verifique se o usuário tem contas que já foram usadas para fazer login no seu app chamando a API com o parâmetro setFilterByAuthorizedAccounts definido como true. Os usuários podem escolher entre as contas disponíveis para fazer login.

Se nenhuma Conta do Google autorizada estiver disponível, o usuário vai receber uma solicitação para fazer o registro com qualquer uma das contas disponíveis. Para fazer isso, solicite ao usuário chamando a API novamente e definindo setFilterByAuthorizedAccounts como false. Saiba mais sobre a inscrição.

Ativar o login automático para usuários recorrentes (recomendado)

Os desenvolvedores precisam ativar o login automático para os usuários que se registrarem com a conta única. Isso proporciona uma experiência perfeita em todos os dispositivos, especialmente durante a migração, quando os usuários podem recuperar rapidamente o acesso à conta sem precisar digitar novamente as credenciais. Para seus usuários, isso elimina a fricção desnecessária quando eles já fizeram login anteriormente.

Para ativar o login automático, use setAutoSelectEnabled(true). O login automático só é possível quando os seguintes critérios são atendidos:

  • Há uma única credencial que corresponde à solicitação, que pode ser uma Conta do Google ou uma senha, e essa credencial corresponde à conta padrão no dispositivo Android.
  • O usuário não saiu explicitamente.
  • O usuário não desativou o login automático nas configurações da Conta do Google.
val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(WEB_CLIENT_ID)
  .setAutoSelectEnabled(true)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Não se esqueça de processar o logout corretamente ao implementar o login automático, para que os usuários possam sempre escolher a conta correta depois de sair explicitamente do app.

Definir um valor de uso único para melhorar a segurança

Para melhorar a segurança de login e evitar ataques de repetição, adicione setNonce para incluir um valor de uso único em cada solicitação. Saiba mais sobre como gerar um valor de uso único.

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(WEB_CLIENT_ID)
  .setAutoSelectEnabled(true)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Criar o fluxo de "Fazer login com o Google"

As etapas para configurar um fluxo do recurso Fazer login com o Google são estas:

  1. Instancie uma GetCredentialRequest e adicione a googleIdOption criada anteriormente usando addCredentialOption() para extrair as credenciais.
  2. Transmita essa solicitação para a chamada getCredential() (Kotlin) ou getCredentialAsync() (Java) para extrair as credenciais disponíveis do usuário.
  3. Quando a API for bem-sucedida, extraia a CustomCredential que contém o resultado dos dados GoogleIdTokenCredential.
  4. O tipo de CustomCredential precisa ser igual ao valor de GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL. Converta o objeto em uma GoogleIdTokenCredential usando o método GoogleIdTokenCredential.createFrom.

  5. Se a conversão for bem-sucedida, extraia e valide o ID da GoogleIdTokenCredential, valide e autentique a credencial no seu servidor.

  6. Se a conversão falhar com uma GoogleIdTokenParsingException, talvez seja necessário atualizar a versão da biblioteca do recurso Fazer login com o Google.

  7. Capture todos os tipos de credenciais personalizadas não reconhecidos.

val request: GetCredentialRequest = Builder()
  .addCredentialOption(googleIdOption)
  .build()

coroutineScope.launch {
  try {
    val result = credentialManager.getCredential(
      request = request,
      context = activityContext,
    )
    handleSignIn(result)
  } catch (e: GetCredentialException) {
    handleFailure(e)
  }
}

fun handleSignIn(result: GetCredentialResponse) {
  // Handle the successfully returned credential.
  val credential = result.credential

  when (credential) {

    // Passkey credential
    is PublicKeyCredential -> {
      // Share responseJson such as a GetCredentialResponse on your server to
      // validate and authenticate
      responseJson = credential.authenticationResponseJson
    }

    // Password credential
    is PasswordCredential -> {
      // Send ID and password to your server to validate and authenticate.
      val username = credential.id
      val password = credential.password
    }

    // GoogleIdToken credential
    is CustomCredential -> {
      if (credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL) {
        try {
          // Use googleIdTokenCredential and extract the ID to validate and
          // authenticate on your server.
          val googleIdTokenCredential = GoogleIdTokenCredential
            .createFrom(credential.data)
          // You can use the members of googleIdTokenCredential directly for UX
          // purposes, but don't use them to store or control access to user
          // data. For that you first need to validate the token:
          // pass googleIdTokenCredential.getIdToken() to the backend server.
          GoogleIdTokenVerifier verifier = ... // see validation instructions
          GoogleIdToken idToken = verifier.verify(idTokenString);
          // To get a stable account identifier (e.g. for storing user data),
          // use the subject ID:
          idToken.getPayload().getSubject()
        } catch (e: GoogleIdTokenParsingException) {
          Log.e(TAG, "Received an invalid google id token response", e)
        }
      } else {
        // Catch any unrecognized custom credential type here.
        Log.e(TAG, "Unexpected type of credential")
      }
    }

    else -> {
      // Catch any unrecognized credential type here.
      Log.e(TAG, "Unexpected type of credential")
    }
  }
}

Acionar um fluxo do botão "Fazer login com o Google"

Para acionar o fluxo do botão "Fazer login com o Google", use GetSignInWithGoogleOption em vez de GetGoogleIdOption:

val signInWithGoogleOption: GetSignInWithGoogleOption = GetSignInWithGoogleOption.Builder()
  .setServerClientId(WEB_CLIENT_ID)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Processe o GoogleIdTokenCredential retornado, conforme descrito no exemplo de código abaixo.

fun handleSignIn(result: GetCredentialResponse) {
  // Handle the successfully returned credential.
  val credential = result.credential

  when (credential) {
    is CustomCredential -> {
      if (credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL) {
        try {
          // Use googleIdTokenCredential and extract id to validate and
          // authenticate on your server.
          val googleIdTokenCredential = GoogleIdTokenCredential
            .createFrom(credential.data)
        } catch (e: GoogleIdTokenParsingException) {
          Log.e(TAG, "Received an invalid google id token response", e)
        }
      }
      else -> {
        // Catch any unrecognized credential type here.
        Log.e(TAG, "Unexpected type of credential")
      }
    }

    else -> {
      // Catch any unrecognized credential type here.
      Log.e(TAG, "Unexpected type of credential")
    }
  }
}

Depois de instanciar a solicitação de login do Google, inicie o fluxo de autenticação de maneira semelhante, conforme mencionado na seção Fazer login com o Google.

Ativar o registro de novos usuários (recomendado)

O recurso "Fazer login com o Google" é a maneira mais fácil de criar uma nova conta com seu app ou serviço em apenas alguns toques.

Se nenhuma credencial salva for encontrada (nenhuma Conta do Google retornada por getGoogleIdOption), peça para o usuário se inscrever. Primeiro, verifique se setFilterByAuthorizedAccounts(true) para saber se há contas usadas anteriormente. Se nenhum deles for encontrado, peça ao usuário para se inscrever com a Conta do Google usando setFilterByAuthorizedAccounts(false)

Exemplo:

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(false)
  .setServerClientId(WEB_CLIENT_ID)
  .build()

Depois de instanciar a solicitação de inscrição do Google, inicie o fluxo de autenticação. Se os usuários não quiserem usar o recurso "Fazer login com o Google" para se inscrever, otimizar seu app para preenchimento automático. Depois que o usuário criar uma conta, considere inscrever o usuário nas chaves de acesso como a etapa final da criação da conta.

Processar a saída

Quando um usuário sair do app, chame o método clearCredentialState() da API para limpar o estado atual da credencial do usuário de todos os provedores de credenciais. Isso vai notificar todos os provedores de credenciais de que qualquer sessão de credencial armazenada para o app precisa ser limpa.

Um provedor de credenciais pode ter armazenado uma sessão de credencial ativa e a usado para limitar as opções de login para futuras chamadas de get-credential. Por exemplo, ele pode priorizar a credencial ativa em vez de qualquer outra credencial disponível. Quando o usuário sair explicitamente do app e para receber as opções de login integradas na próxima vez, chame essa API para permitir que o provedor limpe qualquer sessão de credencial armazenada.