Catálogo de Regras

O Smart Auth avalia o contexto do usuário durante cada tentativa de autenticação para determinar se o acesso é legítimo. Essas avaliações são agrupadas por tipo de contexto — Dispositivo, Localização, e Rede — e cada uma pode conter regras específicas que podem aprovar, desafiar ou bloquear a tentativa.

Esta página documenta as regras disponíveis, como elas funcionam e o que esperar na resposta da API quando são acionadas.

---

Regras de contexto de localização

O contexto de localização avalia se as informações geográficas do usuário são consistentes e confiáveis. Ele se baseia em dados como coordenadas GPS, geolocalização baseada em IP e fuso horário informado pelo dispositivo.

Incompatibilidade de fuso horário

Os Incompatibilidade de fuso horário A regra detecta inconsistências entre o fuso horário informado pelo dispositivo do usuário e as informações geográficas inferidas da rede (endereço IP).

Por que isso importa

Quando o dispositivo de um usuário informa um fuso horário que não corresponde ao país ou região detectados pelo endereço IP, isso pode indicar o uso de uma VPN ou de falsificação de localização para mascarar a origem real da solicitação — um padrão comum em tentativas de fraude.

Como funciona

Quando o contexto de localização está habilitado e a regra de incompatibilidade de fuso horário está ativa na política de acesso, o Smart Auth realiza uma validação em duas camadas em cada tentativa de autenticação:

Camada 1 — Lista de permissões por país

O Smart Auth mantém uma lista de permissões de fusos horários válidos para cada país, com base no Banco de Dados de Fusos Horários da IANA. Ele compara o fuso horário informado pelo dispositivo do usuário com a lista de fusos horários associada ao país detectado pelo endereço IP.

Por exemplo, se o IP indicar que o usuário está no Brasil (BR), o fuso horário do dispositivo deve ser um dos fusos horários brasileiros (por exemplo, America/Sao_Paulo, America/Manaus, America/Bahia, etc.).

Se o fuso horário do dispositivo não pertencer à lista de fusos horários do país detectado, a tentativa é bloqueada.

Camada 2 — Confiança da impressão digital da VPN

Se a primeira validação passar, o Smart Auth realiza uma segunda verificação com base nos dados de impressão digital da VPN. Ele avalia se os sinais de detecção — como metadados da VPN e heurísticas de comparação de fuso horário — indicam uma incompatibilidade. Se a pontuação de confiança atingir ou exceder o limite configurado, a tentativa é bloqueada.

Ambas as camadas devem ser avaliadas em sequência. Uma tentativa só é considerada válida para a regra de fuso horário se passar pelas duas validações.

Configuração da política

A regra de incompatibilidade de fuso horário é configurada dentro do contexto de localização da sua política de acesso. Ela oferece suporte a três modos:

Modo	Comportamento
Permitir	A detecção de incompatibilidade de fuso horário está desativada. Nenhuma validação é realizada.
Bloquear	Se uma incompatibilidade de fuso horário for detectada, a tentativa de autenticação é negada imediatamente.
Desafio	Se uma incompatibilidade de fuso horário for detectada, o usuário é desafiado a fornecer verificação de localização com base em GPS. Se o SDK não oferecer suporte ao desafio por GPS, a incompatibilidade é ignorada.

Os Desafio O modo requer suporte do SDK para desafio de localização com base em GPS. Se a versão do SDK do usuário não oferecer suporte a esse recurso, a incompatibilidade de fuso horário será ignorada em vez de bloquear a tentativa.

Resposta da API

Quando uma incompatibilidade de fuso horário é detectada e a tentativa é bloqueada, a GET /authentications/{attemptId} resposta conterá as seguintes informações no contextEvaluation objeto:

{
  "contextEvaluation": {
    "location_context": {
      "status": "blocked",
      "reason": "TIMEZONE_MISMATCH",
      "description": "TIMEZONE_NOT_IN_COUNTRY_ALLOWLIST"
    }
  }
}

Quando esta regra aciona um bloqueio, o campo reason é TIMEZONE_MISMATCH e o campo

Descrição	Significado
TIMEZONE_NOT_IN_COUNTRY_ALLOWLIST	O fuso horário do dispositivo não é um fuso horário válido para o país detectado pela rede.
TIMEZONE_CONFIDENCE_THRESHOLD_EXCEEDED	A análise da impressão digital da VPN detectou uma incompatibilidade de fuso horário com alta confiança.

Além disso, a resposta inclui os dados brutos de fuso horário coletados durante a tentativa:

Campo	Localização na resposta	Descrição
timezoneFromDevice	context.device.info	O fuso horário informado pelo dispositivo do usuário (por exemplo, America/Sao_Paulo).
timezoneFromIp	context.network	O fuso horário inferido a partir do endereço IP do usuário (por exemplo, Europe/London).

Esses campos são sempre retornados na resposta de autenticação quando disponíveis, independentemente de a regra de incompatibilidade de fuso horário estar ativa.

Cenário de exemplo

Considere um usuário cuja identidade esteja registrada no Brasil:

1. O usuário inicia uma tentativa de autenticação.
2. O Smart Auth detecta o fuso horário do dispositivo como Europe/London.
3. O endereço IP resolve para um provedor brasileiro, indicando que o país BR.
4. Europe/London é não está na lista de fusos horários válidos para BR.
5. A tentativa é bloqueada com o motivo é e a descrição TIMEZONE_NOT_IN_COUNTRY_ALLOWLIST.

Isso pode indicar que o usuário está usando uma VPN brasileira, mas fisicamente localizado na أوروبا — ou que o fuso horário do dispositivo foi alterado manualmente.