Geolocation drivers | laravel-suspicious-login | Spatie       

 SPATIE  

laravel-suspicious-login
========================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-suspicious-login](https://spatie.be/docs/laravel-suspicious-login/v1)  Advanced-usage  Geolocation drivers

 Version   v1      

 Other versions for crawler [v1](https://spatie.be/docs/laravel-suspicious-login/v1) 

  Geolocation drivers    
- [ Introduction ](https://spatie.be/docs/laravel-suspicious-login/v1/introduction)
- [ Support us ](https://spatie.be/docs/laravel-suspicious-login/v1/support-us)
- [ Requirements ](https://spatie.be/docs/laravel-suspicious-login/v1/requirements)
- [ Installation &amp; setup ](https://spatie.be/docs/laravel-suspicious-login/v1/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-suspicious-login/v1/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-suspicious-login/v1/changelog)
- [ About us ](https://spatie.be/docs/laravel-suspicious-login/v1/about-us)

Basic usage
-----------

- [ Getting started ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/getting-started)
- [ How a login is scored ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/how-a-login-is-scored)
- [ Choosing a preset ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/choosing-a-preset)
- [ Customizing presets ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/customizing-presets)
- [ Working with login attempts ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/working-with-login-attempts)
- [ Adding custom properties ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/adding-custom-properties)
- [ Recording logins manually ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/recording-logins-manually)

Available checks
----------------

- [ Overview ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/overview)
- [ New device ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/new-device)
- [ New IP address ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/new-ip)
- [ New country ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/new-country)
- [ Impossible travel ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/impossible-travel)
- [ Allowed and blocked countries ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/country)
- [ Failed attempts ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/failed-attempts)
- [ Credential stuffing ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/credential-stuffing)
- [ Unusual time ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/unusual-time)
- [ Suspicious user agent ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/suspicious-user-agent)
- [ IP reputation ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/ip-reputation)
- [ Multiple countries ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/multiple-countries)

Responding to suspicious logins
-------------------------------

- [ Notifying users ](https://spatie.be/docs/laravel-suspicious-login/v1/responding-to-suspicious-logins/notifying-users)
- [ Blocking logins ](https://spatie.be/docs/laravel-suspicious-login/v1/responding-to-suspicious-logins/blocking-logins)
- [ Writing your own actions ](https://spatie.be/docs/laravel-suspicious-login/v1/responding-to-suspicious-logins/writing-your-own-actions)
- [ Using events ](https://spatie.be/docs/laravel-suspicious-login/v1/responding-to-suspicious-logins/using-events)

Advanced usage
--------------

- [ Creating custom checks ](https://spatie.be/docs/laravel-suspicious-login/v1/advanced-usage/creating-custom-checks)
- [ Geolocation drivers ](https://spatie.be/docs/laravel-suspicious-login/v1/advanced-usage/geolocation-drivers)
- [ IP reputation drivers ](https://spatie.be/docs/laravel-suspicious-login/v1/advanced-usage/ip-reputation-drivers)
- [ Device fingerprints ](https://spatie.be/docs/laravel-suspicious-login/v1/advanced-usage/device-fingerprints)
- [ Using your own model ](https://spatie.be/docs/laravel-suspicious-login/v1/advanced-usage/using-your-own-model)

 Geolocation drivers
===================

###  On this page 

1. [ ipinfo ](#content-ipinfo)
2. [ Cloudflare ](#content-cloudflare)
3. [ MaxMind ](#content-maxmind)
4. [ Disabling location lookups ](#content-disabling-location-lookups)
5. [ Creating your own driver ](#content-creating-your-own-driver)

Four checks need to know where a login comes from: [new country](/docs/laravel-suspicious-login/v1/available-checks/new-country), [multiple countries](/docs/laravel-suspicious-login/v1/available-checks/multiple-countries), [impossible travel](/docs/laravel-suspicious-login/v1/available-checks/impossible-travel) and [allowed and blocked countries](/docs/laravel-suspicious-login/v1/available-checks/country). A geolocation driver turns an IP address into a country, and if it can, a city and coordinates.

The default `ipinfo` driver works without an API token. It sends public IP addresses to ipinfo.io, subject to its request limits. Choose the driver in `config/suspicious-login.php`:

```
'geolocation' => [
    'driver' => 'ipinfo',
    // ...
],
```

DriverCountryCoordinatesNeeds`ipinfo` (default)yesyesoptionally an ipinfo.io token`cloudflare`yeswith visitor location headersyour app behind Cloudflare`maxmind`yesyes`geoip2/geoip2` and a database file`null`nononothing; disables location lookupsLocations are cached per IP address for a week. To cache them for one day instead, set `cache_ttl` in seconds in `config/suspicious-login.php`:

```
'geolocation' => [
    'driver' => 'ipinfo',
    'cache_ttl' => 60 * 60 * 24,
    // ...
],
```

Private and reserved IP addresses, such as `127.0.0.1` in local development, are never looked up. When no location is available, the location checks pass. Other checks still contribute to the score.

Cached locations are shared between drivers. After switching drivers, an IP address can keep its old location until the cache entry expires. To refresh a specific address:

```
use Illuminate\Support\Facades\Cache;

Cache::forget('suspicious-login:location:8.8.8.8');
```

ipinfo
--------------------------------------------------------------------------

The `ipinfo` driver calls the [ipinfo.io](https://ipinfo.io) API. It works without an account, up to ipinfo's free limit. For more requests, create a token and configure it in `config/suspicious-login.php`:

```
'geolocation' => [
    'driver' => 'ipinfo',
    'ipinfo' => [
        'token' => env('IPINFO_TOKEN'),
    ],
    // ...
],
```

Keep the token in your deployment's secrets or `.env` file rather than committing it to source control.

Requests time out after two seconds, so a slow API never holds up a login for long.

Cloudflare
--------------------------------------------------------------------------------------

The `cloudflare` driver reads location headers from the current request without calling an external API. Select it in `config/suspicious-login.php`:

```
'geolocation' => [
    'driver' => 'cloudflare',
    // ...
],
```

When your app runs behind Cloudflare, the `CF-IPCountry` header supplies the visitor's country. For the city and coordinates, which impossible travel needs, turn on the "Add visitor location headers" managed transform in your Cloudflare dashboard.

Make sure Laravel [trusts Cloudflare as a proxy](https://laravel.com/docs/requests#configuring-trusted-proxies). Otherwise `$request->ip()` returns the address of a Cloudflare server instead of the visitor's, and a location cached for that address can be reused for other visitors. Only accept these headers from Cloudflare; requests sent directly to your server must not be able to supply their own location headers.

MaxMind
-----------------------------------------------------------------------------

The `maxmind` driver reads a local GeoLite2 City or GeoIP2 City database. Lookups don't leave your server, which makes it the fastest and most private option.

Install MaxMind's reader:

```
composer require geoip2/geoip2
```

Then [download a GeoLite2 City database](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data) with a free MaxMind account. By default, the driver looks for it in `storage/app/geoip/GeoLite2-City.mmdb`. Select the driver and, if needed, change the database path in `config/suspicious-login.php`:

```
'geolocation' => [
    'driver' => 'maxmind',
    'maxmind' => [
        'database_path' => storage_path('app/geoip/GeoLite2-City.mmdb'),
    ],
    // ...
],
```

Use MaxMind's `geoipupdate` tool to keep your database current.

Disabling location lookups
--------------------------------------------------------------------------------------------------------------------------------------

To avoid sending IP addresses to an external service without setting up another driver, select the string `'null'` in `config/suspicious-login.php`:

```
'geolocation' => [
    'driver' => 'null',
    // ...
],
```

This stops new lookups. Previously cached locations can still be used until they expire; once no cached location remains, location fields stay empty and location checks pass. Existing attempts keep their stored locations.

Creating your own driver
--------------------------------------------------------------------------------------------------------------------------------

A driver implements `Spatie\SuspiciousLogin\Drivers\Geolocation\GeolocationDriver`. It gets an IP address and returns a `Location`, or `null` when it doesn't know:

```
namespace App\SuspiciousLogin;

use Spatie\SuspiciousLogin\Drivers\Geolocation\GeolocationDriver;
use Spatie\SuspiciousLogin\Drivers\Geolocation\Location;

class MyGeolocationDriver implements GeolocationDriver
{
    public function locate(string $ip): ?Location
    {
        $result = MyGeoService::lookup($ip);

        if (! $result) {
            return null;
        }

        return new Location(
            countryCode: $result->country,
            city: $result->city,
            latitude: $result->latitude,
            longitude: $result->longitude,
        );
    }
}
```

Register it in the `boot` method of a service provider:

```
use App\SuspiciousLogin\MyGeolocationDriver;
use Spatie\SuspiciousLogin\Drivers\Geolocation\GeolocationManager;

app(GeolocationManager::class)->extend('my-driver', fn () => new MyGeolocationDriver);
```

Then select it in `config/suspicious-login.php`:

```
'geolocation' => [
    'driver' => 'my-driver',
    // ...
],
```

Results of your driver are cached like those of the built-in ones.

 A good
match?
-------------

### What we do best

- All things Laravel
- Custom frontend components
- Building APIs
- AI-powered features
- Simplifying things
- Clean solutions
- Integrating services

### Not our cup of tea

- WordPress themes
- Cutting corners
- Free mockups to win a job
- "Just execute the briefing"

 In short: we'd like to be a **substantial part** of your project.

 [ Get in touch via email ](mailto:info@spatie.be?subject=A%20good%20match%21&body=Tell%20us%20as%20much%20as%20you%20can%20about%0A-%20your%20online%20project%0A-%20your%20planning%0A-%20your%20budget%0A-%20%E2%80%A6%0A%0AAnything%20that%20helps%20us%20to%20start%20straightforward%21)
