> 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/user-guide/smart-auth/catalog-rules.md). # Rules Catalog Smart Auth evaluates user context during each authentication attempt to determine whether the access is legitimate. These evaluations are grouped by context type — **Device**, **Location**, and **Network** — and each one may contain specific rules that can approve, challenge, or block the attempt. This page documents the available rules, how they work, and what to expect in the API response when they are triggered. *** ## Location Context Rules The location context evaluates whether the user's geographical information is consistent and trustworthy. It relies on data such as GPS coordinates, IP-based geolocation, and device-reported timezone. ### Timezone Mismatch The **Timezone Mismatch** rule detects inconsistencies between the timezone reported by the user's device and the geographical information inferred from their network (IP address). #### Why it matters When a user's device reports a timezone that does not match the country or region detected by their IP address, it may indicate the use of a VPN or location spoofing to mask the real origin of the request — a common pattern in fraud attempts. #### How it works When the Location context is enabled and the timezone mismatch rule is active in the access policy, Smart Auth performs a **two-layer validation** on each authentication attempt: ```mermaid flowchart TD A["Attempt received"] --> B{"Timezone rule active?"} B -->|No| C["Skip validation"] B -->|Yes| D{"Device timezone valid for country?"} D -->|Yes| E{"VPN fingerprint flags mismatch?"} D -->|No| F["❌ TIMEZONE_NOT_IN_COUNTRY_ALLOWLIST"] E -->|No| G["✅ Validation passed"] E -->|Yes| 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 ``` **Layer 1 — Country Allowlist** Smart Auth maintains an allowlist of valid timezones for each country, based on the [IANA Time Zone Database](https://www.iana.org/time-zones). It compares the timezone reported by the user's device against the list of timezones associated with the country detected from the IP address. For example, if the IP indicates the user is in Brazil (`BR`), the device timezone must be one of the Brazilian timezones (e.g., `America/Sao_Paulo`, `America/Manaus`, `America/Bahia`, etc.). If the device timezone does not belong to the detected country's timezone list, the attempt is blocked. **Layer 2 — VPN Fingerprint Confidence** If the first validation passes, Smart Auth performs a second check based on VPN fingerprint data. It evaluates whether detection signals — such as VPN metadata and timezone comparison heuristics — suggest a mismatch. If the confidence score meets or exceeds the configured threshold, the attempt is blocked. {% hint style="info" %} Both layers must be evaluated in sequence. An attempt is only considered valid for the timezone rule if it passes **both** validations. {% endhint %} #### Policy configuration The timezone mismatch rule is configured within the **Location context** of your access policy. It supports three modes: | Mode | Behavior | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Allow** | Timezone mismatch detection is disabled. No validation is performed. | | **Block** | If a timezone mismatch is detected, the authentication attempt is immediately denied. | | **Challenge** | If a timezone mismatch is detected, the user is challenged to provide GPS-based location verification. If the SDK does not support GPS challenge, the mismatch is bypassed. | {% hint style="warning" %} The **Challenge** mode requires SDK support for GPS-based location challenge. If the user's SDK version does not support this feature, the timezone mismatch will be bypassed instead of blocking the attempt. {% endhint %} #### API response When a timezone mismatch is detected and the attempt is blocked, the `GET /authentications/{attemptId}` response will contain the following information in the `contextEvaluation` object: ```json { "contextEvaluation": { "location_context": { "status": "blocked", "reason": "TIMEZONE_MISMATCH", "description": "TIMEZONE_NOT_IN_COUNTRY_ALLOWLIST" } } } ``` When this rule triggers a block, the `reason` field is `TIMEZONE_MISMATCH` and the `description` field indicates the specific cause: | Description | Meaning | | ---------------------------------------- | ------------------------------------------------------------------------------------ | | `TIMEZONE_NOT_IN_COUNTRY_ALLOWLIST` | The device timezone is not a valid timezone for the country detected by the network. | | `TIMEZONE_CONFIDENCE_THRESHOLD_EXCEEDED` | VPN fingerprint analysis detected a timezone mismatch with high confidence. | Additionally, the response includes the raw timezone data collected during the attempt: | Field | Location in response | Description | | -------------------- | --------------------- | ------------------------------------------------------------------------- | | `timezoneFromDevice` | `context.device.info` | The timezone reported by the user's device (e.g., `America/Sao_Paulo`). | | `timezoneFromIp` | `context.network` | The timezone inferred from the user's IP address (e.g., `Europe/London`). | {% hint style="info" %} These fields are always returned in the authentication response when available, regardless of whether the timezone mismatch rule is active. {% endhint %} #### Example scenario Consider a user whose identity is registered in Brazil: 1. The user initiates an authentication attempt. 2. Smart Auth detects the device timezone as `Europe/London`. 3. The IP address resolves to a Brazilian provider, indicating country `BR`. 4. `Europe/London` is **not** in the list of valid timezones for `BR`. 5. The attempt is **blocked** with reason `TIMEZONE_MISMATCH` and description `TIMEZONE_NOT_IN_COUNTRY_ALLOWLIST`. This could indicate the user is using a Brazilian VPN but is physically located in Europe — or that the device timezone was manually changed. --- # 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/user-guide/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.