konsulting/laravel-butler

Butler manages multiple Socialite authentication for your Laravel app.

Butler

Butler manages multiple Socialite authentication for your Laravel app., _(*1)

In a few simple steps you can allow users to log in to your site using multiple providers., _(*2)

Butler is built to work alongside standard Laravel authentication, and uses Socialite to connect to authentication providers., _(*3)

Requirements

• Install Socialite - follow the documentation on the Laravel site., _(*4)

• Set up your Socialite providers (you may need to install extra Socialite Providers)., _(*5)

Installation

• Install Butler using composer: composer require konsulting/laravel-butler, _(*6)

• If you are using Laravel 5.5, Butler will auto-register the service provider and the Facade. However, if you have chosen not to auto-register, or are using an earlier version, add Butler's Service Provider to config/app.php, _(*7)

'providers' => [
    // Other service providers...

    Konsulting\Butler\ButlerServiceProvider::class,
],

• Add Butler's Facade to config/app.php

'aliases' => [
    // Other aliases...

    'Butler' => Konsulting\Butler\ButlerFacade::class,
],

• Add Butler's routes to app/Providers/RouteServiceProvider.php

class RouteServiceProvider ...

public function map()
{
    $this->mapApiRoutes();

    $this->mapWebRoutes();

    \Butler::routes();
}

• Publish configuration and adjust for your site php artisan vendor:publish --provider=Konsulting\\Butler\\ButlerServiceProvider --tag=config

Adjust in config/butler.php. Add the providers you want to make available for Authentication - these map directly to Socialite drivers. There are examples in the published file., _(*8)

    // Other Settings

    'providers' => [
        'google' => [
            'name' => 'Google',
            'scopes' => [], // define any specific scopes you want to request here
            'icon' => 'fa fa-google',
            'class' => 'btn-google',
        ],
        ...
    ]

See configuration options for more information., _(*9)

• Optionally add list of Oauth buttons to your login page, and status feedback., _(*10)

  Add the following includes to your blade template for the login page., _(*11)

@include('butler::status')

@include('butler::list')

Configuration Options

There is a small set of configuration options., _(*12)

Butler Driver

We wrap the socialite driver in a Butler Driver which adds a methods to refresh() a social identity using the refresh token. It will also proxy all the usual SocialiteProvider methods to the orginal provider., _(*13)

    $driver = \Butler::driver(string $providerName); // For a specific social identity, this would be $socialIdentity->provider
    $driver->refresh($socialIdentity);

Security

We have not encrypted any of the retrieved tokens at this time, since the tokens are intended to be short-lived. We’re happy to receive views on this decision., _(*14)

If you find any security issues, or have any concerns, please email keoghan@klever.co.uk, rather than using the issue tracker., _(*15)

Contributing

Contributions are welcome and will be fully credited. We will accept contributions by Pull Request., _(*16)

Please:, _(*17)

• Use the PSR-2 Coding Standard
• Add tests, if you’re not sure how, please ask.
• Document changes in behaviour, including readme.md.

Testing

We use PHPUnit and the excellent orchestral/testbench, _(*18)

Run tests using PHPUnit: vendor/bin/phpunit, _(*19)