Blocking logins | 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)  Responding-to-suspicious-logins  Blocking logins

 Version   v1      

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

  Blocking logins    
- [ 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)

 Blocking logins
===============

###  On this page 

1. [ Customizing the error ](#content-customizing-the-error)
2. [ Customizing the response ](#content-customizing-the-response)
3. [ Letting a user in again ](#content-letting-a-user-in-again)

Sometimes telling the user afterwards isn't enough. `Spatie\SuspiciousLogin\Actions\BlockLoginAction` logs the user back out during the login request and rejects it with a validation error. The `Strict` preset uses it for high risk logins.

```
use Spatie\SuspiciousLogin\Actions\Action;
use Spatie\SuspiciousLogin\Actions\BlockLoginAction;
use Spatie\SuspiciousLogin\Actions\NotifyUserAction;

public function onMediumRisk(): Action|array
{
    return NotifyUserAction::new();
}

public function onHighRisk(): Action|array
{
    return [NotifyUserAction::new(), BlockLoginAction::new()];
}
```

When it runs, the action:

1. marks the login attempt as `blocked`,
2. fires a [`SuspiciousLoginBlockedEvent`](/docs/laravel-suspicious-login/v1/responding-to-suspicious-logins/using-events),
3. logs the user out of the guard they just logged in to,
4. throws a `ValidationException`.

Because the login happens inside `Auth::attempt()`, that exception comes out of your login controller like any other validation error. A regular form redirects back with an error on the `email` field, and a JSON request gets a 422 response. Breeze, Jetstream and Fortify show the error without any changes.

The exception ends the request, so always put `BlockLoginAction` last in the array.

This action requires a session guard with a `logout()` method. It does not revoke API tokens or support stateless guards. For token-based authentication, use a [custom action](/docs/laravel-suspicious-login/v1/responding-to-suspicious-logins/writing-your-own-actions) and reject the attempt before issuing a token.

The user has already been authenticated when the action runs. It does not undo other login listeners or revoke existing sessions. Throwing an exception from a listener alone is not a replacement for logging the user out.

Customizing the error
-----------------------------------------------------------------------------------------------------------------------

```
BlockLoginAction::new()
    ->errorKey('username')
    ->message('We blocked this login because it looked suspicious. Check your email.'),
```

The message is passed through Laravel's `__()` helper, so you can translate it.

Customizing the response
--------------------------------------------------------------------------------------------------------------------------------

To change how a blocked login responds, extend `BlockLoginAction` and override its protected `respond` method:

```
namespace App\SuspiciousLogin\Actions;

use Spatie\SuspiciousLogin\Actions\BlockLoginAction;
use Spatie\SuspiciousLogin\Models\LoginAttempt;

class BlockLoginWithForbiddenResponseAction extends BlockLoginAction
{
    protected function respond(LoginAttempt $attempt): never
    {
        abort(403, 'This login requires verification.');
    }
}
```

Use your action in the preset instead of `BlockLoginAction`:

```
use App\SuspiciousLogin\Actions\BlockLoginWithForbiddenResponseAction;
use Spatie\SuspiciousLogin\Actions\Action;

public function onHighRisk(): Action|array
{
    return BlockLoginWithForbiddenResponseAction::new();
}
```

The attempt is already marked as blocked, the blocked event has been fired, and the user has been logged out when `respond` runs. The method receives the attempt so you can use its ID, risk level or reasons in your response.

The return type is `never`: your method must throw an exception or call `abort()`, not return a response. Actions run inside the login event listener, so returning a response would not send it to the browser. For example, use `abort(redirect('/login-verification'))` for a redirect, or `abort(response()->json(['message' => 'Login blocked.'], 403))` for JSON. Any verification flow is up to your app; the user has already been logged out.

The `errorKey()` and `message()` options configure the default validation response. An override must use them explicitly if it needs them.

Letting a user in again
-----------------------------------------------------------------------------------------------------------------------------

A blocked login never makes its device, IP address or country known. So when the real user tries again from the same laptop, the login is likely to be blocked again.

Once you have confirmed it was them, for example through the support desk, unblock the attempt:

```
$attempt->update(['blocked' => false]);
```

From then on, that attempt counts as a normal successful login, and its device, IP address and country are known for the next one.

 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)
