README

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.

Installation

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": [
            "olssonm/l5-very-basic-auth"
        ]
    }
},

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

'providers' => [
    Olssonm\VeryBasicAuth\VeryBasicAuthServiceProvider::class
]

Configuration

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.

Note

There is no default password. Upon installation you will need to set your own username and password. Please publish the packages configuration to have the ability to set these. If left empty, basic auth will not be active.

Environments

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' => [
    '*'
],

Or

'envs' => [
    'production',
    'development',
    'local'
],

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).

Usage

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.

Group

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

Single

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.

Generating hash for password

If you want to generate a hash for your password, you can use the artisan-command:

php artisan very-basic-auth:generate-password

It will ask you for a password, and then automatically insert the hash into your .env-file

Testing

$ composer test

or

$ 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)

License

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

© 2024 Marcus Olsson.