Download the PHP package directorytree/bartender without Composer

An opinionated way to authenticate users using Laravel Socialite.

Bartender serves you a controller, routes, and a default implementation for easily handling authentication with Laravel Socialite providers. Almost everything in Bartender can be customized.

Index

• Requirements
• Installation
• Setup
• Usage
  • Soft Deletes
  • Email Verification
  • Access/Refresh Tokens
• Extending & Customizing

Requirements

• PHP >= 8.0
• Laravel >= 9.0
• Laravel Socialite >= 5.0

Installation

You can install the package via composer:

Then, publish the migrations. They will create the required columns on the users table:

• provider_id
• provider_name
• provider_access_token
• provider_refresh_token

If your application does not need to store/access provider tokens, you may delete the 2024_10_27_131354_add_provider_token_columns_to_users_table.php migration.

Finally, run the migrations:

Setup

Register the authentication routes using Bartender::routes().

This will register the /auth/{driver}/redirect and /auth/{driver}/callback routes.

Set up any Socialite Providers you need, and update your services.php configuration file with the redirect URL for each provider:

[!important] Remember to fully complete the installation steps for each Socialite Provider you wish to use.

If you receive a Driver [X] not supported exception, you have not completed the installation steps for the provider.

Finally, register the Socialite Provider in your AppServiceProvider using Bartender::serve():

If your application uses a User model outside the default App\Models namespace, you can set it using the Bartender facade.

If your application uses the default Laravel User model in the App\Models namespace, skip this step.

Usage

Direct your user to the /auth/{driver}/redirect route to authenticate with the given driver:

Once the user successfully authenticates, they will be redirected to the /auth/{driver}/callback route, which will automatically create or update their application user account.

[!important] If you receive a Routing requirement for "driver" cannot be empty exception upon clicking one of the login links, you have forgotten to register your the Socialite provider with Bartender using Bartender::serve() in your AppServiceProvider.

Soft Deletes

With the default UserProviderRepository, soft-deleted users will be restored if they log in with their provider.

To change this behaviour, swap out the repository.

Email Verification

With the default UserProviderRepository, users with emails will be automatically verified (by setting the email_verified_at timestamp column) if it is not already set.

To change this behaviour, swap out the repository.

Access/Refresh Tokens

To enable storing the authentication provider access and refresh tokens on your user so that you can access them later, you may apply the StoresProviderTokens interface on your model:

You may also want to add these columns to your model's $hidden attributes, along with encrypted casts for additional security:

Otherwise, if you do not need to store these tokens, you are free to delete the published 2024_10_27_131354_add_provider_token_columns_to_users_table.php migration file and omit applying the StoresProviderTokens interface. Bartender will skip storing these tokens as it does not require them to successfully authenticate users.

Extending & Customizing

Almost everything can be swapped out in Bartender.

If you would like to handle everything yourself for OAuth redirects and callbacks, you may create your own ProviderHandler:

Then, provide it into the second argument in the Bartender::serve method:

You may also extend the built-in UserProviderHandler implementation if you prefer.

For example, if you need to adjust the scopes for a single provider:

Then register it as the handler:

User Creation & Updating

If you would like to customize the creation of the user in the default handler, you may create your own ProviderRepository implementation:

Then, bind your implementation in the service container in your AppServiceProvider:

User Redirects & Flash Messaging

If you would like to customize the behavior of the redirects of the default redirector and flash messages depending on the outcome of a OAuth callback, you can create your own ProviderRedirector implementation:

It's recommended to regenerate the session after authentication to prevent users from exploiting a session fixation attack.

Then, bind your implementation in the service container in your AppServiceProvider: