Laravel stateless HTTP basic auth without the need for a database

Fund package maintenance!

Installs: 1 001 150

Dependents: 2

Suggesters: 0

Security: 0

Stars: 143

Watchers: 2

Forks: 24

Open Issues: 0

v6.9 2023-01-31 08:41 UTC


Latest Version on Packagist Total downloads Software License Build Status


Documentation available in:

🇬🇧 English
🇯🇵 日本語

This package allows you to add a HTTP Basic Auth filter on your routes, without the need to use a database – which the Laravel default auth.basic-middleware relies on.


Perfect when you want to give your clients access to your development site before you have yet to set up your database and/or models. Or perhaps your site doesn't even use a database and you still wish to keep it protected.

On failed authentication the user will get a "401 Unauthorized" response.

A thing to note

While HTTP Basic Auth does give you a protection layer against unwanted visitors, it is still not strictly safe from brute-force attacks. If you are solely using this package for security, you should at least consider looking into Apache or Nginx rate-limiters to limit login attempts.

Version Compatibility

Laravel l5-very-basic-auth
^5.4 5.*
^6 || ^7 || ^8 || ^9 6.*

The odd versioning is due to breaking changes in the testing framework and PHP versions. 3.x-releases are for Laravel 5.4 (PHP 5.6 and up) and 4.x-releases for Laravel 5.5.

Using Laravel 4.x?

Take a look at this gist, it uses the old Route::filter-methods to achieve pretty much the same goal.


Via Composer

$ composer require olssonm/l5-very-basic-auth

Since v4.* (for Laravel 5.5) this package uses Package Auto-Discovery for loading the service provider. Once installed you should see the message

Discovered Package: olssonm/l5-very-basic-auth

If you would like to manually add the provider, turn off Auto-Discovery for the package in your composer.json-file:

"extra": {
    "laravel": {
        "dont-discover": [

And then add the provider in the providers array (config/app.php).

'providers' => [


Run the command $ php artisan vendor:publish and select Provider: Olssonm\VeryBasicAuth\VeryBasicAuthServiceProvider to publish the configuration. You could also type $ php artisan vendor:publish --provider="Olssonm\VeryBasicAuth\VeryBasicAuthServiceProvider" to directly publish the files.

The file very_basic_auth.php will then be copied to your app/config-folder – here you can set various options such as username and password.


There is no default password. Upon installation a random password is set for added security (we don't want everyone to use the same default password). Please publish the packages configuration to have the ability to set a custom password.


You may set the environments that the package should be applied for. You may simply use "*" to use in all environments (this is also the default).

'envs' => [


'envs' => [

Response handlers

When the authentication fails the response handler sends out an error response (see "Views and messages" for more about these options). By default the handler will be \Olssonm\VeryBasicAuth\Handlers\DefaultResponseHandler (see response_handler in very_basic_auth.php). You may however write your own response-logic if you so choose. The only requirement is that it implements the \Olssonm\VeryBasicAuth\Handlers\ResponseHandler-interface, and has an __invoke-method that accepts a request-object, like so:

use Illuminate\Http\Request;
use Olssonm\VeryBasicAuth\Handlers\ResponseHandler;

class CustomResponseHandler implements ResponseHandler
    public function __invoke(Request $request)
        // Do some stuff
        return response('Custom response', 401);

Views and messages

In the very_basic_auth.php-configuration you have the ability to set a custom view instead of a message.

// Message to display if the user "opts out"/clicks "cancel"
'error_message'     => 'You have to supply your credentials to access this resource.',

// If you prefer to use a view with your error message you can uncomment "error_view".
// This will supersede your default response message
// 'error_view'        => 'very_basic_auth::default'

If you uncomment error_view, the middleware will try to find your specified view. You supply this value as usual (without the .blade.php-extention).


The middleware uses the auth.very_basic-filter to protect routes. You can either use Route::group() to protect multiple routes, or chose just to protect them individually.


Route::group(['middleware' => 'auth.very_basic'], function() {
    Route::get('/', ['as' => 'start', 'uses' => 'StartController@index']);
    Route::get('/page', ['as' => 'page', 'uses' => 'StartController@page']);


Route::get('/', [
    'as' => 'start',
    'uses' => 'StartController@index',
    'middleware' => 'auth.very_basic'

You may also set the credentials inline;

Route::get('/', [
    'as' => 'start',
    'uses' => 'StartController@index',
    'middleware' => 'auth.very_basic:username,password'

Note: inline credentials always take president over the very_basic_auth.php-configuration file.


$ composer test


$ phpunit

Laravel always runs in the "testing" environment while running tests. Make sure that testing is set in the envs-array in very_basic_auth.php.

Thank you

A big thank you to the people who has contributed to this package, among others:

kazuhei – for providing the awesome Japanese translation
freekmurze – for additional information on package/vendor installations
faiare – for pointing out and implementing the realm-attribute (RFC7235)


The MIT License (MIT). Please see License File for more information.

© 2022 Marcus Olsson.