Admin Auth

Requirements
Installation
- Authorization
- Alternative advanced installation
Basic usage
Authentication
Password rest
Activation
- User Model
- Self-activation form
Admin middleware

This package handles authentication into Admin UI interface. It provides these features:

User authentication
Reset password
Account activation

Provided functionality is ready to use - package exposes a set of routes, it has controllers and views (based on brackets/admin-ui admin template).

Requirements

This package requires PHP 7.0+ and Laravel 5.5.

It uses brackets/admin-ui as a dependency.

Installation

{danger.fa-exclamation-triangle} This section is only when you want to use this package as a standalone package. If you are using with Craftable, then this package is already installed.

First, let's require this package:

composer require brackets/admin-auth

{primary} If you did not installed brackets/admin-ui yet, this is the moment you should. Follow the Admin UI Installation.

Now let's install this package using:

php artisan admin-auth:install

Finally we need to compile all the assets using npm:

npm install && npm run dev

Authorization

{primary} This section is for those of you who use this package as a standalone package (without brackets/craftable). If yo are using Craftable, you can safely skip this chapter :)

This packages provides some routes, that are for security reasons protected with 1 ability:

admin

But the package does not define this ability, that's left to you and your specific use case.

How to quickly set it up? Let's assume, your use case is, that any logged user should have this ability. To get it working all you have to do is edit your AuthServiceProvider class and define it here:

class AuthServiceProvider extends ServiceProvider
{
    ...
    public function boot()
    {
        Gate::define('admin', function ($user) { return true; });

        $this->registerPolicies();
    }

Alternative advanced installation

If you have existing project and you want to have everything strongly in your hands, you can install this package manually.

Before we start we need to install brackets/admin-ui package (see Admin UI Installation).

Then let's require this package:

composer require brackets/admin-auth

This package is intended to work with your existing User model (i.e. from Laravel's installation). These are the attributes our package can handle (but none of them is required):

first_name (string) represents a first name of the user
last_name (string) represents a last name of the user
activated (boolean) represents a status if user activated
forbidden (boolean) represents a status if user authentication is forbidden
deleted_at (datetime) for soft delete functionality
language (string) holds a user's preferred locale that is going to be used

If you use default User model from Laravel installation, we recommend you to use our migration to migrate to get the most out of our package (but again, it's up to you). Migration can be published using:

php artisan vendor:publish --provider="Brackets\AdminAuth\AdminAuthServiceProvider" --tag="migrations"

Our migration perform following:

it splits the name attribute into first_name and last_name (it also split's the values by first space character)
adds a soft delete functionality with respect to unique constraint on email (you can have several soft deleted users with the same email, but only one can be not deleted)
adds activated functionality to allow user to activate his/her account. To enable this feature you also have to change config activations.enabled to true.
adds forbidden functionality to allow admin to forbid authentication. To enable this feature you also have to change config check-forbidden to true.
adds language preference for admin ui

Either you have published our migration or not, you must migrate.

php artisan migrate

You can publish the config file with:

php artisan vendor:publish --provider="Brackets\AdminAuth\AdminAuthServiceProvider" --tag="config"

By default this package registers a set of routes. These can be disabled with config use-routes => false,.

Next you need to register vendor/brackets/admin-auth/resources/assets/js as one of your modules. Edit your webpack.mix.js like this:

mix.js(['resources/assets/admin/js/admin.js'], 'public/build/admin/js')
    .webpackConfig({
        resolve: {
            modules: [
                path.resolve(__dirname, 'vendor/brackets/admin-ui/resources/assets/js'),
                path.resolve(__dirname, 'vendor/brackets/admin-auth/resources/assets/js'),
                'node_modules'
            ],
        }
    })
    ...

If you will use provided views, you have to register vue components, to append to resources\assets\admin\js\index.js

import 'auth';

Finally we need to compile all the assets using npm:

npm install && npm run dev

Basic usage

Let's point our browser to /admin/login.

Admin login form

Tadaaa :) You should be able to see login form.

Let's create some user, so you can sign into the admin interface. We're gonna use php artisan tinker:

>>> factory(App\User::class)->create(['email' => 'john@example.com', 'password' => bcrypt('password123')]);

Now you can authenticate.

Admin homepage

You should be able to see an empty Admin UI interface (with no content to manage).

{primary} If you are getting UnauthorizedException, see instructions in Authorization section.

Authentication

Authentication part of this package is based on standard Authentication provided by Laravel, with some adjustments and more configurable options.

During the authentication process, depends on the configuration, more checks are made than just checking email and password:

activated - if activation is enabled, then we additionally check for activated == true on user, see more in Activation
forbidden - if forbidden functionality is enabled, then we check for forbidden == false (user's authentication can be forbidden)

Password reset

Password reset is also based on Laravel standard password reset classes.

We have introduced redirect configuration.

We have added a strong password constrain (consisting from at least 7 chars at least one digit etc.).

Activation

This package provides complete functionality around user activation. Main purpose of activation is to confirm user's e-mail address is really an address user has access to. This feature can be disabled with config activations.enabled. If this feature is turned on, user can not log in, unless his account is activated. After user is created, activation email with custom link is sent to the user. After visiting this link, user will be activated.

User Model

For activation to work properly with default Laravel User model, the User model has to implement Brackets\AdminAuth\Contracts\Auth\CanActivate interface. This can be done with Brackets\AdminAuth\Auth\Activations\CanActivate trait.

Also users table need to have activated column. The provided migration will do the trick.

Self-activation form

If you will enable activations.self-activation-form-enabled, user can visit form where he can request to resend the activation e-mail.

Admin middleware

Our package also comes with Brackets\AdminAuth\Http\Middleware\Admin middleware, which checks if the Auth user has the ability called admin. You can add them inside your app/Http/Kernel.php file.

protected $routeMiddleware = [
    // ...
    'admin' => \Brackets\AdminAuth\Http\Middleware\Admin::class,
];

Now you can protect your routes using the middleware you just set up:

Route::group(['middleware' => ['admin']], function () {
    //
});

If the user does not have the ability, response is 403 Unauthenticated. You can use this middleware, if it suites your need.

Prologue

Getting started

Features