> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-docs/caf-product-guides-pt-br/guia-do-usuario/smart-auth/catalog-rules.md). # 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: ```mermaid flowchart TD A["Tentativa recebida"] --> B{"Regra de fuso horário ativa?"} B -->|Não| C["Ignorar validação"] B -->|Sim| D{"Fuso horário do dispositivo válido para o país?"} D -->|Sim| E{"A impressão digital da VPN indica incompatibilidade?"} D -->|Não| F["❌ TIMEZONE_NOT_IN_COUNTRY_ALLOWLIST"] E -->|Não| G["✅ Validação aprovada"] E -->|Sim| H["❌ TIMEZONE_CONFIDENCE_THRESHOLD_EXCEEDED"] style A fill:#3A76CF,color:#fff,stroke:#000 style C fill:#80EABE,color:#000,stroke:#000 style G fill:#80EABE,color:#000,stroke:#000 style F fill:#ff6b6b,color:#fff,stroke:#000 style H fill:#ff6b6b,color:#fff,stroke:#000 ``` **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](https://www.iana.org/time-zones). 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. {% hint style="info" %} 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. {% endhint %} #### 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. | {% hint style="warning" %} 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. {% endhint %} #### 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: ```json { "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`). | {% hint style="info" %} 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. {% endhint %} #### 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.caf.io/caf-docs/caf-product-guides-pt-br/guia-do-usuario/smart-auth/catalog-rules.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.