Pacote de segurança

Este guia descreve uma coleção de recursos que retornam indicadores de confiança adicionais sobre uma Conta do Google. Esses indicadores ajudam seu sistema de gerenciamento da conta a tomar decisões baseadas em risco durante a inscrição, a criação da conta e, mais tarde, sobre usuários recorrentes.

Sessões

Uma solicitação de autenticação feita por um aplicativo retorna um token de ID. Por exemplo, quando um botão "Fazer login com o Google" é pressionado, um token de ID é retornado ao aplicativo cliente ou servidor Android, iOS ou da Web que mostra o botão.

A autenticação para fazer login em uma Conta do Google é um evento distinto e separado. As declarações retornadas no token de ID representam esse evento. Por exemplo, o tempo e os métodos de autenticação usados para fazer login na Conta do Google.

Há dois momentos de autenticação e duas sessões de usuário:

• Sessão do usuário <-> Google : estabelecida quando um usuário faz login na Conta do Google. O Google gerencia o ciclo de vida e a segurança dessa sessão. As declarações auth_time e amr oferecem insights sobre essa sessão.
• Sessão do usuário <-> aplicativo : estabelecida depois que o usuário faz login no aplicativo, geralmente iniciada usando o recurso "Fazer login com o Google". O aplicativo gerencia essa sessão usando as declarações para melhorar as decisões de gerenciamento de sessão e conta.

Os usuários costumam interagir com os Serviços do Google em vários dispositivos, como smartphones, computadores desktop, telas inteligentes ou TVs. Fazer login em cada plataforma ou dispositivo estabelece uma sessão distinta. Para logins na Web, uma sessão é estabelecida entre o navegador específico e o Google. Os modos de navegação privada e anônima criam sessões separadas e isoladas. Por isso, uma única Conta do Google pode ter várias sessões distintas ativas simultaneamente em vários navegadores e dispositivos. Para mais detalhes, consulte Ver dispositivos com acesso à conta.

Status da Conta do Google

Os eventos típicos do ciclo de vida de uma Conta do Google são:

• uma pessoa escolhe Criar uma Conta do Google e, em seguida,
• o Google pode desativar a conta ou um usuário pode reativá-la após seguir as instruções em Como recuperar sua Conta do Google ou serviço do Gmail, e
• uma pessoa pode decidir Excluir sua Conta do Google ou, devido à Política de Contas do Google Inativas, a conta pode ser excluída.

Os recursos do pacote de segurança descritos neste guia se aplicam a contas ativas ou desativadas, mas não a eventos de criação ou exclusão de Contas do Google.

O Google pode desativar uma conta a qualquer momento. Para alguns dos motivos, consulte Sua conta foi desativada. Quando isso ocorre, todas as sessões ativas do Google são encerradas e um evento RISC é enviado pelo serviço de proteção entre contas do Google. As contas desativadas são bloqueadas para usar o recurso "Fazer login com o Google", o que significa que um token de ID nunca é emitido e, portanto, não pode ser usado para monitorar contas de usuário desativadas.

Embora o recebimento de eventos de proteção entre contas (RISC) seja opcional, esses eventos servem como indicadores importantes para gerenciar a sessão entre o usuário e o app e se. As instruções sobre como implementar o RISC e responder a eventos são descritas em Proteger contas de usuário com a proteção entre contas.

Configuração

Para receber declarações adicionais, seu app precisa ser publicado, verificado e ter os recursos do pacote de segurança ativados. Comece confirmando se o app foi publicado e verificado:

1. Abrir o Google Auth Platform
2. Selecione ou crie o projeto do seu app
3. Clique em Público-alvo e confirme se o status de publicação é Em produção
4. Clique em Central de verificação e confirme se o status da verificação é Verificado

Em seguida, ative declarações adicionais:

1. Clique em Configurações no menu
2. Em Configurações avançadas , selecione:
   • Declarações de tempo de sessão para ativar auth_time
   • Declarações de força da autenticação para ativar amr

Para saber mais, acesse a Central de Ajuda de verificação de apps OAuth.

Recursos compatíveis

Esta seção descreve os recursos individuais que compõem o pacote de segurança.

Referências de métodos de autenticação

As referências de métodos de autenticação (amr) são uma declaração do OpenID Connect quedescreve os métodos usados durante o último evento de autenticação entre o usuário e o Google.

Dos possíveis IANA.AMR valores, o Google aceita os seguintes valores que indicam que:

• hwk uma chave de segurança de hardware foi usada
• mfa a autenticação multifator foi concluída
• pwd uma senha foi usada
• swk uma chave de software, como uma chave de acesso, foi usada
• sms uma mensagem SMS foi usada para verificação
• tel uma chamada telefônica foi usada para verificação

Um ou mais desses valores são retornados como uma matriz JSON de strings na declaração amr do token de ID.

A declaração amr é incluída no token de ID somente quando há informações disponíveis sobre o método de autenticação usado. Ela pode não estar presente mesmo quando solicitada.

Os proprietários de Contas do Google podem exigir a verificação em duas etapas e quais métodos de MFA usar. Quando a Proteção Avançada está ativada em uma Conta do Google, um método de verificação em duas etapas forte, como chaves de segurança Titan (hwk) ou chave de acesso (swk), é necessário. Em ambas as situações, o valor mfa está presente quando mais de um fator é usado durante o login na Conta do Google.

A presença de mfa confirma que o evento de autenticação atendeu aos requisitos do Google para autenticação multifator. Por exemplo, uma autenticação da Conta do Google com uma senha (pwd) e uma chave de acesso (swk) resulta nesta declaração "amr": ["mfa", "pwd", "swk"].

Estes recursos têm mais informações sobre segurança da conta e autenticação do usuário: Tenha a segurança de conta mais forte do Google com o Programa Proteção Avançada, Faça login com uma chave de acesso em vez de uma senha, e Use uma chave de segurança na verificação em duas etapas.

Os administradores do Workspace controlam a política de autenticação para contas gerenciadas do Workspace e podem exigir a MFA ou o uso de chaves de segurança. Consulte Visão geral do gerenciamento de identidade do Google e Requisito de autenticação multifator para Google Cloud proteções e controles de login para mais informações.

Tempo de autenticação

A declaração auth_time é uma parte padrão do protocolo OpenID Connect que fornece informações sobre quando o usuário final foi autenticado mais recentemente com o Google. É um número JSON que representa o número de segundos decorridos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC) e é o horário em que o usuário foi autenticado pela última vez. Pense nisso como um carimbo de data/hora que indica o último evento de login do usuário na Conta do Google no dispositivo ou navegador atual. Essa declaração está incluída no token de ID, que é um token da Web JSON (JWT) que contém informações verificadas sobre a autenticação e o usuário.

A declaração auth_time é valiosa para seu aplicativo porque permite determinar há quanto tempo um usuário fez login ativamente em uma Conta do Google no dispositivo ou navegador que está usando. Isso pode ser particularmente importante para fins de segurança, como:

• Tomar uma decisão informada sobre se o app deve emitir um desafio de autenticação adicional antes de realizar ações sensíveis do usuário, como excluir a conta, mudar os métodos de contato da conta ou fazer um pagamento. O Google não aceita solicitações de reautenticação da Conta do Google.

• Usar a atualização e a estabilidade da sessão da Conta do Google do usuário como um indicador de confiança. De modo geral, um valor auth_time recente é uma indicação de atualização, enquanto um valor mais antigo indica estabilidade.

Para apps da Web, a combinação do navegador e do sistema operacional do usuário constitui uma sessão depois que o usuário faz login na Conta do Google. De forma independente, seu site também mantém uma sessão de usuário separada. Um valor auth_time mais recente indica que o usuário fez login na Conta do Google recentemente. Muitas vezes, isso é uma indicação de um usuário ativo e engajado e pode ser interpretado como um indicador de menor risco.

Em plataformas móveis, como o Android, os usuários costumam fazer login diretamente no dispositivo usando métodos biométricos, como impressão digital ou escaneamento facial, e PIN ou padrão de desbloqueio específico do dispositivo. Os apps e plataformas para dispositivos móveis costumam usar esses métodos de autenticação baseados em plataforma em vez de criar uma nova sessão com o Google, resultando em logins infrequentes na Conta do Google e atualizações correspondentes para auth_time. Portanto, um valor auth_time recente pode sinalizar uma mudança em uma sessão de Conta do Google de longa duração e, portanto, um risco maior.

Os indicadores de confiança são um assunto complexo. Espera-se que auth_time seja usado com outros indicadores, como se a autenticação multifator (MFA) está ativada, o método de autenticação usado e a duração da sessão do usuário entre o aplicativo e a plataforma.

Solicitações

O método específico usado para solicitar as declarações auth_time e amr difere de acordo com a API usada. No entanto, todas as APIs incluem um parâmetro claims opcional para solicitar auth_time e amr.

https://accounts.google.com/o/oauth2/v2/auth?
response_type=id_token&
client_id=YOUR_CLIENT_ID&
scope=openid email profile&
redirect_uri=https://example.com/user-login&
nonce=123-456-7890&
claims={ "id_token": {
            "auth_time": { "essential":true },
            "amr": {"essential":true}
          }
        }

<html>
<body>
  <script src="https://accounts.google.com/gsi/client" async></script>
  <script>
    window.onload = function () {
      google.accounts.id.initialize({
        client_id: "YOUR_WEB_CLIENT_ID",
        callback: function(rsp) { console.log(rsp.credential); },
        essential_claims: "auth_time, amr",
      });
      google.accounts.id.renderButton(
        document.getElementById("buttonDiv"),
        { type: "standard", size: "large" }
      );
    }
  </script>
  <div id="buttonDiv"></div>
</body>
</html>

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
    .setAutoSelectEnabled(true)
    .setFilterByAuthorizedAccounts(true)
    .setServerClientId(WEB_CLIENT_ID)
    .setNonce("NONCE")
    .setClaims(ImmutableList.of(
           new Claim("auth_time", true),
           new Claim("amr", true)
    ))
    .build()

let authTimeClaim = GIDClaim.authTime()
let amrClaim = GIDClaim.amr()
let claims = Set([authTimeClaim, amrClaim])


// Start the sign-in process
GIDSignIn.sharedInstance.signIn(
  withPresenting: rootViewController,
  claims: claims
) { signInResult, error in
  guard let result = signInResult else {
    print("Error signing in: (error?.localizedDescription ?? "No error description")")
    return
  }
  // If sign in succeeded, display the app's main content View
  print("ID Token: (result.user.idToken?.tokenString ?? "No token")")
}

GIDClaim *authTimeClaim = [GIDClaim authTimeClaim];
GIDClaim *AMRClaim = [GIDClaim AMRClaim];
NSSet *claims = [NSSet setWithArray:@[authTimeClaim, AMRClaim]];


// Include the claims set and start the sign-in process
[GIDSignIn.sharedInstance
  signInWithPresentingViewController:self
                                hint:nil
                              claims:claims
                          completion:^(GIDSignInResult * _Nullable signInResult,
                                      NSError * _Nullable error) {
                            // On success signInResult.user.idToken
                            // contains the requested claims.
                          }];

Respostas

Quando as declarações auth_time ou amr são incluídas na solicitação, elas são retornadas na resposta de payload do token de ID junto com outras declarações padrão, como iss (emissor), sub (assunto), aud (público-alvo) e exp (tempo de expiração).

As declarações ausentes provavelmente são devidas ao fato de o app não ter sido verificado ou de outras configurações estarem desativadas, que é o padrão. Siga as instruções em Configuração para confirmar se o ID do cliente e o app em uso estão verificados e se as declarações adicionais estão ativadas.

O valor da declaração auth_time é um número JSON que representa o número de segundos decorridos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC) até o momento em que a autenticação do usuário ocorreu pela última vez.

O valor da declaração amr é uma matriz JSON de strings que representa os métodos de autenticação usados durante o último evento de login da Conta do Google.

Este é um exemplo de um token de ID decodificado que inclui as declarações auth_time e amr:

{
  "iss": "https://accounts.google.com",
  "azp": "YOUR_CLIENT_ID",
  "aud": "YOUR_CLIENT_ID",
  "sub": "117726431651943698600",
  "email": "alice@example.com",
  "email_verified": true,
  "nonce": "123-456-7890",
  "auth_time": 1748875426,
  "amr": ["mfa", "pwd", "tel"],
  "nbf": 1748880889,
  "name": "Elisa Beckett",
  "picture": "https://lh3.googleusercontent.com/a/default-user=s96-c",
  "given_name": "Elisa",
  "family_name": "Beckett",
  "iat": 1748881189,
  "exp": 1748884789,
  "jti": "8b5d7ce345787d5dbf14ce6e08a8f88ee8c9b5b1"
}

O token de ID também contém uma declaração iat (emitida em), que indica o horário em que o JWT foi emitido. Ao comparar as declarações iat e auth_time, é possível determinar o tempo decorrido desde a última autenticação do usuário em relação ao momento em que o token de ID específico foi criado. Por exemplo, se iat for 1748881189 e auth_time for 1748875426, a diferença será de 5.763 segundos, o que representa 1 hora, 36 minutos e 3 segundos de tempo decorrido.