README

A simple but highly customizable package for preventing access to private or WIP Laravel projects.

Features

Convenient access control for private projects or pages
Simple, beautiful and fully customizable error page
Replaceable authentication process & token storage

Why just not use the Laravel Maintenance Mode?

Blockade offers a simple way to share access to development or staging environments only by typing in a password. The authenticating user will return the intended URL after a successful login. The built in Laravel Maintenance Mode uses a different approach by denying access in deployment or maintenance procedures.

Do we need yet another access control package?

Yes! From my experience, other maintenance mode packages (and similar) only rely on one authentication method which is either cookie or session based. When working on many projects with different tech stacks, some drivers like session storage in API-only projects are simply not available. Blockade is meant to solve this issue by combining several auth mechanisms in one package.

Installation

composer require romanzipp/laravel-blockade

Configuration

Copy configuration & assets files to project folder:

php artisan blockade:install

You can also publish views (--views) and language files (--lang) to further customize the Blockade template.

Make use of the --update parameter if you are seeing an error message at the bottom.

Usage

To enable Blockade, simply

Set the environment variables BLOCKADE_ENABLED=true & BLOCKADE_PASSWORD=
Register the BlockadeMiddleware class in your middleware stack.

namespace App\Http;

use Illuminate\Foundation\Http\Kernel as HttpKernel;
use romanzipp\Blockade\Http\Middleware\BlockadeMiddleware;

class Kernel extends HttpKernel
{
    // Globally for all routes

    protected $middleware = [
        // ...
        BlockadeMiddleware::class,
    ];

    // In a single middleware group

    protected $middlewareGroups = [
        'web' => [
            // ...
            BlockadeMiddleware::class,
        ]
    ];

    // As named middleware, applied in your routes file

    protected $routeMiddleware = [
        // ...
        'blockade' => BlockadeMiddleware::class,
    ];
}

The package defaults to the provided view for password prompt and stores the authentication hash in a cookie.

To reset previous granted access, just change the BLOCKADE_PASSWORD entry. All issued access tokens will be invalid on the next page request.

Handlers

Handlers are responsible for validating authentication requests and sending successful or failed responses. You can set the active handler in blockade.handler and customize each handler individually via the blockade.handlers.* config entries.

Handler	Description	Class
Form (default)	The password is provided by a form	romanzipp\Blockade\Handlers\FormHandler
Query Parameter	The password is attached as query parameter	romanzipp\Blockade\Handlers\QueryParameterHandler

Stores

Stores are storing (how surprising) the authentication state for later requests. You can set the active store in blockade.store and customize each store individually via the blockade.stores.* config entries.

Store	Description	Class
Cookies (default)	The password hash will be stored as browser cookie	romanzipp\Blockade\Stores\CookieStore
Session	The password hash will be stored in the active session	romanzipp\Blockade\Stores\SessionStore

Important: If you are using the SessionStore make sure the BlockadeMiddleware is appended after the Illuminate\Session\Middleware\StartSession middleware.

Extending

You can create your own authentication process by simply implementing the

romanzipp\Blockade\Handlers\Contracts\HandlerContract interface for handlers and
romanzipp\Blockade\Stores\Contracts\StoreContract interface for stores.

Assets

It is recommended to publish the provided css files via the vendor:publish command listed at the top. If the bundled asset file is not available we will use a fallback from unkpg.com and display an error notice in the footer section.

Use the --update argument to update the published assets.

php artisan blockade:install --update

Disclamer

This is no cryptographically secure authentication

The package stores the authentication token as SHA 256 hash of the configured password.

Testing

./vendor/bin/phpunit

Build Frontend

Development

yarn dev

Production

yarn prod

Credits

Special thanks to Katerina Limpitsouni for the awesome unDraw SVG illustrations!

romanzipp / laravel-blockade

Maintainers

Details